prompt
prompt v0.10.0

View Source Prompt (prompt v0.10.0)

Prompt provides a complete solution for building interactive command line applications.

It's very flexible and can be used just to provide helpers for taking input from the user and displaying output.

basic-usage

 Basic Usage

import Prompt includes utilities for:

advanced-usage

 Advanced usage

See Prompt.Router

building-for-distribution

 Building for Distribution

There are a couple of different options for building a binary ready for distributing. Which ever approach you decide to use, you'll probably want to keep the docs instead of stripping them. For escripts, you'll add the following to the escript key in mix.exs, if using Bakeware, you'll add it to the releases key.

:strip_beams: [keep: ["Docs"]]

escript

 Escript

An escript is the most straightforward approach, but requires that erlang is already installed on the system.

bakeware

 Bakeware

This has been my preferred approach recently. Bakeware uses releases to build a single executable binary that can be run on the system without the dependency on erlang or elixir.

For Bakeware, I also set export RELEASE_DISTRIBUTION=none in rel/env.sh.eex and rel/env.bat.eex - unless you need erlang distribution in your CLI.

For a complete example see Slim

Run MIX_ENV=prod mix release to build the binary. This will output the usual release messages for a mix release command, but in the case of a CLI, it's a bit of a red herring. The binary you want to run as a CLI will be in _build/prod/rel/bakeware/<your_app>.

burrito

 Burrito

Burrito is another option for building a single binary artifact. It is unique because you can build binaries for windows, mac and linux all from one machine.

For a complete example see Genex

Run MIX_ENV=prod mix release to build the binary. This will output the usual release messages for a mix release command, but in the case of a CLI, it's a bit of a red herring. The binary you want to run as a CLI will be in burrito_out/<your_app>.

Link to this section Summary

Types

argv()

The list of strings coming from the commmand-line arguments

command_list()

A keyword list of commands and implementations of Prompt.Command

Input Functions

choice(question, custom, opts \\ [])

Display a choice prompt with custom answers.

confirm(question, opts \\ [])

Display a Y/n prompt.

password(display, opts \\ [])

Prompt the user for input, but conceal the users typing.

select(display, choices, opts \\ [])

Displays options to the user denoted by numbers.

text(display, opts \\ [])

Display text on the screen and wait for the users text imput.

Output Functions

display(text, opts \\ [])

Writes text to the screen.

table(matrix, opts \\ [])

Print an ASCII table of data. Requires a list of lists as input.

Functions

table_data(matrix, opts \\ [border: :normal])

Use this to get an iolist back of the table. Useful when you want an ascii table/1 for other mediums like markdown files.

Link to this section Types

Link to this type

argv()

View Source 
@type argv() :: [String.t()]

The list of strings coming from the commmand-line arguments

Link to this type

command_list()

View Source 
@type command_list() :: keyword(Prompt.Command)

A keyword list of commands and implementations of Prompt.Command

examples

 Examples 

iex> commands = [help: CLI.Commands.Help, version: CLI.Commands.Version]

Link to this section Input Functions

Link to this function

choice(question, custom, opts \\ [])

View Source 
@spec choice(String.t(), keyword(), keyword()) :: :error | atom()

Display a choice prompt with custom answers.

Takes a keyword list of answers in the form of atom to return and string to display.

[yes: "y", no: "n"]

will show "(y/n)" and return :yes or :no based on the choice.

Supported options:

  • :color - The text color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow].

  • :background_color - The background color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow].

  • :default_answer - The default answer for the choices. Defaults to the first choice.

examples

 Examples 

iex> Prompt.choice("Save password?",
...>   [yes: "y", no: "n", regenerate: "r"],
...>   default_answer: :regenerate
...> )
"Save Password? (y/n/R):" [enter]
iex> :regenerate
Link to this function

confirm(question, opts \\ [])

View Source 
@spec confirm(
  String.t(),
  keyword()
) :: :yes | :no | :error

Display a Y/n prompt.

Sets 'Y' as the the default answer, allowing the user to just press the enter key. To make 'n' the default answer pass the option default_answer: :no

Supported options:

  • :color - The text color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow].

  • :background_color - The background color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow].

  • :default_answer - The default answer to the confirmation. The default value is :yes.

  • :mask_line - If set to true, this will mask the current line by replacing it with #####. Useful when showing passwords in the terminal. The default value is false.

examples

 Examples 

iex> Prompt.confirm("Send the email?")
"Send the email? (Y/n):" Y
iex> :yes

iex> Prompt.confirm("Send the email?", default_answer: :no)
"Send the email? (y/N):" [enter]
iex> :no
Link to this function

password(display, opts \\ [])

View Source 
@spec password(
  String.t(),
  keyword()
) :: String.t()

Prompt the user for input, but conceal the users typing.

Supported options:

  • :color - The text color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

  • :background_color - The background color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

examples

 Examples 

iex> Prompt.password("Enter your passsword")
"Enter your password:"
iex> "super_secret_passphrase"
Link to this function

select(display, choices, opts \\ [])

View Source 
@spec select(String.t(), [String.t()] | [{String.t(), any()}], keyword()) ::
  any() | :error

Displays options to the user denoted by numbers.

Allows for a list of 2 tuples where the first value is what is displayed and the second value is what is returned to the caller.

Supported options:

  • :color - The text color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

  • :background_color - The background color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

  • :multi - Allows multiple selections from the options presented. The default value is false.

examples

 Examples 

iex> Prompt.select("Choose One", ["Choice A", "Choice B"])
"  [1] Choice A"
"  [2] Choice B"
"Choose One [1-2]:" 1
iex> "Choice A"

iex> Prompt.select("Choose One", [{"Choice A", 1000}, {"Choice B", 1001}])
"  [1] Choice A"
"  [2] Choice B"
"Choose One [1-2]:" 2
iex> 1001

iex> Prompt.select("Choose as many as you want", ["Choice A", "Choice B"], multi: true)
"  [1] Choice A"
"  [2] Choice B"
"Choose as many as you want [1-2]:" 1 2
iex> ["Choice A", "Choice B"]
Link to this function

text(display, opts \\ [])

View Source 
@spec text(
  String.t(),
  keyword()
) :: String.t() | :error | :error_min | :error_max

Display text on the screen and wait for the users text imput.

Supported options:

  • :color - The text color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

  • :background_color - The background color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

  • :min - The minimum charactors required for input The default value is 0.

  • :max - The maximum charactors required for input The default value is 0.

examples

 Examples 

iex> Prompt.text("Enter your email")
"Enter your email:" t@t.com
iex> t@t.com

Link to this section Output Functions

Link to this function

display(text, opts \\ [])

View Source 
@spec display(
  String.t() | [String.t()],
  keyword()
) :: :ok

Writes text to the screen.

Takes a single string argument or a list of strings where each item in the list will be diplayed on a new line.

Supported options:

  • :color - The text color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

  • :background_color - The background color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

  • :position - Print the content starting from the leftmost position or the rightmost position The default value is :left.

  • :mask_line - If set to true, this will mask the current line by replacing it with #####. Useful when showing passwords in the terminal. The default value is false.

examples

 Examples 

iex> Prompt.display("Hello from the terminal!")
"Hello from the terminal!"

iex> Prompt.display(["Hello", "from", "the", "terminal"])
"Hello"
"from"
"the"
"terminal"
Link to this function

table(matrix, opts \\ [])

View Source 
@spec table([list()], keyword()) :: :ok

Print an ASCII table of data. Requires a list of lists as input.

Supported options:

  • :header - Use the first element as the header for the table. The default value is false.

  • :border - Determine how the border is displayed, one of :normal (default), :markdown, or :none The default value is :normal.

  • :color - The text color. One of [:black, :blue, :cyan, :green, :light_black, :light_blue, :light_cyan, :light_green, :light_magneta, :light_red, :light_white, :light_yellow, :magenta, :red, :white, :yellow]. Defaults to the terminal default.

examples

 Examples 

iex> Prompt.table([["Hello", "from", "the", "terminal!"],["this", "is", "another", "row"]])
"
 +-------+------+---------+----------+
 | Hello | from | the     | terminal |
 | this  | is   | another | row      |
 +-------+------+---------+----------+
"

iex> Prompt.table([["One", "Two", "Three", "Four"], ["Hello", "from", "the", "terminal!"],["this", "is", "another", "row"]], header: true)
"
 +-------+------+---------+----------+
 | One   | Two  | Three   | Four     |
 +-------+------+---------+----------+
 | Hello | from | the     | terminal |
 | this  | is   | another | row      |
 +-------+------+---------+----------+
"

iex> Prompt.table([["One", "Two", "Three", "Four"], ["Hello", "from", "the", "terminal!"],["this", "is", "another", "row"]], header: true, border: :markdown)
"
 | One   | Two  | Three   | Four     |
 |-------|------|---------|----------|
 | Hello | from | the     | terminal |
 | this  | is   | another | row      |
"

iex> Prompt.table([["Hello", "from", "the", "terminal!"],["this", "is", "another", "row"]], border: :none)
"
 Hello from the     terminal
 this  is   another row
"

Link to this section Functions

Link to this function

table_data(matrix, opts \\ [border: :normal])

View Source 
@spec table_data([list()], keyword()) :: [<<_::0>> | [any()], ...]

Use this to get an iolist back of the table. Useful when you want an ascii table/1 for other mediums like markdown files.