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(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:



107
108
109
110
111
112
113
 
# File 'lib/gli/dsl.rb', line 107

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 ]



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/gli/dsl.rb', line 150

def command(*names)
  command_options = {
    :description => @next_desc,
    :arguments_name => @next_arg_name,
    :arguments_options => @next_arg_options,
    :long_desc => @next_long_desc,
    :skips_pre => @skips_pre,
    :skips_post => @skips_post,
    :skips_around => @skips_around,
  }
  @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
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.



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

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

:type

A Class (or object you passed to GLI::App#accept) to trigger type coversion

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



71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/gli/dsl.rb', line 71

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:



183
184
185
 
# File 'lib/gli/dsl.rb', line 183

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



93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/gli/dsl.rb', line 93

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:



187
188
189
 
# File 'lib/gli/dsl.rb', line 187

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