commando v0.1.0 Commando

Command line parser with default values, useful help messages, and other features.

Uses OptionParser for parsing, and extends it with:

  • Simple and informative help messages
  • Default values for switches
  • Ability to specify required switches
  • Descriptive error messages

Link to this section Summary

Functions

Creates a new Commando instance

Returns a help message for the Commando instance, to be displayed with e.g. IO.puts

Parse command line arguments

Add a standardized help-message switch (—help, -h) to the Commando instance

Link to this section Types

Link to this type conf()
conf ::
  {:required, boolean} |
  {:alias, atom} |
  {:default, any}
Link to this type conf_list()
conf_list() :: [conf]
Link to this type parse_result()
parse_result() :: [{atom, any}]
Link to this type switch_type()
switch_type() :: :boolean | :count | :integer | :float | :string

Link to this section Functions

Link to this function create(name, description \\ "", example \\ "")

Creates a new Commando instance.

Examples

iex> Commando.create("app").app_name
"app"

iex> Commando.create("app", "Doc test app").app_description
"Doc test app"

iex> Commando.create("app", "Doc test app", "mix run").example
"mix run"
Link to this function help_message(commando)
help_message(Commando.State.t) :: String.t

Returns a help message for the Commando instance, to be displayed with e.g. IO.puts.

Below is an example help message:

demo - Short demo app

Arguments:
  --path, -p : (Required) Some path (Default: "path")
  --help : Print help message

Example: mix run

Examples

iex> Commando.create("demo", "Short demo app", "mix run") |>
...>  Commando.with_help() |>
...>  Commando.with_switch(:path, :string, "Some path", required: true, alias: :p, default: "path") |>
...>  Commando.help_message()
"demo - Short demo app\n\nArguments:\n  --path, -p : (Required) Some path (Default: \"path\")\n  --help, -h : Print help message\n\nExample: mix run"
Link to this function parse(commando, args)
parse(Commando.State.t, [String.t]) ::
  {:ok, parse_result} |
  :help |
  {:error, String.t}

Parse command line arguments.

Returns one of:

  • {:help, message} - If you added the help swith using Commando.with_help/1 and --help or -h switches were present. message contains the formatted help message to show.
  • {:ok, result} - If command line args were parsed successfully and all required arguments were present. result is a keyword list mapping switches to their parsed values.
  • {:error, reason} - If invalid flags were supplied, or a required argument was missing.

Examples

iex> Commando.create("app") |> Commando.with_switch(:path, :string, "Path") |> Commando.parse(["--path", "abc"])
{:ok, [path: "abc"]}

iex> import Commando
iex> create("app") |> with_switch(:path, :string, "Path", alias: :p) |> parse(["-p", "abc"])
{:ok, [path: "abc"]}

iex> import Commando
iex> create("app") |> parse(["--path", "abc"])
{:error, "Unknown options: --path"}

iex> import Commando
iex> create("app") |> with_switch(:foo, :boolean, "") |> parse(["--foo"])
{:ok, [foo: true]}

iex> import Commando
iex> create("app") |> with_switch(:foo, :count, "", alias: :f) |> parse(["--foo", "-f", "-f"])
{:ok, [foo: 3]}

iex> import Commando
iex> create("app") |> with_switch(:foo, :integer, "") |> parse(["--foo", "12"])
{:ok, [foo: 12]}

iex> import Commando
iex> create("app") |> with_switch(:foo, :integer, "") |> parse(["--foo", "bar"])
{:error, "Unknown options: --foo"}

Add a standardized help-message switch (—help, -h) to the Commando instance.

Usage

The application should check the result of Commando.parse/2 to verify if this switch is true. If so, it should show the Commando.help_message/1 and exit.

Link to this function with_switch(commando, switch, type, description, conf \\ [])

Add a switch to a Commando instance.

Returns a new Commando instance containing the switch.

Description

The description will be shown for the switch in the help message generated by Commando.help_message/1.

Switch Types

The available switch types are :boolean, :count, :integer, :float, :string.

The following switches types take no arguments:

  • :boolean - sets the value to true when given (see also the “Negation switches” section below)
  • :count - counts the number of times the switch is given

The following switches take one argument:

  • :integer - parses the value as an integer
  • :float - parses the value as a float
  • :string - parses the value as a string

For more information on available switch types, see https://hexdocs.pm/elixir/OptionParser.html#parse/2

Configuration

conf is a list of configuration keywords. The following condfigurations are available:

  • default: any - If switch is not specified, it will recieve this default value.
  • alias: atom - An alias for this switch. e.g. for :data you might pass alias: :d, you can then on the command line use --data or -d.
  • required: boolean - If true, Commando.parse/2 will return an error if this switch is not present in args.

Examples

iex> Commando.create("test_app", "Test app", "mix run") |>
...>   Commando.with_switch(:path, :string, "Path", required: true, alias: :p, default: "path/")
%Commando.State{aliases: [p: :path], app_description: "Test app",
 app_name: "test_app", defaults: [path: "path/"],
 descriptions: [path: "Path"], example: "mix run", required: [:path],
 switches: [path: :string]}