clasp-ruby 0.20.1 → 0.22.0.1

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:      19th April 2019
+# Updated:      22nd August 2020
 #
 # Home:         http://github.com/synesissoftware/CLASP.Ruby
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -51,9 +52,10 @@
 module CLASP
 
 	# Current version of the CLASP.Ruby library
-	VERSION				=	'0.20.1'
+	VERSION				=	'0.22.0.1'
 
 	private
+	# @!visibility private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
 	public
 	# Major version of the CLASP.Ruby library

data/test/unit/tc_cli.rb

@@ -2,6 +2,8 @@
 
 $:.unshift File.join(File.dirname(__FILE__), '../..', 'lib')
 
+if RUBY_VERSION >= '2'
+
 require 'clasp'
 
 require 'test/unit'
@@ -20,3 +22,5 @@ class Test_CLI < Test::Unit::TestCase
 	end
 end
 
+end # RUBY_VERSION
+

data/test/unit/tc_default_value.rb

@@ -6,8 +6,6 @@ require 'clasp'
 
 require 'test/unit'
 
-require 'xqsr3/extensions/test/unit'
-
 class Test_DefaultValue < Test::Unit::TestCase
 
 	def test_long_form_without_default
@@ -30,7 +28,27 @@ class Test_DefaultValue < Test::Unit::TestCase
 		assert_nil option0.value
 	end
 
-	def test_long_form_with_default
+	def test_long_form_with_default_empty_value
+
+		specifications	=	[
+
+			CLASP.Option('--verbosity', values: [ 'silent', 'terse', 'normal', 'chatty', 'verbose' ], default_value: 'normal')
+		]
+
+		argv	=	[ '--verbosity=' ]
+		args	=	CLASP::Arguments.new(argv, specifications)
+
+		assert_equal 0, args.flags.size
+		assert_equal 1, args.options.size
+		assert_equal 0, args.values.size
+
+		option0	=	args.options[0]
+
+		assert_equal '--verbosity', option0.name
+		assert_equal 'normal', option0.value
+	end
+
+	def test_long_form_with_default_missing_value
 
 		specifications	=	[
 

data/test/unit/tc_option_required.rb

@@ -17,7 +17,7 @@ class Test_Option_required < Test::Unit::TestCase
 		assert_equal [], o.values_range
 		assert_equal nil, o.default_value
 		assert_equal ({}), o.extras
-		assert_false o.required?
+		assert !o.required?
 		assert_equal "'--verbose' not specified; use --help for usage", o.required_message
 	end
 
@@ -30,7 +30,7 @@ class Test_Option_required < Test::Unit::TestCase
 		assert_equal [], o.values_range
 		assert_equal nil, o.default_value
 		assert_equal ({}), o.extras
-		assert_false o.required?
+		assert !o.required?
 		assert_equal "Verbosity not specified; use --help for usage", o.required_message
 	end
 
@@ -43,7 +43,7 @@ class Test_Option_required < Test::Unit::TestCase
 		assert_equal [], o.values_range
 		assert_equal nil, o.default_value
 		assert_equal ({}), o.extras
-		assert_true o.required?
+		assert o.required?
 		assert_equal "Verbosity not given", o.required_message
 	end
 end

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
+