Declaring flags and switches

Originally, all options to a flag or switch were declared rake-style as statements preceding the call to flag or switch. There are now a variety of options and you can use a hash-like syntax to set them. Not every option has an old-style declaration form.

Flags

Flags are options that take an argument, e.g. --format=xml There are a variety of options that can be used to control how your flag works:

• :arg_name - The name of the argument for use in the help output. This should be short and ideally not contain spaces. For example, if your flag takes a file name, you might use file_name or path_to_file.
• :default_value - The default value if the flag is not specified. This value shows up in the help output.
• :desc - The short description that shows up in the app's help output.
• :long_desc - A longer description only available when generating help in RDoc
• :mask - If true, the value of this flag will be shown masked. This is useful if your config file stores a password. When GLI shows the default value in the help file, it will use the value it finds in the config file as the default. If that value is something you don't want shown in the help output, use this option.
• :must_match - This can be used to automatically require a particular format of the argument.
  • If it's a Regexp, the argument must match that regexp or GLI will generate an error.
  • If it's an Array, the argument's value must be a member of that array.
  • If it's a Hash, the argument's value must be a key in that Hash, but the value provided at runtime will be that key's value.
• :multiple - if true, users can specify the flag multiple times on the command line, and this will be returned to your app as an Array of String. If false, the last value of the flag on the command line is used.
• :required - If true, this flag must be specified on the command-line. Generally, you don't want to do this and insist on command-line arguments instead, howver if your app is complex enough, this may be useful.
• :type - A class to which the string argument should be converted. There are a limited number of conversions built-in, so this is most useful if you define your own using accept (see below)

Examples

desc 'Set the filename'
flag [:f,:filename,'file-name']
# => -f /some/file or --filename=/some/file or --file-name=some/file all accepted

flag [:f,:filename,'file-name'], :desc => 'Set the filename'
# => Same as above

flag :ipaddress, :desc => "IP Address", :must_match => /\d+\.\d+\.\d+\.\d+/
# => --ipaddress=foo causes an error
# => --ipaddress=123.34.32.12 works

flag :environment, :must_match => ["production","staging","development"]
# => --environment=test will fail
# => --environment=development will work

flag :environment, :must_match => { "production"  => :prod,
                                    "staging"     => :stage,
                                    "development" => :dev}
# => --environment=test will fail
# => --environment=development will work and options[:environment] will be :dev

Examples with accept

The accept command is global. It should come before commands and flags. (#219)

# accepts are global
accept Array do |value|
  value.split(/,/).map(&:strip)
end

accept(Hash) do |value|
  result = {}
  value.split(/,/).each do |pair|
    k,v = pair.split(/:/)
    result[k] = v
  end
  result
end

flag :names, :desc => "list of names", :type => Array
# --names=dave,amy,rudy 
# returns ['dave','amy','rudy'] for options[:names]

flag :abbreviations, :desc => "Hash of abbreviations", :type => Hash
# --abbreviations="a.m:Ante Meridian,e.g.:Exempli gratia" 
# returns {"a.m"=>"Ante Meridian", "e.g."=>"Exempli gratia"} for options[:abbreviations]

Switches

Switches take fewer options.

• :default_value - The default value if this switch is omitted. This should be a boolean value and defaults to false
• :desc - The short description that shows up in the app's help output.
• :long_desc - A longer description only available when generating help in RDoc
• :negatable - if true (the default), the switch can be turned on or off via a --no- version of the switch.

Examples

switch :verbose, :default_value => true
# --verbose has no real effect, as options[:verbose] is true
# --no-verbose sets options[:verbose] to false, since this is negatable by default

switch :verbose, :negatable => false
# options[:verbose] is false if omitted on the command line
# --verbose sets options[:verbose] to true
# --no-verbose is not a recognized option