clasp-ruby 0.20.3 → 0.22.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2cdf702af24b59501e6bbe93ba1985416e7793a7dd3dd2a3cfedae7847156a2a
+  data.tar.gz: 6efa37c0a5f2914498de32916f6d6be2fbe79ab87d0af3a32f10dc5163595309
+SHA512:
+  metadata.gz: 5660b7d456acadbbaeacbfb04f83cfb2dfe94b5918cb731a7194fe0da0efba198e1be3196870fb1ea338cf489e528b703d406e8cee949065e234764181ac2a47
+  data.tar.gz: 83c5cbbb81fd29695e7c00f600bcfc5812854534c5dae6d61812e9ee1d9c68e058aa21c493adced37c3121e54cf724f048b7cf7bd700cff8f91ffbb1440499de

data/lib/clasp/arguments.rb

@@ -46,7 +46,8 @@
 
 
 
-require File.join(File.dirname(__FILE__), 'specifications.rb')
+require File.join(File.dirname(__FILE__), 'specifications')
+require File.join(File.dirname(__FILE__), 'util', 'value_parser')
 
 require 'yaml'
 
@@ -136,17 +137,40 @@ class Arguments
 	# Class that represents a parsed option
 	class OptionArgument
 
+		include ::CLASP::Util::ValueParser
+
 		# @!visibility private
 		#
 		# [PRIVATE] This method is subject to changed between versions and
 		# should not be called directly from application code
 		def initialize(arg, given_index, given_name, resolved_name, argument_spec, given_hyphens, given_label, value, extras) # :nodoc:
 
-			actual_value			=	value
+			resolved_value			=	nil
+
+			if argument_spec
+
+				case constraint = (argument_spec.constraint || {})
+=begin
+				when Proc
+
+					resolved_value = value_from_Proc(constraint, value, arg, given_index, given_name, argument_spec, extras)
+=end
+				when Hash
+
+					if constraint.empty?
+
+						resolved_value	=	(value || '').empty? ? argument_spec.default_value : value
+					else
+
+						resolved_value	=	value_from_Hash(constraint, value, arg, given_index, given_name, argument_spec, extras)
+					end
+				else
 
-			if (value || '').empty? && argument_spec
+					warn "unexpected constraint on argument specification #{argument_spec} when parsing argument '#{arg}'"
+				end
+			else
 
-				actual_value = argument_spec.default_value
+				resolved_value		=	value
 			end
 
 			@arg					=	arg
@@ -155,7 +179,8 @@ class Arguments
 			@argument_specification	=	argument_spec
 			@given_hyphens			=	given_hyphens
 			@given_label			=	given_label
-			@value					=	actual_value
+			@given_value			=	value
+			@value					=	resolved_value
 			@name					=	resolved_name || given_name
 			@extras					=	extras.nil? ? {} : extras
 		end
@@ -172,7 +197,9 @@ class Arguments
 		attr_reader :given_label
 		# (String) The resolved name of the argument
 		attr_reader :name
-		# (String) The value of the option
+		# (String) The given value of the option
+		attr_reader :given_value
+		# (????) The value of the option, which may be of a type other than string subject to the option specification's constraint
 		attr_reader :value
 		# (Object, Hash) The extras associated with the argument
 		attr_reader :extras
@@ -458,7 +485,7 @@ class Arguments
 		values	=	[]
 
 		forced_value		=	false
-		want_option_value	=	false
+		pending_option		=	nil
 
 		argv.each_with_index do |arg, index|
 
@@ -563,15 +590,22 @@ class Arguments
 
 					if argument_spec and argument_spec.is_a? CLASP::OptionSpecification and not value
 
-						want_option_value = true
-						options << OptionArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, nil, argument_spec ? argument_spec.extras : nil)
+						pending_option = {
+
+							arg:			arg,
+							index:			index,
+							given_name:		given_name,
+							resolved_name:	resolved_name,
+							argument_spec:	argument_spec,
+							hyphens_size:	hyphens.size,
+							given_label:	given_label,
+							extras:			argument_spec ? argument_spec.extras : nil,
+						}
 					elsif value
 
-						want_option_value = false
 						options << OptionArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, value, argument_spec ? argument_spec.extras : nil)
 					else
 
-						want_option_value = false
 						flags << FlagArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, argument_spec ? argument_spec.extras : nil)
 					end
 
@@ -579,20 +613,31 @@ class Arguments
 				end
 			end
 
-			if want_option_value and not forced_value
+			if pending_option
 
-				option	=	options[-1]
-				option.instance_eval("@value='#{arg}'")
-				want_option_value = false
-			else
+				value = forced_value ? nil : arg
 
-				arg		=	arg.dup
-				arg_ix	=	::Integer === index ? index : index.dup
+				options << OptionArgument.new(pending_option[:arg], pending_option[:index], pending_option[:given_name], pending_option[:resolved_name], pending_option[:argument_spec], pending_option[:hyphens_size], pending_option[:given_label], value, pending_option[:extras])
 
-				arg.define_singleton_method(:given_index) { arg_ix }
+				pending_option = nil
 
-				values << arg
+				next unless forced_value
 			end
+
+			arg		=	arg.dup
+			arg_ix	=	::Integer === index ? index : index.dup
+
+			arg.define_singleton_method(:given_index) { arg_ix }
+
+			values << arg
+		end
+
+		if pending_option
+
+			value = nil
+
+			options << OptionArgument.new(pending_option[:arg], pending_option[:index], pending_option[:given_name], pending_option[:resolved_name], pending_option[:argument_spec], pending_option[:hyphens_size], pending_option[:given_label], value, pending_option[:extras])
+
 		end
 
 		return flags, options, values

data/lib/clasp/clasp.rb

@@ -50,6 +50,15 @@ require 'clasp/specifications'
 require 'clasp/cli'
 require 'clasp/version'
 
+module CLASP
+
+	# TBC (but is a shorthand for calling +Arguments.new()+
+	def self.parse(argv = ARGV, specifications = nil, options = {})
+
+		return Arguments.new(argv, specifications, options)
+	end
+end # module CLASP
+
 # ############################## end of file ############################# #
 
 

data/lib/clasp/specifications.rb

@@ -5,7 +5,7 @@
 # Purpose:      Argument specification classes
 #
 # Created:      25th October 2014
-# Updated:      20th April 2019
+# Updated:      29th April 2019
 #
 # Home:         http://github.com/synesissoftware/CLASP.Ruby
 #
@@ -57,8 +57,40 @@ module CLASP
 # ######################################################################## #
 # classes
 
+# @!visibility private
+class SpecificationBase # :nodoc: all
+
+	private
+	# @!visibility private
+	def check_arity_(blk, range, label) # :nodoc:
+
+		raise ArgumentError, "block must be a #{Proc}; #{blk.class} given" unless blk.nil? || Proc === blk
+
+		if blk
+
+			case blk.arity
+			when range
+
+				;
+			else
+
+				msg = "wrong arity for #{label}"
+
+				if $DEBUG
+
+					raise ArgumentError, msg
+				else
+
+					warn msg
+				end
+			end
+		end
+	end
+	public
+end
+
 # A class that represents the specification for a command-line flag
-class FlagSpecification
+class FlagSpecification < SpecificationBase
 
 	# Creates a FlagSpecification instance from the given name, aliases, and help
 	#
@@ -69,12 +101,19 @@ class FlagSpecification
 	#   - +aliases+ (+Array+) 0 or more strings specifying short-form or option-value aliases
 	#   - +help+ (+String+) The help string, which may be +nil+
 	#   - +extras+ An application-defined additional parameter. If +nil+, it is assigned an empty +Hash+
-	def initialize(name, aliases, help, extras = nil)
+	#
+	# * *Block* An optional block that is called when a matching flag argument is found
+	#
+	# *NOTE:* Users should prefer the +CLASP::Flag()+ method
+	def initialize(name, aliases, help, extras = nil, &blk)
+
+		check_arity_(blk, 0..3, "flag")
 
 		@name			=	name
 		@aliases		=	(aliases || []).select { |a| a and not a.empty? }
 		@help			=	help
 		@extras			=	extras || {}
+		@action			=	blk
 	end
 
 	# The flag's name string
@@ -86,6 +125,17 @@ class FlagSpecification
 	# The flag's extras
 	attr_reader :extras
 
+	# (Proc) The procedure
+	attr_reader :action
+
+	# @!visibility private
+	def action=(blk) # :nodoc: all
+
+		check_arity_(blk, 0..3, "flag")
+
+		@action = blk
+	end
+
 	# String form of the flag
 	def to_s
 
@@ -133,28 +183,38 @@ class FlagSpecification
 	@@Version_	=	self.new('--version', [], 'shows version and terminates')
   public
 	# An instance of FlagSpecification that provides default '--help' information
-	def self.Help(extras = nil)
+	#
+	# If you wish to specify +extras+ or attach a block, you may do so
+	def self.Help(extras = nil, &blk)
 
 		h = @@Help_
 
-		return self.new(h.name, h.aliases, h.help, extras) if extras
+		if extras || blk
+
+			return self.new(h.name, h.aliases, h.help, extras, &blk)
+		end
 
 		h
 	end
 
 	# An instance of FlagSpecification that provides default '--version' information
-	def self.Version(extras = nil)
+	#
+	# If you wish to specify +extras+ or attach a block, you may do so
+	def self.Version(extras = nil, &blk)
 
 		h = @@Version_
 
-		return self.new(h.name, h.aliases, h.help, extras) if extras
+		if extras || blk
+
+			return self.new(h.name, h.aliases, h.help, extras, &blk)
+		end
 
 		h
 	end
 end
 
 # A class that represents the specification for a command-line option
-class OptionSpecification
+class OptionSpecification < SpecificationBase
 
 	# Creates an OptionSpecification instance from the given name, aliases, help,
 	# values_range, and default_value
@@ -169,8 +229,15 @@ class OptionSpecification
 	#   - +default_value+ (+String+) The default value of the option, which will be used in the case where an option is specified without a value. May be +nil+
 	#   - +required+ (boolean) Whether the option is required. May be +nil+
 	#   - +required_message+ (::String) Message to be used when reporting that a required option is missing. May be +nil+ in which case a message of the form "<option-name> not specified; use --help for usage". If begins with the nul character ("\0"), then is used in the place of the <option-name> and placed into the rest of the standard form message
+	#   - +constraint+ (Hash) Constraint to be applied to the parsed values of options matching this specification. NOTE: only integer constraints are supported in the current version
 	#   - +extras+ An application-defined additional parameter. If +nil+, it is assigned an empty +Hash+
-	def initialize(name, aliases, help, values_range, default_value, required, required_message, extras = nil)
+	#
+	# * *Block* An optional block that is called when a matching option argument is found
+	#
+	# *NOTE:* Users should prefer the +CLASP::Option()+ method
+	def initialize(name, aliases, help, values_range, default_value, required, required_message, constraint, extras = nil, &blk)
+
+		check_arity_(blk, 0..3, "option")
 
 		@name				=	name
 		@aliases			=	(aliases || []).select { |a| a and not a.empty? }
@@ -179,7 +246,9 @@ class OptionSpecification
 		@default_value		=	default_value
 		@required			=	required
 		@required_message	=	nil
+		@constraint			=	constraint || {}
 		@extras				=	extras || {}
+		@action				=	blk
 
 		rm_name				=	nil
 
@@ -214,16 +283,28 @@ class OptionSpecification
 	attr_reader	:default_value
 	# Indicates whether the option is required
 	def required?; @required; end
-	# The message to be used when reporting that a required option is
-	# missing
+	# The message to be used when reporting that a required option is missing
 	attr_reader	:required_message
+	# The value constraint
+	attr_reader :constraint
 	# The option's extras
 	attr_reader :extras
 
+	# (Proc) The procedure
+	attr_reader :action
+
+	# @!visibility private
+	def action=(blk) # :nodoc: all
+
+		check_arity_(blk, 0..3, "flag")
+
+		@action = blk
+	end
+
 	# String form of the option
 	def to_s
 
-		"{#{name}; aliases=#{aliases.join(', ')}; values_range=[ #{values_range.join(', ')} ]; default_value='#{default_value}'; help='#{help}'; required?=#{required?}; extras=#{extras}}"
+		"{#{name}; aliases=#{aliases.join(', ')}; values_range=[ #{values_range.join(', ')} ]; default_value='#{default_value}'; help='#{help}'; required?=#{required?}; required_message=#{required_message}; constraint=#{constraint}; extras=#{extras}}"
 	end
 
 	# @!visibility private
@@ -311,7 +392,9 @@ end
 #   - +:aliases+ (::Array) An array of aliases, e.g. [ '-v', '-verb' ]. Ignored if +:alias+ is specified
 #   - +:extras+ An application-defined object, usually a hash of custom attributes
 #   - +:help+ (::String) A help string
-def CLASP.Flag(name, options = {})
+#
+# * *Block* An optional block that is called when a matching flag argument is found
+def CLASP.Flag(name, options = {}, &blk)
 
 	aliases	=	nil
 	help	=	nil
@@ -344,7 +427,7 @@ def CLASP.Flag(name, options = {})
 		end
 	end
 
-	CLASP::FlagSpecification.new(name, aliases, help, extras)
+	CLASP::FlagSpecification.new(name, aliases, help, extras, &blk)
 end
 
 # Generator method that obtains a CLASP::OptionSpecification according to the given
@@ -366,9 +449,12 @@ end
 #   - +required+ (boolean) Whether the option is required. May be +nil+
 #   - +required_message+ (::String) Message to be used when reporting that a required option is missing. May be +nil+ in which case a message of the form "<option-name> not specified; use --help for usage". If begins with the nul character ("\0"), then is used in the place of the <option-name> and placed into the rest of the standard form message
 #   - +extras+ An application-defined additional parameter. If +nil+, it is assigned an empty +Hash+.
+#   - +constraint+ (Hash) Constraint to be applied to the parsed values of options matching this specification. NOTE: only integer constraints are supported in the current version
 #   - +:values_range+ (::Array) An array defining the accepted values for the option
 #   - +:values+ [DEPRECATED] Alternative to +:values_range+
-def CLASP.Option(name, options = {})
+#
+# * *Block* An optional block that is called when a matching option argument is found
+def CLASP.Option(name, options = {}, &blk)
 
 	aliases			=	nil
 	help			=	nil
@@ -376,6 +462,7 @@ def CLASP.Option(name, options = {})
 	default_value	=	nil
 	required		=	false
 	require_message	=	nil
+	constraint		=	nil
 	extras			=	nil
 
 	options.each do |k, v|
@@ -407,6 +494,9 @@ def CLASP.Option(name, options = {})
 			when	:extras
 
 				extras	=	v
+			when	:constraint
+
+				constraint	=	v
 			else
 
 				raise ArgumentError, "invalid option for option: '#{k}' => '#{v}'"
@@ -417,7 +507,7 @@ def CLASP.Option(name, options = {})
 		end
 	end
 
-	CLASP::OptionSpecification.new(name, aliases, help, values_range, default_value, required, require_message, extras)
+	CLASP::OptionSpecification.new(name, aliases, help, values_range, default_value, required, require_message, constraint, extras, &blk)
 end
 
 def CLASP.Alias(name, *args)

data/lib/clasp/util/exceptions.rb

@@ -0,0 +1,82 @@
+
+# ######################################################################## #
+# File:         clasp/util/exceptions.rb
+#
+# Purpose:      Exception classes
+#
+# Created:      20th April 2019
+# Updated:      28th April 2019
+#
+# Home:         http://github.com/synesissoftware/CLASP.Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2019, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+
+=begin
+=end
+
+module CLASP # :nodoc:
+
+# Exceptions
+module Exceptions
+
+	# Root exception for CLASP
+	class CLASPException < RuntimeError; end
+
+	# Root exception for value parsing
+	class ValueParserException < CLASPException; end
+
+	# No value specified (and no default value) for an option
+	class MissingValueException < ValueParserException; end
+
+	# Exception class indicating invalid values (as opposed to types)
+	class InvalidValueException < ValueParserException; end
+
+	# The given value could not be recognised as a (properly-formatted) number
+	class InvalidNumberException < InvalidValueException; end
+
+	# The given value could not be recognised as a (properly-formatted) integer
+	class InvalidIntegerException < InvalidNumberException; end
+
+	# The value was a valid integer but is out of range
+	class IntegerOutOfRangeException < InvalidValueException; end
+
+end # module Exceptions
+end # module CLASP
+
+# ############################## end of file ############################# #
+
+

data/lib/clasp/util/value_parser.rb

@@ -0,0 +1,222 @@
+
+# ######################################################################## #
+# File:         clasp/util/value_parser.rb
+#
+# Purpose:      Utility component for typed values
+#
+# Created:      20th April 2019
+# Updated:      28th April 2019
+#
+# Home:         http://github.com/synesissoftware/CLASP.Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2019, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+
+require File.join(File.dirname(__FILE__), 'exceptions')
+
+=begin
+=end
+
+module CLASP # :nodoc:
+module Util # :nodoc:
+
+# @!visibility private
+module ValueParser # :nodoc: all
+
+	module Internal_ # :nodoc: all
+
+		include Exceptions
+
+		def self.is_integer? type
+
+			h	=	{}
+
+			return true if Integer == type
+			return true if :integer == type
+
+			false
+		end
+
+		def self.obtain_integer value, constraint, argument_spec
+
+			# If no value is given, then use the default (and don't do any
+			# range testing)
+
+			if (value || '').empty?
+
+				def_value = argument_spec.default_value
+
+				if (def_value || '').to_s.empty?
+
+					msg = "no value specified for the option '#{argument_spec.name}', which has no default value either"
+
+					warn msg if $DEBUG
+
+					raise MissingValueException, msg
+				end
+
+				begin
+
+					return Integer(def_value)
+				rescue ArgumentError => x
+
+					msg = "default value '#{def_value}' specified for option '#{argument_spec.name}' that requires the value to be an integer"
+
+					warn msg if $DEBUG
+
+					raise InvalidIntegerException, msg
+				end
+			end
+
+			# obtain the integer from the value
+
+			v = nil
+
+			begin
+
+				v = Integer(value)
+			rescue ArgumentError => x
+
+				msg = "value '#{value}' specified for option '#{argument_spec.name}' that requires the value to be an integer"
+
+				warn msg if $DEBUG
+
+				raise InvalidIntegerException, msg
+			end
+
+			# Is there a value constraint?:
+			#
+			# - values (obtained from argument_spec#values)
+			# - range
+			# - minimum & maximum
+
+			values_range	=	argument_spec.values_range
+
+			unless values_range.empty?
+
+				v_s		=	v.to_s
+
+				v_s		=	'+' + v_s unless '-' == v_s[0]
+
+				vr_s	=	values_range.map { |x| x.to_s }.map { |x| '-' == x[0] ? x : '+' + x }
+
+				unless vr_s.include? v_s
+
+					msg = "given value '#{value}' specified for option '#{argument_spec.name}' does not fall within the required range"
+
+					raise IntegerOutOfRangeException, msg
+				end
+			else
+
+				case range = constraint[:range]
+				when :negative
+
+					if v >= 0
+
+						msg	=	"given value '#{value}' specified for option '#{argument_spec.name}' must be a negative integer"
+
+						raise IntegerOutOfRangeException, msg
+					end
+				when :positive
+
+					if v < 1
+
+						msg	=	"given value '#{value}' specified for option '#{argument_spec.name}' must be a positive integer"
+
+						raise IntegerOutOfRangeException, msg
+					end
+				when :non_positive
+
+					if v > 0
+
+						msg	=	"given value '#{value}' specified for option '#{argument_spec.name}' must be a non-positive integer"
+
+						raise IntegerOutOfRangeException, msg
+					end
+				when :non_negative
+
+					if v < 0
+
+						msg	=	"given value '#{value}' specified for option '#{argument_spec.name}' must be a non-negative integer"
+
+						raise IntegerOutOfRangeException, msg
+					end
+				when Range
+
+					unless range.include?
+
+						msg = "given value '#{value}' specified for option '#{argument_spec.name}' does not fall within the required range"
+
+						raise IntegerOutOfRangeException, msg
+					end
+				else
+
+					;
+				end
+			end
+
+			v
+		end
+	end # module Internal_
+
+	def value_from_Proc(constraint, value, arg, given_index, given_name, argument_spec, extras)
+
+		value
+	end
+
+	def value_from_Hash(constraint, value, arg, given_index, given_name, argument_spec, extras)
+
+		# Check if type is specified; if not, String is assumed
+
+		type	=	constraint[:type]
+
+
+		if Internal_.is_integer?(type)
+
+			return Internal_.obtain_integer(value, constraint, argument_spec)
+		end
+
+
+		value
+	end
+end # module ValueParser
+
+end # module util
+end # module CLASP
+
+# ############################## end of file ############################# #
+
+

data/lib/clasp/version.rb

@@ -5,12 +5,13 @@
 # Purpose:      Version for CLASP.Ruby library
 #
 # Created:      16th November 2014
-# Updated:      20th April 2019
+# Updated:      26th June 2022
 #
 # Home:         http://github.com/synesissoftware/CLASP.Ruby
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2022, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -51,7 +52,7 @@
 module CLASP
 
 	# Current version of the CLASP.Ruby library
-	VERSION				=	'0.20.3'
+	VERSION				=	'0.22.1'
 
 	private
 	# @!visibility private

data/test/unit/tc_typed_options.rb

@@ -0,0 +1,310 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../..', 'lib')
+
+require 'clasp'
+
+require 'xqsr3/extensions/test/unit' if RUBY_VERSION >= '2'
+
+require 'test/unit'
+
+class Test_TypedOptionValues < Test::Unit::TestCase
+
+	if RUBY_VERSION < '2'
+
+		def assert_raise_with_message(type_spec, message_spec, *args, &block)
+
+			assert_raise(type_spec, *args, &block)
+		end
+	end
+
+	def test_Integer_no_range
+
+		specifications	=	[
+
+			CLASP.Option('--level', default_value: 1234, constraint: { type: Integer })
+		]
+
+		# with no arguments
+		begin
+
+			argv = []
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 0, args.options.size
+			assert_equal 0, args.values.size
+		end
+
+		# with default value
+		begin
+
+			argv = [ '--level=' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '', opt.given_value
+			assert_equal 1234, opt.value
+		end
+
+		# with explicit value 0
+		begin
+
+			argv = [ '--level=0' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '0', opt.given_value
+			assert_equal 0, opt.value
+		end
+
+		# with explicit value -100
+		begin
+
+			argv = [ '--level=-100' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '-100', opt.given_value
+			assert_equal -100, opt.value
+		end
+
+		# with explicit value 123456789
+		begin
+
+			argv = [ '--level=123456789' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '123456789', opt.given_value
+			assert_equal 123456789, opt.value
+		end
+
+		# with explicit value +123456789
+		begin
+
+			argv = [ '--level=+123456789' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '+123456789', opt.given_value
+			assert_equal 123456789, opt.value
+		end
+	end
+
+	def test_Integer_positive
+
+		specifications	=	[
+
+			CLASP.Option('--level', default_value: 1234, constraint: { type: Integer, range: :positive })
+		]
+
+		# with no arguments
+		begin
+
+			argv = []
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 0, args.options.size
+			assert_equal 0, args.values.size
+		end
+
+		# with default value
+		begin
+
+			argv = [ '--level=' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '', opt.given_value
+			assert_equal 1234, opt.value
+		end
+
+		# with explicit value 0
+		begin
+
+			argv = [ '--level=0' ]
+
+			assert_raise_with_message(CLASP::Exceptions::IntegerOutOfRangeException, /\b0\b.*--level.*must be a positive integer/) { CLASP.parse argv, specifications }
+		end
+
+		# with explicit value -100
+		begin
+
+			argv = [ '--level=-100' ]
+
+			assert_raise_with_message(CLASP::Exceptions::IntegerOutOfRangeException, /-100\b.*--level.*must be a positive integer/) { CLASP.parse argv, specifications }
+		end
+
+		# with explicit value 123456789
+		begin
+
+			argv = [ '--level=123456789' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '123456789', opt.given_value
+			assert_equal 123456789, opt.value
+		end
+
+		# with explicit value +123456789
+		begin
+
+			argv = [ '--level=+123456789' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '+123456789', opt.given_value
+			assert_equal 123456789, opt.value
+		end
+	end
+
+	def test_Integer_range_values_range
+
+		specifications	=	[
+
+			CLASP.Option('--level', default_value: 1234, values_range: [ 1234, -1234, 7, 19 ], constraint: { type: Integer })
+		]
+
+		# with no arguments
+		begin
+
+			argv = []
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 0, args.options.size
+			assert_equal 0, args.values.size
+		end
+
+		# with default value
+		begin
+
+			argv = [ '--level=' ]
+
+			args = CLASP.parse argv, specifications
+
+			assert_equal 0, args.flags.size
+			assert_equal 1, args.options.size
+			assert_equal 0, args.values.size
+
+			opt	=	args.options[0]
+
+			assert_equal 0, opt.given_index
+			assert_equal specifications[0], opt.argument_specification
+			assert_equal '--level', opt.name
+			assert_equal '', opt.given_value
+			assert_equal 1234, opt.value
+		end
+
+		# with explicit value 0
+		begin
+
+			argv = [ '--level=0' ]
+
+			assert_raise_with_message(CLASP::Exceptions::IntegerOutOfRangeException, /\b0\b.*--level.*does not fall within the required range/) { CLASP.parse argv, specifications }
+		end
+
+		spec0	=	specifications[0]
+		values	=	spec0.values_range.sort[0]..spec0.values_range.sort[-1]
+
+		values.each do |val|
+
+			argv = [ "--level=#{val}" ]
+
+			if spec0.values_range.include? val
+
+				args = CLASP.parse argv, specifications
+
+				assert_equal 0, args.flags.size
+				assert_equal 1, args.options.size
+				assert_equal 0, args.values.size
+
+				opt	=	args.options[0]
+
+				assert_equal 0, opt.given_index
+				assert_equal specifications[0], opt.argument_specification
+				assert_equal '--level', opt.name
+				assert_equal val.to_s, opt.given_value
+				assert_equal val, opt.value
+			else
+
+			assert_raise_with_message(CLASP::Exceptions::IntegerOutOfRangeException, /#{val}\b.*--level.*does not fall within the required range/) { CLASP.parse argv, specifications }
+			end
+		end
+	end
+end
+

data/test/unit/tc_with_action.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../..', 'lib')
+
+require 'clasp'
+
+require 'xqsr3/extensions/test/unit'
+
+require 'test/unit'
+
+class Test_WithAction < Test::Unit::TestCase
+
+	def test_flag_with_action
+
+		debug = false
+
+		specifications	=	[
+
+			CLASP.Flag('--debug', alias: '-d') { debug = true }
+		]
+		argv	=	[]
+		args	=	CLASP.parse argv, specifications
+
+		assert_equal 0, args.flags.size
+		assert_equal 0, args.options.size
+		assert_equal 0, args.values.size
+
+		assert_false debug
+
+		argv2	=	[ '--debug' ]
+		args2	=	CLASP.parse argv2, specifications
+
+		assert_equal 1, args2.flags.size
+		assert_equal 0, args2.options.size
+		assert_equal 0, args2.values.size
+
+		assert_false debug
+
+		if ix = args2.flags.index('--debug')
+
+			flag = args2.flags[ix]
+
+			flag.argument_specification.action.call(flag, flag.argument_specification)
+		end
+
+		assert_true debug
+	end
+end
+
+

metadata

@@ -1,72 +1,66 @@
 --- !ruby/object:Gem::Specification
 name: clasp-ruby
 version: !ruby/object:Gem::Version
-  version: 0.20.3
-  prerelease: 
+  version: 0.22.1
 platform: ruby
 authors:
 - Matt Wilson
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-04-20 00:00:00.000000000 Z
+date: 2022-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xqsr3
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.30'
+        version: '0.37'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.30'
-description: ! 'Command-Line Argument Sorting and Parsing library that provides a
-  powerful
-
-  abstraction of command-line interpretation facilities. CLASP.Ruby is a Ruby port
-  of the popular CLASP (C/C++) library, and provides declarative specification of
-  command-line flags and options, aliasing, flag combination, UNIX de-facto standard
-  flag processing, and a number of utility functions for expressing usage and version
-  information.
-
-'
+        version: '0.37'
+description: |
+  Command-Line Argument Sorting and Parsing library that provides a powerful
+  abstraction of command-line interpretation facilities. CLASP.Ruby is a Ruby port of the popular CLASP (C/C++) library, and provides declarative specification of command-line flags and options, aliasing, flag combination, UNIX de-facto standard flag processing, and a number of utility functions for expressing usage and version information.
 email: matthew@synesis.com.au
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - examples/cr-example.rb
 - examples/flag_and_option_specifications.md
 - examples/flag_and_option_specifications.rb
 - examples/show_usage_and_version.md
 - examples/show_usage_and_version.rb
 - examples/simple_command_line_no_specifications.rb
+- lib/clasp-ruby.rb
+- lib/clasp.rb
 - lib/clasp/arguments.rb
 - lib/clasp/clasp.rb
 - lib/clasp/cli.rb
 - lib/clasp/doc_.rb
 - lib/clasp/old_module.rb
 - lib/clasp/specifications.rb
+- lib/clasp/util/exceptions.rb
+- lib/clasp/util/value_parser.rb
 - lib/clasp/version.rb
-- lib/clasp-ruby.rb
-- lib/clasp.rb
 - test/scratch/test_list_command_line.rb
 - test/scratch/test_specifications.rb
 - test/scratch/test_usage.rb
 - test/scratch/test_usage_from_DATA.rb
 - test/scratch/test_usage_with_duplicate_specifications.rb
+- test/unit/tc_ARGV_rewrite.rb
 - test/unit/tc_arguments_1.rb
 - test/unit/tc_arguments_2.rb
 - test/unit/tc_arguments_3.rb
 - test/unit/tc_arguments_inspect.rb
-- test/unit/tc_ARGV_rewrite.rb
 - test/unit/tc_cli.rb
 - test/unit/tc_default_value.rb
 - test/unit/tc_defaults_1.rb
@@ -75,33 +69,34 @@ files:
 - test/unit/tc_option_required.rb
 - test/unit/tc_option_value_aliases.rb
 - test/unit/tc_specifications.rb
+- test/unit/tc_typed_options.rb
 - test/unit/tc_usage.rb
+- test/unit/tc_with_action.rb
 - test/unit/ts_all.rb
-- README.md
-- LICENSE
 homepage: http://github.com/synesissoftware/CLASP.Ruby
 licenses:
 - BSD-3-Clause
-post_install_message: 
+metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.23.2
-signing_key: 
-specification_version: 3
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
 summary: CLASP.Ruby
 test_files: []