ex_cli v0.1.1 ExCLI.DSL

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
    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

Summary

Macros

Adds an argument to the command

Defines a command for the application

Set the description of the application or the command

Set the long_description of the application or the command

Set the name of the application

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

Defines the block to run when executing the command

Macros

argument(name, options \\ [])

Specs

argument(term, 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)

Specs

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

Defines a command for the application

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

description(value)

Specs

description(term, String.t) :: any

Set the description of the application or the command

long_description(value)

Specs

long_description(term, String.t) :: any

Set the long_description of the application or the command

name(name)

Specs

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

Set the name of the application

option(name, options \\ [])

Specs

option(term, 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)

Specs

run(term, 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.