clasp-ruby 0.22.1 → 0.23.0.2

data/lib/clasp/arguments.rb

@@ -6,12 +6,13 @@
 #               CLASP.Ruby
 #
 # Created:      14th February 2014
-# Updated:      20th April 2019
+# Updated:      20th January 2024
 #
 # Home:         http://github.com/synesissoftware/CLASP.Ruby
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -62,704 +63,715 @@ module CLASP
 # The main class for processing command-line arguments
 class Arguments
 
-	# Class that represents a parsed flag
-	class FlagArgument
-
-		# @!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, extras) # :nodoc:
-
-			@arg					=	arg
-			@given_index			=	given_index
-			@given_name				=	given_name
-			@argument_specification	=	argument_spec
-			@given_hyphens			=	given_hyphens
-			@given_label			=	given_label
-			@name					=	resolved_name || given_name
-			@extras					=	extras.nil? ? {} : extras
-		end
-
-		# (Integer) The command-line index of the argument
-		attr_reader :given_index
-		# (String) The given name of the argument as it appeared in the command-line
-		attr_reader :given_name
-		# (CLASP::FlagSpecification) The specification matching the argument, or +nil+
-		attr_reader :argument_specification
-		# (Integer) The number of hyphens of the argument as it appeared in the command-line
-		attr_reader :given_hyphens
-		# (String) The label of the argument as it appeared in the command-line
-		attr_reader :given_label
-		# (String) The resolved name of the argument
-		attr_reader :name
-		# (Object, Hash) The extras associated with the argument
-		attr_reader :extras
-
-		# [DEPRECATED] Use +argument_specification+
-		def argument_alias; @argument_specification; end
-
-		# (String) The string form of the flag, which is the same as +name+
-		def to_s
-
-			@name
-		end
-
-		# @!visibility private
-		def eql?(rhs) # :nodoc:
-
-			return false if rhs.nil?
-
-			# check name and aliases
-			return true if @name == rhs
-			return argument_specification.aliases.include? rhs if argument_specification
-			false
-		end
-
-		# @!visibility private
-		def ==(rhs) # :nodoc:
-
-			return false if rhs.nil?
-			if not rhs.instance_of? String
-
-				rhs = rhs.name
-			end
-			eql? rhs
-		end
-
-		# A hash-code for this instance
-		def hash
-
-			@arg.hash
-		end
-	end
-
-	# 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:
-
-			resolved_value			=	nil
-
-			if argument_spec
-
-				case constraint = (argument_spec.constraint || {})
+    # Class that represents a parsed flag
+    class FlagArgument
+
+        # @!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, extras) # :nodoc:
+
+            @arg                    =   arg
+            @given_index            =   given_index
+            @given_name             =   given_name
+            @argument_specification =   argument_spec
+            @given_hyphens          =   given_hyphens
+            @given_label            =   given_label
+            @name                   =   resolved_name || given_name
+            @extras                 =   extras.nil? ? {} : extras
+        end
+
+        # (Integer) The command-line index of the argument
+        attr_reader :given_index
+        # (String) The given name of the argument as it appeared in the command-line
+        attr_reader :given_name
+        # (CLASP::FlagSpecification) The specification matching the argument, or +nil+
+        attr_reader :argument_specification
+        # (Integer) The number of hyphens of the argument as it appeared in the command-line
+        attr_reader :given_hyphens
+        # (String) The label of the argument as it appeared in the command-line
+        attr_reader :given_label
+        # (String) The resolved name of the argument
+        attr_reader :name
+        # (Object, Hash) The extras associated with the argument
+        attr_reader :extras
+
+        # [DEPRECATED] Use +argument_specification+
+        def argument_alias; @argument_specification; end
+
+        # (String) The string form of the flag, which is the same as +name+
+        def to_s
+
+            @name
+        end
+
+        # @!visibility private
+        def eql?(rhs) # :nodoc:
+
+            return false if rhs.nil?
+
+            # check name and aliases
+            return true if @name == rhs
+            return argument_specification.aliases.include? rhs if argument_specification
+            false
+        end
+
+        # @!visibility private
+        def ==(rhs) # :nodoc:
+
+            return false if rhs.nil?
+            if not rhs.instance_of? String
+
+                rhs = rhs.name
+            end
+            eql? rhs
+        end
+
+        # A hash-code for this instance
+        def hash
+
+            @arg.hash
+        end
+    end
+
+    # 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:
+
+            resolved_value = nil
+
+            if argument_spec
+
+                case constraint = (argument_spec.constraint || {})
 =begin
-				when Proc
+                when Proc
 
-					resolved_value = value_from_Proc(constraint, value, arg, given_index, given_name, argument_spec, extras)
+                    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
-
-					warn "unexpected constraint on argument specification #{argument_spec} when parsing argument '#{arg}'"
-				end
-			else
-
-				resolved_value		=	value
-			end
-
-			@arg					=	arg
-			@given_index			=	given_index
-			@given_name				=	given_name
-			@argument_specification	=	argument_spec
-			@given_hyphens			=	given_hyphens
-			@given_label			=	given_label
-			@given_value			=	value
-			@value					=	resolved_value
-			@name					=	resolved_name || given_name
-			@extras					=	extras.nil? ? {} : extras
-		end
-
-		# (Integer) The command-line index of the argument
-		attr_reader :given_index
-		# (String) The given name of the argument as it appeared in the command-line
-		attr_reader :given_name
-		# (CLASP::OptionSpecification) The specification matching the argument, or +nil+
-		attr_reader :argument_specification
-		# (Integer) The number of hyphens of the argument as it appeared in the command-line
-		attr_reader :given_hyphens
-		# (String) The label of the argument as it appeared in the command-line
-		attr_reader :given_label
-		# (String) The resolved name of the argument
-		attr_reader :name
-		# (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
-
-		# [DEPRECATED] Use +argument_specification+
-		def argument_alias; @argument_specification; end
-
-		# @!visibility private
-		def eql?(rhs) # :nodoc:
-
-			return false if rhs.nil?
-
-			# check name and aliases
-			return true if @name == rhs
-			return argument_specification.aliases.include? rhs if argument_specification
-			false
-		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
+
+                    warn "unexpected constraint on argument specification #{argument_spec} when parsing argument '#{arg}'"
+                end
+            else
+
+                resolved_value      =   value
+            end
+
+            @arg                    =   arg
+            @given_index            =   given_index
+            @given_name             =   given_name
+            @argument_specification =   argument_spec
+            @given_hyphens          =   given_hyphens
+            @given_label            =   given_label
+            @given_value            =   value
+            @value                  =   resolved_value
+            @name                   =   resolved_name || given_name
+            @extras                 =   extras.nil? ? {} : extras
+        end
+
+        # (Integer) The command-line index of the argument
+        attr_reader :given_index
+        # (String) The given name of the argument as it appeared in the command-line
+        attr_reader :given_name
+        # (CLASP::OptionSpecification) The specification matching the argument, or +nil+
+        attr_reader :argument_specification
+        # (Integer) The number of hyphens of the argument as it appeared in the command-line
+        attr_reader :given_hyphens
+        # (String) The label of the argument as it appeared in the command-line
+        attr_reader :given_label
+        # (String) The resolved name of the argument
+        attr_reader :name
+        # (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
+
+        # [DEPRECATED] Use +argument_specification+
+        def argument_alias; @argument_specification; end
+
+        # @!visibility private
+        def eql?(rhs) # :nodoc:
+
+            return false if rhs.nil?
+
+            # check name and aliases
+            return true if @name == rhs
+            return argument_specification.aliases.include? rhs if argument_specification
+            false
+        end
 
-		# @!visibility private
-		def ==(rhs) # :nodoc:
+        # @!visibility private
+        def ==(rhs) # :nodoc:
 
-			return false if rhs.nil?
-			if not rhs.instance_of? String
+            return false if rhs.nil?
+            if not rhs.instance_of? String
 
-				rhs = rhs.name
-			end
-			eql? rhs
-		end
+                rhs = rhs.name
+            end
+            eql? rhs
+        end
 
-		# A hash-code for this instance
-		def hash
+        # A hash-code for this instance
+        def hash
 
-			@arg.hash
-		end
+            @arg.hash
+        end
 
-		# (String) The string form of the flag, which is the same as +name+=+value+
-		def to_s
+        # (String) The string form of the flag, which is the same as +name+=+value+
+        def to_s
 
-			"#{name}=#{value}"
-		end
-	end
+            "#{name}=#{value}"
+        end
+    end
 
-	# ######################
-	# Construction
+    # ######################
+    # Construction
 
-	# Loads an instance of the class, as specified by +source+, according to the given parameters
-	#
-	# See the documentation for the ::CLASP module for examples
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +argv+ (+Array+) The arguments array. May not be +nil+. Defaults to +ARGV+
-	#   - +source+ (+Hash+, +IO+) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification
-	#   - +options+ An options hash, containing any of the following options
-	#
-	# * *Options:*
-	#   - +mutate_argv:+ (+Boolean+) Determines if the library should mutate +argv+. Defaults to +true+. This is essential when using CLASP in conjunction with <tt>$\<</tt>
-	#
-	def self.load(argv, source, options = {}) # :yields: An instance of +CLASP::Arguments+
+    # Loads an instance of the class, as specified by +source+, according to the given parameters
+    #
+    # See the documentation for the ::CLASP module for examples
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +argv+ (+Array+) The arguments array. May not be +nil+. Defaults to +ARGV+
+    #   - +source+ (+Hash+, +IO+) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification
+    #   - +options+ An options hash, containing any of the following options
+    #
+    # * *Options:*
+    #   - +:mutate_argv+ (+Boolean+) Determines if the library should mutate +argv+. Defaults to +true+. This is essential when using CLASP in conjunction with <tt>$\<</tt>
+    #
+    def self.load(argv, source, options = {}) # :yields: An instance of +CLASP::Arguments+
 
-		options ||= {}
+        options ||= {}
 
-		specs = load_specifications(source, options)
+        specs = load_specifications(source, options)
 
-		self.new argv, specs, options
-	end
+        self.new argv, specs, options
+    end
 
-	# Loads the specifications as specified by +source+, according to the given parameters
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +source+ (+Hash+, +IO+) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification
-	#   - +options+ An options hash, containing any of the following options
-	def self.load_specifications(source, options = {}) # :yields: An array of specification instances
+    # Loads the specifications as specified by +source+, according to the given parameters
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +source+ (+Hash+, +IO+) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification
+    #   - +options+ An options hash, containing any of the following options
+    def self.load_specifications(source, options = {}) # :yields: An array of specification instances
 
-		options ||= {}
+        options ||= {}
 
-		h = nil
+        h = nil
 
-		case source
-		when ::IO
+        case source
+        when ::IO
 
-			h = YAML.load(source.read)
-		when ::Hash
+            h = YAML.load(source.read)
+        when ::Hash
 
-			h = source
-		else
+            h = source
+        else
 
-			if source.respond_to?(:to_hash)
+            if source.respond_to?(:to_hash)
 
-				h = source.to_hash
-			else
+                h = source.to_hash
+            else
 
-				raise TypeError, "#{self}.#{__method__}() 'source' argument must be a #{::Hash}, or an object implementing #{::IO}, or a type implementing to_hash'"
-			end
-		end
+                raise TypeError, "#{self}.#{__method__}() 'source' argument must be a #{::Hash}, or an object implementing #{::IO}, or a type implementing to_hash'"
+            end
+        end
 
-		specs	=	[]
+        specs   =   []
 
-		_clasp	=	h['clasp'] or raise ArgumentError, "missing top-level 'clasp' element in load configuration"
-		::Hash === _clasp or raise ArgumentError, "top-level 'clasp' element must be a #{::Hash}"
+        _clasp  =   h['clasp'] or raise ArgumentError, "missing top-level 'clasp' element in load configuration"
+        ::Hash === _clasp or raise ArgumentError, "top-level 'clasp' element must be a #{::Hash}"
 
-		_specs	=	(_clasp['arg-specs'] || _clasp['specifications'] || _clasp['aliases']) or raise ArgumentError, "missing element 'clasp/specifications'"
-		::Array === _specs or raise ArgumentError, "top-level 'specifications' element must be a #{::Hash}"
+        _specs  =   (_clasp['arg-specs'] || _clasp['specifications'] || _clasp['aliases']) or raise ArgumentError, "missing element 'clasp/specifications'"
+        ::Array === _specs or raise ArgumentError, "top-level 'specifications' element must be a #{::Hash}"
 
-		_specs.each do |_spec|
+        _specs.each do |_spec|
 
-			case _spec
-			when ::Hash
+            case _spec
+            when ::Hash
 
-				# TODO: make a utility function and shrink all the following
+                # TODO: make a utility function and shrink all the following
 
-				_spec.each do |_arg_type, _details|
+                _spec.each do |_arg_type, _details|
 
-					case _arg_type
-					when 'flag', :flag
+                    case _arg_type
+                    when 'flag', :flag
 
-						_name	=	_details['name']
+                        _name = _details['name']
 
-						unless _name
+                        unless _name
 
-							warn "flag specification missing required 'name' field"
-						else
+                            warn "flag specification missing required 'name' field"
+                        else
 
-							_alias		=	_details['alias']
-							_aliases	=	_details['aliases']
-							_help		=	_details['help'] || _details['description']
+                            _alias      =   _details['alias']
+                            _aliases    =   _details['aliases']
+                            _help       =   _details['help'] || _details['description']
 
-							specs << CLASP.Flag(_name, alias: _alias, aliases: _aliases, help: _help)
-						end
-					when 'option', :option
+                            specs << CLASP.Flag(_name, alias: _alias, aliases: _aliases, help: _help)
+                        end
+                    when 'option', :option
 
-						_name	=	_details['name']
+                        _name = _details['name']
 
-						unless _name
+                        unless _name
 
-							warn "option specification missing required 'name' field"
-						else
+                            warn "option specification missing required 'name' field"
+                        else
 
-							_alias				=	_details['alias']
-							_aliases			=	_details['aliases']
-							_default_value		=	_details['default_value'] || _details['default']
-							_help				=	_details['help'] || _details['description']
-							_required			=	_details['required']
-							_required_message	=	_details['required_message']
-							_values_range		=	_details['values_range'] || _details['values']
+                            _alias              =   _details['alias']
+                            _aliases            =   _details['aliases']
+                            _default_value      =   _details['default_value'] || _details['default']
+                            _help               =   _details['help'] || _details['description']
+                            _required           =   _details['required']
+                            _required_message   =   _details['required_message']
+                            _values_range       =   _details['values_range'] || _details['values']
 
-							specs << CLASP.Option(_name, alias: _alias, aliases: _aliases, default_value: _default_value, help: _help, required: _required, required_message: _required_message, values_range: _values_range)
-						end
-					when 'alias', :alias
+                            specs << CLASP.Option(_name, alias: _alias, aliases: _aliases, default_value: _default_value, help: _help, required: _required, required_message: _required_message, values_range: _values_range)
+                        end
+                    when 'alias', :alias
 
-						_resolved	=	_details['resolved']
+                        _resolved = _details['resolved']
 
-						unless _resolved
+                        unless _resolved
 
-							warn "alias specification missing required 'resolved' field"
-						else
+                            warn "alias specification missing required 'resolved' field"
+                        else
 
-							_alias				=	_details['alias']
-							_aliases			=	_details['aliases']
+                            _alias      =   _details['alias']
+                            _aliases    =   _details['aliases']
 
-							unless _alias || _aliases
+                            unless _alias || _aliases
 
-								warn "alias specification missing required 'alias' or 'aliases' field"
-							else
+                                warn "alias specification missing required 'alias' or 'aliases' field"
+                            else
 
-								specs << CLASP.Flag(_resolved, alias: _alias, aliases: _aliases)
-							end
-						end
-					else
+                                specs << CLASP.Flag(_resolved, alias: _alias, aliases: _aliases)
+                            end
+                        end
+                    else
 
-						warn "unknown arg-type '#{_arg_type}' specified"
-					end
-				end
-			else
+                        warn "unknown arg-type '#{_arg_type}' specified"
+                    end
+                end
+            else
 
-				warn "non-#{::Hash} element in 'clasp/specifications': #{_spec} (of type #{_spec.class})"
-			end
-		end
+                warn "non-#{::Hash} element in 'clasp/specifications': #{_spec} (of type #{_spec.class})"
+            end
+        end
 
-		specs
-	end
+        specs
+    end
 
-	# Constructs an instance of the class, according to the given parameters
-	#
-	# See the documentation for the ::CLASP module for examples
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +argv+ (+Array+) The arguments array. May not be +nil+. Defaults to +ARGV+
-	#   - +specifications+ (+Array+) The specifications array. Defaults to +nil+. If none supplied, no aliasing will be performed
-	#   - +options+ An options hash, containing any of the following options
-	#
-	# * *Options:*
-	#   - +mutate_argv:+ (+Boolean+) Determines if the library should mutate +argv+. Defaults to +true+. This is essential when using CLASP in conjunction with <tt>$\<</tt>
-	#
-	def initialize(argv = ARGV, specifications = nil, options = {})
+    # Constructs an instance of the class, according to the given parameters
+    #
+    # See the documentation for the ::CLASP module for examples
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +argv+ (+Array+) The arguments array. May not be +nil+. Defaults to +ARGV+
+    #   - +specifications+ (+Array+) The specifications array. Defaults to +nil+. If none supplied, no aliasing will be performed
+    #   - +options+ An options hash, containing any of the following options
+    #
+    # * *Options:*
+    #   - +:mutate_argv+ (+Boolean+) Determines if the library should mutate +argv+. Defaults to +true+. This is essential when using CLASP in conjunction with <tt>$\<</tt>
+    #
+    def initialize(argv = ARGV, specifications = nil, options = {})
 
-		# have to do this name-swap, as 'options' has CLASP-specific
-		# meaning
-		init_opts, options	=	options.dup, nil
+        # have to do this name-swap, as 'options' has CLASP-specific
+        # meaning
+        init_opts, options  =   options.dup, nil
 
-		init_opts[:mutate_argv] = true unless init_opts.has_key? :mutate_argv
+        init_opts[:mutate_argv] = true unless init_opts.has_key? :mutate_argv
 
-		@program_name		=	init_opts[:program_name] || Arguments.derive_program_name_
+        @program_name       =   init_opts[:program_name] || Arguments.derive_program_name_
 
-		@argv				=	argv
-		argv				=	argv.dup
-		@argv_original_copy	=	argv.dup.freeze
+        @argv               =   argv
+        argv                =   argv.dup
+        @argv_original_copy =   argv.dup.freeze
 
-		@specifications		=	specifications
-		@aliases			=	@specifications
+        @specifications     =   specifications
+        @aliases            =   @specifications
 
-		specifications		=	nil if specifications and specifications.empty?
+        specifications      =   nil if specifications and specifications.empty?
 
-		flags, options, values = Arguments.parse_(argv, specifications)
+        flags, options, values, double_slash_index = Arguments.parse_(argv, specifications)
 
-		[ flags, options, values ].each do |ar|
+        [ flags, options, values ].each do |ar|
 
-			class << ar
+            class << ar
 
-				undef :inspect
-				undef :to_s
+                undef :inspect
+                undef :to_s
 
-				def to_s
+                def to_s
 
-					s	=	''
+                    s   =   ''
 
-					s	+=	'['
-					s	+=	self.map { |v| %Q<"#{v}"> }.join(', ')
-					s	+=	']'
+                    s   +=  '['
+                    s   +=  self.map { |v| %Q<"#{v}"> }.join(', ')
+                    s   +=  ']'
 
-					s
-				end
+                    s
+                end
 
-				def inspect
+                def inspect
 
-					s	=	''
+                    s   =   ''
 
-					s	+=	"#<#{self.class}:0x#{(object_id << 1).to_s(16)} ["
-					s	+=	self.map { |v| v.inspect }.join(', ')
-					s	+=	"]>"
+                    s   +=  "#<#{self.class}:0x#{(object_id << 1).to_s(16)} ["
+                    s   +=  self.map { |v| v.inspect }.join(', ')
+                    s   +=  "]>"
 
-					s
-				end
-			end
-		end
+                    s
+                end
+            end
+        end
 
-		@flags		=	flags.freeze
-		@options	=	options.freeze
-		@values		=	values.freeze
+        @flags      =   flags.freeze
+        @options    =   options.freeze
+        @values     =   values.freeze
 
-		# do argv-mutation, if required
-		if init_opts[:mutate_argv]
+        @double_slash_index = double_slash_index
 
-			while not argv.empty?
+        # do argv-mutation, if required
+        if init_opts[:mutate_argv]
 
-				argv.shift
-			end
+            while not argv.empty?
 
-			@values.each do |v|
+                argv.shift
+            end
 
-				argv << v
-			end
-		end
-	end
+            @values.each do |v|
 
-	private
-	# @!visibility private
-	def self.derive_program_name_ # :nodoc:
+                argv << v
+            end
+        end
+    end
 
-		$0
-	end
+    private
+    # @!visibility private
+    def self.derive_program_name_ # :nodoc:
 
-	# @!visibility private
-	def self.parse_(argv, specifications) # :nodoc:
+        $0
+    end
 
-		flags	=	[]
-		options	=	[]
-		values	=	[]
+    # @!visibility private
+    def self.parse_(argv, specifications) # :nodoc:
 
-		forced_value		=	false
-		pending_option		=	nil
+        flags   =   []
+        options =   []
+        values  =   []
 
-		argv.each_with_index do |arg, index|
+        double_slash_index = nil
 
-			if not forced_value
+        forced_value    =   false
+        pending_option  =   nil
 
-				if '--' == arg
+        argv.each_with_index do |arg, index|
 
-					# all subsequent arguments are values
-					forced_value = true
-					next
-				end
+            if not forced_value
 
-				# do regex test to see if option/flag/value
-				if arg =~ /^(-+)([^=]+)/
+                if '--' == arg
 
-					hyphens			=	$1
-					given_label		=	$2
-					given_name		=	"#$1#$2"
-					value			=	($' and not $'.empty?) ? $'[1 ... $'.size] : nil
-					argument_spec	=	nil
-					resolved_name	=	nil
+                    # all subsequent arguments are values
+                    forced_value = true
 
-					(specifications || []).each do |s|
+                    double_slash_index = index if double_slash_index.nil?
 
-						if s.name == given_name or s.aliases.include? given_name
+                    next
+                end
 
-							argument_spec	=	s
-							resolved_name	=	s.name
+                # do regex test to see if option/flag/value
+                if arg =~ /^(-+)([^=]+)/
 
-							# need to check whether the alias is a default-option
-							# and, if so, expand out its name and value, and replace
-							# the name and (if none previously specified) the value
-							if resolved_name =~ /^(-+)([^=]+)=/
+                    hyphens         =   $1
+                    given_label     =   $2
+                    given_name      =   "#$1#$2"
+                    value           =   ($' and not $'.empty?) ? $'[1 ... $'.size] : nil
+                    argument_spec   =   nil
+                    resolved_name   =   nil
 
-								resolved_name	=	"#$1#$2"
-								value			||=	$'
+                    (specifications || []).each do |s|
 
-								# now find the underlying (option) specification
-								specifications.each do |t|
+                        if s.name == given_name or s.aliases.include? given_name
 
-									if t.name == resolved_name or t.aliases.include? resolved_name
+                            argument_spec   =   s
+                            resolved_name   =   s.name
 
-										argument_spec	=	t
+                            # need to check whether the alias is a default-option
+                            # and, if so, expand out its name and value, and replace
+                            # the name and (if none previously specified) the value
+                            if resolved_name =~ /^(-+)([^=]+)=/
 
-										break
-									end
-								end
-							end
+                                resolved_name   =   "#$1#$2"
+                                value           ||= $'
 
-							break
-						end
-					end
+                                # now find the underlying (option) specification
+                                specifications.each do |t|
 
-					# Here we intercept and (potentially) cater to grouped flags
-					if not argument_spec and not value and specifications and 1 == hyphens.size
+                                    if t.name == resolved_name or t.aliases.include? resolved_name
 
-						# Must match all
-						flag_aliases = []
-						given_label[0 ... given_label.size].each_char do |c|
+                                        argument_spec = t
 
-							new_flag	=	"-#{c.chr}"
+                                        break
+                                    end
+                                end
+                            end
 
-							flag_alias	=	nil
+                            break
+                        end
+                    end
 
-							# special case where the flag's actual name is short form and found here
-							flag_alias	||=	specifications.detect { |s| s.is_a?(CLASP::FlagSpecification) && s.name == new_flag }
+                    # Here we intercept and (potentially) cater to grouped flags
+                    if not argument_spec and not value and specifications and 1 == hyphens.size
 
-							# if not found as a flag, look in each specifications' aliases
-							flag_alias	||=	specifications.detect { |s| s.aliases.include? new_flag }
+                        # Must match all
+                        flag_aliases = []
+                        given_label[0 ... given_label.size].each_char do |c|
 
-							if not flag_alias
+                            new_flag    =   "-#{c.chr}"
 
-								flag_aliases	=	nil
-								break
-							else
+                            flag_alias  =   nil
 
-								flag_aliases	<<	flag_alias
-							end
-						end
+                            # special case where the flag's actual name is short form and found here
+                            flag_alias  ||= specifications.detect { |s| s.is_a?(CLASP::FlagSpecification) && s.name == new_flag }
 
-						if flag_aliases
+                            # if not found as a flag, look in each specifications' aliases
+                            flag_alias  ||= specifications.detect { |s| s.aliases.include? new_flag }
 
-							# got them all, so now have to process them all
-							# as normal. Note: is this susceptible to
-							# infinite recursion
+                            if not flag_alias
 
-							# convert to argv and invoke
-							flags_argv = flag_aliases.map { |s| s.name }
+                                flag_aliases   =   nil
+                                break
+                            else
 
-							grp_flags, grp_options, grp_value = Arguments.parse_(flags_argv, specifications)
+                                flag_aliases   <<  flag_alias
+                            end
+                        end
 
-							grp_flags.map! { |f| FlagArgument.new(arg, index, given_name, f.name, f.argument_specification, hyphens.size, given_label, argument_spec ? argument_spec.extras : nil) }
-							grp_options.map! { |o| OptionArgument.new(arg, index, given_name, o.name, o.argument_specification, hyphens.size, given_label, o.value, argument_spec ? argument_spec.extras : nil) }
+                        if flag_aliases
 
-							flags.push(*grp_flags)
-							options.push(*grp_options)
-							values.push(*grp_value)
+                            # got them all, so now have to process them all
+                            # as normal. Note: is this susceptible to
+                            # infinite recursion
 
-							next
-						end
-					end
+                            # convert to argv and invoke
+                            flags_argv = flag_aliases.map { |s| s.name }
 
-					if argument_spec and argument_spec.is_a? CLASP::OptionSpecification and not value
+                            grp_flags, grp_options, grp_value, grp_double_slash_index = Arguments.parse_(flags_argv, specifications)
 
-						pending_option = {
+                            grp_flags.map! { |f| FlagArgument.new(arg, index, given_name, f.name, f.argument_specification, hyphens.size, given_label, argument_spec ? argument_spec.extras : nil) }
+                            grp_options.map! { |o| OptionArgument.new(arg, index, given_name, o.name, o.argument_specification, hyphens.size, given_label, o.value, argument_spec ? argument_spec.extras : nil) }
 
-							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
+                            flags.push(*grp_flags)
+                            options.push(*grp_options)
+                            values.push(*grp_value)
 
-						options << OptionArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, value, argument_spec ? argument_spec.extras : nil)
-					else
+                            next
+                        end
+                    end
 
-						flags << FlagArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, argument_spec ? argument_spec.extras : nil)
-					end
+                    if argument_spec and argument_spec.is_a? CLASP::OptionSpecification and not value
 
-					next
-				end
-			end
+                        pending_option = {
 
-			if 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
 
-				value = forced_value ? nil : arg
+                        options << OptionArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, value, argument_spec ? argument_spec.extras : nil)
+                    else
 
-				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])
+                        flags << FlagArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, argument_spec ? argument_spec.extras : nil)
+                    end
 
-				pending_option = nil
+                    next
+                end
+            end
 
-				next unless forced_value
-			end
+            if pending_option
 
-			arg		=	arg.dup
-			arg_ix	=	::Integer === index ? index : index.dup
+                value = forced_value ? nil : arg
 
-			arg.define_singleton_method(:given_index) { arg_ix }
+                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])
 
-			values << arg
-		end
+                pending_option = nil
 
-		if pending_option
+                next unless forced_value
+            end
 
-			value = nil
+            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 }
 
-		end
+            values << arg
+        end
 
-		return flags, options, values
-	end
+        if pending_option
 
-	# ######################
-	# Attributes
+            value = nil
 
-	public
-	# (Array) a frozen array of specifications
-	attr_reader :specifications
+            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])
 
-	# [DEPRECATED] Instead refer to +specifications+
-	attr_reader :aliases
+        end
 
-	# (Array) a frozen array of flags
-	attr_reader :flags
+        return flags, options, values, double_slash_index
+    end
 
-	# (Array) a frozen array of options
-	attr_reader :options
+    # ######################
+    # Attributes
 
-	# (Array) a frozen array of values
-	attr_reader :values
+    public
+    # (Array) a frozen array of specifications
+    attr_reader :specifications
 
-	# (Array) the (possibly mutated) array of arguments instance passed to new
-	attr_reader :argv
+    # [DEPRECATED] Instead refer to +specifications+
+    attr_reader :aliases
 
-	# (Array) unchanged copy of the original array of arguments passed to new
-	attr_reader :argv_original_copy
+    # (Array) a frozen array of flags
+    attr_reader :flags
 
-	# (String) The program name
-	attr_reader :program_name
+    # (Array) a frozen array of options
+    attr_reader :options
 
-	# Finds the first unknown flag or option; +nil+ if all used
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#   - +options+ (Hash) options
-	#
-	# * *Options:*
-	#   - +:specifications+ ([CLASP::Specification]) Array of specifications. If not specified, the instance's +specifications+ attribute is used
-	#
-	# === Return
-	# (CLASP::Arguments::OptionArgument) The first unknown option; +nil+ if none found
-	def find_first_unknown options = {}
+    # (Array) a frozen array of values
+    attr_reader :values
 
-		option	=	{} if options.nil?
+    # (Integer, +nil+) index of the first '--', if present; +nil+ otherwise
+    attr_reader :double_slash_index
 
-		raise ArgumentError, "options must be nil or Hash - #{option.class} given" unless options.is_a? ::Hash
+    # (Array) the (possibly mutated) array of arguments instance passed to new
+    attr_reader :argv
 
-		specifications	=	options[:specifications] || options[:aliases] || @specifications
+    # (Array) unchanged copy of the original array of arguments passed to new
+    attr_reader :argv_original_copy
 
-		raise ArgumentError, "specifications may not be nil" if specifications.nil?
+    # (String) The program name
+    attr_reader :program_name
 
-		flags.each do |f|
+    # Finds the first unknown flag or option; +nil+ if all used
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +options+ (Hash) options
+    #
+    # * *Options:*
+    #   - +:specifications+ ([CLASP::Specification]) Array of specifications. If not specified, the instance's +specifications+ attribute is used
+    #
+    # === Return
+    # (CLASP::Arguments::OptionArgument) The first unknown option; +nil+ if none found
+    def find_first_unknown options = {}
 
-			return f unless specifications.any? { |al| al.is_a?(::CLASP::FlagSpecification) && al.name == f.name }
-		end
+        option = {} if options.nil?
 
-		self.options.each do |o|
+        raise ArgumentError, "options must be nil or Hash - #{option.class} given" unless options.is_a? ::Hash
 
-			return o unless specifications.any? { |al| al.is_a?(::CLASP::OptionSpecification) && al.name == o.name }
-		end
+        specifications = options[:specifications] || options[:aliases] || @specifications
 
-		nil
-	end
+        raise ArgumentError, "specifications may not be nil" if specifications.nil?
 
-	# Searches for a flag that matches the given id, returning the flag if
-	# found; +nil+ otherwise
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#  - +id+ (String, CLASP::FlagArgument) The name of a flag, or the flag itself
-	#
-	# === Return
-	# (CLASP::Arguments::FlagArgument) The first flag matching +id+; +nil+ if none found
-	def find_flag(id)
+        flags.each do |f|
 
-		flags.each do |flag|
+            return f unless specifications.any? { |al| al.is_a?(::CLASP::FlagSpecification) && al.name == f.name }
+        end
 
-			return flag if flag == id
-		end
+        self.options.each do |o|
 
-		nil
-	end
+            return o unless specifications.any? { |al| al.is_a?(::CLASP::OptionSpecification) && al.name == o.name }
+        end
 
-	# Searches for a option that matches the given id, returning the option
-	# if found; +nil+ otherwise
-	#
-	# === Signature
-	#
-	# * *Parameter:*
-	#  - +id+ (String, CLASP::OptionArgument) The name of a option, or the option itself
-	#
-	# === Return
-	# (CLASP::Arguments::OptionArgument) The first option matching +id+; +nil+ if none found
-	def find_option(id)
+        nil
+    end
 
-		options.each do |option|
+    # Searches for a flag that matches the given id, returning the flag if
+    # found; +nil+ otherwise
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #  - +id+ (String, CLASP::FlagArgument) The name of a flag, or the flag itself
+    #
+    # === Return
+    # (CLASP::Arguments::FlagArgument) The first flag matching +id+; +nil+ if none found
+    def find_flag(id)
 
-			return option if option == id
-		end
+        flags.each do |flag|
 
-		nil
-	end
+            return flag if flag == id
+        end
 
-	# #################################################################### #
-	# backwards-compatible
+        nil
+    end
 
-	# @!visibility private
-	Flag	=	FlagArgument	# :nodoc:
-	# @!visibility private
-	Option	=	OptionArgument	# :nodoc:
+    # Searches for a option that matches the given id, returning the option
+    # if found; +nil+ otherwise
+    #
+    # === Signature
+    #
+    # * *Parameter:*
+    #  - +id+ (String, CLASP::OptionArgument) The name of a option, or the option itself
+    #
+    # === Return
+    # (CLASP::Arguments::OptionArgument) The first option matching +id+; +nil+ if none found
+    def find_option(id)
+
+        options.each do |option|
+
+            return option if option == id
+        end
+
+        nil
+    end
+
+    # #################################################################### #
+    # backwards-compatible
+
+    # @!visibility private
+    Flag    =   FlagArgument    # :nodoc:
+    # @!visibility private
+    Option  =   OptionArgument  # :nodoc:
 end # class Arguments
 
+
 # ######################################################################## #
 # module
 
 end # module CLASP
 
-# ############################## end of file ############################# #
 
+# ############################## end of file ############################# #