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

When used on a command, you can provide an optional list of modifiers:

• :optional - indicate that this argument is optional. Affects help output only.
• :multiple - indicate that the argument has a "or more" arity

Examples

arg_name 'task_name', :multiple
command :new do |c|
  # ..
end

> my_app help new
NAME
    new

SYNOPSIS
    my_app new task_name[, task_name]*

arg_name 'task_name', :optional
command :new do |c|
  # ..
end

> my_app help new
NAME
    new

SYNOPSIS
    my_app new [task_name]

arg_name 'task_name', [:optional, :multiple]
command :new do |c|
  # ..
end

> my_app help new
NAME
    new

SYNOPSIS
    my_app new [task_name][, task_name]*

command

Declare a command or Subcommands. 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 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. When the path is an absolute path, *.rb files are required from this path. When the path is relative, files are found relative to the LOAD_PATH. The first form is useful for runtime plugin support. The second is useful for organizing your app's commands into various files.

command_missing

Similar to Ruby's method_missing this is another way to extend your CLI app with plugins akin to commands_from. This works best if you don't know the commands until you've parsed the command line.

command_missing do |command_name, global_options|
  if command_name =~ /^custom:(.*)/ 
    command command_name do |c|
      c.action do |g,o,a|
        # your code here
      end
    end
  end
end

config_file

Name the configuration file for your application. See Config.

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. See Subcommands for more details on how this works.

default_desc

For a command with subcommands and an action block, this can be used to specify what happens in the action block. See Subcommands for more details on how this works.

default_value

Indicate the default value of the next flag or switch. 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.

Regarding switches

A switch default value other than false is a bit odd, but not totally crazy. Note that it only makes sense if the switch can be negated. For example:

desc "Show verbose output"
default_value true
switch :verbose, :negatable => false

In this case, it's impossible to turn off the switch. Thus, this form is not allowed, and GLI will raise an error about it. Instead, this:

desc "Show verbose output"
default_value true
switch :verbose

Means that, by default verbose is on, but the user can turn it off via --no-verbose

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.

example

Used to provide an example command-line invocation that will show up in help docs.

command :list do |c|
  c.example "todo list", desc: "List all tasks"
  c.example "todo list --wip", desc: "List all tasks in progress"
end

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.

See Declaring Flags and Switches for more detailed info.

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.

preserve_argv

If called, ARGV (or whatever is passed to run()) will not be modified; it will be copied before use. This allows you to have complete access to the command line via ARGV anywhere in your code if you need to.

This is off by default, as turning it on would break backwards compatibility.

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

sort_help

Use this to affect how the commands in the help are sorted. By default, they are sorted by name, alphabetically. By using :manually, they will be ordered based on the order declared. See Controlling help output for more info.

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.

See Declaring Flags and Switches for more detailed info.

synopsis_format

Use this to control the command-line synopsis. Useful if your app has a lot of flags and switches, :compact will show a generic, short synopsis, while :full (the default) will show all flags and switches for subcommands. See Controlling help output for more info.

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.

wrap_help_text

By default, help text is wrapped to the size of the terminal. If you'd like to format it yourself, use :verbatim, and if you'd like it always all on one line use :one_line. See Controlling help output for more info.