Module: GLI::DSL

Included in:
App, Command
Defined in:
lib/gli/dsl.rb

Overview

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.

Instance Method Summary collapse

Instance Method Details

#arg(name, options = []) ⇒ Object

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



54
55
56
57
 
# File 'lib/gli/dsl.rb', line 54

def arg(name, options=[])
  @next_arguments ||= []
  @next_arguments << Argument.new(name, Array(options).flatten)
end

#arg_name(name, options = []) ⇒ Object

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



34
35
36
37
 
# File 'lib/gli/dsl.rb', line 34

def arg_name(name,options=[])
  @next_arg_name = name
  @next_arg_options = options
end

#clear_nexts ⇒ Object

:nodoc:



128
129
130
131
132
133
134
 
# File 'lib/gli/dsl.rb', line 128

def clear_nexts # :nodoc:
  @next_desc = nil
  @next_arg_name = nil
  @next_arg_options = nil
  @next_default_value = nil
  @next_long_desc = nil
end

#command(*names) ⇒ Object Also known as: c

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 ]



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# 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 = []
  command
end

#command_missing(&block) ⇒ Object 



208
209
210
 
# File 'lib/gli/dsl.rb', line 208

def command_missing(&block)
  @command_missing_block = block
end

#default_value(val) ⇒ Object

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.



66
 
# File 'lib/gli/dsl.rb', line 66

def default_value(val); @next_default_value = val; end

#desc(description) ⇒ Object Also known as: d

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



9
 
# File 'lib/gli/dsl.rb', line 9

def desc(description); @next_desc = description; end

#flag(*names) ⇒ Object Also known as: f

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



92
93
94
95
96
97
98
99
100
101
102
103
 
# 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

#flags_declaration_order ⇒ Object

:nodoc:



212
213
214
 
# File 'lib/gli/dsl.rb', line 212

def flags_declaration_order # :nodoc:
  @flags_declaration_order ||= []
end

#long_desc(long_desc) ⇒ Object

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.



16
 
# File 'lib/gli/dsl.rb', line 16

def long_desc(long_desc); @next_long_desc = long_desc; end

#switch(*names) ⇒ Object Also known as: s

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



114
115
116
117
118
119
120
121
122
123
124
125
 
# 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

#switches_declaration_order ⇒ Object

:nodoc:



216
217
218
 
# File 'lib/gli/dsl.rb', line 216

def switches_declaration_order # :nodoc:
  @switches_declaration_order ||= []
end