The primary DSL
for GLI
. This represents the methods shared between your top-level app and the commands. See GLI::Command
for additional methods that apply only to command objects.
Describes one of the arguments of the next command
name
-
A String that briefly describes the argument given to the following command.
options
-
Symbol or array of symbols to annotate this argument. This doesn't affect parsing, just the help output. Values recognized are:
:optional
-
indicates this argument is optional; will format it with square brackets
:multiple
-
indicates multiple values are accepted; will format appropriately
Example:
arg :output
arg :input, :multiple
command :pack do ...
Produces the synopsis:
app.rb [global options] pack output input...
Source: show
# File lib/gli/dsl.rb, line 54 def arg(name, options=[]) @next_arguments ||= [] @next_arguments << Argument.new(name, Array(options).flatten) end
Describe the argument name of the next flag. It's important to keep this VERY short and, ideally, without any spaces (see Example).
name
-
A String that briefly describes the argument given to the following command or flag.
options
-
Symbol or array of symbols to annotate this argument. This doesn't affect parsing, just the help output. Values recognized are:
:optional
-
indicates this argument is optional; will format it with square brackets
:multiple
-
indicates multiple values are accepted; will format appropriately
Example:
desc 'Set the filename'
arg_name 'file_name'
flag [:f,:filename]
Produces:
-f, --filename=file_name Set the filename
Source: show
# File lib/gli/dsl.rb, line 34 def arg_name(name,options=[]) @next_arg_name = name @next_arg_options = options end
Define a new command. This can be done in a few ways, but the most common method is to pass a symbol (or Array of symbols) representing the command name (or names) and a block.
The block will be given an instance of the Command
that was created. You then may call methods on this object to define aspects of that Command
.
Alternatively, you can call this with a one element Hash, where the key is the symbol representing the name of the command, and the value being an Array of symbols representing the commands to call in order, as a chained or compound command. Note that these commands must exist already, and that only those command-specific options defined in this command will be parsed and passed to the chained commands. This might not be what you expect
names
-
a String or Symbol, or an Array of String or Symbol that represent all the different names and aliases for this command or a Hash, as described above.
Examples
# Make a command named list
command :list do |c|
c.action do |global_options,options,args|
# your command code
end
end
# Make a command named list, callable by ls as well
command [:list,:ls] do |c|
c.action do |global_options,options,args|
# your command code
end
end
# Make a command named all, that calls list and list_contexts
command :all => [ :list, :list_contexts ]
# Make a command named all, aliased as :a:, that calls list and list_contexts
command [:all,:a] => [ :list, :list_contexts ]
Source: show
# File lib/gli/dsl.rb, line 171 def command(*names) command_options = { :description => @next_desc, :arguments_name => @next_arg_name, :arguments_options => @next_arg_options, :arguments => @next_arguments, :long_desc => @next_long_desc, :skips_pre => @skips_pre, :skips_post => @skips_post, :skips_around => @skips_around, :hide_commands_without_desc => @hide_commands_without_desc, } @commands_declaration_order ||= [] if names.first.kind_of? Hash command = GLI::Commands::CompoundCommand.new(self, names.first, command_options) command.parent = self commands[command.name] = command @commands_declaration_order << command else new_command = Command.new(command_options.merge(:names => [names].flatten)) command = commands[new_command.name] if command.nil? command = new_command command.parent = self commands[command.name] = command @commands_declaration_order << command end yield command end clear_nexts @next_arguments = [] end
set the default value of the next flag or switch
val
-
The default value to be used for the following flag if the user doesn't specify one and, when using a config file, the config also doesn't specify one. For a switch, this is the value to be used if the switch isn't specified on the command-line. Note that if you set a switch to have a default of true, using the switch on the command-line has no effect. To disable a switch where the default is true, use the
--no-
form.
Source: show
# File lib/gli/dsl.rb, line 66 def default_value(val); @next_default_value = val; end
Describe the next switch, flag, or command. This should be a short, one-line description
description
-
A String of the short descripiton of the switch, flag, or command following
Source: show
# File lib/gli/dsl.rb, line 9 def desc(description); @next_desc = description; end
Create a flag, which is a switch that takes an argument
names
-
a String or Symbol, or an Array of String or Symbol that represent all the different names and aliases for this flag. The last element can be a hash of options:
:desc
-
the description, instead of using
desc
:long_desc
-
the long_description, instead of using
long_desc
:default_value
-
the default value, instead of using
default_value
:arg_name
-
the arg name, instead of using
arg_name
:must_match
-
A regexp that the flag's value must match or an array of allowable values
:type
-
A Class (or object you passed to
GLI::App#accept
) to trigger type coversion :multiple
-
if true, flag may be used multiple times and values are stored in an array
Example:
desc 'Set the filename'
flag [:f,:filename,'file-name']
flag :ipaddress, :desc => "IP Address", :must_match => /\d+\.\d+\.\d+\.\d+/
flag :names, :desc => "list of names", :type => Array
Produces:
-f, --filename, --file-name=arg Set the filename
Source: show
# File lib/gli/dsl.rb, line 92 def flag(*names) options = extract_options(names) names = [names].flatten verify_unused(names) flag = Flag.new(names,options) flags[flag.name] = flag clear_nexts flags_declaration_order << flag flag end
Provide a longer, more detailed description. This will be reformatted and wrapped to fit in the terminal's columns
long_desc
-
A String that is s longer description of the switch, flag, or command following.
Source: show
# File lib/gli/dsl.rb, line 16 def long_desc(long_desc); @next_long_desc = long_desc; end
Create a switch, which is a command line flag that takes no arguments (thus, it switches something on)
names
-
a String or Symbol, or an Array of String or Symbol that represent all the different names and aliases for this switch. The last element can be a hash of options:
:desc
-
the description, instead of using
desc
:long_desc
-
the long_description, instead of using
long_desc
:default_value
-
if the switch is omitted, use this as the default value. By default, switches default to off, or
false
:negatable
-
if true, this switch will get a negatable form (e.g.
--[no-]switch
, false it will not. Default is true
Source: show
# File lib/gli/dsl.rb, line 114 def switch(*names) options = extract_options(names) names = [names].flatten verify_unused(names) switch = Switch.new(names,options) switches[switch.name] = switch clear_nexts switches_declaration_order << switch switch end