Class: LibCLImate::Climate

Inherits:
Object
  • Object
show all
Defined in:
lib/libclimate/climate.rb

Overview

Class used to gather together the CLI specification, and execute it

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|_self| ... } ⇒ Climate

Creates an instance of the Climate class.

Signature

  • Parameters:

    • options:

      An options hash, containing any of the following options.

  • Options:

    • :no_help_flag

      Prevents the use of the CLASP::Flag.Help flag-alias

    • :no_version_flag

      Prevents the use of the CLASP::Version.Help flag-alias

  • Block

    An optional block which receives the constructing instance, allowing the user to modify the attributes.

Yields:

  • (_self)

Yield Parameters:



169
170
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
 
# File 'lib/libclimate/climate.rb', line 169

def initialize(options={}) # :yields: climate

  options ||=  {}

  program_name = File.basename($0)
  program_name = (program_name =~ /\.rb$/) ? "#$`(#$&)" : program_name

  if defined? Colcon

    program_name = "#{::Colcon::Decorations::Bold}#{program_name}#{::Colcon::Decorations::Unbold}"
  end

  @aliases     = []
  @exit_on_unknown = true
  @exit_on_usage   =  true
  @info_lines      =  nil
  @program_name    = program_name
  @stdout        = $stdout
  @stderr        = $stderr
  @usage_values    = usage_values
  @version     = []

  @aliases << CLASP::Flag.Help(handle: proc { show_usage_ }) unless options[:no_help_flag]
  @aliases << CLASP::Flag.Version(handle: proc { show_version_ }) unless options[:no_version_flag]

  yield self if block_given?
end

Instance Attribute Details

#aliases ⇒ Array (readonly)

An array of aliases attached to the climate instance, whose contents should be modified by adding (or removing) CLASP aliases

Returns:

  • (Array) —

    The aliases



199
200
201
 
# File 'lib/libclimate/climate.rb', line 199

def aliases
  @aliases
end

#exit_on_unknown ⇒ Boolean

Indicates whether exit will be called (with non-zero exit code) when an unknown command-line flag or option is encountered

Returns:

  • (Boolean)

  • true exit(1) will be called

  • false exit will not be called



204
205
206
 
# File 'lib/libclimate/climate.rb', line 204

def exit_on_unknown
  @exit_on_unknown
end

#exit_on_usage ⇒ Boolean

Returns Indicates whether exit will be called (with zero exit code) when usage/version is requested on the command-line.

Returns:

  • (Boolean) —

    Indicates whether exit will be called (with zero exit code) when usage/version is requested on the command-line



206
207
208
 
# File 'lib/libclimate/climate.rb', line 206

def exit_on_usage
  @exit_on_usage
end

#info_lines ⇒ Array

Returns Optional array of string of program-information that will be written before the rest of the usage block when usage is requested on the command-line.

Returns:

  • (Array) —

    Optional array of string of program-information that will be written before the rest of the usage block when usage is requested on the command-line



208
209
210
 
# File 'lib/libclimate/climate.rb', line 208

def info_lines
  @info_lines
end

#program_name ⇒ String

Returns A program name; defaults to the name of the executing script.

Returns:

  • (String) —

    A program name; defaults to the name of the executing script



210
211
212
 
# File 'lib/libclimate/climate.rb', line 210

def program_name
  @program_name
end

#stderr ⇒ IO

Returns The output stream for contingent output; defaults to $stderr.

Returns:

  • (IO) —

    The output stream for contingent output; defaults to $stderr



214
215
216
 
# File 'lib/libclimate/climate.rb', line 214

def stderr
  @stderr
end

#stdout ⇒ IO

Returns The output stream for normative output; defaults to $stdout.

Returns:

  • (IO) —

    The output stream for normative output; defaults to $stdout



212
213
214
 
# File 'lib/libclimate/climate.rb', line 212

def stdout
  @stdout
end

#usage_values ⇒ String

Returns Optional string to describe the program values, eg <xyz “[ { <<directory> | &lt;file> } ]”.

Returns:

  • (String) —

    Optional string to describe the program values, eg <xyz “[ { <<directory> | &lt;file> } ]”



216
217
218
 
# File 'lib/libclimate/climate.rb', line 216

def usage_values
  @usage_values
end

#version ⇒ String, Array

Returns A version string or an array of integers representing the version components.

Returns:

  • (String, Array) —

    A version string or an array of integers representing the version components



218
219
220
 
# File 'lib/libclimate/climate.rb', line 218

def version
  @version
end

Instance Method Details

#abort(message, options = {}) ⇒ Object

Calls abort() with the given message prefixed by the program_name

Signature

  • Parameters:

    • message

      The message string

    • options

      An option hash, containing any of the following options

  • Options:

    • :stream

      optional The output stream to use. Defaults to the value of the attribute stderr.

    • :program_name

      optional Uses the given value rather than the program_name attribute; does not prefix if the empty string

    • :exit

      optional The exit code. Defaults to 1. Does not exit if nil specified.

  • Return: The combined message string, if exit() not called.



404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/libclimate/climate.rb', line 404

def abort message, options={}

  prog_name  =  options[:program_name]
  prog_name  ||=  program_name
  prog_name  ||=  ''

  stream   =  options[:stream]
  stream   ||=  stderr
  stream   ||=  $stderr

  exit_code  =  options.has_key?(:exit) ? options[:exit] : 1

  if prog_name.empty?

    msg = message
  else

    msg = "#{prog_name}: #{message}"
  end


  stream.puts msg

  exit(exit_code) if exit_code

  msg
end

#add_alias(name, *aliases) ⇒ Object

Adds a flag to aliases

Signature

  • Parameters

    • name

      The flag name

    • options

      An options hash, containing any of the following options.

Raises:

  • (ArgumentError) 


470
471
472
473
474
475
476
477
478
 
# File 'lib/libclimate/climate.rb', line 470

def add_alias(name, *aliases)

  ::Xqsr3::Quality::ParameterChecking.check_parameter name, 'name', allow_nil: false, types: [ ::String, ::Symbol ]
  raise ArgumentError, "must supply at least one alias" if aliases.empty?

  klass = CLASP::Option

  self.aliases << klass(name, aliases: aliases)
end

#add_flag(name, options = {}) ⇒ Object

Adds a flag to aliases

Signature

  • Parameters

    • name

      The flag name

    • options

      An options hash, containing any of the following options.

  • Options

    • :help
    • :alias
    • :aliases
    • :extras


445
446
447
448
 
# File 'lib/libclimate/climate.rb', line 445

def add_flag(name, options={})

  aliases << CLASP.Flag(name, **options)
end

#add_option(name, options = {}) ⇒ Object

  • Options

    • :alias
    • :aliases
    • :help
    • :values_range
    • :default_value
    • :extras


458
459
460
461
 
# File 'lib/libclimate/climate.rb', line 458

def add_option(name, options={})

  aliases << CLASP.Option(name, **options)
end

#run(argv = ARGV) ⇒ Object

Executes the prepared Climate instance

Signature

  • Parameters:

    • argv

      The array of arguments; defaults to ARGV

  • Returns:

Raises:

  • (ArgumentError) 


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
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/libclimate/climate.rb', line 229

def run argv = ARGV

  raise ArgumentError, "argv may not be nil" if argv.nil?

  arguments  =  CLASP::Arguments.new argv, aliases
  flags    = arguments.flags
  options    = arguments.options
  values   =  arguments.values.to_a

  results    = {

    flags: {

      given:   flags,
      handled: [],
      unhandled: [],
      unknown: []
    },

    options: {

      given:   options,
      handled: [],
      unhandled: [],
      unknown: []
    },

    values: values
  }

  flags.each do |f|

    al = aliases.detect do |a|

      a.kind_of?(::CLASP::Flag) && f.name == a.name
    end

    if al

      selector = :unhandled

      # see if it has a :action attribute (which will have been
      # monkey-patched to CLASP.Flag()

      if al.respond_to?(:action) && !al.action.nil?

        al.action.call(f, al)

        selector = :handled
      else

        ex = al.extras

        case ex
        when ::Hash
          if ex.has_key? :handle

            ex[:handle].call(f, al)

            selector = :handled
          end
        end
      end

      results[:flags][selector] << f
    else

      message = "unrecognised flag '#{f}'; use --help for usage"

      if exit_on_unknown

        self.abort message
      else

        if program_name && !program_name.empty?

          message = "#{program_name}: #{message}"
        end

        stderr.puts message
      end

      results[:flags][:unknown] << f
    end
  end

  options.each do |o|

    al = aliases.detect do |a|

      a.kind_of?(::CLASP::Option) && o.name == a.name
    end

    if al

      selector = :unhandled

      # see if it has a :action attribute (which will have been
      # monkey-patched to CLASP.Option()

      if al.respond_to?(:action) && !al.action.nil?

        al.action.call(o, al)

        selector = :handled
      else

        ex = al.extras

        case ex
        when ::Hash
          if ex.has_key? :handle

            ex[:handle].call(o, al)

            selector = :handled
          end
        end
      end

      results[:options][selector] << o
    else

      message = "unrecognised option '#{o}'; use --help for usage"

      if exit_on_unknown

        self.abort message
      else

        if program_name && !program_name.empty?

          message = "#{program_name}: #{message}"
        end

        stderr.puts message
      end

      results[:options][:unknown] << o
    end
  end

  def results.flags

    self[:flags]
  end

  def results.options

    self[:options]
  end

  def results.values

    self[:values]
  end

  results
end