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.