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

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.

@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.

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.

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

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.

Executes the given fun while keeping the paths for the given app or apps code in the current code path.

This is useful when running mix tasks that change the code path, for command line applications installed globally with mix archive.insall.

It is not needed for regular mix tasks or escripts.

Outputs iodata in the current shell.

Outputs iodata in the current shell.