Defining Program Actions

Cheatsheet

# --- Action Definition

usage   "server PORT [--background]"
help    "Start the server, optionally in the background"
option  "-b --background", "Start in the background"
param   "PORT", "Server port to listen on"
env_var "HOST", "Host address to listen to"
example "server 3000 -b"
action  :server do |args|
  # ... action code here
end

# --- Command Prefix

command 'prefix'

# all actions here will be prefixed by 'prefix'

action :anything do
  # ...
end

endcommand

Reference

usage string

Specify the usage pattern of the following action. This string is expected to be in any format recognized by docopt.

In some cases ( compact usage example ) you may want to force-disable the usage text for the following action. Simply use usage false.

This command is optional if the action does not have any arguments.

Examples:

usage "command"              # The next action (:command) has no 
                             # arguments (optional in this case)

usage "greet <name>"         # The next action (:greet) has one
                             # require argument, called 'name'

usage "run [--fast --slow]"  # The next action (:run) has two 
                             # optional flags.

usage false                  # Disable usage pattern for the next 
                             # action.

help string

Specify the help message for the following action. This is the message that will be displayed when you execute run --help

This command is optional.

Example: help "Greet the user with a colorful 'Hello!'"

option string, description [, label]

Specify the help information for any of the option flags. This is the place where you can specify that a certain flag also has a short version.

Normally, the help message for all options appear under the Options: caption. If you provide the third <label> argument, it will appear under a different caption.

See Also: Options Label Example

This command is optional unless the usage pattern may be ambiguous.

Examples:

option "-c --color", "Show message with a color"
option "--force", "Force delete", "Delete Options"

param string, description [, label]

Specify the help information for any of the positional parameters. This is purely decorative and has no impact on the operation of the Runfile.

Normally, the help message for all parameters appear under the Parameters: caption. If you provide the third <label> argument, it will appear under a different caption.

See Also: Parameters Example

This command is optional.

Examples:

param "PORT", "Server port to listen to"
param "SOURCE", "File to copy", "Copy Options"

env_var string, description [, label]

Specify the help information for any environment variables your Runfile may need. This is purely decorative and has no impact on the operation of the Runfile.

Normally, the help message for all environment variables appears under the Environment Variables: caption. If you provide the third <label> argument, it will appear under a different caption.

See Also: Environment Variables Example

This command is optional.

Examples:

env_var "HOST", "Host address to listen on"
env_var "USER", "SSH user", "SSH Environment Variables"

example string

Add an example command to the general help information. When adding an example, the command run --help will show an Examples: section at the end of the help text, with all added examples.

You do not need to include the run or run runfile_name at the beginning of your example text, it is done automatically.

See Also: Example Command Example

This command is optional.

Examples:

example "copy source.txt dest.txt --force"
example "copy source.txt --here"

action name [, alias] { block }

Define the actual action block that will be called.
This command is required

Examples:

# If you do not need to process any arguments:
action :command do 
  # your code here
end

# if you want to handle arguments defined in `usage`:
action :command do |args|
  # your code here
  # access any argument with arg['--flagname'] or arg['<arg>']
end

# If you wish to use commands with hyphen, simply use single quotes:
action :'drink-beer' do 
  # your code here
end

# To define an alias (shortcut) to a command, use:
action :command, :c do 
  # your code here
end

See Also: Alias Example

command string

The command command lets you define a namespace. Once you use this command, any subsequent action will be associated with this namespace.

This is a way to create sub commands.

Call without parameter to revert back to the global namespace.

This command is optional.

Example: command "html"

See Also: Namespace Example

endcommand

Alias of command. Intended as a syntactic sugar so that you can end a command 'namespace' with endcommand instead of an empty command.

This command is optional.

Runfile Documentation