Artificery behaviour (artificery v0.4.3)

This module defines the behaviour and public API for Artificery command line applications.

Usage

To get started, simply use this module, and you can start defining your CLI right away:

use Artificery

command :hello, "Say hello" do
  option :name, :string, "The name of the person to greet"
end

...

def hello(_argv, %{name: name}) do
  Console.success "Hello #{name}!"
end

This module exports a few macros for building up complex CLI applications, so please review the documentation for more information on each, and how to use them.

Link to this section Summary

Functions

Like option, but rather than a command switch, it defines a positional argument.

Like argument/2, but takes either help text or a keyword list of flags.

Like argument/3, but takes a name, type, help text and keyword list of flags.

Defines a new command with the given name and either help text or flags.

Defines a new command with the given name, flags or help text, and definition, or flags, help text, and no definition.

Defines a new command with the given name, flags, help text, and definition.

Defines an option which can be imported into one or more commands.

Like defoption/3, but takes the option name, type, help, and flags.

Imports an option defined via defoption into the current scope.

When used in the following form

Similar to defoption, but defines an option inline.

Link to this section Types

Specs

argv() :: [String.t()]

Specs

options() :: %{required(atom()) => term()}

Link to this section Functions

Link to this macro

argument(name, type)

(macro)

Like option, but rather than a command switch, it defines a positional argument.

Beyond the semantics of switches vs positional args, this takes the same configuration as option or defoption.

Examples

argument :name, :string
Link to this macro

argument(name, type, help)

(macro)

Like argument/2, but takes either help text or a keyword list of flags.

Examples

argument :name, :string, "The name to use"

argument :name, :string, required: true
Link to this macro

argument(name, type, help, flags)

(macro)

Like argument/3, but takes a name, type, help text and keyword list of flags.

Examples

argument :name, :string, "The name to use", required: true
Link to this macro

command(name, help)

(macro)

Defines a new command with the given name and either help text or flags.

Examples

command :info, "Displays info about stuff"

command :info, hidden: true
Link to this macro

command(name, help, help)

(macro)

Defines a new command with the given name, flags or help text, and definition, or flags, help text, and no definition.

Examples

command :info, "Displays info about stuff" do
  ...
end

command :info, [hidden: true] do
  ...
end

command :info, [hidden: true], "Displays info about stuff" do
  ...
end
Link to this macro

command(name, flags, help, list)

(macro)

Defines a new command with the given name, flags, help text, and definition.

Examples

command :admin, hidden: true, "Does admin stuff" do
  ...
end
Link to this macro

defoption(name, type, flags)

(macro)

Defines an option which can be imported into one or more commands.

This is an abstract option definition, i.e. it doesn't define an option in any scope, it defines options for reuse.

This macro takes the option name, type, and either help text or options.

Valid types are the same as those defined in OptionParser.

Examples

defoption :verbose, :boolean, "Turns on verbose output"

defoption :verbose, :boolean, hidden: true
Link to this macro

defoption(name, type, help, flags)

(macro)

Like defoption/3, but takes the option name, type, help, and flags.

Examples

defoption :verbose, :boolean, "Turns on verbose output", hidden: true
Link to this macro

option(name)

(macro)

Imports an option defined via defoption into the current scope.

You may optionally override flags for a given option by passing a keyword list as a second argument.

You are not allowed to override the type of the option, but you may override the help text, by passing help: "..." as an override. If you need to override the type, it is better if you use option/3 or option/4

Examples

defoption :name, :string, "Name of person"

command :hello, "Says hello" do
  # Import with no overrides
  option :name

  # Import with overrides
  option :name, required: true, alias: :n

  # Import and customize help text
  option :name, help: "Name of the person to greet"
end
Link to this macro

option(name, overrides)

(macro)

When used in the following form:

option :foo, :string

This defines a new option, foo, of type string, with no help or flags defined.

When used like this:

option :foo, required: true

It imports an option definition (as created via defoption) and provides overrides for the original definition.

Link to this macro

option(name, type, flags)

(macro)

Similar to defoption, but defines an option inline.

Options defined this way apply either to the global scope, if they aren't nested within a command macro, or to the scope of the command they are defined in.

See defoption for usage examples.

Link to this macro

option(name, type, help, flags)

(macro)

Link to this section Callbacks

Link to this callback

pre_dispatch(arg1, argv, options)

Specs

pre_dispatch(Artificery.Command.t(), argv(), options()) ::
  {:ok, options()} | no_return()