ex_cli v0.1.6 ExCLI.DSL View Source

A DSL to easily write CLI applications.

This module should be used in a CLI specific module, and the macros should be used to define an application.

Options

escript - If set to true, it will generate a main function so that the module can be set as the main_module of an escript
mix_task - If specified, a mix task with the given name will be generated.

Example

defmodule SampleCLI do
  use ExCLI.DSL, escript: true, mix_task: :sample

  name "mycli"
  description "My CLI"
  long_description """
  This is my long description
  """

  option :verbose,
    help: "Increase the verbosity level",
    aliases: [:v],
    count: true

  command :hello do
    aliases [:hi]
    description "Greets the user"
    long_description """
    Gives a nice a warm greeting to whoever would listen
    """

    argument :name
    option :from, help: "the sender of hello"

    run context do
      if context.verbose >= 1 do
        IO.puts("I am going to emit a greeting.")
      end
      if from = context[:from] do
        IO.write("#{from} says: ")
      end
      IO.puts("Hello #{context.name}!")
     end
  end
end

Link to this section Summary

Functions

aliases(names)

Adds aliases to the command

argument(name, options \\ [])

Adds an argument to the command

command(name, list)

Defines a command for the application

default_command(name)

Set the default_command of the application

description(value)

Set the description of the application or the command

long_description(value)

Set the long_description of the application or the command

name(name)

Set the name of the application

option(name, options \\ [])

Adds an option to the command or the application or the command

run(arg, list)

Defines the block to run when executing the command

Link to this section Functions

aliases(names) (macro)

aliases([atom()]) :: any()

Adds aliases to the command.

Aliases can be used in place of the command’s name on the command line.

argument(name, options \\ []) (macro)

argument(atom(), Keyword.t()) :: any()

Adds an argument to the command.

The first argument should be an atom representing the name of the argument, which will be used to store the value in the generated application context.

Options

type - The type of the argument. Can be one of the following
- :integer - Will be parsed as an integer
- :float - Will be parsed as a float
- :boolean - Will be parsed as a boolean (should be "yes" or "no")
:list - When true, the argument will accept multiple values and should be the last argument of the command
:default - The default value for the option
:as - The key of the option in the context
:metavar - The name of the option argument displayed in the help

command(name, list) (macro)

command(atom(), Keyword.t()) :: any()

Defines a command for the application

The first argument should be an atom with the name of the command.

default_command(name) (macro)

default_command(atom()) :: any()

Set the default_command of the application

description(value) (macro)

description(String.t()) :: any()

Set the description of the application or the command

long_description(value) (macro)

long_description(String.t()) :: any()

Set the long_description of the application or the command

name(name) (macro)

name(String.t() | atom()) :: any()

Set the name of the application

option(name, options \\ []) (macro)

option(atom(), Keyword.t()) :: any()

Adds an option to the command or the application or the command.

The first argument should be an atom representing the name of the argument, which will be used to store the value in the generated application context.

Options

Accepts the same options as argument except for :list and :default, as well as:

:required - The command will fail if this option is not passed
:aliases - A list of aliases (atoms) for the option
:accumulate - Will accumulate the options in a list
:type - The type of the argument. See argument/2 type documentation for available types.

When the type option is :boolean, it will not consume the next argument except if it is yes or no. It will also accept --no-OPTION to negate the option.
:default - The default value for the argument
:as - The key of the argument in the context
:process - A function to process the option, or an alias to an existing function.

The following aliases are available
- {:const, value} - Will store the value in the context
When :process is a function, it must have the following signature
```
process(arg :: ExCLI.Argument.t, context :: map, args :: [String.t]) :: {:ok, map, [String.t]} | {:error, atom, Keyword.t}
```
where arg is the current argument (or option), context is a map with all the current parsed values and args are the current parsed arguments.

The function should return either {:ok, context, args} with context and args updated on success, or {:error, reason, details} on failure.

run(arg, list) (macro)

run(any(), Keyword.t()) :: any()

Defines the block to run when executing the command.

The first argument is the context: a map containing the parsed argument, which will be accessible within the block. The map will have all the argument and option keys with the parsed values. It will not contain options without default if they were not given.

See this module example for a sample usage.