The schema for command line options.

Schema Options

The following are the options supported in a schema. They are used for validating passed command line arguments:

• :type - The type of the argument. Can be one of :string, :boolean, :integer, :float, :counter, :atom. If not set defaults to :string.

  iex> schema = [
  ...>   name: [type: :string],
  ...>   retries: [type: :integer],
  ...>   interval: [type: :float],
  ...>   debug: [type: :boolean],
  ...>   verbose: [type: :counter],
  ...>   mode: [type: :atom]
  ...> ]
  ...> 
  ...> CliOptions.parse!(
  ...>   ["--name", "foo", "--retries", "3", "--interval", "2.5", "--debug"],
  ...>   schema
  ...> )
  {[name: "foo", retries: 3, interval: 2.5, debug: true, verbose: 0], [], []}
  
  iex> CliOptions.parse!(
  ...>   ["--verbose", "--verbose", "--mode", "parallel"],
  ...>   schema
  ...> )
  {[debug: false, verbose: 2, mode: :parallel], [], []}

  The default value is :string.

• :default (term/0) - The default value for the CLI option if that option is not provided in the CLI arguments. This is validated according to the given :type.

  iex> schema = [user_name: [default: "John"]]
  ...> 
  ...> # with no option provided
  ...> CliOptions.parse!([], schema)
  {[user_name: "John"], [], []}
  
  iex> # provided CLI options override the default value
  ...> CliOptions.parse!(["--user-name", "Jack"], schema)
  {[user_name: "Jack"], [], []}

• :long (String.t/0) - The long name for the option, it is expected to be provided as --{long_name}. If not set defaults to the option name itself, casted to string with underscores replaced by dashes.

  iex> schema = [
  ...>   # long not set, it is set to --user-name
  ...>   user_name: [type: :string],
  ...>   # you can explicitly set a long name with underscores if needed
  ...>   another_user_name: [type: :string, long: "another_user_name"]
  ...> ]
  ...> 
  ...> CliOptions.parse!(["--user-name", "John", "--another_user_name", "Jack"], schema)
  {[user_name: "John", another_user_name: "Jack"], [], []}

• :short (String.t/0) - An optional short name for the option. It is expected to be a single letter string.

  iex> schema = [user_name: [short: "U"]]
  ...> 
  ...> CliOptions.parse!(["-U", "John"], schema)
  {[user_name: "John"], [], []}

• :aliases (list of String.t/0) - Long aliases for the option. It is expected to be a list of strings.

  iex> schema = [user_name: [aliases: ["user_name"]]]
  ...> 
  ...> # with the default long name
  ...> CliOptions.parse!(["--user-name", "John"], schema)
  {[user_name: "John"], [], []}
  
  iex> # with an alias
  ...> CliOptions.parse!(["--user_name", "John"], schema)
  {[user_name: "John"], [], []}

  The default value is [].

• :short_aliases (list of String.t/0) - Similar to :aliases, but for short names. The default value is [].

• :doc (String.t/0 or false) - The documentation for the CLI option. Can be any markdown string. This will be used in the automatically generated options documentation. If set to false then the option will not be included in the generated docs.

• :doc_section (atom/0) - The section in the documentation this option will be put under. If not set the option is added to the default unnamed section. If set you must also provide the :sections option in the CliOptions.docs/2 call.

• :required (boolean/0) - Defines if the option is required or not. An exception will be raised if a required option is not provided in the CLI arguments. The default value is false.

• :multiple (boolean/0) - If set to true an option can be provided multiple times.

  iex> schema = [project: [multiple: true]]
  ...> 
  ...> CliOptions.parse!(["--project", "foo", "--project", "bar"], schema)
  {[project: ["foo", "bar"]], [], []}

  The default value is false.

• :separator (String.t/0) - An optional separator for passing multiple values with the same cli argument. Applicable only if multiple is set to true.

  iex> schema = [project: [multiple: true, separator: ";"]]
  ...> 
  ...> # passing the projects multiple times
  ...> CliOptions.parse!(["--project", "foo", "--project", "bar"], schema)
  {[project: ["foo", "bar"]], [], []}
  
  iex> # using a separator
  ...> CliOptions.parse!(["--project", "foo;bar"], schema)
  {[project: ["foo", "bar"]], [], []}
  
  iex> # using a separator and passing the argument multiple times
  ...> CliOptions.parse!(["--project", "foo;bar", "--project", "baz;fan"], schema)
  {[project: ["foo", "bar", "baz", "fan"]], [], []}

• :allowed (list of String.t/0) - A set of allowed values for the option. If any other value is given an exception will be raised during parsing.

• :deprecated (String.t/0) - Defines a message to indicate that the option is deprecated. The message will be displayed as a warning when passing the item.

• :env (String.t/0) - An environment variable to get this option from, if it is missing from the command line arguments. If the option is provided by the user the environment variable is ignored.

  For boolean options, the flag is considered set if the environment variable has a truthy value (1, true) and ignored in any other case.