View Source AoC.CLI (aoc v0.7.0)

Summary

Functions

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

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.

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

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.

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

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

Returns the current shell used by AoC.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.

Functions

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.

Link to this function

format_usage(command, opts \\ [])

View Source

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.

Link to this function

halt_error(err_code \\ 1, iodata)

View Source

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.

Link to this macro

is_valid_day(day)

View Source (macro)
Link to this macro

is_valid_day(year, day)

View Source (macro)
Link to this macro

is_valid_part(part)

View Source (macro)
Link to this macro

is_valid_year(year)

View Source (macro)

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. Keys for without default values that are not provided in argv will not be defined in the results.
  • :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.

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}}
Link to this function

parse_or_halt!(argv, command)

View Source

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 AoC.CLI or AoC.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 AoC.CLI to send output.

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

Link to this function

validate_options!(options)

View Source

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

Link to this function

write_defaults(defaults)

View Source

Outputs iodata in the current shell.

Link to this function

year_day_command(module, opts \\ [])

View Source