Module: GLI

Extended by:
GLI
Included in:
GLI
Defined in:
lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/gli/flag.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/gli/switch.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/gli/command.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/gli_version.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/support/help.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/support/rdoc.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/support/scaffold.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/support/initconfig.rb,
lib/bbcloud/vendor/gli-1.1.2/lib/gli/command_line_token.rb

Overview

A means to define and parse a command line interface that works as Git’s does, in that you specify global options, a command name, command specific options, and then command arguments.

Defined Under Namespace

Classes: Command, CommandLineToken, DefaultHelpCommand, Flag, InitConfig, RDocCommand, Scaffold, Switch

Constant Summary collapse

VERSION = 
'1.1.2'
@@program_name = 
$0.split(/\//)[-1]
@@post_block = 
nil
@@pre_block = 
nil
@@error_block = 
nil
@@config_file = 
nil

Instance Method Summary collapse

Instance Method Details

#arg_name(name) ⇒ Object

describe the argument name of the next flag



42
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 42

def arg_name(name); @@next_arg_name = name; end

#clear_nexts ⇒ Object 



181
182
183
184
185
186
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 181

def clear_nexts
  @@next_desc = nil
  @@next_arg_name = nil
  @@next_default_value = nil
  @@next_long_desc = nil
end

#command(*names) {|command| ... } ⇒ Object Also known as: c

Define a command.

Yields:



74
75
76
77
78
79
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 74

def command(*names)
  command = Command.new([names].flatten,@@next_desc,@@next_arg_name,@@next_long_desc)
  commands[command.name] = command
  yield command
  clear_nexts
end

#commands ⇒ Object 



192
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 192

def commands; @@commands ||= {}; end

#config_file(filename) ⇒ Object

Sets the config file. If not an absolute path sets the path to the user’s home directory



63
64
65
66
67
68
69
70
71
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 63

def config_file(filename)
  if filename =~ /^\//
    @@config_file = filename
  else
    @@config_file = Etc.getpwuid.dir + '/' + filename
  end
  commands[:initconfig] = InitConfig.new(@@config_file)
  @@config_file
end

#default_command_options(command, command_configs) ⇒ Object 



309
310
311
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 309

def default_command_options(command,command_configs)
  options = (command_configs && command_configs[command.name.to_sym]) || {}
end

#default_value(val) ⇒ Object

set the default value of the next flag



45
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 45

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



35
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 35

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

#find_command(name) ⇒ Object 



313
314
315
316
317
318
319
320
321
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 313

def find_command(name)
  sym = name.to_sym
  return commands[name.to_sym] if commands[sym]
  commands.keys.each do |command_name|
    command = commands[command_name]
    return command if (command.aliases && command.aliases.include?(sym))
  end
  nil
end

#find_non_flag_index(args) ⇒ Object

Finds the index of the first non-flag argument or -1 if there wasn’t one.



168
169
170
171
172
173
174
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 168

def find_non_flag_index(args)
  args.each_index do |i|
    return i if args[i] =~ /^[^\-]/;
    return i-1 if args[i] =~ /^\-\-$/;
  end
  -1;
end

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

Create a flag, which is a switch that takes an argument



48
49
50
51
52
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 48

def flag(*names)
  flag = Flag.new([names].flatten,@@next_desc,@@next_arg_name,@@next_default_value,@@next_long_desc)
  flags[flag.name] = flag
  clear_nexts
end

#flags ⇒ Object 



190
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 190

def flags; @@flags ||= {}; end

#long_desc(long_desc) ⇒ Object

Provide a longer, more detailed description. This will be reformatted and wrapped to fit in 80 columns



39
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 39

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

#on_error(&a_proc) ⇒ Object

Define a block to run if an error occurs. The block will receive any Exception that was caught. It should return false to avoid the built-in error handling (which basically just prints out a message)



102
103
104
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 102

def on_error(&a_proc)
  @@error_block = a_proc
end

#parse_config ⇒ Object 



131
132
133
134
135
136
137
138
139
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 131

def parse_config
  return nil if @@config_file.nil?
  require 'yaml'
  if File.exist?(@@config_file)
    File.open(@@config_file) { |f| YAML::load(f) }
  else
    {}
  end
end

#parse_options(args, config = nil) ⇒ Object

Returns an array of four values:

* global options (as a Hash)
* Command 
* command options (as a Hash)
* arguments (as an Array)



153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 153

def parse_options(args,config=nil)
  command_configs = {}
  if config.nil?
    config = {}
  else
    command_configs = config.delete(GLI::InitConfig::COMMANDS_KEY) if !config.nil?
  end
  global_options,command,options,arguments = parse_options_helper(args.clone,config,nil,Options.new,Array.new,command_configs)
  flags.each { |name,flag| global_options[name] = flag.default_value if !global_options[name] }
  command.flags.each { |name,flag| options[name] = flag.default_value if !options[name] }
  return [global_options,command,options,arguments]
end

#parse_options_helper(args, global_options, command, command_options, arguments, command_configs) ⇒ Object

Recursive helper for parsing command line options

args

the arguments that have yet to be processed

global_options

the global options hash

command

the Command that has been identified (or nil if not identified yet)

command_options

options for Command

arguments

the arguments for Command

command_configs

the configuration file for all commands, used as defaults

This works by finding the first non-switch/flag argument, and taking that sublist and trying to pick out flags and switches. After this is done, one of the following is true:

* the sublist is empty - in this case, go again, as there might be more flags to parse
* the sublist has a flag left in it - unknown flag; we bail
* the sublist has a non-flag left in it - this is the command (or the start of the arguments list)

This sort of does the same thing in two phases; in the first phase, the command hasn’t been identified, so we are looking for global switches and flags, ending when we get the command.

Once the command has been found, we start looking for command-specific flags and switches. When those have been found, we know the rest of the argument list is arguments for the command



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 213

def parse_options_helper(args,global_options,command,command_options,arguments,command_configs)
  non_flag_i = find_non_flag_index(args)
  all_flags = false
  if non_flag_i == 0
    # no flags
    if !command
      command_name = args.shift
      command = find_command(command_name)
      raise "Unknown command '#{command_name}'" if !command
      return parse_options_helper(args,
                                  global_options,
                                  command,
                                  default_command_options(command,command_configs),
                                  arguments,
                                  command_configs)
    else
      return global_options,command,command_options,arguments + args
    end
  elsif non_flag_i == -1
    all_flags = true
  end

  try_me = args[0..non_flag_i]
  rest = args[(non_flag_i+1)..args.length]
  if all_flags
    try_me = args 
    rest = []
  end

  # Suck up whatever options we can
  switch_hash = switches
  flag_hash = flags
  options = global_options
  if command
    switch_hash = command.switches
    flag_hash = command.flags
    options = command_options
  end

  switch_hash.each do |name,switch|
    value = switch.get_value!(try_me)
    options[name] = value if !options[name]
  end

  flag_hash.each do |name,flag|
    value = flag.get_value!(try_me)
    # So, there's a case where the first time we request the value for a flag,
    # we get the default and not the user-provided value.  The next time we request
    # it, we want to override it with the real value.
    # HOWEVER, sometimes this happens in reverse, so we want to err on taking the
    # user-provided, non-default value where possible.
    if value 
      if options[name]
        options[name] = value if options[name] == flag.default_value
      else
        options[name] = value
      end
    end
  end

  if try_me.empty?
    return [global_options,command,command_options,arguments] if rest.empty?
    # If we have no more options we've parsed them all
    # and rest may have more
    return parse_options_helper(rest,global_options,command,command_options,arguments,command_configs)
  else
    if command
      check = rest
      check = rest + try_me if all_flags 
      check.each() do |arg| 
        if arg =~ /^\-\-$/
          try_me.delete arg
          break 
        end
        raise "Unknown argument #{arg}" if arg =~ /^\-/ 
      end
      return [global_options,command,command_options,try_me + rest]
    else
      # Now we have our command name
      command_name = try_me.shift
      raise "Unknown argument #{command_name}" if command_name =~ /^\-/

      command = find_command(command_name)
      raise "Unknown command '#{command_name}'" if !command

      return parse_options_helper(rest,
                                  global_options,
                                  command,
                                  default_command_options(command,command_configs),
                                  arguments,
                                  command_configs)
    end
  end

end

#post(&a_proc) ⇒ Object

Define a block to run after command hase been executed, only if there was not an error. The block will receive the global-options,command,options, and arguments



94
95
96
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 94

def post(&a_proc)
  @@post_block = a_proc
end

#pre(&a_proc) ⇒ Object

Define a block to run after command line arguments are parsed but before any command is run. If this block raises an exception the command specified will not be executed. The block will receive the global-options,command,options, and arguments If this block evaluates to true, the program will proceed; otherwise the program will end immediately



87
88
89
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 87

def pre(&a_proc)
  @@pre_block = a_proc
end

#program_name(override = nil) ⇒ Object 



141
142
143
144
145
146
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 141

def program_name(override=nil)
  if override
    @@program_name = override
  end
  @@program_name
end

#reset ⇒ Object

Reset the GLI module internal data structures; mostly for testing



25
26
27
28
29
30
31
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 25

def reset
  switches.clear
  flags.clear
  commands.clear
  @@config_file = nil
  clear_nexts
end

#run(args) ⇒ Object

Runs whatever command is needed based on the arguments.



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 107

def run(args)
  rdoc = RDocCommand.new
  commands[:rdoc] = rdoc if !commands[:rdoc]
  commands[:help] = DefaultHelpCommand.new(rdoc) if !commands[:help]
  begin
    config = parse_config
    global_options,command,options,arguments = parse_options(args,config)
    proceed = true
    proceed = @@pre_block.call(global_options,command,options,arguments) if @@pre_block 
    if proceed
      command = commands[:help] if !command
      command.execute(global_options,options,arguments)
      @@post_block.call(global_options,command,options,arguments) if @@post_block 
    end
  rescue Exception => ex
    regular_error_handling = true
    regular_error_handling = @@error_block.call(ex) if @@error_block

    if regular_error_handling
      puts "error: #{ex.message}"
    end
  end
end

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

Create a switch



55
56
57
58
59
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 55

def switch(*names)
  switch = Switch.new([names].flatten,@@next_desc,@@next_long_desc)
  switches[switch.name] = switch
  clear_nexts
end

#switches ⇒ Object 



191
 
# File 'lib/bbcloud/vendor/gli-1.1.2/lib/gli.rb', line 191

def switches; @@switches ||= {}; end