xqsr3 0.39.1 → 0.39.2.1

data/lib/xqsr3/conversion/bool_parser.rb

@@ -5,7 +5,7 @@
 # Purpose:  Definition of the ::Xqsr3::Conversion::BoolParser module
 #
 # Created:  3rd June 2017
-# Updated:  29th March 2024
+# Updated:  12th April 2024
 #
 # Home:     http://github.com/synesissoftware/xqsr3
 #
@@ -45,69 +45,64 @@
 # ######################################################################## #
 
 
-# ##########################################################
-# ::Xqsr3::Conversion::BoolParser
-
 =begin
 =end
 
 module Xqsr3
 module Conversion
 
-# +include-able module that provides Boolean parsing
-module BoolParser
+  # +include-able module that provides Boolean parsing
+  module BoolParser
 
-  private
-  def self.matches_to_ s, expr
+    private
+    def self.matches_to_ s, expr
 
-    case expr
-    when ::Regexp
-      return expr =~ s
-    else
-      return s == expr
+      case expr
+      when ::Regexp
+        return expr =~ s
+      else
+        return s == expr
+      end
     end
-  end
-
-  public
-
-  # Recognised truey values
-  DEFAULT_TRUE_VALUES   = [ /true/i, '1' ]
-  # Recognised falsey values
-  DEFAULT_FALSE_VALUES  = [ /false/i, '0' ]
-
-  # Attempts to parse the given string +s+ to a Boolean value, based on the
-  # given +options+
-  #
-  # === Signature
-  #
-  # * *Parameters:*
-  #   - +s+ The string to be parsed
-  #   - +options+ An options hash, containing any of the following options
-  #
-  # * *Options:*
-  #   - +:false_values+ (::Array) An array of strings or regular expressions against which to match for false value. Defaults to +DEFAULT_FALSE_VALUES+
-  #   - +:true_values+ (::Array) An array of strings or regular expressions against which to match for true value. Defaults to +DEFAULT_TRUE_VALUES+
-  #   - +:default_value+ An object to be returned if matching fails.  Defaults to +nil+
-  #   - +:false_value+ An object to be returned if matching succeeds to match against +:false_values+. Defaults to +false+
-  #   - +:true_value+ An object to be returned if matching succeeds to match against +:true_values+. Defaults to +true+
-  def self.to_bool s, **options
-
-    true_values   = options[:true_values] || DEFAULT_TRUE_VALUES
-    true_values   = [ true_values ] unless true_values.is_a? ::Array
-    false_values  = options[:false_values] || DEFAULT_FALSE_VALUES
-    false_values  = [ false_values ] unless false_values.is_a? ::Array
-    default_value = options[:default] || nil
-    true_value    = options[:true] || true
-    false_value   = options[:false] || false
-
-    return true_value if true_values.any? { |v| self.matches_to_ s, v }
-    return false_value if false_values.any? { |v| self.matches_to_ s, v }
-
-    return default_value
-  end
-
-end # module BoolParser
 
+    public
+
+    # Recognised truey values
+    DEFAULT_TRUE_VALUES   = [ /true/i, '1' ]
+    # Recognised falsey values
+    DEFAULT_FALSE_VALUES  = [ /false/i, '0' ]
+
+    # Attempts to parse the given string +s+ to a Boolean value, based on the
+    # given +options+
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +s+ The string to be parsed;
+    #   - +options+ (+Hash+) Options that control the behaviour of the method;
+    #
+    # * *Options:*
+    #   - +:false_values+ (+Array+) An array of strings or regular expressions against which to match for false value. Defaults to +DEFAULT_FALSE_VALUES+;
+    #   - +:true_values+ (+Array+) An array of strings or regular expressions against which to match for true value. Defaults to +DEFAULT_TRUE_VALUES+;
+    #   - +:default_value+ An object to be returned if matching fails.  Defaults to +nil+;
+    #   - +:false_value+ An object to be returned if matching succeeds to match against +:false_values+. Defaults to +false+;
+    #   - +:true_value+ An object to be returned if matching succeeds to match against +:true_values+. Defaults to +true+;
+    def self.to_bool s, **options
+
+      true_values   = options[:true_values] || DEFAULT_TRUE_VALUES
+      true_values   = [ true_values ] unless true_values.is_a? ::Array
+      false_values  = options[:false_values] || DEFAULT_FALSE_VALUES
+      false_values  = [ false_values ] unless false_values.is_a? ::Array
+      default_value = options[:default] || nil
+      true_value    = options[:true] || true
+      false_value   = options[:false] || false
+
+      return true_value if true_values.any? { |v| self.matches_to_ s, v }
+      return false_value if false_values.any? { |v| self.matches_to_ s, v }
+
+      return default_value
+    end
+  end # module BoolParser
 end # module Conversion
 end # module Xqsr3
 

data/lib/xqsr3/conversion/integer_parser.rb

@@ -5,7 +5,7 @@
 # Purpose:  Definition of the ::Xqsr3::Conversion::IntegerParser module
 #
 # Created:  21st November 2017
-# Updated:  29th March 2024
+# Updated:  12th April 2024
 #
 # Home:     http://github.com/synesissoftware/xqsr3
 #
@@ -45,140 +45,135 @@
 # ######################################################################## #
 
 
-# ##########################################################
-# ::Xqsr3::Conversion::IntegerParser
-
 =begin
 =end
 
 module Xqsr3
 module Conversion
 
-# +include-able module that provides Integer parsing
-module IntegerParser
+  # +include-able module that provides Integer parsing
+  module IntegerParser
 
-  private
-  # @!visibility private
-  module IntegerParser_Helper_ # :nodoc: all
+    private
+    # @!visibility private
+    module IntegerParser_Helper_ # :nodoc: all
 
-    if Kernel.respond_to?(:xqsr3_Integer_original_method)
+      if Kernel.respond_to?(:xqsr3_Integer_original_method)
 
-      def self.invoke_Integer_1(arg)
+        def self.invoke_Integer_1(arg)
 
-        Kernel.xqsr3_Integer_original_method(arg)
-      end
+          Kernel.xqsr3_Integer_original_method(arg)
+        end
 
-      def self.invoke_Integer_2(arg, base)
+        def self.invoke_Integer_2(arg, base)
 
-        Kernel.xqsr3_Integer_original_method(arg, base)
-      end
-    else
+          Kernel.xqsr3_Integer_original_method(arg, base)
+        end
+      else
 
-      def self.invoke_Integer_1(arg)
+        def self.invoke_Integer_1(arg)
 
-        Kernel.Integer(arg)
-      end
+          Kernel.Integer(arg)
+        end
 
-      def self.invoke_Integer_2(arg, base)
+        def self.invoke_Integer_2(arg, base)
 
-        Kernel.Integer(arg, base)
+          Kernel.Integer(arg, base)
+        end
       end
-    end
 
-    def self.invoke_Integer(arg, base)
+      def self.invoke_Integer(arg, base)
 
-      case arg
-      when ::String
+        case arg
+        when ::String
 
-        self.invoke_Integer_2 arg, base
-      else
+          self.invoke_Integer_2 arg, base
+        else
 
-        if $DEBUG
+          if $DEBUG
 
-          case base
-          when nil, 0
+            case base
+            when nil, 0
 
-            ;
-          else
+              ;
+            else
 
-            warn "WARNING: #{self}::#{__method__}: " + 'base specified for non string value'
+              warn "WARNING: #{self}::#{__method__}: " + 'base specified for non string value'
+            end
           end
-        end
 
-        self.invoke_Integer_1 arg
+          self.invoke_Integer_1 arg
+        end
       end
-    end
 
-    def self.to_integer_ arg, base, options, &block
+      def self.to_integer_ arg, base, options, &block
 
-      case options
-      when ::Hash
-        ;
-      else
+        case options
+        when ::Hash
+          ;
+        else
 
-        raise TypeError, "options must be of type #{::Hash}, #{options.class} given"
-      end
+          raise TypeError, "options must be of type #{::Hash}, #{options.class} given"
+        end
 
-      if block_given?
+        if block_given?
 
-        begin
+          begin
 
-          return self.invoke_Integer arg, base
-        rescue ArgumentError, TypeError => x
+            return self.invoke_Integer arg, base
+          rescue ArgumentError, TypeError => x
 
-          return yield x, arg, base, options
+            return yield x, arg, base, options
+          end
         end
-      end
 
-      if options.has_key?(:default) || options[:nil]
+        if options.has_key?(:default) || options[:nil]
 
-        unless arg.nil?
+          unless arg.nil?
 
-          begin
+            begin
 
-            return self.invoke_Integer arg, base
-          rescue ArgumentError, TypeError
+              return self.invoke_Integer arg, base
+            rescue ArgumentError, TypeError
+            end
           end
-        end
 
-        return options[:default] if options.has_key? :default
+          return options[:default] if options.has_key? :default
 
-        return nil
-      else
+          return nil
+        else
 
-        self.invoke_Integer arg, base
+          self.invoke_Integer arg, base
+        end
       end
+    end # module IntegerParser_Helper_
+    public
+
+    # Attempts to convert a variable to an integer, according to the given
+    # options and block
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +arg+ The argument to be converted (to +Fixnum+ or +Bignum+);
+    #   - +base+ A value of 0, or between 2 and 36. Defaults to 0;
+    #   - +options+ (+Hash+) Options that control the behaviour of the method;
+    #   - +block+ An optional caller-supplied 4-parameter block - taking the exception, +arg+, +base+, and +options+ - that will be invoked with the +ArgumentError+ exception, allowing the caller to take additional action. If the block returns then its return value will be returned to the caller;
+    #
+    # * *Options:*
+    #   - +:default+ A default value to be used when +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+;
+    #   - +:nil+ Returns +nil+ if +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+. Ignored if +:default+ is specified;
+    def self.to_integer arg, base = 0, **options, &block
+
+      IntegerParser_Helper_.to_integer_ arg, base, options, &block
     end
-  end # module IntegerParser_Helper_
-  public
-
-  # Attempts to convert a variable to an integer, according to the given
-  # options and block
-  #
-  # === Signature
-  #
-  # * *Parameters:*
-  #   - +arg+ The argument to be converted (to +Fixnum+ or +Bignum+)
-  #   - +base+ A value of 0, or between 2 and 36. Defaults to 0
-  #   - +options+ An options hash, containing any of the following options
-  #   - +block+ An optional caller-supplied 4-parameter block - taking the exception, +arg+, +base+, and +options+ - that will be invoked with the +ArgumentError+ exception, allowing the caller to take additional action. If the block returns then its return value will be returned to the caller
-  #
-  # * *Options:*
-  #   - +:default+ A default value to be used when +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+
-  #   - +:nil+ Returns +nil+ if +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+. Ignored if +:default+ is specified
-  def self.to_integer arg, base = 0, **options, &block
-
-    IntegerParser_Helper_.to_integer_ arg, base, options, &block
-  end
-
-  # Instance form of ::Xqsr3::Conversion::IntegerParser.to_integer
-  def to_integer base = 0, **options, &block
-
-    IntegerParser_Helper_.to_integer_ self, base, options, &block
-  end
-
-end # module IntegerParser
 
+    # Instance form of ::Xqsr3::Conversion::IntegerParser.to_integer
+    def to_integer base = 0, **options, &block
+
+      IntegerParser_Helper_.to_integer_ self, base, options, &block
+    end
+  end # module IntegerParser
 end # module Conversion
 end # module Xqsr3
 

data/lib/xqsr3/diagnostics/exception_utilities.rb

@@ -5,7 +5,7 @@
 # Purpose:  Definition of the ExceptionUtilities module
 #
 # Created:  12th February 2015
-# Updated:  29th March 2024
+# Updated:  12th April 2024
 #
 # Home:     http://github.com/synesissoftware/xqsr3
 #
@@ -45,174 +45,169 @@
 # ######################################################################## #
 
 
-# ##########################################################
-# ::Xqsr3::Diagnostics::ExceptionUtilities
-
 =begin
 =end
 
 module Xqsr3
 module Diagnostics
 
-module ExceptionUtilities
-
-  # Raises an instance of a named exception that takes options in its
-  # constructor, as in:
-  #
-  #     class ArgumentErrorWithOptions < ArgumentError
-  #
-  #       def initialize(message = nil, **options)
-  #
-  #         . . .
-  #       end
-  #
-  #       attr_reader :options
-  #     end
-  #
-  #     begin
-  #
-  #       raise_with_options ArgumentErrorWithOptions, "message-1", opt1: :val1, opt2: 'val2'
-  #     rescue => x
-  #
-  #       $stderr.puts x.options # => {:opt1=>:val1, :opt2=>"val2"}
-  #     end
-  #
-  # It can also be used with full compatibility with <tt>Kernel#raise</tt>, as in:
-  #
-  #     begin
-  #
-  #       raise_with_options ArgumentError, "message-2"
-  #     rescue => x
-  #
-  #       $stderr.puts x.class # => ArgumenError
-  #       $stderr.puts x.message # => "message-2"
-  #     end
-  #
-  # and:
-  #
-  #     begin
-  #
-  #       raise_with_options "message-3"
-  #     rescue => x
-  #
-  #       $stderr.puts x.class # => RuntimeError
-  #       $stderr.puts x.message # => "message-3"
-  #     end
-  #
-  # === Parameters
-  #
-  # * +args+ 0 or more arguments
-  # * +options+ An options hash
-  #
-  # === Parameter Interpretation
-  #
-  # If the first argument is a class, it is assumed to be the exception
-  # type that will be raised; if not, RuntimeError is raised as is normal
-  # with Kernel#raise. The remaining arguments are passed - via the
-  # <tt>*</tt> operator - to the class's constructor.
-  #
-  # All options passed to this method are respread - by the
-  # <tt>**</tt> operator - and passed to the underlying
-  # <tt>Kernel#raise</tt> call.
-  #
-  # === Exceptions
-  #
-  # - An instance of <tt>arg[0]</tt> if <tt>args[0].is_a?(::Class)</tt>; or
-  # - An instance of +RuntimeError+
-  def self.raise_with_options *args, **options
-
-    # special handling in case called indirectly
-
-    called_indirectly = options[:called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96]
-
-    case called_indirectly
-    when nil, false
-
-      called_indirectly = 0
-    when true
-
-      called_indirectly = 1
-    when ::Integer
-
-      ;
-    else
-
-      abort "indirect-call option (#{called_indirectly}) has invalid type (#{called_indirectly.class})"
-    end
+  module ExceptionUtilities
+
+    # Raises an instance of a named exception that takes options in its
+    # constructor, as in:
+    #
+    #     class ArgumentErrorWithOptions < ArgumentError
+    #
+    #       def initialize(message = nil, **options)
+    #
+    #         . . .
+    #       end
+    #
+    #       attr_reader :options
+    #     end
+    #
+    #     begin
+    #
+    #       raise_with_options ArgumentErrorWithOptions, "message-1", opt1: :val1, opt2: 'val2'
+    #     rescue => x
+    #
+    #       $stderr.puts x.options # => {:opt1=>:val1, :opt2=>"val2"}
+    #     end
+    #
+    # It can also be used with full compatibility with <tt>Kernel#raise</tt>, as in:
+    #
+    #     begin
+    #
+    #       raise_with_options ArgumentError, "message-2"
+    #     rescue => x
+    #
+    #       $stderr.puts x.class # => ArgumenError
+    #       $stderr.puts x.message # => "message-2"
+    #     end
+    #
+    # and:
+    #
+    #     begin
+    #
+    #       raise_with_options "message-3"
+    #     rescue => x
+    #
+    #       $stderr.puts x.class # => RuntimeError
+    #       $stderr.puts x.message # => "message-3"
+    #     end
+    #
+    # === Parameters
+    #
+    # * +args+ 0 or more arguments
+    # * +options+ An options hash
+    #
+    # === Parameter Interpretation
+    #
+    # If the first argument is a class, it is assumed to be the exception
+    # type that will be raised; if not, RuntimeError is raised as is normal
+    # with Kernel#raise. The remaining arguments are passed - via the
+    # <tt>*</tt> operator - to the class's constructor.
+    #
+    # All options passed to this method are respread - by the
+    # <tt>**</tt> operator - and passed to the underlying
+    # <tt>Kernel#raise</tt> call.
+    #
+    # === Exceptions
+    # - An instance of <tt>arg[0]</tt> if <tt>args[0].is_a?(::Class)</tt>; or
+    # - An instance of +RuntimeError+
+    def self.raise_with_options *args, **options
 
-    options.delete :called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96 if called_indirectly
+      # special handling in case called indirectly
 
+      called_indirectly = options[:called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96]
 
-    # Use cases:
-    #
-    # 1. No options
-    # 2. Non-class and options
-    # 3. Class and options
-    #   3.a Class and options
-    #   3.b Class and options and message
-    #   3.c Class and options and message and call-stack
+      case called_indirectly
+      when nil, false
 
-    class_given = args.size > 0 && args[0].is_a?(::Class)
+        called_indirectly = 0
+      when true
 
-    if class_given && !options.empty?
+        called_indirectly = 1
+      when ::Integer
 
-      exception_class_or_instance_or_message_string = args.shift
+        ;
+      else
 
-      # 3. Class and options
+        abort "indirect-call option (#{called_indirectly}) has invalid type (#{called_indirectly.class})"
+      end
+
+      options.delete :called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96 if called_indirectly
 
+
+      # Use cases:
+      #
+      # 1. No options
+      # 2. Non-class and options
+      # 3. Class and options
       #   3.a Class and options
       #   3.b Class and options and message
       #   3.c Class and options and message and call-stack
 
+      class_given = args.size > 0 && args[0].is_a?(::Class)
 
-      xargs = []
+      if class_given && !options.empty?
 
-      xargs << args.shift unless args.empty?
+        exception_class_or_instance_or_message_string = args.shift
 
-      x = exception_class_or_instance_or_message_string.new(*xargs, **options)
+        # 3. Class and options
 
-      rargs = []
-      rargs << x
-      rargs += [ nil, args.shift ] unless args.empty?
+        #   3.a Class and options
+        #   3.b Class and options and message
+        #   3.c Class and options and message and call-stack
 
-      # now need to trim backtrace
 
-      begin
+        xargs = []
 
-        Kernel.raise(*rargs)
-      rescue => x
+        xargs << args.shift unless args.empty?
 
-        bt = x.backtrace
-        (0..called_indirectly).each { bt.shift }
-        Kernel.raise x, x.message, bt
+        x = exception_class_or_instance_or_message_string.new(*xargs, **options)
+
+        rargs = []
+        rargs << x
+        rargs += [ nil, args.shift ] unless args.empty?
+
+        # now need to trim backtrace
+
+        begin
+
+          Kernel.raise(*rargs)
+        rescue => x
+
+          bt = x.backtrace
+          (0..called_indirectly).each { bt.shift }
+          Kernel.raise x, x.message, bt
+        end
       end
-    end
 
-    unless options.empty?
+      unless options.empty?
 
-      # 2. Non-class and options
+        # 2. Non-class and options
 
-      warn "cannot utilise options in raise_with_options when first argument is non-class"
-    else
+        warn "cannot utilise options in raise_with_options when first argument is non-class"
+      else
 
-      # 1. No options
-    end
+        # 1. No options
+      end
 
 
-    # now need to trim backtrace
+      # now need to trim backtrace
 
-    begin
+      begin
 
-      Kernel.raise(*args)
-    rescue => x
+        Kernel.raise(*args)
+      rescue => x
 
-      bt = x.backtrace
-      (0..called_indirectly).each { bt.shift }
-      Kernel.raise x, x.message, bt
+        bt = x.backtrace
+        (0..called_indirectly).each { bt.shift }
+        Kernel.raise x, x.message, bt
+      end
     end
-  end
-end # module ExceptionUtilities
-
+  end # module ExceptionUtilities
 end # module Diagnostics
 end # module Xqsr3