CliMate.CLI (CLI Mate v0.7.1)

Main 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

Parsing

parse(argv, command)

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.

parse_or_halt!(argv, command)

Attempts to parse the command line arguments argv with the defined command.

Shell & IO

color(iodata, color)

Outputs iodata in the current shell, wrapped with formatting information, such as [color, iodata, :default_color].

debug(iodata)

Outputs iodata in the current shell, formatted with cyan color.

error(iodata)

Outputs iodata to stderr in the current shell, formatted with bright red color.

halt(err_code \\ 0)

Stops the execution of the Erlang runtime, with a given return code.

halt_error(err_code \\ 1, iodata)

Combines error/1 then halt/1. Halts the Erlang runtime with a 1 return code by default.

halt_success(iodata)

Combines success/1 then halt/1. Halts the Erlang runtime with a 0 return code.

put_shell(module)

Defines the current shell to send console messages to. Accepts either CliMate.CLI or CliMate.CLI.ProcessShell.

shell()

Returns the current shell to send output to.

success(iodata)

Outputs iodata in the current shell, formatted with green color.

warn(iodata)

Outputs iodata to stderr in the current shell, formatted with yellow color.

writeln(iodata)

Outputs iodata in the current shell.

Functions

format_usage(command, opts \\ [])

Returns a standard "usage" documentation block describing the different options of the given command.

safe_to_string(term)

Returns a string representation of the given term, with fallback to Kernel.inspect/1.

Parsing

parse(argv, command)

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. Note that 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.Option module.

Note that 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.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}}

parse_or_halt!(argv, command)

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.

Shell & IO

color(iodata, color)

@spec color(iodata(), atom()) :: [atom() | [iodata() | [:default_color | []]]]

Outputs iodata in the current shell, wrapped with formatting information, such as [color, iodata, :default_color].

color should be a IO.ANSI.format/2 compatible atom.

debug(iodata)

Outputs iodata in the current shell, formatted with cyan color.

error(iodata)

Outputs iodata to stderr in the current shell, formatted with bright red color.

halt(err_code \\ 0)

Stops the execution of the Erlang runtime, with a given return code.

If not provided, the return code will be 0.

halt_error(err_code \\ 1, iodata)

@spec halt_error(err_code :: integer(), term()) :: no_return()

Combines error/1 then halt/1. Halts the Erlang runtime with a 1 return code by default.

halt_success(iodata)

Combines success/1 then halt/1. Halts the Erlang runtime with a 0 return code.

put_shell(module)

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.

shell()

Returns the current shell to send output to.

success(iodata)

Outputs iodata in the current shell, formatted with green color.

warn(iodata)

Outputs iodata to stderr in the current shell, formatted with yellow color.

writeln(iodata)

Outputs iodata in the current shell.

Functions

format_usage(command, opts \\ [])

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.

safe_to_string(term)

@spec safe_to_string(term()) :: binary()

Returns a string representation of the given term, with fallback to Kernel.inspect/1.