libclimate-ruby 0.16.0.1 → 0.17.0.1

data/lib/libclimate/climate.rb

@@ -1,17 +1,17 @@
 
 # ######################################################################## #
-# File:         lib/libclimate/climate.rb
+# File:     lib/libclimate/climate.rb
 #
-# Purpose:      Definition of the ::LibCLImate::Climate class
+# Purpose:  Definition of the ::LibCLImate::Climate class
 #
-# Created:      13th July 2015
-# Updated:      24th July 2022
+# Created:  13th July 2015
+# Updated:  6th March 2025
 #
-# Home:         http://github.com/synesissoftware/libCLImate.Ruby
+# Home:     http://github.com/synesissoftware/libCLImate.Ruby
 #
-# Author:       Matthew Wilson
+# Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2022, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2015-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -55,13 +55,13 @@ require 'yaml'
 # TODO: Need to work with other colouring libraries, too
 if !defined? Colcon # :nodoc:
 
-	begin
+  begin
 
-		require 'colcon'
-	rescue LoadError #=> x
+    require 'colcon'
+  rescue LoadError #=> x
 
-		warn "could not load colcon library" if $DEBUG
-	end
+    warn "could not load colcon library" if $DEBUG
+  end
 end
 
 # We monkey-patch CLASP module's Flag and Option generator methods by
@@ -70,66 +70,66 @@ end
 
 class << CLASP
 
-	alias_method :Flag_old, :Flag # :nodoc:
-	alias_method :Option_old, :Option # :nodoc:
+  alias_method :Flag_old, :Flag # :nodoc:
+  alias_method :Option_old, :Option # :nodoc:
 
-	# Defines a flag, attaching the given block
-	def Flag(name, options={}, &blk)
+  # Defines a flag, attaching the given block
+  def Flag(name, options={}, &blk)
 
-		f = self.Flag_old(name, options)
+    f = self.Flag_old(name, options)
 
-		# anticipate this functionality being added to CLASP
-		unless f.respond_to? :action
+    # anticipate this functionality being added to CLASP
+    unless f.respond_to? :action
 
-			class << f
+      class << f
 
-				attr_accessor :action
-			end
-		end
+        attr_accessor :action
+      end
+    end
 
-		if blk
+    if blk
 
-			case blk.arity
-			when 0, 1, 2
-			else
+      case blk.arity
+      when 0, 1, 2
+      else
 
-				warn "wrong arity for flag"
-			end
+        warn "wrong arity for flag"
+      end
 
-			f.action = blk
-		end
+      f.action = blk
+    end
 
-		f
-	end
+    f
+  end
 
-	# Defines an option, attaching the given block
-	def Option(name, options={}, &blk)
+  # Defines an option, attaching the given block
+  def Option(name, options={}, &blk)
 
-		o = self.Option_old(name, options)
+    o = self.Option_old(name, options)
 
-		# anticipate this functionality being added to CLASP
-		unless o.respond_to? :action
+    # anticipate this functionality being added to CLASP
+    unless o.respond_to? :action
 
-			class << o
+      class << o
 
-				attr_accessor :action
-			end
-		end
+        attr_accessor :action
+      end
+    end
 
-		if blk
+    if blk
 
-			case blk.arity
-			when 0, 1, 2
-			else
+      case blk.arity
+      when 0, 1, 2
+      else
 
-				warn "wrong arity for option"
-			end
+        warn "wrong arity for option"
+      end
 
-			o.action = blk
-		end
+      o.action = blk
+    end
 
-		o
-	end
+    o
+  end
 end
 
 #:startdoc:
@@ -144,7 +144,7 @@ module LibCLImate
 #
 #   program_options = {}
 #
-#   climate = LibCLImate::Climate.new do |cl|
+#   climate = LibCLImate::Climate.new(value_attributes: true)  do |cl|
 #
 #     cl.add_flag('--verbose', alias: '-v', help: 'Makes program output verbose') { program_options[:verbose] = true }
 #
@@ -153,8 +153,9 @@ module LibCLImate
 #       program_options[:flavour] = check_flavour(o.value) or cl.abort "Invalid flavour '#{o.value}'; use --help for usage"
 #     end
 #
-#     cl.usage_values = '<value-1> [ ... <value-N> ]'
-#     cl.constrain_values = 1..100000
+#     cl.usage_values = '<source-path> [ <destination-path> ]'
+#     cl.constrain_values = 1..2
+#     cl.value_names = %w{ source-path destination-path }
 #
 #     cl.info_lines = [
 #
@@ -164,1238 +165,1271 @@ module LibCLImate
 #     ]
 #   end
 #
+#   r = climate.run ARGV
+#
+#   puts "copying from '#{r.source_path}' to '#{r.destination_path || '.'}'"
+#
 class Climate
 
-	include ::Xqsr3::Quality::ParameterChecking
+  include ::Xqsr3::Quality::ParameterChecking
+
+  # Represents the results obtained from +Climate#parse()+
+  class ParseResults
+
+    def initialize(climate, arguments, options)
+
+      @climate            = climate
+
+      @arguments          = arguments
+
+      @argv               = arguments.argv
+      @argv_original_copy = arguments.argv_original_copy
+      @specifications     = arguments.specifications
+      @program_name       = climate.program_name
+      @flags              = arguments.flags
+      @options            = arguments.options
+      @values             = arguments.values
+      @double_slash_index = arguments.double_slash_index
+    end
+
+    # (Climate) The +Climate+ instance from which this instance was obtained
+    attr_reader :climate
+
+    # ([String]) The original arguments passed into the +Climate#parse()+ method
+    attr_reader :argv
 
-	# Represents the results obtained from +Climate#parse()+
-	class ParseResults
+    # (Array) unchanged copy of the original array of arguments passed to parse
+    attr_reader :argv_original_copy
 
-		def initialize(climate, arguments, options)
+    # (Array) a frozen array of specifications
+    attr_reader :specifications
 
-			@climate				=	climate
+    # (String) The program name
+    attr_reader :program_name
 
-			@arguments				=	arguments
+    # (String) A (frozen) array of flags
+    attr_reader :flags
 
-			@argv					=	arguments.argv
-			@argv_original_copy		=	arguments.argv_original_copy
-			@specifications			=	arguments.specifications
-			@program_name			=	climate.program_name
-			@flags					=	arguments.flags
-			@options				=	arguments.options
-			@values					=	arguments.values
-			@double_slash_index		=	arguments.double_slash_index
-		end
+    # (String) A (frozen) array of options
+    attr_reader :options
 
-		# (Climate) The +Climate+ instance from which this instance was obtained
-		attr_reader :climate
+    # (String) A (frozen) array of values
+    attr_reader :values
 
-		# ([String]) The original arguments passed into the +Climate#parse()+ method
-		attr_reader :argv
+    attr_reader :double_slash_index
 
-		# (Array) unchanged copy of the original array of arguments passed to parse
-		attr_reader :argv_original_copy
+    # Verifies the initiating command-line against the specifications,
+    # raising an exception if any missing, unused, or unrecognised flags,
+    # options, or values are found
+    def verify(**options)
 
-		# (Array) a frozen array of specifications
-		attr_reader :specifications
+      if v = options[:raise]
 
-		# (String) The program name
-		attr_reader :program_name
+        hm = {}
 
-		# (String) A (frozen) array of flags
-		attr_reader :flags
+        hm[:raise_on_required] = v unless options.has_key?(:raise_on_required)
+        hm[:raise_on_unrecognised] = v unless options.has_key?(:raise_on_unrecognised)
+        hm[:raise_on_unused] = v unless options.has_key?(:raise_on_unused)
 
-		# (String) A (frozen) array of options
-		attr_reader :options
+        options = options.merge hm
+      end
 
-		# (String) A (frozen) array of values
-		attr_reader :values
+      raise_on_required     = options[:raise_on_required]
+      raise_on_unrecognised = options[:raise_on_unrecognised]
+      raise_on_unused       = options[:raise_on_unused]
 
-		attr_reader :double_slash_index
 
-		# Verifies the initiating command-line against the specifications,
-		# raising an exception if any missing, unused, or unrecognised flags,
-		# options, or values are found
-		def verify(**options)
+      # Verification:
+      #
+      # 1. Check arguments recognised
+      # 1.a Flags
+      # 1.b Options
+      # 2. police any required options
+      # 3. Check values
 
-			if v = options[:raise]
+      # 1.a Flags
 
-				hm = {}
+      self.flags.each do |flag|
 
-				hm[:raise_on_required] = v unless options.has_key?(:raise_on_required)
-				hm[:raise_on_unrecognised] = v unless options.has_key?(:raise_on_unrecognised)
-				hm[:raise_on_unused] = v unless options.has_key?(:raise_on_unused)
+        spec = specifications.detect do |sp|
 
-				options = options.merge hm
-			end
+          sp.kind_of?(::CLASP::FlagSpecification) && flag.name == sp.name
+        end
 
-			raise_on_required		=	options[:raise_on_required]
-			raise_on_unrecognised	=	options[:raise_on_unrecognised]
-			raise_on_unused			=	options[:raise_on_unused]
+        if spec
 
+          if spec.respond_to?(:action) && !spec.action.nil?
 
-			# Verification:
-			#
-			# 1. Check arguments recognised
-			# 1.a Flags
-			# 1.b Options
-			# 2. police any required options
-			# 3. Check values
+            spec.action.call(flag, spec)
+          end
+        else
 
-			# 1.a Flags
+          message = make_abort_message_("unrecognised flag '#{f}'")
 
-			self.flags.each do |flag|
+          if false
 
-				spec = specifications.detect do |sp|
+          elsif climate.ignore_unknown
 
-					sp.kind_of?(::CLASP::FlagSpecification) && flag.name == sp.name
-				end
+            ;
+          elsif raise_on_unrecognised
 
-				if spec
+            if raise_on_unrecognised.is_a?(Class)
 
-					if spec.respond_to?(:action) && !spec.action.nil?
+              raise raise_on_unrecognised, message
+            else
 
-						spec.action.call(flag, spec)
-					end
-				else
+              raise RuntimeError, message
+            end
+          elsif climate.exit_on_unknown
 
-					message = make_abort_message_("unrecognised flag '#{f}'")
+            climate.abort message
+          else
 
-					if false
+            if program_name && !program_name.empty?
 
-					elsif climate.ignore_unknown
+              message = "#{program_name}: #{message}"
+            end
 
-						;
-					elsif raise_on_unrecognised
+            climate.stderr.puts message
+          end
+        end
+      end
 
-						if raise_on_unrecognised.is_a?(Class)
+      # 1.b Options
 
-							raise raise_on_unrecognised, message
-						else
+      self.options.each do |option|
 
-							raise RuntimeError, message
-						end
-					elsif climate.exit_on_unknown
+        spec = specifications.detect do |sp|
 
-						climate.abort message
-					else
+          sp.kind_of?(::CLASP::OptionSpecification) && option.name == sp.name
+        end
 
-						if program_name && !program_name.empty?
+        if spec
 
-							message = "#{program_name}: #{message}"
-						end
+          if spec.respond_to?(:action) && !spec.action.nil?
 
-						climate.stderr.puts message
-					end
-				end
-			end
+            spec.action.call(option, spec)
+          end
+        else
 
-			# 1.b Options
+          message = make_abort_message_("unrecognised option '#{f}'")
 
-			self.options.each do |option|
+          if false
 
-				spec = specifications.detect do |sp|
+          elsif climate.ignore_unknown
 
-					sp.kind_of?(::CLASP::OptionSpecification) && option.name == sp.name
-				end
+            ;
+          elsif raise_on_unrecognised
 
-				if spec
+            if raise_on_unrecognised.is_a?(Class)
 
-					if spec.respond_to?(:action) && !spec.action.nil?
+              raise raise_on_unrecognised, message
+            else
 
-						spec.action.call(option, spec)
-					end
-				else
+              raise RuntimeError, message
+            end
+          elsif climate.exit_on_unknown
 
-					message = make_abort_message_("unrecognised option '#{f}'")
+            climate.abort message
+          else
 
-					if false
+            if program_name && !program_name.empty?
 
-					elsif climate.ignore_unknown
+              message = "#{program_name}: #{message}"
+            end
 
-						;
-					elsif raise_on_unrecognised
+            climate.stderr.puts message
+          end
+        end
+      end
 
-						if raise_on_unrecognised.is_a?(Class)
+      # 2. police any required options
 
-							raise raise_on_unrecognised, message
-						else
+      climate.check_required_options_(specifications, self.options, [], raise_on_required)
 
-							raise RuntimeError, message
-						end
-					elsif climate.exit_on_unknown
+      # 3. Check values
 
-						climate.abort message
-					else
+      climate.check_value_constraints_(values)
+    end
 
-						if program_name && !program_name.empty?
+    def flag_is_specified(id)
 
-							message = "#{program_name}: #{message}"
-						end
+      !@arguments.find_flag(id).nil?
+    end
 
-						climate.stderr.puts message
-					end
-				end
-			end
+    def lookup_flag(id)
 
-			# 2. police any required options
+      @arguments.find_flag(id)
+    end
 
-			climate.check_required_options_(specifications, self.options, [], raise_on_required)
+    def lookup_option(id)
 
-			# 3. Check values
+      @arguments.find_option(id)
+    end
 
-			climate.check_value_constraints_(values)
-		end
+  end # end class ParseResults
 
-		def flag_is_specified(id)
 
-			!@arguments.find_flag(id).nil?
-		end
+  #:stopdoc:
 
-		def lookup_flag(id)
+  private
+  module Climate_Constants_
 
-			@arguments.find_flag(id)
-		end
+    GIVEN_SPECS_ = "_Given_Specs_01B59422_8407_4c89_9432_8160C52BD5AD"
+  end # module Climate_Constants_
 
-		def lookup_option(id)
+  def make_abort_message_(msg)
 
-			@arguments.find_option(id)
-		end
+    if 0 != (usage_help_suffix || 0).size
 
-	end # end class ParseResults
+      "#{msg}; #{usage_help_suffix}"
+    else
 
+      msg
+    end
+  end
 
-	#:stopdoc:
+  def show_usage_()
 
-	private
-	module Climate_Constants_
+    options = {}
+    options.merge! stream: stdout, program_name: program_name, version: version, exit: exit_on_usage ? 0 : nil
+    options[:info_lines] = info_lines if info_lines
+    options[:values] = usage_values if usage_values
+    options[:flags_and_options] = flags_and_options if flags_and_options
 
-		GIVEN_SPECS_ = "_Given_Specs_01B59422_8407_4c89_9432_8160C52BD5AD"
-	end # module Climate_Constants_
+    CLASP.show_usage specifications, options
+  end
 
-	def make_abort_message_(msg)
+  def show_version_()
 
-		if 0 != (usage_help_suffix || 0).size
+    CLASP.show_version specifications, stream: stdout, program_name: program_name, version: version, exit: exit_on_usage ? 0 : nil
+  end
 
-			"#{msg}; #{usage_help_suffix}"
-		else
+  def infer_version_(ctxt)
 
-			msg
-		end
-	end
+    # algorithm:
+    #
+    # 1. PROGRAM_VERSION: loaded from ctxt / global
+    # 2. PROGRAM_VER(SION)_(MAJOR|MINOR|(PATCH|REVISION)|BUILD): loaded from
+    #    ctxt / global
 
-	def show_usage_()
+    if ctxt
 
-		options	=	{}
-		options.merge! stream: stdout, program_name: program_name, version: version, exit: exit_on_usage ? 0 : nil
-		options[:info_lines] = info_lines if info_lines
-		options[:values] = usage_values if usage_values
-		options[:flags_and_options] = flags_and_options if flags_and_options
+      ctxt = ctxt.class unless ::Class === ctxt
 
-		CLASP.show_usage specifications, options
-	end
+      return ctxt.const_get(:PROGRAM_VERSION) if ctxt.const_defined? :PROGRAM_VERSION
 
-	def show_version_()
+      ver = []
 
-		CLASP.show_version specifications, stream: stdout, program_name: program_name, version: version, exit: exit_on_usage ? 0 : nil
-	end
+      if ctxt.const_defined? :PROGRAM_VER_MAJOR
 
-	def infer_version_(ctxt)
+        ver << ctxt.const_get(:PROGRAM_VER_MAJOR)
 
-		# algorithm:
-		#
-		# 1. PROGRAM_VERSION: loaded from ctxt / global
-		# 2. PROGRAM_VER(SION)_(MAJOR|MINOR|(PATCH|REVISION)|BUILD): loaded from
-		#    ctxt / global
+        if ctxt.const_defined? :PROGRAM_VER_MINOR
 
-		if ctxt
+          ver << ctxt.const_get(:PROGRAM_VER_MINOR)
 
-			ctxt = ctxt.class unless ::Class === ctxt
+          if ctxt.const_defined?(:PROGRAM_VER_REVISION) || ctxt.const_defined?(:PROGRAM_VER_PATCH)
 
-			return ctxt.const_get(:PROGRAM_VERSION) if ctxt.const_defined? :PROGRAM_VERSION
+            if ctxt.const_defined?(:PROGRAM_VER_PATCH)
 
-			ver = []
+              ver << ctxt.const_get(:PROGRAM_VER_PATCH)
+            else
 
-			if ctxt.const_defined? :PROGRAM_VER_MAJOR
+              ver << ctxt.const_get(:PROGRAM_VER_REVISION)
+            end
 
-				ver << ctxt.const_get(:PROGRAM_VER_MAJOR)
+            if ctxt.const_defined? :PROGRAM_VER_BUILD
 
-				if ctxt.const_defined? :PROGRAM_VER_MINOR
+              ver << ctxt.const_get(:PROGRAM_VER_BUILD)
+            end
+          end
+        end
 
-					ver << ctxt.const_get(:PROGRAM_VER_MINOR)
+        return ver
+      end
+    else
 
-					if ctxt.const_defined?(:PROGRAM_VER_REVISION) || ctxt.const_defined?(:PROGRAM_VER_PATCH)
+      return PROGRAM_VERSION if defined? PROGRAM_VERSION
 
-						if ctxt.const_defined?(:PROGRAM_VER_PATCH)
+      ver = []
 
-							ver << ctxt.const_get(:PROGRAM_VER_PATCH)
-						else
+      if defined? PROGRAM_VER_MAJOR
 
-							ver << ctxt.const_get(:PROGRAM_VER_REVISION)
-						end
+        ver << PROGRAM_VER_MAJOR
 
-						if ctxt.const_defined? :PROGRAM_VER_BUILD
+        if defined? PROGRAM_VER_MINOR
 
-							ver << ctxt.const_get(:PROGRAM_VER_BUILD)
-						end
-					end
-				end
+          ver << PROGRAM_VER_MINOR
 
-				return ver
-			end
-		else
+          if defined?(PROGRAM_VER_REVISION) || defined?(PROGRAM_VER_PATCH)
 
-			return PROGRAM_VERSION if defined? PROGRAM_VERSION
+            if defined?(PROGRAM_VER_PATCH)
 
-			ver = []
+              ver << PROGRAM_VER_PATCH
+            else
 
-			if defined? PROGRAM_VER_MAJOR
+              ver << PROGRAM_VER_REVISION
+            end
 
-				ver << PROGRAM_VER_MAJOR
+            if defined? PROGRAM_VER_BUILD
 
-				if defined? PROGRAM_VER_MINOR
+              ver << PROGRAM_VER_BUILD
+            end
+          end
+        end
 
-					ver << PROGRAM_VER_MINOR
+        return ver
+      end
+    end
 
-					if defined?(PROGRAM_VER_REVISION) || defined?(PROGRAM_VER_PATCH)
+    nil
+  end
 
-						if defined?(PROGRAM_VER_PATCH)
+  def self.check_type_(v, types)
 
-							ver << PROGRAM_VER_PATCH
-						else
+    return true if v.nil?
 
-							ver << PROGRAM_VER_REVISION
-						end
+    types = [ types ] unless Array === types
 
-						if defined? PROGRAM_VER_BUILD
+    return true if types.empty?
 
-							ver << PROGRAM_VER_BUILD
-						end
-					end
-				end
+    types.each do |type|
 
-				return ver
-			end
-		end
+      if false
 
-		nil
-	end
+        ;
+      elsif :boolean == type
 
-	def self.check_type_(v, types)
+        return true if [ TrueClass, FalseClass ].include? v.class
+      elsif type.is_a?(Class)
 
-		return true if v.nil?
+        return true if v.is_a?(type)
+      elsif type.is_a?(Array)
 
-		types = [ types ] unless Array === types
+        t0 = type[0]
 
-		return true if types.empty?
+        if t0
 
-		types.each do |type|
+          #return true if v.is_a?
+        else
 
-			if false
+          # Can be array of anything
 
-				;
-			elsif :boolean == type
+          return true if v.is_a?(Array)
+        end
+      else
 
-				return true if [ TrueClass, FalseClass ].include? v.class
-			elsif type.is_a?(Class)
+        warn "Cannot validate type of '#{v}' (#{v.class}) against type specification '#{type}'"
+      end
+    end
 
-				return true if v.is_a?(type)
-			elsif type.is_a?(Array)
+    false
+  end
 
-				t0 = type[0]
+  def self.lookup_element_(h, types, name, path)
 
-				if t0
+    if h.has_key?(name)
 
-					#return true if v.is_a?
-				else
+      r = h[name]
 
-					# Can be array of anything
+      unless self.check_type_(r, types)
 
-					return true if v.is_a?(Array)
-				end
-			else
+        raise TypeError, "element '#{name}' is of type '#{r.class}' and '#{types}' is required"
+      end
 
-				warn "Cannot validate type of '#{v}' (#{v.class}) against type specification '#{type}'"
-			end
-		end
+      return r
+    end
 
-		false
-	end
+    nil
+  end
 
-	def self.lookup_element_(h, types, name, path)
+  def self.require_element_(h, types, name, path)
 
-		if h.has_key?(name)
+    unless h.has_key?(name)
 
-			r = h[name]
+      if (path || '').empty?
 
-			unless self.check_type_(r, types)
+        raise ArgumentError, "missing top-level element '#{name}' in load configuration"
+      else
 
-				raise TypeError, "element '#{name}' is of type '#{r.class}' and '#{types}' is required"
-			end
+        raise ArgumentError, "missing element '#{path}/#{name}' in load configuration"
+      end
+    else
 
-			return r
-		end
+      r = h[name]
 
-		nil
-	end
+      unless self.check_type_(r, types)
 
-	def self.require_element_(h, types, name, path)
+        raise TypeError, "element '#{name}' is of type '#{r.class}' and '#{types}' is required"
+      end
 
-		unless h.has_key?(name)
+      return r
+    end
+  end
 
-			if (path || '').empty?
+  public
+  def check_required_options_(specifications, options, missing, raise_on_required)
 
-				raise ArgumentError, "missing top-level element '#{name}' in load configuration"
-			else
+    required_specifications = specifications.select do |sp|
 
-				raise ArgumentError, "missing element '#{path}/#{name}' in load configuration"
-			end
-		else
+      sp.kind_of?(::CLASP::OptionSpecification) && sp.required?
+    end
 
-			r = h[name]
+    required_specifications = Hash[required_specifications.map { |sp| [ sp.name, sp ] }]
 
-			unless self.check_type_(r, types)
+    given_options = Hash[options.map { |o| [ o.name, o ]}]
 
-				raise TypeError, "element '#{name}' is of type '#{r.class}' and '#{types}' is required"
-			end
+    required_specifications.each do |k, sp|
 
-			return r
-		end
-	end
+      unless given_options.has_key? k
 
-	public
-	def check_required_options_(specifications, options, missing, raise_on_required)
+        message = sp.required_message
 
-		required_specifications = specifications.select do |sp|
+        if false
 
-			sp.kind_of?(::CLASP::OptionSpecification) && sp.required?
-		end
+          ;
+        elsif raise_on_required
 
-		required_specifications = Hash[required_specifications.map { |sp| [ sp.name, sp ] }]
+          if raise_on_required.is_a?(Class)
 
-		given_options = Hash[options.map { |o| [ o.name, o ]}]
+            raise raise_on_required, message
+          else
 
-		required_specifications.each do |k, sp|
+            raise RuntimeError, message
+          end
+        elsif exit_on_missing
 
-			unless given_options.has_key? k
+          self.abort message
+        else
 
-				message = sp.required_message
+          if program_name && !program_name.empty?
 
-				if false
+            message = "#{program_name}: #{message}"
+          end
 
-					;
-				elsif raise_on_required
+          stderr.puts message
+        end
 
-					if raise_on_required.is_a?(Class)
+        missing << sp
+        #results[:missing_option_aliases] << sp
+      end
+    end
+  end
 
-						raise raise_on_required, message
-					else
+  def check_value_constraints_(values)
 
-						raise RuntimeError, message
-					end
-				elsif exit_on_missing
+    # now police the values
 
-					self.abort message
-				else
+    values_constraint = constrain_values
+    values_constraint = values_constraint.begin if ::Range === values_constraint && values_constraint.end == values_constraint.begin
+    val_names         = ::Array === value_names ? value_names : []
 
-					if program_name && !program_name.empty?
+    case values_constraint
+    when nil
 
-						message = "#{program_name}: #{message}"
-					end
+      ;
+    when ::Array
 
-					stderr.puts message
-				end
+      warn "value of 'constrain_values' attribute, if an #{::Array}, must not be empty and all elements must be of type #{::Integer}" if values_constraint.empty? || !values_constraint.all? { |v| ::Integer === v }
 
-				missing << sp
-				#results[:missing_option_aliases] << sp
-			end
-		end
-	end
+      unless values_constraint.include? values.size
 
-	def check_value_constraints_(values)
+        message = make_abort_message_("wrong number of values: #{values.size} given, #{values_constraint} required")
 
-		# now police the values
+        if exit_on_missing
 
-		values_constraint	=	constrain_values
-		values_constraint	=	values_constraint.begin if ::Range === values_constraint && values_constraint.end == values_constraint.begin
-		val_names			=	::Array === value_names ? value_names : []
+          self.abort message
+        else
 
-		case values_constraint
-		when nil
+          if program_name && !program_name.empty?
 
-			;
-		when ::Array
+            message = "#{program_name}: #{message}"
+          end
 
-			warn "value of 'constrain_values' attribute, if an #{::Array}, must not be empty and all elements must be of type #{::Integer}" if values_constraint.empty? || !values_constraint.all? { |v| ::Integer === v }
+          stderr.puts message
+        end
+      end
+    when ::Integer
 
-			unless values_constraint.include? values.size
+      unless values.size == values_constraint
 
-				message = make_abort_message_("wrong number of values: #{values.size} given, #{values_constraint} required")
+        if name = val_names[values.size]
 
-				if exit_on_missing
+          message = make_abort_message_(name + ' not specified')
+        else
 
-					self.abort message
-				else
+          message = make_abort_message_("wrong number of values: #{values.size} given, #{values_constraint} required")
+        end
 
-					if program_name && !program_name.empty?
+        if exit_on_missing
 
-						message = "#{program_name}: #{message}"
-					end
+          self.abort message
+        else
 
-					stderr.puts message
-				end
-			end
-		when ::Integer
+          if program_name && !program_name.empty?
 
-			unless values.size == values_constraint
+            message = "#{program_name}: #{message}"
+          end
 
-				if name = val_names[values.size]
+          stderr.puts message
+        end
+      end
+    when ::Range
 
-					message = make_abort_message_(name + ' not specified')
-				else
+      unless values_constraint.include? values.size
 
-					message = make_abort_message_("wrong number of values: #{values.size} given, #{values_constraint} required")
-				end
+        if name = val_names[values.size]
 
-				if exit_on_missing
+          message = make_abort_message_(name + ' not specified')
+        else
 
-					self.abort message
-				else
+          message = make_abort_message_("wrong number of values: #{values.size} givens, #{values_constraint.begin} - #{values_constraint.end - (values_constraint.exclude_end? ? 1 : 0)} required")
+        end
 
-					if program_name && !program_name.empty?
+        if exit_on_missing
 
-						message = "#{program_name}: #{message}"
-					end
+          self.abort message
+        else
 
-					stderr.puts message
-				end
-			end
-		when ::Range
+          if program_name && !program_name.empty?
 
-			unless values_constraint.include? values.size
+            message = "#{program_name}: #{message}"
+          end
 
-				if name = val_names[values.size]
+          stderr.puts message
+        end
+      end
+    else
 
-					message = make_abort_message_(name + ' not specified')
-				else
+      warn "value of 'constrain_values' attribute - '#{constrain_values}' (#{constrain_values.class}) - of wrong type : must be #{::Array}, #{::Integer}, #{::Range}, or nil"
+    end
+  end
+  #:startdoc:
 
-					message = make_abort_message_("wrong number of values: #{values.size} givens, #{values_constraint.begin} - #{values_constraint.end - (values_constraint.exclude_end? ? 1 : 0)} required")
-				end
+  public
 
-				if exit_on_missing
+  # Loads an instance of the class, as specified by +source+, according to the given parameters
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +source+:: (+Hash+, +IO+) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification
+  #   - +options+:: An options hash, containing any of the following options
+  #
+  # * *Options:*
+  #   - +:no_help_flag+ (boolean) Prevents the use of the +CLASP::Flag.Help+ flag-specification
+  #   - +:no_version_flag+ (boolean) Prevents the use of the +CLASP::Flag.Version+ flag-specification
+  #   - +:program_name+ (::String) An explicit program-name, which is inferred from +$0+ if this is +nil+
+  #   - +:version+ (String, [Integer], [String]) A version specification. If not specified, this is inferred
+  #   - +:version_context+ Object or class that defines a context for searching the version. Ignored if +:version+ is specified
+  #
+  # * *Block* An optional block that receives the initialising Climate instance, allowing the user to modify the attributes.
+  def self.load(source, options = (options_defaulted_ = {}), &blk) # :yields: climate
 
-					self.abort message
-				else
+    check_parameter options, 'options', allow_nil: true, type: ::Hash
 
-					if program_name && !program_name.empty?
+    options ||= {}
 
-						message = "#{program_name}: #{message}"
-					end
+    h = nil
 
-					stderr.puts message
-				end
-			end
-		else
+    case source
+    when ::IO
 
-			warn "value of 'constrain_values' attribute - '#{constrain_values}' (#{constrain_values.class}) - of wrong type : must be #{::Array}, #{::Integer}, #{::Range}, or nil"
-		end
-	end
-	#:startdoc:
+      h = YAML.load source.read
+    when ::Hash
 
-	public
+      h = source
+    else
 
-	# Loads an instance of the class, as specified by +source+, according to the given parameters
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +source+:: (+Hash+, +IO+) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification
-	#   - +options+:: An options hash, containing any of the following options
-	#
-	# * *Options:*
-	#   - +:no_help_flag+ (boolean) Prevents the use of the +CLASP::Flag.Help+ flag-specification
-	#   - +:no_version_flag+ (boolean) Prevents the use of the +CLASP::Flag.Version+ flag-specification
-	#   - +:program_name+ (::String) An explicit program-name, which is inferred from +$0+ if this is +nil+
-	#   - +:version+ (String, [Integer], [String]) A version specification. If not specified, this is inferred
-	#   - +:version_context+ Object or class that defines a context for searching the version. Ignored if +:version+ is specified
-	#
-	# * *Block* An optional block that receives the initialising Climate instance, allowing the user to modify the attributes.
-	def self.load(source, options = (options_defaulted_ = {}), &blk) # :yields: climate
+      if source.respond_to?(:to_hash)
 
-		check_parameter options, 'options', allow_nil: true, type: ::Hash
+        h = source.to_hash
+      else
 
-		options ||= {}
+        raise TypeError, "#{self}.#{__method__}() 'source' argument must be a #{::Hash}, or an object implementing #{::IO}, or a type implementing 'to_hash'"
+      end
+    end
 
-		h = nil
+    _libclimate         = require_element_(h, Hash, 'libclimate', nil)
+    _exit_on_missing    = lookup_element_(_libclimate, :boolean, 'exit_on_missing', 'libclimate')
+    _ignore_unknown     = lookup_element_(_libclimate, :boolean, 'ignore_unknown', 'libclimate')
+    _exit_on_unknown    = lookup_element_(_libclimate, :boolean, 'exit_on_unknown', 'libclimate')
+    _exit_on_usage      = lookup_element_(_libclimate, :boolean, 'exit_on_usage', 'libclimate')
+    _info_lines         = lookup_element_(_libclimate, Array, 'info_lines', 'libclimate')
+    _program_name       = lookup_element_(_libclimate, String, 'program_name', 'libclimate')
+    _constrain_values   = lookup_element_(_libclimate, [ Integer, Range ], 'constrain_values', 'libclimate')
+    _flags_and_options  = lookup_element_(_libclimate, String, 'flags_and_options', 'libclimate')
+    _usage_values       = lookup_element_(_libclimate, String, 'usage_values', 'libclimate')
+    _value_names        = lookup_element_(_libclimate, Array, 'value_names', 'libclimate')
+    _version            = lookup_element_(_libclimate, [ String, [] ], 'version', 'libclimate')
 
-		case source
-		when ::IO
+    specs = CLASP::Arguments.load_specifications _libclimate, options
 
-			h = YAML.load source.read
-		when ::Hash
+    cl    = Climate.new(options.merge(Climate_Constants_::GIVEN_SPECS_ => specs), &blk)
 
-			h = source
-		else
+    cl.exit_on_missing    = _exit_on_missing unless _exit_on_missing.nil?
+    cl.ignore_unknown     = _ignore_unknown unless _ignore_unknown.nil?
+    cl.exit_on_unknown    = _exit_on_unknown unless _exit_on_unknown.nil?
+    cl.exit_on_usage      = _exit_on_usage unless _exit_on_usage.nil?
+    cl.info_lines         = _info_lines unless _info_lines.nil?
+    cl.program_name       = _program_name unless _program_name.nil?
+    cl.constrain_values   = _constrain_values unless _constrain_values.nil?
+    cl.flags_and_options  = _flags_and_options unless _flags_and_options.nil?
+    cl.usage_values       = _usage_values unless _usage_values.nil?
+    cl.value_names        = _value_names unless _value_names.nil?
+    cl.version            = _version unless _version.nil?
 
-			if source.respond_to?(:to_hash)
+    cl
+  end
 
-				h = source.to_hash
-			else
+  # Creates an instance of the Climate class.
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +options:+ (Hash) An options hash, containing any of the following options.
+  #
+  # * *Options:*
+  #   - +:no_help_flag+ (boolean) Prevents the use of the +CLASP::Flag.Help+ flag-specification
+  #   - +:no_version_flag+ (boolean) Prevents the use of the +CLASP::Flag.Version+ flag-specification
+  #   - +:program_name+ (::String) An explicit program-name, which is inferred from +$0+ if this is +nil+
+  #   - +:value_attributes+ (boolean) Causes any possible value-names, as described in `#value_names`, to be applied as attributes with the given values, if any, on the command-line
+  #   - +:version+ (String, [Integer], [String]) A version specification. If not specified, this is inferred
+  #   - +:version_context+ Object or class that defines a context for searching the version. Ignored if +:version+ is specified
+  #
+  # * *Block* An optional block that receives the initialising Climate instance, allowing the user to modify the attributes.
+  def initialize(options={}, &blk) # :yields: climate
+
+    check_parameter options, 'options', allow_nil: true, type: ::Hash
+
+    options ||= {}
+
+    check_option options, :no_help_flag, type: :boolean, allow_nil: true
+    check_option options, :no_version_flag, type: :boolean, allow_nil: true
+    check_option options, :program_name, type: ::String, allow_nil: true
+
+    pr_name = options[:program_name]
+
+    unless pr_name
+
+      pr_name = File.basename($0)
+      pr_name = (pr_name =~ /\.(?:bat|cmd|rb|sh)$/) ? "#$`(#$&)" : pr_name
+    end
+
+    given_specs         = options[Climate_Constants_::GIVEN_SPECS_]
+
+    @specifications     = []
+    @ignore_unknown     = false
+    @exit_on_unknown    = true
+    @exit_on_missing    = true
+    @exit_on_usage      = true
+    @info_lines         = nil
+    set_program_name pr_name
+    @stdout             = $stdout
+    @stderr             = $stderr
+    @constrain_values   = nil
+    @flags_and_options  = flags_and_options
+    @usage_help_suffix  = 'use --help for usage'
+    @usage_values       = usage_values
+    @value_names        = []
+    version_context     = options[:version_context]
+    @version            = options[:version] || infer_version_(version_context)
+
+    @value_attributes   = options[:value_attributes]
+
+    unless options[:no_help_flag]
+
+      f = CLASP::Flag.Help()
+
+      unless f.respond_to?(:action)
+
+        class << f
+
+          attr_accessor :action
+        end
+      end
+
+      f.action = Proc.new { show_usage_ }
+
+      @specifications << f
+    end
+
+    unless options[:no_version_flag]
+
+      f = CLASP::Flag.Version()
+
+      unless f.respond_to?(:action)
+
+        class << f
+
+          attr_accessor :action
+        end
+      end
+
+      f.action = Proc.new { show_version_ }
+
+      @specifications << f
+    end
+
+    @specifications = @specifications + given_specs if given_specs
+
+    yield self if block_given?
+  end
+
+  # [DEPRECATED] This method is now deprecated. Instead use +program_name=+
+  def set_program_name(name)
+
+    @program_name = name
+  end
+
+  # ([CLASP::Specification]) An array of specifications attached to the climate instance, whose contents should be modified by adding (or removing) CLASP specifications
+  attr_reader :specifications
+  # [DEPRECATED] Instead, use +specifications+
+  def aliases; specifications; end
+  # (boolean) Indicates whether exit will be called (with non-zero exit code) when a required command-line option is missing. Defaults to +true+
+  attr_accessor :exit_on_missing
+  # (boolean) Indicates whether unknown flags or options will be ignored. This overrides +:exit_on_unknown+. Defaults to +false+
+  attr_accessor :ignore_unknown
+  # (boolean) Indicates whether exit will be called (with non-zero exit code) when an unknown command-line flag or option is encountered. Defaults to +true+
+  attr_accessor :exit_on_unknown
+  # (boolean) Indicates whether exit will be called (with zero exit code) when usage/version is requested on the command-line. Defaults to +true+
+  attr_accessor :exit_on_usage
+  # ([String]) 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
+  attr_accessor :info_lines
+  # (String) A program name; defaults to the name of the executing script
+  def program_name
+
+    name = @program_name
+
+    if defined?(Colcon) && @stdout.tty?
+
+      name = "#{::Colcon::Decorations::Bold}#{name}#{::Colcon::Decorations::Unbold}"
+    end
+
+    name
+  end
+  # Sets the +program_name+ attribute
+  attr_writer :program_name
+  # @return (::IO) The output stream for normative output; defaults to $stdout
+  attr_accessor :stdout
+  # @return (::IO) The output stream for contingent output; defaults to $stderr
+  attr_accessor :stderr
+  # (Integer, Range) Optional constraint on the values that must be provided to the program
+  attr_accessor :constrain_values
+  # (String) Optional string to describe the flags and options section. Defaults to "[ +...+ +flags+ +and+ +options+ +...+ ]"
+  attr_accessor :flags_and_options
+  # (String) The string that is appended to #abort calls made during #run. Defaults to "use --help for usage"
+  attr_accessor :usage_help_suffix
+  # @return (::String) Optional string to describe the program values, eg \<xyz "[ { <<directory> | &lt;file> } ]"
+  attr_accessor :usage_values
+  # ([String]) Zero-based array of names for values to be used when that value is not present (according to the +:constrain_values+ attribute)
+  attr_accessor :value_names
+  # (String, [String], [Integer]) A version string or an array of integers/strings representing the version component(s)
+  attr_accessor :version
+
+  # Parse the given command-line (passed as +argv+) by the given instance
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +argv+ ([String]) The array of arguments; defaults to <tt>ARGV</tt>
+  #
+  # === Returns
+  # (ParseResults) Results
+  def parse(argv = ARGV, **options) # :yields: ParseResults
+
+    raise ArgumentError, "argv may not be nil" if argv.nil?
+
+    arguments = CLASP::Arguments.new argv, specifications
+
+    ParseResults.new(self, arguments, argv)
+  end
+
+  # Parse the given command-line (passed as +argv+) by the given instance,
+  # and verifies it
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +argv+ ([String]) The array of arguments; defaults to <tt>ARGV</tt>
+  #   - +options+ (Hash) Options
+  #
+  # * *Options:*
+  #   - +:raise_on_required+ (boolean, Exception) Causes an/the given exception to be raised if any required options are not specified in the command-line
+  #   - +:raise_on_unrecognised+ (boolean, Exception) Causes an/the given exception to be raised if any unrecognised flags/options are specified in the command-line
+  #   - +:raise_on_unused+ (boolean, Exception) Causes an/the given exception to be raised if any given flags/options are not used
+  #   - +:raise+ (boolean, Exception) Causes an/the given exception to be raised in all conditions
+  #
+  # === Returns
+  # (ParseResults) Results
+  def parse_and_verify(argv = ARGV, **options) # :yields: ParseResults
+
+    r = parse argv, **options
+
+    r.verify(**options)
+
+    r
+  end
+
+  # [DEPRECATED] Use +Climate#parse_and_verify()+ (but be aware that the
+  # returned result is of a different type
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +argv+ ([String]) The array of arguments; defaults to <tt>ARGV</tt>
+  #
+  # === Returns
+  # an instance of a type derived from +::Hash+ with the additional
+  # attributes +flags+, +options+, +values+, +double_slash_index+ and
+  # +argv+.
+  def run(argv = ARGV, **options) # :yields: customised +::Hash+
 
-				raise TypeError, "#{self}.#{__method__}() 'source' argument must be a #{::Hash}, or an object implementing #{::IO}, or a type implementing 'to_hash'"
-			end
-		end
+    raise ArgumentError, "argv may not be nil" if argv.nil?
 
-		_libclimate				=	require_element_(h, Hash, 'libclimate', nil)
-		_exit_on_missing		=	lookup_element_(_libclimate, :boolean, 'exit_on_missing', 'libclimate')
-		_ignore_unknown			=	lookup_element_(_libclimate, :boolean, 'ignore_unknown', 'libclimate')
-		_exit_on_unknown		=	lookup_element_(_libclimate, :boolean, 'exit_on_unknown', 'libclimate')
-		_exit_on_usage			=	lookup_element_(_libclimate, :boolean, 'exit_on_usage', 'libclimate')
-		_info_lines				=	lookup_element_(_libclimate, Array, 'info_lines', 'libclimate')
-		_program_name			=	lookup_element_(_libclimate, String, 'program_name', 'libclimate')
-		_constrain_values		=	lookup_element_(_libclimate, [ Integer, Range ], 'constrain_values', 'libclimate')
-		_flags_and_options		=	lookup_element_(_libclimate, String, 'flags_and_options', 'libclimate')
-		_usage_values			=	lookup_element_(_libclimate, String, 'usage_values', 'libclimate')
-		_value_names			=	lookup_element_(_libclimate, Array, 'value_names', 'libclimate')
-		_version				=	lookup_element_(_libclimate, [ String, [] ], 'version', 'libclimate')
+    arguments = CLASP::Arguments.new argv, specifications
 
-		specs					=	CLASP::Arguments.load_specifications _libclimate, options
+    run_ argv, arguments, **options
+  end
 
-		cl						=	Climate.new(options.merge(Climate_Constants_::GIVEN_SPECS_ => specs), &blk)
+  private
+  def run_(argv, arguments, **opts) # :nodoc:
 
-		cl.exit_on_missing		=	_exit_on_missing unless _exit_on_missing.nil?
-		cl.ignore_unknown		=	_ignore_unknown unless _ignore_unknown.nil?
-		cl.exit_on_unknown		=	_exit_on_unknown unless _exit_on_unknown.nil?
-		cl.exit_on_usage		=	_exit_on_usage unless _exit_on_usage.nil?
-		cl.info_lines			=	_info_lines unless _info_lines.nil?
-		cl.program_name			=	_program_name unless _program_name.nil?
-		cl.constrain_values		=	_constrain_values unless _constrain_values.nil?
-		cl.flags_and_options	=	_flags_and_options unless _flags_and_options.nil?
-		cl.usage_values			=	_usage_values unless _usage_values.nil?
-		cl.value_names			=	_value_names unless _value_names.nil?
-		cl.version				=	_version unless _version.nil?
+    flags   = arguments.flags
+    options = arguments.options
+    values  = arguments.values.to_a
 
-		cl
-	end
+    double_slash_index = arguments.double_slash_index
 
-	# Creates an instance of the Climate class.
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +options:+ (Hash) An options hash, containing any of the following options.
-	#
-	# * *Options:*
-	#   - +:no_help_flag+ (boolean) Prevents the use of the +CLASP::Flag.Help+ flag-specification
-	#   - +:no_version_flag+ (boolean) Prevents the use of the +CLASP::Flag.Version+ flag-specification
-	#   - +:program_name+ (::String) An explicit program-name, which is inferred from +$0+ if this is +nil+
-	#   - +:version+ (String, [Integer], [String]) A version specification. If not specified, this is inferred
-	#   - +:version_context+ Object or class that defines a context for searching the version. Ignored if +:version+ is specified
-	#
-	# * *Block* An optional block that receives the initialising Climate instance, allowing the user to modify the attributes.
-	def initialize(options={}, &blk) # :yields: climate
-
-		check_parameter options, 'options', allow_nil: true, type: ::Hash
-
-		options ||=	{}
-
-		check_option options, :no_help_flag, type: :boolean, allow_nil: true
-		check_option options, :no_version_flag, type: :boolean, allow_nil: true
-		check_option options, :program_name, type: ::String, allow_nil: true
-
-		pr_name		=	options[:program_name]
-
-		unless pr_name
-
-			pr_name	=	File.basename($0)
-			pr_name	=	(pr_name =~ /\.(?:bat|cmd|rb|sh)$/) ? "#$`(#$&)" : pr_name
-		end
-
-		given_specs			=	options[Climate_Constants_::GIVEN_SPECS_]
-
-		@specifications		=	[]
-		@ignore_unknown		=	false
-		@exit_on_unknown	=	true
-		@exit_on_missing	=	true
-		@exit_on_usage		=	true
-		@info_lines			=	nil
-		set_program_name pr_name
-		@stdout				=	$stdout
-		@stderr				=	$stderr
-		@constrain_values	=	nil
-		@flags_and_options	=	flags_and_options
-		@usage_help_suffix	=	'use --help for usage'
-		@usage_values		=	usage_values
-		@value_names		=	[]
-		version_context		=	options[:version_context]
-		@version			=	options[:version] || infer_version_(version_context)
-
-		unless options[:no_help_flag]
-
-			f	=	CLASP::Flag.Help()
-
-			unless f.respond_to?(:action)
-
-				class << f
-
-					attr_accessor :action
-				end
-			end
-
-			f.action = Proc.new { show_usage_ }
-
-			@specifications << f
-		end
-
-		unless options[:no_version_flag]
-
-			f	=	CLASP::Flag.Version()
-
-			unless f.respond_to?(:action)
-
-				class << f
-
-					attr_accessor :action
-				end
-			end
-
-			f.action = Proc.new { show_version_ }
-
-			@specifications << f
-		end
-
-		@specifications	=	@specifications + given_specs if given_specs
-
-		yield self if block_given?
-	end
-
-	# [DEPRECATED] This method is now deprecated. Instead use +program_name=+
-	def set_program_name(name)
-
-		@program_name = name
-	end
-
-	# ([CLASP::Specification]) An array of specifications attached to the climate instance, whose contents should be modified by adding (or removing) CLASP specifications
-	attr_reader :specifications
-	# [DEPRECATED] Instead, use +specifications+
-	def aliases; specifications; end
-	# (boolean) Indicates whether exit will be called (with non-zero exit code) when a required command-line option is missing. Defaults to +true+
-	attr_accessor :exit_on_missing
-	# (boolean) Indicates whether unknown flags or options will be ignored. This overrides +:exit_on_unknown+. Defaults to +false+
-	attr_accessor :ignore_unknown
-	# (boolean) Indicates whether exit will be called (with non-zero exit code) when an unknown command-line flag or option is encountered. Defaults to +true+
-	attr_accessor :exit_on_unknown
-	# (boolean) Indicates whether exit will be called (with zero exit code) when usage/version is requested on the command-line. Defaults to +true+
-	attr_accessor :exit_on_usage
-	# ([String]) 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
-	attr_accessor :info_lines
-	# (String) A program name; defaults to the name of the executing script
-	def program_name
-
-		name = @program_name
-
-		if defined?(Colcon) && @stdout.tty?
-
-			name = "#{::Colcon::Decorations::Bold}#{name}#{::Colcon::Decorations::Unbold}"
-		end
-
-		name
-	end
-	# Sets the +program_name+ attribute
-	attr_writer :program_name
-	# @return (::IO) The output stream for normative output; defaults to $stdout
-	attr_accessor :stdout
-	# @return (::IO) The output stream for contingent output; defaults to $stderr
-	attr_accessor :stderr
-	# (Integer, Range) Optional constraint on the values that must be provided to the program
-	attr_accessor :constrain_values
-	# (String) Optional string to describe the flags and options section. Defaults to "[ +...+ +flags+ +and+ +options+ +...+ ]"
-	attr_accessor :flags_and_options
-	# (String) The string that is appended to #abort calls made during #run. Defaults to "use --help for usage"
-	attr_accessor :usage_help_suffix
-	# @return (::String) Optional string to describe the program values, eg \<xyz "[ { <<directory> | &lt;file> } ]"
-	attr_accessor :usage_values
-	# ([String]) Zero-based array of names for values to be used when that value is not present (according to the +:constrain_values+ attribute)
-	attr_accessor :value_names
-	# (String, [String], [Integer]) A version string or an array of integers/strings representing the version component(s)
-	attr_accessor :version
-
-	# Parse the given command-line (passed as +argv+) by the given instance
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +argv+ ([String]) The array of arguments; defaults to <tt>ARGV</tt>
-	#
-	# === Returns
-	# (ParseResults) Results
-	def parse(argv = ARGV) # :yields: ParseResults
-
-		raise ArgumentError, "argv may not be nil" if argv.nil?
-
-		arguments = CLASP::Arguments.new argv, specifications
-
-		ParseResults.new(self, arguments, argv)
-	end
-
-	# Parse the given command-line (passed as +argv+) by the given instance,
-	# and verifies it
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +argv+ ([String]) The array of arguments; defaults to <tt>ARGV</tt>
-	#   - +options+ (Hash) Options
-	#
-	# * *Options:*
-	#   - +:raise_on_required+ (boolean, Exception) Causes an/the given exception to be raised if any required options are not specified in the command-line
-	#   - +:raise_on_unrecognised+ (boolean, Exception) Causes an/the given exception to be raised if any unrecognised flags/options are specified in the command-line
-	#   - +:raise_on_unused+ (boolean, Exception) Causes an/the given exception to be raised if any given flags/options are not used
-	#   - +:raise+ (boolean, Exception) Causes an/the given exception to be raised in all conditions
-	#
-	# === Returns
-	# (ParseResults) Results
-	def parse_and_verify(argv = ARGV, **options) # :yields: ParseResults
-
-		r = parse argv
-
-		r.verify(**options)
-
-		r
-	end
-
-	# [DEPRECATED] Use +Climate#parse_and_verify()+ (but be aware that the
-	# returned result is of a different type
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +argv+ ([String]) The array of arguments; defaults to <tt>ARGV</tt>
-	#
-	# === Returns
-	# an instance of a type derived from +::Hash+ with the additional
-	# attributes +flags+, +options+, +values+, +double_slash_index+ and
-	# +argv+.
-	def run(argv = ARGV) # :yields: customised +::Hash+
+    results = {
 
-		raise ArgumentError, "argv may not be nil" if argv.nil?
+      flags: {
 
-		arguments = CLASP::Arguments.new argv, specifications
+        given:      flags,
+        handled:    [],
+        unhandled:  [],
+        unknown:    [],
+      },
 
-		run_ argv, arguments
-	end
+      options: {
 
-	private
-	def run_(argv, arguments) # :nodoc:
+        given:      options,
+        handled:    [],
+        unhandled:  [],
+        unknown:  [],
+      },
 
-		flags		=	arguments.flags
-		options		=	arguments.options
-		values		=	arguments.values.to_a
+      values: values,
 
-		double_slash_index	=	arguments.double_slash_index
+      missing_option_aliases: [],
+    }
 
-		results		=	{
+    # Verification:
+    #
+    # 1. Check arguments recognised
+    # 1.a Flags
+    # 1.b Options
+    # 2. police any required options
+    # 3. Check values
 
-			flags: {
+    # 1.a Flags
 
-				given:		flags,
-				handled:	[],
-				unhandled:	[],
-				unknown:	[],
-			},
+    flags.each do |f|
 
-			options: {
+      spec = specifications.detect do |sp|
 
-				given:		options,
-				handled:	[],
-				unhandled:	[],
-				unknown:	[],
-			},
+        sp.kind_of?(::CLASP::FlagSpecification) && f.name == sp.name
+      end
 
-			values:	values,
+      if spec
 
-			missing_option_aliases: [],
-		}
+        selector = :unhandled
 
-		# Verification:
-		#
-		# 1. Check arguments recognised
-		# 1.a Flags
-		# 1.b Options
-		# 2. police any required options
-		# 3. Check values
+        if spec.respond_to?(:action) && !spec.action.nil?
 
-		# 1.a Flags
+          spec.action.call(f, spec)
 
-		flags.each do |f|
+          selector = :handled
+        end
 
-			spec = specifications.detect do |sp|
+        results[:flags][selector] << f
+      else
 
-				sp.kind_of?(::CLASP::FlagSpecification) && f.name == sp.name
-			end
+        message = make_abort_message_("unrecognised flag '#{f}'")
 
-			if spec
+        if false
 
-				selector	=	:unhandled
+        elsif ignore_unknown
 
-				if spec.respond_to?(:action) && !spec.action.nil?
+          ;
+        elsif exit_on_unknown
 
-					spec.action.call(f, spec)
+          self.abort message
+        else
 
-					selector = :handled
-				end
+          if program_name && !program_name.empty?
 
-				results[:flags][selector] << f
-			else
+            message = "#{program_name}: #{message}"
+          end
 
-				message = make_abort_message_("unrecognised flag '#{f}'")
+          stderr.puts message
+        end
 
-				if false
+        results[:flags][:unknown] << f
+      end
+    end
 
-				elsif ignore_unknown
+    # 1.b Options
 
-					;
-				elsif exit_on_unknown
+    options.each do |o|
 
-					self.abort message
-				else
+      spec = specifications.detect do |sp|
 
-					if program_name && !program_name.empty?
+        sp.kind_of?(::CLASP::OptionSpecification) && o.name == sp.name
+      end
 
-						message = "#{program_name}: #{message}"
-					end
+      if spec
 
-					stderr.puts message
-				end
+        selector = :unhandled
 
-				results[:flags][:unknown] << f
-			end
-		end
+        if spec.respond_to?(:action) && !spec.action.nil?
 
-		# 1.b Options
+          spec.action.call(o, spec)
 
-		options.each do |o|
+          selector = :handled
+        end
 
-			spec = specifications.detect do |sp|
+        results[:options][selector] << o
+      else
 
-				sp.kind_of?(::CLASP::OptionSpecification) && o.name == sp.name
-			end
+        message = make_abort_message_("unrecognised option '#{o}'")
 
-			if spec
+        if false
 
-				selector	=	:unhandled
+        elsif ignore_unknown
 
-				if spec.respond_to?(:action) && !spec.action.nil?
+          ;
+        elsif exit_on_unknown
 
-					spec.action.call(o, spec)
+          self.abort message
+        else
 
-					selector = :handled
-				end
+          if program_name && !program_name.empty?
 
-				results[:options][selector] << o
-			else
+            message = "#{program_name}: #{message}"
+          end
 
-				message = make_abort_message_("unrecognised option '#{o}'")
+          stderr.puts message
+        end
 
-				if false
+        results[:options][:unknown] << o
+      end
+    end
 
-				elsif ignore_unknown
+    # 2. police any required options
 
-					;
-				elsif exit_on_unknown
+    check_required_options_(specifications, results[:options][:given], results[:missing_option_aliases], false)
 
-					self.abort message
-				else
+    # 3. Check values
 
-					if program_name && !program_name.empty?
+    check_value_constraints_(values)
 
-						message = "#{program_name}: #{message}"
-					end
 
-					stderr.puts message
-				end
 
-				results[:options][:unknown] << o
-			end
-		end
+    def results.flags
 
-		# 2. police any required options
+      self[:flags]
+    end
 
-		check_required_options_(specifications, results[:options][:given], results[:missing_option_aliases], false)
+    def results.options
 
-		# 3. Check values
+      self[:options]
+    end
 
-		check_value_constraints_(values)
+    def results.values
 
+      self[:values]
+    end
 
+    results.define_singleton_method(:double_slash_index) do
 
-		def results.flags
+      double_slash_index
+    end
 
-			self[:flags]
-		end
+    results.define_singleton_method(:argv) do
 
-		def results.options
+      argv
+    end
 
-			self[:options]
-		end
 
-		def results.values
+    if opts[:value_attributes] || @value_attributes
 
-			self[:values]
-		end
+      (value_names || []).each_with_index do |name, index|
 
-		results.define_singleton_method(:double_slash_index) do
+      name = name.gsub(/-/, '_').to_sym
 
-			double_slash_index
-		end
+      if results.respond_to? name
 
-		results.define_singleton_method(:argv) do
+        warn "cannot create attribute `#{name}` on instance of `#{results.class}` because that name is already used"
+      else
 
-			argv
-		end
+        value = results.values[index]
 
-		results
-	end
-	public
+        results.define_singleton_method(name) do
 
-	# Calls abort() with the given message prefixed by the program_name
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +message+ (String) The message string
-	#   - +options+ (Hash) 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+ (String) {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 explicitly
-	#
-	# === Returns
-	# The combined message string, if <tt>exit()</tt> not called.
-	def abort(message, options={})
+        value
+        end
+      end
+      end
+    end
 
-		prog_name	=	options[:program_name]
-		prog_name	||=	program_name
-		prog_name	||=	''
 
-		stream		=	options[:stream]
-		stream		||=	stderr
-		stream		||=	$stderr
+    results.freeze
 
-		exit_code	=	options.has_key?(:exit) ? options[:exit] : 1
+    results
+  end
+  public
 
-		if prog_name.empty?
+  # Calls abort() with the given message prefixed by the program_name
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +message+ (String) The message string
+  #   - +options+ (Hash) 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+ (String) {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 explicitly
+  #
+  # === Returns
+  # The combined message string, if <tt>exit()</tt> not called.
+  def abort(message, options={})
 
-			msg = message
-		else
-
-			msg = "#{prog_name}: #{message}"
-		end
-
-
-		stream.puts msg
-
-		exit(exit_code) if exit_code
-
-		msg
-	end
-
-	# Adds a flag to +specifications+
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +name_or_flag+ (String, ::CLASP::FlagSpecification) The flag name or instance of CLASP::FlagSpecification
-	#   - +options+ (Hash) An options hash, containing any of the following options
-	#
-	# * *Options:*
-	#   - +:alias+ (String) A single alias
-	#   - +:aliases+ ([String]) An array of aliases
-	#   - +:help+ (String) Description string used when writing response to "+--help+" flag
-	#   - +:required+ (boolean) Indicates whether the flag is required, causing #run to fail with appropriate message if the flag is not specified in the command-line arguments
-	#
-	# * *Block* An optional block that is invoked when the parsed command-line contains the given flag, receiving the argument and the alias
-	#
-	# === Examples
-	#
-	# ==== Specification(s) of a flag (single statement)
-	#
-	def add_flag(name_or_flag, options={}, &blk)
-
-		check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ]
-
-		if ::CLASP::FlagSpecification === name_or_flag
-
-			specifications << name_or_flag
-		else
-
-			specifications << CLASP.Flag(name_or_flag, **options, &blk)
-		end
-	end
-
-	# Adds an option to +specifications+
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +name_or_option+ (String, CLASP::OptionSpecification) The option name or instance of CLASP::OptionSpecification
-	#   - +options+ (Hash) An options hash, containing any of the following options
-	#
-	# * *Options:*
-	#   - +:alias+ (String) A single alias
-	#   - +:aliases+ ([String]) An array of aliases
-	#   - +:help+ (String) Description string used when writing response to "+--help+" flag
-	#   - +:values_range+ ([String]) An array of strings representing the valid/expected values used when writing response to "+--help+" flag. NOTE: the current version does not validate against these values, but a future version may do so
-	#   - +:default_value+ (String) The default version used when, say, for the option +--my-opt+ the command-line contain the argument "+--my-opt=+"
-	#
-	# * *Block* An optional block that is invoked when the parsed command-line contains the given option, receiving the argument and the alias
-	#
-	def add_option(name_or_option, options={}, &blk)
-
-		check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ]
-
-		if ::CLASP::OptionSpecification === name_or_option
-
-			specifications << name_or_option
-		else
-
-			specifications << CLASP.Option(name_or_option, **options, &blk)
-		end
-	end
-
-	# Adds an alias to +specifications+
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +name_or_specification+ (String) The flag/option name or the valued option
-	#   - +aliases+ (*[String]) One or more aliases
-	#
-	# === Examples
-	#
-	# ==== Specification(s) of a flag (single statement)
-	#
-	#  climate.add_flag('--mark-missing', alias: '-x')
-	#
-	#  climate.add_flag('--absolute-path', aliases: [ '-abs', '-p' ])
-	#
-	# ==== Specification(s) 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')
-	#
-	# ==== Specification(s) of an option (single statement)
-	#
-	#  climate.add_option('--add-patterns', alias: '-p')
-	#
-	# ==== Specification(s) of an option (multiple statements)
-	#
-	#  climate.add_option('--add-patterns')
-	#  climate.add_alias('--add-patterns', '-p')
-	#
-	# ==== Specification of a valued option (which has to be multiple statements)
-	#
-	#  climate.add_option('--verbosity', values: [ 'succinct', 'verbose' ])
-	#  climate.add_alias('--verbosity=succinct', '-s')
-	#  climate.add_alias('--verbosity=verbose', '-v')
-	def add_alias(name_or_specification, *aliases)
-
-		check_parameter name_or_specification, 'name_or_specification', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification, ::CLASP::OptionSpecification ]
-		raise ArgumentError, "must supply at least one alias" if aliases.empty?
-
-		case name_or_specification
-		when ::CLASP::FlagSpecification
-
-			self.specifications << name_or_specification
-		when ::CLASP::OptionSpecification
-
-			self.specifications << name_or_specification
-		else
-
-			self.specifications << CLASP.Alias(name_or_specification, aliases: aliases)
-		end
-	end
-
-	# Attaches a block to an already-registered flag
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +name_or_flag+ (String, ::CLASP::FlagSpecification) The flag name or instance of CLASP::FlagSpecification
-	#   - +options+ (Hash) An options hash, containing any of the following options. No options are recognised currently
-	#
-	# * *Options:*
-	#
-	# * *Block* A required block that is invoked when the parsed command-line contains the given flag, receiving the argument and the alias
-	#
-	def on_flag(name_or_flag, options={}, &blk)
-
-		check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ]
-
-		raise ArgumentError, "on_flag() requires a block to be given" unless block_given?
-
-		specifications.each do |spec|
-
-			case spec
-			when CLASP::FlagSpecification
-
-				if spec == name_or_flag
-
-					spec.action = blk
-
-					return true
-				end
-			end
-		end
-
-		warn "The Climate instance does not contain a FlagSpecification matching '#{name_or_flag}' (#{name_or_flag.class})"
-
-		false
-	end
-
-	# Attaches a block to an already-registered option
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +name_or_option+ (String, ::CLASP::OptionSpecification) The option name or instance of CLASP::OptionSpecification
-	#   - +options+ (Hash) An options hash, containing any of the following options. No options are recognised currently
-	#
-	# * *Options:*
-	#
-	# * *Block* A required block that is invoked when the parsed command-line contains the given option, receiving the argument and the alias
-	#
-	def on_option(name_or_option, options={}, &blk)
-
-		check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ]
-
-		raise ArgumentError, "on_option() requires a block to be given" unless block_given?
-
-		specifications.each do |spec|
-
-			case spec
-			when CLASP::OptionSpecification
-
-				if spec == name_or_option
-
-					spec.action = blk
-
-					return true
-				end
-			end
-		end
-
-		warn "The Climate instance does not contain an OptionSpecification matching '#{name_or_option}' (#{name_or_option.class})"
+    prog_name =   options[:program_name]
+    prog_name ||= program_name
+    prog_name ||= ''
 
-		false
-	end
+    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
+
+  # Adds a flag to +specifications+
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +name_or_flag+ (String, ::CLASP::FlagSpecification) The flag name or instance of CLASP::FlagSpecification
+  #   - +options+ (Hash) An options hash, containing any of the following options
+  #
+  # * *Options:*
+  #   - +:alias+ (String) A single alias
+  #   - +:aliases+ ([String]) An array of aliases
+  #   - +:help+ (String) Description string used when writing response to "+--help+" flag
+  #   - +:required+ (boolean) Indicates whether the flag is required, causing #run to fail with appropriate message if the flag is not specified in the command-line arguments
+  #
+  # * *Block* An optional block that is invoked when the parsed command-line contains the given flag, receiving the argument and the alias
+  #
+  # === Examples
+  #
+  # ==== Specification(s) of a flag (single statement)
+  #
+  def add_flag(name_or_flag, options={}, &blk)
+
+    check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ]
+
+    if ::CLASP::FlagSpecification === name_or_flag
+
+      specifications << name_or_flag
+    else
+
+      specifications << CLASP.Flag(name_or_flag, **options, &blk)
+    end
+  end
+
+  # Adds an option to +specifications+
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +name_or_option+ (String, CLASP::OptionSpecification) The option name or instance of CLASP::OptionSpecification
+  #   - +options+ (Hash) An options hash, containing any of the following options
+  #
+  # * *Options:*
+  #   - +:alias+ (String) A single alias
+  #   - +:aliases+ ([String]) An array of aliases
+  #   - +:help+ (String) Description string used when writing response to "+--help+" flag
+  #   - +:values_range+ ([String]) An array of strings representing the valid/expected values used when writing response to "+--help+" flag. NOTE: the current version does not validate against these values, but a future version may do so
+  #   - +:default_value+ (String) The default version used when, say, for the option +--my-opt+ the command-line contain the argument "+--my-opt=+"
+  #
+  # * *Block* An optional block that is invoked when the parsed command-line contains the given option, receiving the argument and the alias
+  #
+  def add_option(name_or_option, options={}, &blk)
+
+    check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ]
+
+    if ::CLASP::OptionSpecification === name_or_option
+
+      specifications << name_or_option
+    else
+
+      specifications << CLASP.Option(name_or_option, **options, &blk)
+    end
+  end
+
+  # Adds an alias to +specifications+
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +name_or_specification+ (String) The flag/option name or the valued option
+  #   - +aliases+ (*[String]) One or more aliases
+  #
+  # === Examples
+  #
+  # ==== Specification(s) of a flag (single statement)
+  #
+  #  climate.add_flag('--mark-missing', alias: '-x')
+  #
+  #  climate.add_flag('--absolute-path', aliases: [ '-abs', '-p' ])
+  #
+  # ==== Specification(s) 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')
+  #
+  # ==== Specification(s) of an option (single statement)
+  #
+  #  climate.add_option('--add-patterns', alias: '-p')
+  #
+  # ==== Specification(s) of an option (multiple statements)
+  #
+  #  climate.add_option('--add-patterns')
+  #  climate.add_alias('--add-patterns', '-p')
+  #
+  # ==== Specification of a valued option (which has to be multiple statements)
+  #
+  #  climate.add_option('--verbosity', values: [ 'succinct', 'verbose' ])
+  #  climate.add_alias('--verbosity=succinct', '-s')
+  #  climate.add_alias('--verbosity=verbose', '-v')
+  def add_alias(name_or_specification, *aliases)
+
+    check_parameter name_or_specification, 'name_or_specification', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification, ::CLASP::OptionSpecification ]
+    raise ArgumentError, "must supply at least one alias" if aliases.empty?
+
+    case name_or_specification
+    when ::CLASP::FlagSpecification
+
+      self.specifications << name_or_specification
+    when ::CLASP::OptionSpecification
+
+      self.specifications << name_or_specification
+    else
+
+      self.specifications << CLASP.Alias(name_or_specification, aliases: aliases)
+    end
+  end
+
+  # Attaches a block to an already-registered flag
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +name_or_flag+ (String, ::CLASP::FlagSpecification) The flag name or instance of CLASP::FlagSpecification
+  #   - +options+ (Hash) An options hash, containing any of the following options. No options are recognised currently
+  #
+  # * *Options:*
+  #
+  # * *Block* A required block that is invoked when the parsed command-line contains the given flag, receiving the argument and the alias
+  #
+  def on_flag(name_or_flag, options={}, &blk)
+
+    check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ]
+
+    raise ArgumentError, "on_flag() requires a block to be given" unless block_given?
+
+    specifications.each do |spec|
+
+      case spec
+      when CLASP::FlagSpecification
+
+        if spec == name_or_flag
+
+          spec.action = blk
+
+          return true
+        end
+      end
+    end
+
+    warn "The Climate instance does not contain a FlagSpecification matching '#{name_or_flag}' (#{name_or_flag.class})"
+
+    false
+  end
+
+  # Attaches a block to an already-registered option
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #   - +name_or_option+ (String, ::CLASP::OptionSpecification) The option name or instance of CLASP::OptionSpecification
+  #   - +options+ (Hash) An options hash, containing any of the following options. No options are recognised currently
+  #
+  # * *Options:*
+  #
+  # * *Block* A required block that is invoked when the parsed command-line contains the given option, receiving the argument and the alias
+  #
+  def on_option(name_or_option, options={}, &blk)
+
+    check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ]
+
+    raise ArgumentError, "on_option() requires a block to be given" unless block_given?
+
+    specifications.each do |spec|
+
+      case spec
+      when CLASP::OptionSpecification
+
+        if spec == name_or_option
+
+          spec.action = blk
+
+          return true
+        end
+      end
+    end
+
+    warn "The Climate instance does not contain an OptionSpecification matching '#{name_or_option}' (#{name_or_option.class})"
+
+    false
+  end
 end # class Climate
 end # module LibCLImate
 
+
 # ############################## end of file ############################# #