# `CliMate.CLI.Argument`
[🔗](https://github.com/lud/cli_mate/blob/v0.10.2/lib/cli_mate/cli/argument.ex#L1)

Describes an argument.

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

* `:required` - A boolean. Arguments are required by default.
* `:type` - `:string`, `:integer` or `:float`. Defaults to `:string`.
* `:doc` - A string to document what the argument is for. This is not used at
  the moment but future releases will exploit it.
* `:cast` - A fun accepting the value, or a `{module, function, arguments}`,
  returning a result tuple.  See the "Casting" section below for more
  information.
* `:repeat` - A boolean, defines a variadic argument that accepts several
  values. This can only be enabled on the last argument.

### Casting

When the `:cast` option is a fun, it will be called with the deserialized
value. When it is an "MFA" tuple, the deserialized value will be prepended to
the given arguments.

#### Cast functions input

What is a deserialized value though? By default it will be the raw string
passed in the shell as command line arguments. But if the `:type` option is
also defined to `:integer` or `:float`, your cast function will be called with
the corresponding type. If that type deserialization fails, the cast function
will not be called.

#### Repeated arguments

When the `:repeat` option is enabled, the cast function is called on each
value individually, not on the entire list.

#### Returning errors

Cast functions must return `{:ok, value}` or `{:error, reason}`. The `reason`
can be anything, but at the moment CliMate doesn't do any special formatting
on it to display errors (besides calling `to_string/1` with a safe fallback to
`inspect/1`). It is advised to return a meaningful error message as the
reason.

#### Compilation commands

When commands are declared as a module attribute, you cannot use local
functions definitions or the compilation will fail with "undefined function
...". You need to use a remote form by prefixing by `__MODULE__`, or use an
MFA tuple.

    defmodule MyCommand do
      use Mix.Task

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

# `caster`

```elixir
@type caster() ::
  (term() -> {:ok, term()} | {:error, term()}) | {module(), atom(), [term()]}
```

# `t`

```elixir
@type t() :: %CliMate.CLI.Argument{
  cast: nil | caster(),
  doc: binary() | nil,
  key: atom(),
  repeat: term(),
  required: boolean(),
  type: vtype()
}
```

# `vtype`

```elixir
@type vtype() :: :integer | :float | :string
```

# `new`

# `validate_cast!`

Validates that the given cast value is a valid caster.

A valid caster is either `nil`, a function of arity 1, or an MFA tuple
`{module, function, args}` where args is a list.

Raises `ArgumentError` if the cast is invalid.

---

*Consult [api-reference.md](api-reference.md) for complete listing*