HelpfulOptions.Switches (helpful_options v0.2.0)

Summary

Functions

Returns the help block related to switches

Switches that have not been specified are returned as an error

Types

@type switch() :: %{
  type: switch_type(),
  short: String.t() | atom(),
  description: String.t(),
  required: boolean(),
  default: term()
}
Link to this type

switch_type()

@type switch_type() ::
  :boolean
  | :count
  | :float
  | :floats
  | :integer
  | :integers
  | :string
  | :strings
@type t() :: [{atom(), switch()}] | :any | nil

Functions

@spec help(t()) :: String.t()

Returns the help block related to switches

iex> HelpfulOptions.Switches.help(foo: %{type: :string}, bar: %{type: :integer})
{
  :ok,
  "-h, --help                     Show a help message\n" <>
  "-q, --quiet                    Suppress output\n" <>
  "-v, --verbose                  Increase verbosity\n" <>
  "  --foo=FOO                    Optional parameter\n" <>
  "  --bar=BAR                    Optional parameter"
}

Returns a generic test when :any is used:

iex> HelpfulOptions.Switches.help(:any)
{:ok, "Accepts any switch-type arguments"}

By default, it returns an empty string:

iex> HelpfulOptions.Switches.help(nil)
{
  :ok,
  "-h, --help                     Show a help message\n" <>
  "-q, --quiet                    Suppress output\n" <>
  "-v, --verbose                  Increase verbosity"
}
Link to this function

parse(args, switches \\ nil)

@spec parse([String.t()], Keyword.t() | :any | nil) ::
  {:ok, map(), [String.t()]} | {:error, HelpfulOptions.SwitchErrors.t()}

Switches that have not been specified are returned as an error:

iex> HelpfulOptions.Switches.parse(["--bar", "hi"], foo: %{type: :string})
{:error, %HelpfulOptions.SwitchErrors{unknown: ["--bar"]}}

Switch parameters of the wrong type are returned as an error:

iex> HelpfulOptions.Switches.parse(["--bar", "hi"], bar: %{type: :float})
{:error, %HelpfulOptions.SwitchErrors{incorrect: [{"--bar", "hi"}]}}

Invalid switch types are returned as an error:

iex> HelpfulOptions.Switches.parse(["--bar", "hi"], bar: %{type: :invalid})
{:error, %HelpfulOptions.SwitchErrors{invalid: [bar: {:invalid_type, :invalid}]}}

:default and :required are incompatible

iex> HelpfulOptions.Switches.parse([], [foo: %{type: :string, required: true, default: "ok"}])
{:error, %HelpfulOptions.SwitchErrors{invalid: [foo: :required_and_default]}}

Default switches

--help, --quiet and --verbose are handled automatically.

--help can be supplied without any configuration:

iex> HelpfulOptions.Switches.parse(["--help"], nil)
{:ok, %{help: true}, []}

--quiet and --verbose have the side-effect of setting the Logger level. By default, it is set to :info, --verbose sets it to :debug, while :quiet sets it to :none.

iex> HelpfulOptions.Switches.parse(["--quiet"], nil)
{:ok, %{quiet: true}, []}