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:



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/libclimate/climate.rb', line 189

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



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

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



224
225
226
 
# File 'lib/libclimate/climate.rb', line 224

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



226
227
228
 
# File 'lib/libclimate/climate.rb', line 226

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



228
229
230
 
# File 'lib/libclimate/climate.rb', line 228

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



230
231
232
 
# File 'lib/libclimate/climate.rb', line 230

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



234
235
236
 
# File 'lib/libclimate/climate.rb', line 234

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



232
233
234
 
# File 'lib/libclimate/climate.rb', line 232

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> } ]”



236
237
238
 
# File 'lib/libclimate/climate.rb', line 236

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



238
239
240
 
# File 'lib/libclimate/climate.rb', line 238

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.



433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
 
# File 'lib/libclimate/climate.rb', line 433

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/option name or the valued option

    • aliases

      One or more aliases

Examples

Alias(es) of a flag (single statement)

climate.add_flag(‘–mark-missing’, alias: ‘-x’)

climate.add_flag(‘–absolute-path’, aliases: [ ‘-abs’, ‘-p’ ])

Alias(es) of a flag (multiple statements)

climate.add_flag(‘–mark-missing’) climate.add_alias(‘–mark-missing’, ‘-x’)

climate.add_flag(‘–absolute-path’) climate.add_alias(‘–absolute-path’, ‘-abs’, ‘-p’)

Alias(es) of an option (single statement)

climate.add_option(‘–add-patterns’, alias: ‘-p’)

Alias(es) of an option (multiple statements)

climate.add_option(‘–add-patterns’) climate.add_alias(‘–add-patterns’, ‘-p’)

Alias of a valued option (which has to be multiple statements)

climate.add_option(‘–verbosity’) climate.add_alias(‘–verbosity=succinct’, ‘-s’) climate.add_alias(‘–verbosity=verbose’, ‘-v’)

Raises:

  • (ArgumentError) 


534
535
536
537
538
539
540
 
# File 'lib/libclimate/climate.rb', line 534

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?

  self.aliases << CLASP.Option(name, aliases: aliases)
end

#add_flag(name, options = {}, &block) ⇒ 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


474
475
476
477
478
479
 
# File 'lib/libclimate/climate.rb', line 474

def add_flag(name, options={}, &block)

  ::Xqsr3::Quality::ParameterChecking.check_parameter name, 'name', allow_nil: false, types: [ ::String, ::Symbol ]

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

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

  • Options

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


489
490
491
492
493
494
 
# File 'lib/libclimate/climate.rb', line 489

def add_option(name, options={}, &block)

  ::Xqsr3::Quality::ParameterChecking.check_parameter name, 'name', allow_nil: false, types: [ ::String, ::Symbol ]

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

#run(argv = ARGV) ⇒ Object

Executes the prepared Climate instance

Signature

  • Parameters:

    • argv

      The array of arguments; defaults to ARGV

  • Returns: an instance of a type derived from ::Hash with the additional attributes flags, options, values, and argv.

Raises:

  • (ArgumentError) 


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
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/libclimate/climate.rb', line 251

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.define_singleton_method(:argv) do

    argv
  end

  results
end