Reference

Reference

This is an overview of the GLI DSL. The RDoc is occasionally more specific, and occasionally absent, so this is the best place to see what's available

action

Specify the action to take when a command is executed from the command line. This is only usable in a command block on the command object (e.g. c.action). This takes a block that yields three parameters: a hash of global options specified on the commandline, a hash of command-specific options specified on the command line, and an array of arguments parsed after the options were set on the command line. So, a command like git --git-dir=/tmp commit -a -m 'Foo bar' foo.c bar.c would result in the global hash containing :'git-dir' => '/tmp', the options hash containing :a => true, :m => 'Foo bar' and the arguments array being 'foo.c', 'bar.c'

arg_name

Describe the name of the argument to the next flag or command. This can be used at the global level or inside a command block on the command object (e.g. c.arg_name)

config_file

Name the configuration file for your applicaiton. This can either be an absolute path to where the applicaiton will find the configuration file, or a relative path, that will be interpretted as relative to the user's home directory. Default is nil, which means no configuration file will be used. Declaring this creates a special initconfig command that can bootstrap this configuration file for your users.

command

Declare a command. This takes a symbol, String or array of symbols/Strings and a block. The block yields one argument, the command itself.

default_value

Indicate the default value of the next flag. This can be used at the global level or inside a command block on the command object (e.g. c.default_value)

desc

Describe the next flag, switch, or command you will declare. This can be used at the global level or inside a command block on the command object (e.g. c.desc)

flag

Declare a flag, which is a command line switch that takes an argument. This takes either a symbol, String, or an array of symbols/Strings. The first symbol decared is used in your program to determine the flag's value at runtime. This can be used at the global level or inside a command block on the command object (e.g. c.flag)

long_desc

Provide a more lengthy description of the next flag, switch, or command you will declare. This will appear in command line output for commands when you get help for a command. For flags and switches, this will only appear in the generated rdoc and not on the command line. This can be used at the global level or inside a command block on the command object (e.g. c.long_desc)

on_error

Declare an error handling routine that will be called if any command (or other GLI processing) encouters an exception. This is a block that will receive the exception that was caught. All exceptions are routed through this block. If the block evaluates to true, the built-in error handling will be called after, otherwise, nothing will happen.

post

Declare code to run after every command that didn't experience an error. This is not available inside a command block. This takes a block that will receive four arguments: the global argument hash (as in action), the command (instance of Command), the command-specific options (as in action, and the parsed command line arguments (as in action).

pre

Declare code to run before every command. This is not available inside a command block. This takes a block that will receive four arguments: the global argument hash (as in action), the command (instance of Command), the command-specific options (as in action, and the parsed command line arguments (as in action). If this block evaluates to false, the command will not be executed and the program will stop.

switch

Declare a switch, which is a command-line switch taking no argument that indicates a boolean "true" when specified on the command line. This takes either a symbol, String or array of symbols/Strings. The first symbol declared is used in your program to determine if the switch was set. This can be used at the global level or inside a command block on the command object (e.g. c.switch)

version

Indicate the verison of your application/library. This is used by the default help command to allow users to see the version of your application.