CliMate.CLI (CLI Mate v0.8.1)
View SourceMain API to interact with the command line.
Basic usage
import CliMate.CLI
def run(argv) do
command = [options: [verbose: [type: :boolean]], arguments: [n: [type: :integer]]]
%{options: opts, arguments: args} = parse_or_halt!(argv, command)
if opts.verbose do
writeln("Hello!")
end
case do_something_useful(args.n) do
:ok -> halt_success("Done!")
{:error, reason} -> halt_error(reason)
end
end
Summary
Functions
Wraps the given iodata
with the given color
.
Outputs iodata
in the current shell, formatted with cyan color.
Outputs iodata
to stderr
in the current shell, formatted with bright
red color.
Delegates all CliMate.CLI
functions from the calling module.
Returns a standard "usage" documentation block describing the different options of the given command.
Stops the execution of the Erlang runtime, with a given return code.
Accepts the command line arguments and the definition of a command (options, arguments, and metadata) and returns a parse result with flues extracted from the command line arguments.
Attempts to parse the command line arguments argv
with the defined
command.
Defines the current shell to send console messages to. Accepts either
CliMate.CLI
or CliMate.CLI.ProcessShell
.
Returns a string representation of the given term, with fallback to
Kernel.inspect/1
.
Returns the current shell to send output to.
Outputs iodata
in the current shell, formatted with green color.
Outputs iodata
to stderr
in the current shell, formatted with yellow
color.
Outputs iodata
in the current shell.
Outputs iodata
in the current shell.
Functions
Wraps the given iodata
with the given color
.
color
should be a IO.ANSI.format/2
compatible atom.
Outputs iodata
in the current shell, formatted with cyan color.
Outputs iodata
to stderr
in the current shell, formatted with bright
red color.
Delegates all CliMate.CLI
functions from the calling module.
This is useful if you want to define a module where all your CLI helpers
reside, instead of calling, say, writeln("hello")
from
CliMate.CLI
but fancy_subtitle("Hello!")
from
MyApp.CliHelpers
.
Returns a standard "usage" documentation block describing the different options of the given command.
Options
:format
- If:moduledoc
, the formatted usage will be compatible for embedding in a@moduledoc
attribute. Any other value will generate a simple terminal styled text. Defaults to:cli
.:io_columns
- Number of columns for the terminal, defaults to a call to:io.columns/0
. Only used when format is:cli
.
Stops the execution of the Erlang runtime, with a given return code.
If not provided, the return code will be 0
.
Combines error/1
then halt/1
. Halts the Erlang runtime with a 1
return code by default.
Combines success/1
then halt/1
. Halts the Erlang runtime with a 0
return code.
Accepts the command line arguments and the definition of a command (options, arguments, and metadata) and returns a parse result with flues extracted from the command line arguments.
Defining options
Options definitions is a Keyword
whose keys are the option name, and values
are the options parameters. Keys with underscores like some_thing
define
options in kebab case like --some-thing
.
The available settings for an option are described in the
CliMate.CLI.Option
module.
The :help
option is always defined and cannot be overridden.
Options examples
iex> {:ok, result} = parse(~w(--who joe), [options: [who: [type: :string]]])
iex> result.options.who
"joe"
iex> {:ok, result} = parse(~w(--who joe), [options: [who: []]])
iex> result.options.who
"joe"
iex> {:ok, result} = parse(~w(--port 4000), [options: [port: [type: :integer]]])
iex> result.options.port
4000
iex> {:ok, result} = parse(~w(-p 4000), [options: [port: [type: :integer, short: :p]]])
iex> result.options.port
4000
iex> parse(~w(--port nope), [options: [port: [type: :integer]]])
{:error, {:invalid, [{"--port", "nope"}]}}
iex> {:ok, result} = parse([], [options: [lang: [default: "elixir"]]])
iex> result.options.lang
"elixir"
iex> {:ok, result} = parse([], [options: [lang: []]])
iex> Map.has_key?(result.options, :lang)
false
iex> {:ok, result} = parse([], options: [])
iex> result.options.help
false
iex> {:ok, result} = parse(~w(--help), options: [])
iex> result.options.help
true
Defining arguments
Arguments can be defined in the same way as options, providing a Keyword
where the keys are the argument names and the values are the parameters.
The available settings for an argument are described in the
CliMate.CLI.Argument
module.
Arguments examples
iex> {:ok, result} = parse(~w(joe), arguments: [who: []])
iex> result.arguments.who
"joe"
iex> parse([], arguments: [who: []])
{:error, {:missing_argument, :who}}
iex> {:ok, result} = parse([], arguments: [who: [required: false]])
iex> result.arguments
%{}
iex> cast = fn string -> Date.from_iso8601(string) end
iex> {:ok, result} = parse(["2022-12-22"], arguments: [date: [cast: cast]])
iex> result.arguments.date
~D[2022-12-22]
iex> cast = {Date, :from_iso8601, []}
iex> {:ok, result} = parse(["2022-12-22"], arguments: [date: [cast: cast]])
iex> result.arguments.date
~D[2022-12-22]
iex> cast = {Date, :from_iso8601, []}
iex> parse(["not-a-date"], arguments: [date: [cast: cast]])
{:error, {:argument_cast, :date, :invalid_format}}
Attempts to parse the command line arguments argv
with the defined
command.
Command options and arguments are documented in the parse/2
function of
this module.
In parse_or_halt!/2
, the successful return value will not be wrapped in
an :ok
tuple, but directly a map with the :options
and :arguments
keys.
In case of a parse error, this function will output the usage block followed by a formatted error message, and halt the Erlang runtime.
Defines the current shell to send console messages to. Accepts either
CliMate.CLI
or CliMate.CLI.ProcessShell
.
This is mostly done for testing. The default shell outputs to standard io as you would expect.
The shell is saved to :persistent_term
, so shell should not be changed
repeatedly during runtime. This method of persistence is subject to change and
should not be relied on.
Returns a string representation of the given term, with fallback to
Kernel.inspect/1
.
Returns the current shell to send output to.
Outputs iodata
in the current shell, formatted with green color.
Outputs iodata
to stderr
in the current shell, formatted with yellow
color.
Outputs iodata
in the current shell.
Outputs iodata
in the current shell.