Describes an option.

When declaring a command, the :options entry is a keyword list that accepts these settings, all optional:

• :type - CliMate uses the OptionParser module under the hood, so the following types are accepted:

  • :boolean - If the default value is true, OptionParser supports the --no- prefix to the options.
  • :count - Counts the number of times the flag is given.
  • :integer - Value is parsed or an error is returned.
  • :float - Same as :integer.
  • :string - Value is used as-is.

• :doc - A string describing the role of the option. It is displayed in the usage block shown with --help or mix help.

• :short - A single letter atom like :a, :b, etc. For instance with these options:

  @command options: [
    name: [short: :n]
  ]

• :default - The default value to set if the option is not given. See the "Default values" section below.

  The command line will accept both --name and -n switches.

• :keep - A boolean. This flag is used with OptionParser. When true duplicate options will not override each other but will rather be accumulated in a list. The option value will always be a list even when provided a single time in the command line arguments. The option will also be present, as an empty list, if the option is not given in command line arguments.

• :doc_arg - A string to display in the usage block. Defaults the type of the option, as in:

  Options
  
    -n --some-int <integer>  This option does not define :doc_arg.
    -o --other-int <other>   Here "other" was provided as :doc_arg.

• :default_doc - The string to output when CliMate does not know how to display the default value. That is, when the default value is defined by a function. Not used when :default is not defined.

Default values

Default values can be omitted, in that case, the option will not be present at all when CliMate.CLI.parse/2 will be called. This is especially important for booleans, where one would expect that they automatically default to false. It is not the case.

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_for_some_opt/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"

Note that when the command is defined in a module attribute, you need to pass the module prefix or the compilation will fail:

defmodule MyCommand do
  use Mix.Task

  @command name: "my command",
           options: [
             some_arg: [
               default: &__MODULE__.cast_some/1
             ]
           ]
end