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[, input]*
# 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
# 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.
# 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 ]
# 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.
# 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
# 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
# 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.
# 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
# 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