CliMate.Argument (CLI Mate v0.7.1)
View SourceDescribes 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.
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.
Returning errors
Cast functions must return {:ok, value}
or {:error, reason}
. The reason
can be anything, but at the moment CliMate does no spcial formatting on it to
display errors (besides calling to_string/1
with a safe fallback to
inspect/1
). It is advised to return a meaninful 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