libclimate-ruby 0.14.0.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e9c4224cfebaa4069ba4cd5544fa888b1223fed
-  data.tar.gz: f5b70a644cae5c0431a038f6f6afbfc0ce29da7b
+  metadata.gz: 3b5494527c8f55a49015bfa7fb78ee362315a117
+  data.tar.gz: ed66aad3de517bf0aa0689c40cfd4f469a820ad1
 SHA512:
-  metadata.gz: 6ee75cc2c09e1490dc92567a8dadb5cc091ea92e8c455fe823ba1179449c5c91453d1e290df7557927c64dfe02ad1074081ef2ac71d0b827e2d7e2309ea0a29b
-  data.tar.gz: beaca3d7b2e613565d1169acc705bf62750677877b6d80d04d05583e1bcd1e2c358b0c5d175c3d9630b19bd70f0a6ec30be47b2acc84c0301b7fd9125f431a4c
+  metadata.gz: 0b1eece97175423d77773c767dacf8148ea03dfd73c38a11840bf3eb0bfaeab54120be55ac5975c6e5cad9ca7afc82016750856bfccdffa091fa3a709b7141bf
+  data.tar.gz: 4913b8c35f85347a4c3ccbbe8cf9e89d74caaafdcfc9aa2eb8ac30f3f3d4cc5e7878a779326ac821b6a37f1d6b5f9270dc26f5fa9c5ea415d00d479fcf9ff197

data/README.md

@@ -3,6 +3,14 @@ libCLImate, for Ruby
 
 [![Gem Version](https://badge.fury.io/rb/libclimate-ruby.svg)](https://badge.fury.io/rb/libclimate-ruby)
 
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Installation](#installation)
+3. [Components](#components)
+4. [Examples](#examples)
+5. [Project Information](#project-information)
+
 ## Introduction
 
 **libCLImate** is a portable, lightweight mini-framework that encapsulates the common aspects of **C**ommand-**L**ine **I**nterface boilerplate, including:
@@ -12,14 +20,6 @@ libCLImate, for Ruby
 
 **libCLImate.Ruby** is the Ruby version.
 
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [Installation](#installation)
-3. [Components](#components)
-4. [Examples](#examples)
-5. [Project Information](#project-information)
-
 ## Installation
 
 Install via **gem** as in:
@@ -38,7 +38,41 @@ require 'libclimate'
 
 ## Components
 
-T.B.C.
+In common with several other variants of **libCLImate**, **libCLImate.Ruby** revolves around a ``Climate`` ``class`` whose initialiser takes a block and acts as a lightweight DSL for concise definition of a command-line parsing instance, as in:
+
+```Ruby
+options = {}
+climate = LibCLImate::Climate.new do |cl|
+
+	cl.add_flag('--debug', alias: '-d', help: 'runs in Debug mode') do
+
+		options[:debug] = true
+	end
+	cl.add_option('--verbosity', alias: '-v', help: 'specifies the verbosity', values: [ 'terse', 'quiet', 'silent', 'chatty' ]) do |o, a|
+
+		options[:verbosity] = o.value
+	end
+	cl.add_alias('--verbosity=chatty', '-c')
+
+	cl.version = [ 0, 1, 0 ]
+
+	cl.info_lines =  [
+
+		'libCLImate.Ruby examples',
+		:version,
+		"Illustrates use of libCLImate.Ruby's specification of flags, options, and specifications",
+		'',
+	]
+
+	cl.constrain_values = 1..2
+	cl.usage_values = "<dir-1> [ <dir-2> ]"
+	cl.value_names = [
+
+		"first directory",
+		"second directory",
+	]
+end
+```
 
 ## Examples
 

data/examples/flag_and_option_specifications.from_DATA.md

@@ -27,7 +27,7 @@ climate = LibCLImate::Climate.load DATA do |cl|
 	cl.on_option('--verbosity') { |o, a| options[:verbosity] = o.value }
 end
 
-r = climate.run ARGV
+r = climate.parse_and_verify ARGV
 
 
 # Program-specific processing of flags/options
@@ -87,10 +87,8 @@ libclimate:
   -
   version:
   - 0
-  - 1
-  - "2"
-```
-```ruby
+  - 2
+  - "0"
 ```
 
 ## Usage
@@ -130,7 +128,7 @@ it gives the output:
 
 ```
 libCLImate.Ruby examples
-flag_and_option_specifications.from_DATA(.rb) 0.1.2
+flag_and_option_specifications.from_DATA(.rb) 0.2.0
 Illustrates use of libCLImate.Ruby's specification of flags, options, and aliases, from DATA
 
 USAGE: flag_and_option_specifications.from_DATA(.rb) [... flags/options ...] <dir-1> [ <dir-2> ]

data/examples/flag_and_option_specifications.from_DATA.rb

@@ -18,7 +18,7 @@ climate = LibCLImate::Climate.load DATA do |cl|
 	cl.on_option('--verbosity') { |o, a| options[:verbosity] = o.value }
 end
 
-r = climate.run ARGV
+r = climate.parse_and_verify ARGV
 
 
 # Program-specific processing of flags/options
@@ -78,6 +78,6 @@ libclimate:
   -
   version:
   - 0
-  - 1
-  - "2"
+  - 2
+  - "0"
 

data/examples/flag_and_option_specifications.md

@@ -30,7 +30,7 @@ climate = LibCLImate::Climate.new do |cl|
 	end
 	cl.add_alias('--verbosity=chatty', '-c')
 
-	cl.version = [ 0, 0, 1 ]
+	cl.version = [ 0, 1, 0 ]
 
 	cl.info_lines =  [
 
@@ -39,9 +39,17 @@ climate = LibCLImate::Climate.new do |cl|
 		"Illustrates use of libCLImate.Ruby's specification of flags, options, and specifications",
 		'',
 	]
+
+	cl.constrain_values = 1..2
+	cl.usage_values = "<dir-1> [ <dir-2> ]"
+	cl.value_names = [
+
+		"first directory",
+		"second directory",
+	]
 end
 
-r = climate.run ARGV
+r = climate.parse_and_verify ARGV
 
 
 
@@ -56,6 +64,10 @@ if options[:debug]
 
 	$stdout.puts 'Debug mode is specified'
 end
+
+# some notional output
+
+$stdout.puts "processing in '#{r.values[0]}'" + (r.values.size > 1 ? " and '#{r.values[1]}'" : '')
 ```
 
 ## Usage
@@ -77,6 +89,7 @@ or (in a Unix shell):
 it gives the output:
 
 ```
+flag_and_option_specifications(.rb): first directory not specified; use --help for usage
 ```
 
 ### Show usage
@@ -91,7 +104,7 @@ it gives the output:
 
 ```
 libCLImate.Ruby examples
-flag_and_option_specifications.rb 0.0.1
+flag_and_option_specifications.rb 0.1.0
 Illustrates use of libCLImate.Ruby's specification of flags, options, and specifications
 
 USAGE: flag_and_option_specifications.rb [ ... flags and options ... ]
@@ -124,7 +137,7 @@ flags/options:
 If executed with the arguments
 
 ```
-    ruby examples/flag_and_option_specifications.rb --debug --verbosity=silent
+    ruby examples/flag_and_option_specifications.rb dir-1 dir-2 --debug --verbosity=silent
 ```
 
 it gives the output:
@@ -132,6 +145,7 @@ it gives the output:
 ```
 verbosity is specified as: silent
 Debug mode is specified
+processing in 'dir-1' and 'dir-2'
 ```
 
 ### Specify flags and options in short-form

data/examples/flag_and_option_specifications.rb

@@ -21,7 +21,7 @@ climate = LibCLImate::Climate.new do |cl|
 	end
 	cl.add_alias('--verbosity=chatty', '-c')
 
-	cl.version = [ 0, 0, 1 ]
+	cl.version = [ 0, 1, 0 ]
 
 	cl.info_lines =  [
 
@@ -30,9 +30,17 @@ climate = LibCLImate::Climate.new do |cl|
 		"Illustrates use of libCLImate.Ruby's specification of flags, options, and specifications",
 		'',
 	]
+
+	cl.constrain_values = 1..2
+	cl.usage_values = "<dir-1> [ <dir-2> ]"
+	cl.value_names = [
+
+		"first directory",
+		"second directory",
+	]
 end
 
-r = climate.run ARGV
+r = climate.parse_and_verify ARGV
 
 
 
@@ -49,5 +57,7 @@ if options[:debug]
 end
 
 
+# some notional output
 
+$stdout.puts "processing in '#{r.values[0]}'" + (r.values.size > 1 ? " and '#{r.values[1]}'" : '')
 

data/examples/show_usage_and_version.md

@@ -19,7 +19,7 @@ require 'libclimate'
 
 climate = LibCLImate::Climate.new do |cl|
 
-	cl.version = [ 0, 0, 1 ]
+	cl.version = [ 0, 1, 0 ]
 
 	cl.info_lines =  [
 
@@ -30,7 +30,7 @@ climate = LibCLImate::Climate.new do |cl|
 	]
 end
 
-climate.run ARGV
+climate.parse_and_verify ARGV
 
 
 
@@ -71,7 +71,7 @@ it gives the output:
 
 ```
 libCLImate.Ruby examples
-show_usage_and_version.rb 0.0.1
+show_usage_and_version.rb 0.1.0
 Illustrates use of libCLImate.Ruby's automatic support for '--help' and '--version'
 
 USAGE: show_usage_and_version.rb [ ... flags and options ... ]
@@ -96,7 +96,7 @@ If executed with the arguments
 it gives the output:
 
 ```
-show_usage_and_version.rb 0.0.1
+show_usage_and_version.rb 0.1.0
 ```
 
 ### Unknown option
@@ -114,4 +114,3 @@ show_usage_and_version.rb: unrecognised flag/option: --unknown=value
 ```
 
 with an exit code of 1
-

data/examples/show_usage_and_version.rb

@@ -10,7 +10,7 @@ require 'libclimate'
 
 climate = LibCLImate::Climate.new do |cl|
 
-	cl.version = [ 0, 0, 1 ]
+	cl.version = [ 0, 1, 0 ]
 
 	cl.info_lines =  [
 
@@ -21,7 +21,7 @@ climate = LibCLImate::Climate.new do |cl|
 	]
 end
 
-climate.run ARGV
+climate.parse_and_verify ARGV
 
 
 

data/lib/libclimate/climate.rb

@@ -5,7 +5,7 @@
 # Purpose:      Definition of the ::LibCLImate::Climate class
 #
 # Created:      13th July 2015
-# Updated:      15th April 2019
+# Updated:      29th April 2019
 #
 # Home:         http://github.com/synesissoftware/libCLImate.Ruby
 #
@@ -51,6 +51,7 @@ require 'yaml'
 
 #:stopdoc:
 
+# TODO: Need to work with other colouring libraries, too
 if !defined? Colcon # :nodoc:
 
 	begin
@@ -77,11 +78,12 @@ class << CLASP
 		f = self.Flag_old(name, options)
 
 		# anticipate this functionality being added to CLASP
-		return f if f.respond_to? :action
+		unless f.respond_to? :action
 
-		class << f
+			class << f
 
-			attr_accessor :action
+				attr_accessor :action
+			end
 		end
 
 		if blk
@@ -105,11 +107,12 @@ class << CLASP
 		o = self.Option_old(name, options)
 
 		# anticipate this functionality being added to CLASP
-		return o if o.respond_to? :action
+		unless o.respond_to? :action
 
-		class << o
+			class << o
 
-			attr_accessor :action
+				attr_accessor :action
+			end
 		end
 
 		if blk
@@ -130,7 +133,6 @@ end
 
 #:startdoc:
 
-
 module LibCLImate
 
 # Class used to gather together the CLI specification, and execute it
@@ -145,7 +147,7 @@ module LibCLImate
 #
 #     cl.add_flag('--verbose', alias: '-v', help: 'Makes program output verbose') { program_options[:verbose] = true }
 #
-#     cl.add_option('--flavour', alias: '-f', help: 'Specifies the flavour') do |o, a|
+#     cl.add_option('--flavour', alias: '-f', help: 'Specifies the flavour') do |o, sp|
 #
 #       program_options[:flavour] = check_flavour(o.value) or cl.abort "Invalid flavour '#{o.value}'; use --help for usage"
 #     end
@@ -165,6 +167,200 @@ class Climate
 
 	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
+		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
+
+		# (Array) unchanged copy of the original array of arguments passed to parse
+		attr_reader :argv_original_copy
+
+		# (Array) a frozen array of specifications
+		attr_reader :specifications
+
+		# (String) The program name
+		attr_reader :program_name
+
+		# (String) A (frozen) array of flags
+		attr_reader :flags
+
+		# (String) A (frozen) array of options
+		attr_reader :options
+
+		# (String) A (frozen) array of values
+		attr_reader :values
+
+		# 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)
+
+			if v = options[:raise]
+
+				hm = {}
+
+				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)
+
+				options = options.merge hm
+			end
+
+			raise_on_required		=	options[:raise_on_required]
+			raise_on_unrecognised	=	options[:raise_on_unrecognised]
+			raise_on_unused			=	options[:raise_on_unused]
+
+
+			# Verification:
+			#
+			# 1. Check arguments recognised
+			# 1.a Flags
+			# 1.b Options
+			# 2. police any required options
+			# 3. Check values
+
+			# 1.a Flags
+
+			self.flags.each do |flag|
+
+				spec = specifications.detect do |sp|
+
+					sp.kind_of?(::CLASP::FlagSpecification) && flag.name == sp.name
+				end
+
+				if spec
+
+					if spec.respond_to?(:action) && !spec.action.nil?
+
+						spec.action.call(flag, spec)
+					end
+				else
+
+					message = make_abort_message_("unrecognised flag '#{f}'")
+
+					if false
+
+					elsif climate.ignore_unknown
+
+						;
+					elsif raise_on_unrecognised
+
+						if raise_on_unrecognised.is_a?(Class)
+
+							raise raise_on_unrecognised, message
+						else
+
+							raise RuntimeError, message
+						end
+					elsif climate.exit_on_unknown
+
+						climate.abort message
+					else
+
+						if program_name && !program_name.empty?
+
+							message = "#{program_name}: #{message}"
+						end
+
+						climate.stderr.puts message
+					end
+				end
+			end
+
+			# 1.b Options
+
+			self.options.each do |option|
+
+				spec = specifications.detect do |sp|
+
+					sp.kind_of?(::CLASP::OptionSpecification) && option.name == sp.name
+				end
+
+				if spec
+
+					if spec.respond_to?(:action) && !spec.action.nil?
+
+						spec.action.call(option, spec)
+					end
+				else
+
+					message = make_abort_message_("unrecognised option '#{f}'")
+
+					if false
+
+					elsif climate.ignore_unknown
+
+						;
+					elsif raise_on_unrecognised
+
+						if raise_on_unrecognised.is_a?(Class)
+
+							raise raise_on_unrecognised, message
+						else
+
+							raise RuntimeError, message
+						end
+					elsif climate.exit_on_unknown
+
+						climate.abort message
+					else
+
+						if program_name && !program_name.empty?
+
+							message = "#{program_name}: #{message}"
+						end
+
+						climate.stderr.puts message
+					end
+				end
+			end
+
+			# 2. police any required options
+
+			climate.check_required_options_(specifications, self.options, [], raise_on_required)
+
+			# 3. Check values
+
+			climate.check_value_constraints_(values)
+		end
+
+		def flag_is_specified(id)
+
+			!@arguments.find_flag(id).nil?
+		end
+
+		def lookup_flag(id)
+
+			@arguments.find_flag(id)
+		end
+
+		def lookup_option(id)
+
+			@arguments.find_option(id)
+		end
+
+	end # end class ParseResults
+
+
 	#:stopdoc:
 
 	private
@@ -173,7 +369,7 @@ class Climate
 		GIVEN_SPECS_ = "_Given_Specs_01B59422_8407_4c89_9432_8160C52BD5AD"
 	end # module Climate_Constants_
 
-	def make_abort_message_ msg
+	def make_abort_message_(msg)
 
 		if 0 != (usage_help_suffix || 0).size
 
@@ -184,7 +380,7 @@ class Climate
 		end
 	end
 
-	def show_usage_
+	def show_usage_()
 
 		options	=	{}
 		options.merge! stream: stdout, program_name: program_name, version: version, exit: exit_on_usage ? 0 : nil
@@ -195,12 +391,12 @@ class Climate
 		CLASP.show_usage specifications, options
 	end
 
-	def show_version_
+	def show_version_()
 
 		CLASP.show_version specifications, stream: stdout, program_name: program_name, version: version, exit: exit_on_usage ? 0 : nil
 	end
 
-	def infer_version_ ctxt
+	def infer_version_(ctxt)
 
 		# algorithm:
 		#
@@ -362,6 +558,144 @@ class Climate
 			return r
 		end
 	end
+
+	public
+	def check_required_options_(specifications, options, missing, raise_on_required)
+
+		required_specifications = specifications.select do |sp|
+
+			sp.kind_of?(::CLASP::OptionSpecification) && sp.required?
+		end
+
+		required_specifications = Hash[required_specifications.map { |sp| [ sp.name, sp ] }]
+
+		given_options = Hash[options.map { |o| [ o.name, o ]}]
+
+		required_specifications.each do |k, sp|
+
+			unless given_options.has_key? k
+
+				message = sp.required_message
+
+				if false
+
+					;
+				elsif raise_on_required
+
+					if raise_on_required.is_a?(Class)
+
+						raise raise_on_required, message
+					else
+
+						raise RuntimeError, message
+					end
+				elsif exit_on_missing
+
+					self.abort message
+				else
+
+					if program_name && !program_name.empty?
+
+						message = "#{program_name}: #{message}"
+					end
+
+					stderr.puts message
+				end
+
+				missing << sp
+				#results[:missing_option_aliases] << sp
+			end
+		end
+	end
+
+	def check_value_constraints_(values)
+
+		# now police the values
+
+		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 : []
+
+		case values_constraint
+		when nil
+
+			;
+		when ::Array
+
+			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 }
+
+			unless values_constraint.include? values.size
+
+				message = make_abort_message_("wrong number of values: #{values.size} given, #{values_constraint} required")
+
+				if exit_on_missing
+
+					self.abort message
+				else
+
+					if program_name && !program_name.empty?
+
+						message = "#{program_name}: #{message}"
+					end
+
+					stderr.puts message
+				end
+			end
+		when ::Integer
+
+			unless values.size == values_constraint
+
+				if name = val_names[values.size]
+
+					message = make_abort_message_(name + ' not specified')
+				else
+
+					message = make_abort_message_("wrong number of values: #{values.size} given, #{values_constraint} required")
+				end
+
+				if exit_on_missing
+
+					self.abort message
+				else
+
+					if program_name && !program_name.empty?
+
+						message = "#{program_name}: #{message}"
+					end
+
+					stderr.puts message
+				end
+			end
+		when ::Range
+
+			unless values_constraint.include? values.size
+
+				if name = val_names[values.size]
+
+					message = make_abort_message_(name + ' not specified')
+				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 exit_on_missing
+
+					self.abort message
+				else
+
+					if program_name && !program_name.empty?
+
+						message = "#{program_name}: #{message}"
+					end
+
+					stderr.puts message
+				end
+			end
+		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:
 
 	public
@@ -382,7 +716,7 @@ class Climate
 	#   - +: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
+	def self.load(source, options = (options_defaulted_ = {}), &blk) # :yields: climate
 
 		check_parameter options, 'options', allow_nil: true, type: ::Hash
 
@@ -492,8 +826,39 @@ class Climate
 		version_context		=	options[:version_context]
 		@version			=	options[:version] || infer_version_(version_context)
 
-		@specifications << CLASP::Flag.Help(handle: proc { show_usage_ }) unless options[:no_help_flag]
-		@specifications << CLASP::Flag.Version(handle: proc { show_version_ }) unless options[:no_version_flag]
+		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
 
@@ -501,9 +866,9 @@ class Climate
 	end
 
 	# [DEPRECATED] This method is now deprecated. Instead use +program_name=+
-	def set_program_name name
+	def set_program_name(name)
 
-		@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
@@ -551,7 +916,52 @@ class Climate
 	# (String, [String], [Integer]) A version string or an array of integers/strings representing the version component(s)
 	attr_accessor :version
 
-	# Executes the prepared Climate instance
+	# 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
 	#
@@ -562,17 +972,17 @@ class Climate
 	# an instance of a type derived from +::Hash+ with the additional
 	# attributes +flags+, +options+, +values+, and +argv+.
 	#
-	def run argv = ARGV # :yields: customised +::Hash+
+	def run(argv = ARGV) # :yields: customised +::Hash+
 
 		raise ArgumentError, "argv may not be nil" if argv.nil?
 
-		arguments	=	CLASP::Arguments.new argv, specifications
+		arguments = CLASP::Arguments.new argv, specifications
 
 		run_ argv, arguments
 	end
 
 	private
-	def run_ argv, arguments # :nodoc:
+	def run_(argv, arguments) # :nodoc:
 
 		flags		=	arguments.flags
 		options		=	arguments.options
@@ -601,39 +1011,32 @@ class Climate
 			missing_option_aliases: [],
 		}
 
+		# Verification:
+		#
+		# 1. Check arguments recognised
+		# 1.a Flags
+		# 1.b Options
+		# 2. police any required options
+		# 3. Check values
+
+		# 1.a Flags
+
 		flags.each do |f|
 
-			al = specifications.detect do |a|
+			spec = specifications.detect do |sp|
 
-				a.kind_of?(::CLASP::Flag) && f.name == a.name
+				sp.kind_of?(::CLASP::FlagSpecification) && f.name == sp.name
 			end
 
-			if al
+			if spec
 
 				selector	=	:unhandled
 
-				# see if it has an :action attribute (which will have been
-				# monkey-patched to CLASP.Flag()
+				if spec.respond_to?(:action) && !spec.action.nil?
 
-				if al.respond_to?(:action) && !al.action.nil?
-
-					al.action.call(f, al)
+					spec.action.call(f, spec)
 
 					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
@@ -663,39 +1066,24 @@ class Climate
 			end
 		end
 
+		# 1.b Options
+
 		options.each do |o|
 
-			al = specifications.detect do |a|
+			spec = specifications.detect do |sp|
 
-				a.kind_of?(::CLASP::Option) && o.name == a.name
+				sp.kind_of?(::CLASP::OptionSpecification) && o.name == sp.name
 			end
 
-			if al
+			if spec
 
 				selector	=	:unhandled
 
-				# see if it has an :action attribute (which will have been
-				# monkey-patched to CLASP.Option()
-
-				if al.respond_to?(:action) && !al.action.nil?
+				if spec.respond_to?(:action) && !spec.action.nil?
 
-					al.action.call(o, al)
+					spec.action.call(o, spec)
 
 					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
@@ -725,126 +1113,13 @@ class Climate
 			end
 		end
 
+		# 2. police any required options
 
-		# now police any required options
-
-		required_specifications = specifications.select do |a|
-
-			a.kind_of?(::CLASP::Option) && a.required?
-		end
-
-		required_specifications = Hash[required_specifications.map { |a| [ a.name, a ] }]
-
-		given_options = Hash[results[:options][:given].map { |o| [ o.name, o ]}]
+		check_required_options_(specifications, results[:options][:given], results[:missing_option_aliases], false)
 
-		required_specifications.each do |k, a|
+		# 3. Check values
 
-			unless given_options.has_key? k
-
-				message = a.required_message
-
-				if exit_on_missing
-
-					self.abort message
-				else
-
-					if program_name && !program_name.empty?
-
-						message = "#{program_name}: #{message}"
-					end
-
-					stderr.puts message
-				end
-
-				results[:missing_option_aliases] << a
-			end
-		end
-
-		# now police the values
-
-		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 : []
-
-		case values_constraint
-		when nil
-
-			;
-		when ::Array
-
-			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 }
-
-			unless values_constraint.include? values.size
-
-				message = make_abort_message_("wrong number of values: #{values.size} given, #{values_constraint} required")
-
-				if exit_on_missing
-
-					self.abort message
-				else
-
-					if program_name && !program_name.empty?
-
-						message = "#{program_name}: #{message}"
-					end
-
-					stderr.puts message
-				end
-			end
-		when ::Integer
-
-			unless values.size == values_constraint
-
-				if name = val_names[values.size]
-
-					message = make_abort_message_(name + ' not specified')
-				else
-
-					message = make_abort_message_("wrong number of values: #{values.size} given, #{values_constraint} required")
-				end
-
-				if exit_on_missing
-
-					self.abort message
-				else
-
-					if program_name && !program_name.empty?
-
-						message = "#{program_name}: #{message}"
-					end
-
-					stderr.puts message
-				end
-			end
-		when ::Range
-
-			unless values_constraint.include? values.size
-
-				if name = val_names[values.size]
-
-					message = make_abort_message_(name + ' not specified')
-				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 exit_on_missing
-
-					self.abort message
-				else
-
-					if program_name && !program_name.empty?
-
-						message = "#{program_name}: #{message}"
-					end
-
-					stderr.puts message
-				end
-			end
-		else
-
-			warn "value of 'constrain_values' attribute - '#{constrain_values}' (#{constrain_values.class}) - of wrong type : must be #{::Array}, #{::Integer}, #{::Range}, or nil"
-		end
+		check_value_constraints_(values)
 
 
 
@@ -887,7 +1162,7 @@ class Climate
 	#
 	# === Returns
 	# The combined message string, if <tt>exit()</tt> not called.
-	def abort message, options={}
+	def abort(message, options={})
 
 		prog_name	=	options[:program_name]
 		prog_name	||=	program_name
@@ -939,7 +1214,7 @@ class Climate
 
 		check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ]
 
-		if ::CLASP::Flag === name_or_flag
+		if ::CLASP::FlagSpecification === name_or_flag
 
 			specifications << name_or_flag
 		else
@@ -969,7 +1244,7 @@ class Climate
 
 		check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ]
 
-		if ::CLASP::Option === name_or_option
+		if ::CLASP::OptionSpecification === name_or_option
 
 			specifications << name_or_option
 		else
@@ -1022,10 +1297,10 @@ class Climate
 		raise ArgumentError, "must supply at least one alias" if aliases.empty?
 
 		case name_or_specification
-		when ::CLASP::Flag
+		when ::CLASP::FlagSpecification
 
 			self.specifications << name_or_specification
-		when ::CLASP::Option
+		when ::CLASP::OptionSpecification
 
 			self.specifications << name_or_specification
 		else