Reference

Reference

This is an overview of the GLI DSL. The RDoc for GLI::App, GLI::DSL, and GLI::Command is fairly complete, so refer to the RDoc for more info.

accept

This is a pass-through to OptionParser's accept method that allows you to implement your own type conversions from command-line arguments.

action

Specify the action to take when a command is executed from the command line.

arg_name

Describe the name of the argument to show the user in the help system for 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. See Config.

command

Declare a command or subcommand. There are generally two forms:

• String, Symbol, or Array of String/Symbol - declare a command that has one or more names. The first in an Array is the primary name of the command. In this form, command takes a block that can be used to declare options as well as the action
• A Hash with one key/value pair: the key is a String, Symbol or Array of String/Symbol representing the name of the command. The value is an array of Symbol of the names of commands that should be triggered, in order, by this command. In this form, no block should be given, since this command just chains other commands.

commands_from

Specify a path, relative to the Ruby load path, from which any .rb file should be requireed, as a means to put commands in a separate files. This could also be used as a plugin mechanism.

default_command

Inside a command block, this can be used to specify which subcommand to run by default if the user omits the subcommand on the command line.

default_desc

For a command with subcommands and an action block, this can be used to specify what happens in the action block.

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. The value will be shown in the help text.

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.

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.

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. Two newlines will be interpretted as a new paragraph in the output. This can be used at the global level or inside a command block on the command object.

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

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). See Hooks.

program_desc

A short description what of your program does, to include as the first part of the help statement.

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

skips_post

Use this (doesn't take arguments) to indicate that, when the user issues the command following, the post block should not be called after the command executes.

skips_pre

Use this (doesn't take arguments) to indicate that, when the user issues the command following, the pre block should not be called before the command executes. As an example, the builtin help command skips the pre block

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.

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. The value provided by the scaffolding should be sufficient, but you can change it here if you prefer another way of managing your application's version.