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) - The documentation for the CLI option. Can be any markdown string. This will be used in the automatically generate options documentation.

• :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.

• :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.