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'

    c.action do |global_options,options,arguments|
      raise "Must supply one file" unless arguments.size == 1
      if global_options[:force] || !File.exists?(arguments[0])
        write_file(arguments[0])
      else
        puts "Not overwriting #{arguments[0]}"
      end
    end

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)

    desc 'File name to use when writing data'
    arg_name 'path_to_file'
    flag [:f,:filename]

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

    config_file '.glirc'

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. This argument should be used to describe the command-specific options as well as to specify the code to run when this command is called.

    desc 'Commit your changes'
    command :commit do |c|
      c.desc 'Message for your commit'
      c.flag :m
      c.action do |global_options,options,arguments|
        # ...
      end
    end

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 'File name to use when writing data'
    arg_name 'path_to_file'
    default_value Etc.getpwuid.dir + "/foobar.txt"

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.

    desc 'Be much more verbose'
    c.switch [:v,:verbose]

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.

    desc 'File name to use when writing data'
    flag [:f,'filename']

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.

    desc 'Commit changes'
    long_desc <<EOS
    Packages your commit for sending to a remote repository.  This will only commit
    things that you've explcitly added using the "add" command.
    EOS

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.

    desc 'Dry-run, don't change the disk'
    switch [:n,'dry-run',:dryrun]

use_openstruct

By default, GLI passes global_options and options to command action blocks, pre blocks, and post blocks as Hashes. If you'd like to receive them as an OpenStruct:

    use_openstruct true

The arguments passed to your blocks are actually a subclass of OpenStruct that provides [] and []= access to make them hash-like.

(Note that previous versions of GLI passed the OpenStruct by default; this created complication and confusion, since OpenStruct doesn't conform to the Hash interface)

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.

    require 'gli_version'

    version GLI::VERSION