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.

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

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

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.

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 values 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 following parameters are available:

• :type - Can be either :boolean, :integer or :string. The default value is :string.
• :short - Defines the shortcut for the option, for instance -p instead of --port.
• :default - Defines the default value if the corresponding option is not defined in argv.See "Default values" below.
• :doc - Accepts a string that will be used when formatting the usage block for the command.

Note that the :help option is always defined and cannot be overridden.

Default values

Default values can be omitted, in that case, the option will not be present at all if not provided in the command line.

When defined, a default value can be:

• A raw value, that is anything that is not a function. This value will be used as the default value.

• A function of arity zero. This function will be called when the option is not provided in the command line and the result value will be used as the default value. For instance fn -> 123 end or &default_age/0.

• A function of arity one. This function will be called with the option key as its argument. For instance, passing &default_opt/1 as the :default for an option definition allow to define the following function:

  defp default_opt(:port), do: 4000
  defp default_opt(:scheme), do: "http"

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, providing a Keyword where the keys are the argument names and the values are the parameters.

Defining arguments

The following parameters are available:

• :required - A boolean marking the argument as required. Note that arguments are required by default. Keys for optional arguments that are not provided by the command line will not be defined in the results.
• :cast - Accepts a fun or a {module, function, arguments} tuple to transform the argument value when parsing. The invoked function must return a result tuple: {:ok, _} | {:error, _}.
• :doc - Accepts a string that will be used when formatting the usage block for the command. Note that this is not currently implemented for arguments.

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 Modkit.CLI or Modkit.CLI.ProcessShell.

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 the current shell used by Modkit.CLI to send output.

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.