artificery v0.2.3 Artificery behaviour

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. This is an abstract option definition, i.e. it doesn’t define an option in any scope, it defines options for reuse

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

Link to this section Types

Link to this type argv()
argv() :: [String.t()]
Link to this type options()
options() :: %{optional(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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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(arg0, argv, options)
pre_dispatch(Artificery.Command.t(), argv(), options()) ::
  {:ok, options()} | no_return()