Artificery behaviour (artificery v0.4.4)

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.

Summary

Functions

argument(name, type)

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

argument(name, type, help)

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

argument(name, type, help, flags)

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

command(name, help)

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

command(name, help, help)

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

command(name, flags, help, list)

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

defoption(name, type, flags)

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

defoption(name, type, help, flags)

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

option(name)

Imports an option defined via defoption into the current scope.

option(name, overrides)

When used in the following form

option(name, type, flags)

Similar to defoption, but defines an option inline.

option(name, type, help, flags)

Types

argv()

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

options()

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

Callbacks

pre_dispatch(t, argv, options)

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

Functions

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

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

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

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

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

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

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

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

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

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.

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.

option(name, type, help, flags)

(macro)