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
Add a switch to a Commando instance
Link to this section Types
Link to this section Functions
create(String.t, String.t, String.t) :: Commando.State.t
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"
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"
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 usingCommando.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.
with_switch(Commando.State.t, atom, Commando.State.switch_type, String.t, conf_list) :: Commando.State.t
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 totrue
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 passalias: :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 inargs
.
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]}