clasp-ruby 0.19.1 → 0.19.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78227e0cdf1825a5e5fd14e2c73f5746b5ee6535cb0b6d977ca8a55843085f66
-  data.tar.gz: 1cdddc16d5fb788cb6452888d105ac3d55fee66b96fda5e295259f11de5e8266
+  metadata.gz: 69caf746b37b7e16ba320e99323da8dd939d902d5f94c2e7d7911e872cfcbe01
+  data.tar.gz: 5618e602950f633aa11c1ecad79edcce0fcd2edc7f8686c04a42b060b6569db9
 SHA512:
-  metadata.gz: 75d5ea350254328cce10122cca14cc50292d07a9a9782d88ecead5874c3ef86e1aa2ecb6a63710de0401a904584e5c538755c68ad709b4799ca4c9a754506fde
-  data.tar.gz: 0ab1f38316e51b7d8ab910a70e891981145a973f4162f777113ae2dc5beb9c104ba0625abc9114e002b40ce8ae7d19012b5fcb0724eebcac69b956f15bc4957f
+  metadata.gz: 28a4e8557e601beee4f2730fe1535c8c8f6eae5911d587df17286799284ae717e2062c4f48030f6544b0a05124d8ddd82bee497a991b775e5d1d6917df845f6e
+  data.tar.gz: 569c62d78ff95828e4af59066b6b65cf13746a58cd432f0f51ba54f4f1e082ac5e71e6dc59aeb02110b73599c08da57f0cec9c24f7eaa337cccd015bc9e11e5a

data/lib/clasp/arguments.rb

@@ -61,11 +61,13 @@ module CLASP
 # The main class for processing command-line arguments
 class Arguments
 
-	#:stopdoc:
-	private
-	# @!visibility private
-	class FlagArgument # :nodoc: all
+	# 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
@@ -78,17 +80,26 @@ class Arguments
 			@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
 
-		def argument_alias; @argument_specification; end # :nodoc:
+		# [DEPRECATED] Use +argument_specification+
+		def argument_alias; @argument_specification; end
 
-		def to_s # :nodoc:
+		# (String) The string form of the flag, which is the same as +name+
+		def to_s
 
 			@name
 		end
@@ -113,15 +124,20 @@ class Arguments
 			eql? rhs
 		end
 
-		def hash # :nodoc:
+		# A hash-code for this instance
+		def hash
 
 			@arg.hash
 		end
 	end
 
-	# @!visibility private
-	class OptionArgument # :nodoc: all
+	# Class that represents a parsed option
+	class OptionArgument
 
+		# @!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:
 
 			@arg					=	arg
@@ -135,16 +151,25 @@ class Arguments
 			@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 value of the option
 		attr_reader :value
+		# (Object, Hash) The extras associated with the argument
 		attr_reader :extras
 
-		def argument_alias; @argument_specification; end # :nodoc:
+		# [DEPRECATED] Use +argument_specification+
+		def argument_alias; @argument_specification; end
 
 		def eql?(rhs) # :nodoc:
 
@@ -166,24 +191,22 @@ class Arguments
 			eql? rhs
 		end
 
-		def hash # :nodoc:
+		# A hash-code for this instance
+		def hash
 
 			@arg.hash
 		end
 
-		def to_s # :nodoc:
+		# (String) The string form of the flag, which is the same as +name+=+value+
+		def to_s
 
 			"#{name}=#{value}"
 		end
 	end
 
-	#:startdoc:
-
 	# ######################
 	# Construction
 
-	public
-
 	# Loads an instance of the class, as specified by +source+, according to the given parameters
 	#
 	# See the documentation for the ::CLASP module for examples
@@ -191,12 +214,12 @@ class Arguments
 	# === 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
+	#   - +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>
+	#   - +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+
 
@@ -212,8 +235,8 @@ class Arguments
 	# === 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
+	#   - +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 ||= {}
@@ -331,12 +354,12 @@ class Arguments
 	# === 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
+	#   - +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>
+	#   - +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 = {})
 
@@ -357,7 +380,7 @@ class Arguments
 
 		specifications		=	nil if specifications and specifications.empty?
 
-		flags, options, values = Arguments.parse(argv, specifications)
+		flags, options, values = Arguments.parse_(argv, specifications)
 
 		[ flags, options, values ].each do |ar|
 
@@ -394,7 +417,6 @@ class Arguments
 		@options	=	options.freeze
 		@values		=	values.freeze
 
-
 		# do argv-mutation, if required
 		if init_opts[:mutate_argv]
 
@@ -418,7 +440,7 @@ class Arguments
 	end
 
 	# @!visibility private
-	def self.parse(argv, specifications) # :nodoc:
+	def self.parse_(argv, specifications) # :nodoc:
 
 		flags	=	[]
 		options	=	[]
@@ -448,12 +470,12 @@ class Arguments
 					argument_spec	=	nil
 					resolved_name	=	nil
 
-					(specifications || []).each do |a|
+					(specifications || []).each do |s|
 
-						if a.name == given_name or a.aliases.include? given_name
+						if s.name == given_name or s.aliases.include? given_name
 
-							argument_spec	=	a
-							resolved_name	=	a.name
+							argument_spec	=	s
+							resolved_name	=	s.name
 
 							# need to check whether the alias is a default-option
 							# and, if so, expand out its name and value, and replace
@@ -480,10 +502,10 @@ class Arguments
 							flag_alias	=	nil
 
 							# special case where the flag's actual name is short form and found here
-							flag_alias	||=	specifications.detect { |a| a.is_a?(CLASP::FlagSpecification) && a.name == new_flag }
+							flag_alias	||=	specifications.detect { |s| s.is_a?(CLASP::FlagSpecification) && s.name == new_flag }
 
 							# if not found as a flag, look in each specifications' aliases
-							flag_alias	||=	specifications.detect { |a| a.aliases.include? new_flag }
+							flag_alias	||=	specifications.detect { |s| s.aliases.include? new_flag }
 
 							if not flag_alias
 
@@ -502,9 +524,9 @@ class Arguments
 							# infinite recursion
 
 							# convert to argv and invoke
-							flags_argv = flag_aliases.map { |a| a.name }
+							flags_argv = flag_aliases.map { |s| s.name }
 
-							grp_flags, grp_options, grp_value = Arguments.parse flags_argv, specifications
+							grp_flags, grp_options, grp_value = Arguments.parse_(flags_argv, specifications)
 
 							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) }
@@ -552,38 +574,48 @@ class Arguments
 		end
 
 		return flags, options, values
-
 	end
 
 	# ######################
 	# Attributes
 
 	public
-	# an immutable array of specifications
+	# (Array) a frozen array of specifications
 	attr_reader :specifications
 
 	# [DEPRECATED] Instead refer to +specifications+
 	attr_reader :aliases
 
-	# an immutable array of flags
+	# (Array) a frozen array of flags
 	attr_reader :flags
 
-	# an immutable array of options
+	# (Array) a frozen array of options
 	attr_reader :options
 
-	# an immutable array of values
+	# (Array) a frozen array of values
 	attr_reader :values
 
-	# the (possibly mutated) array of arguments instance passed to new
+	# (Array) the (possibly mutated) array of arguments instance passed to new
 	attr_reader :argv
 
-	# unchanged copy of the original array of arguments passed to new
+	# (Array) unchanged copy of the original array of arguments passed to new
 	attr_reader :argv_original_copy
 
 	# (String) The program name
 	attr_reader :program_name
 
-	# finds the first unknown flag or option; +nil+ if all used
+	# 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 = {}
 
 		option	=	{} if options.nil?
@@ -613,7 +645,10 @@ class Arguments
 	# === Signature
 	#
 	# * *Parameters:*
-	#  - +id+:: (String, CLASP::Flag) The name of a flag, or the flag itself
+	#  - +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 |flag|
@@ -630,7 +665,10 @@ class Arguments
 	# === Signature
 	#
 	# * *Parameter:*
-	#  - +id+:: (String, CLASP::Flag) The name of a option, or the option itself
+	#  - +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|
@@ -644,9 +682,11 @@ class Arguments
 	# #################################################################### #
 	# backwards-compatible
 
+	# @!visibility private
 	Flag	=	FlagArgument	# :nodoc:
+	# @!visibility private
 	Option	=	OptionArgument	# :nodoc:
-end
+end # class Arguments
 
 # ######################################################################## #
 # module

data/lib/clasp/cli.rb

@@ -5,7 +5,7 @@
 # Purpose:      Command-line interface
 #
 # Created:      27th July 2015
-# Updated:      12th April 2019
+# Updated:      19th April 2019
 #
 # Home:         http://github.com/synesissoftware/CLASP.Ruby
 #
@@ -114,17 +114,17 @@ end # module CLI_helpers_
 # === Signature
 #
 # * *Parameters:*
-#   - +specifications+:: (+Array+) The arguments array. May not be +nil+. Defaults to +ARGV+.
-#   - +options+:: An options hash, containing any of the following options.
+#   - +specifications+ (+Array+) The arguments array. May not be +nil+. Defaults to +ARGV+.
+#   - +options+ An options hash, containing any of the following options.
 #
 # * *Options:*
-#   - +:exit+::                                 a program exit code; <tt>exit()</tt> not called if not specified (or +nil+).
-#   - +:program_name+::                         program name; inferred from <tt>$0</tt> if not specified.
-#   - +:stream+::                               output stream; <tt>$stdout</tt> if not specified.
-#   - +:suppress_blank_lines_between_options+:: does exactly what it says on the tin.
-#   - +:values+::                               appends this string to USAGE line if specified.
-#   - +:flags_and_options+::                    inserts a custom string instead of the default string <tt>'[ ... flags and options ... ]'</tt>.
-#   - +:info_lines+::                           inserts 0+ information lines prior to the usage.
+#   - +:exit+                                 a program exit code; <tt>exit()</tt> not called if not specified (or +nil+).
+#   - +:program_name+                         program name; inferred from <tt>$0</tt> if not specified.
+#   - +:stream+                               output stream; <tt>$stdout</tt> if not specified.
+#   - +:suppress_blank_lines_between_options+ does exactly what it says on the tin.
+#   - +:values+                               appends this string to USAGE line if specified.
+#   - +:flags_and_options+                    inserts a custom string instead of the default string <tt>'[ ... flags and options ... ]'</tt>.
+#   - +:info_lines+                           inserts 0+ information lines prior to the usage.
 def self.show_usage specifications, options={}
 
 	options	||=	{}
@@ -255,19 +255,19 @@ end
 # === Signature
 #
 # * *Parameters:*
-#   - +specifications+:: (+Array+) The arguments array. May not be +nil+. Defaults to +ARGV+.
-#   - +options+:: An options hash, containing any of the following options.
+#   - +specifications+ (+Array+) The arguments array. May not be +nil+. Defaults to +ARGV+.
+#   - +options+ An options hash, containing any of the following options.
 #
 # * *Options:*
-#   - +:exit+::                 a program exit code; <tt>exit()</tt> not called if not specified (or +nil+).
-#   - +:program_name+::         program name; inferred from <tt>$0</tt> if not specified.
-#   - +:stream+::               output stream; <tt>$stdout</tt> if not specified.
-#   - +:version+::              an array (of N elements, each of which will be separated by a period '.'), or a string. Must be specified if not +:version_major+.
-#   - +:version_major+::        a number or string. Only considered and must be specified if +:version+ is not.
-#   - +:version_minor+::        a number or string. Only considered if +:version+ is not.
-#   - +:version_revision+::     a number or string. Only considered if +:version+ is not.
-#   - +:version_build+::        a number or string. Only considered if +:version+ is not.
-#   - +:version_prefix+::       optional string to prefix the version number(s).
+#   - +:exit+                 a program exit code; <tt>exit()</tt> not called if not specified (or +nil+).
+#   - +:program_name+         program name; inferred from <tt>$0</tt> if not specified.
+#   - +:stream+               output stream; <tt>$stdout</tt> if not specified.
+#   - +:version+              an array (of N elements, each of which will be separated by a period '.'), or a string. Must be specified if not +:version_major+.
+#   - +:version_major+        a number or string. Only considered and must be specified if +:version+ is not.
+#   - +:version_minor+        a number or string. Only considered if +:version+ is not.
+#   - +:version_revision+     a number or string. Only considered if +:version+ is not.
+#   - +:version_build+        a number or string. Only considered if +:version+ is not.
+#   - +:version_prefix+       optional string to prefix the version number(s).
 def self.show_version specifications, options = {}
 
 	options	||=	{}

data/lib/clasp/specifications.rb

@@ -65,10 +65,10 @@ class FlagSpecification
 	# === Signature
 	#
 	# * *Parameters*
-	#   - +name+:: (+String+) The name, or long-form, of the flag
-	#   - +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+
+	#   - +name+ (+String+) The name, or long-form, of the flag
+	#   - +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)
 
 		@name			=	name
@@ -161,14 +161,14 @@ class OptionSpecification
 	# === Signature
 	#
 	# * *Parameters*
-	#   - +name+:: (+String+) The name, or long-form, of the option
-	#   - +aliases+:: (+Array+) 0 or more strings specifying short-form or option-value aliases
-	#   - +help+:: (+String+) The help string, which may be +nil+
-	#   - +values_range+:: (+Array+) 0 or more strings specifying values supported by the option
-	#   - +default_value+:: (+String+) The default value of the option. 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
-	#   - +extras+:: An application-defined additional parameter. If +nil+, it is assigned an empty +Hash+
+	#   - +name+ (+String+) The name, or long-form, of the option
+	#   - +aliases+ (+Array+) 0 or more strings specifying short-form or option-value aliases
+	#   - +help+ (+String+) The help string, which may be +nil+
+	#   - +values_range+ (+Array+) 0 or more strings specifying values supported by the option
+	#   - +default_value+ (+String+) The default value of the option. 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
+	#   - +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)
 
 		@name				=	name
@@ -301,14 +301,14 @@ end
 # === Signature
 #
 # * *Parameters:*
-#   - +name+:: [::String] The flag name, e.g. '--verbose'
-#   - +options+:: [::Hash] An options hash, containing any of the following options:
+#   - +name+ (::String) The flag name, e.g. '--verbose'
+#   - +options+ (::Hash) An options hash, containing any of the following options:
 #
 # * *Options:*
-#   - +:alias+ [::String] An alias, e.g. '-v'
-#   - +:aliases+ [::Array] An array of aliases, e.g. [ '-v', '-verb' ]. Ignored if +:alias+ is specified
+#   - +:alias+ (::String) An alias, e.g. '-v'
+#   - +: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
+#   - +:help+ (::String) A help string
 def CLASP.Flag(name, options = {})
 
 	aliases	=	nil
@@ -351,20 +351,20 @@ end
 # === Signature
 #
 # * *Parameters:*
-#   - +name+:: [::String] The flag name, e.g. '--verbose'
-#   - +options+:: [::Hash] An options hash, containing any of the following options:
+#   - +name+ (::String) The flag name, e.g. '--verbose'
+#   - +options+ (::Hash) An options hash, containing any of the following options:
 #
 # * *Options:*
-#   - +:alias+ [::String] An alias, e.g. '-v'
-#   - +:aliases+ [::Array] An array of aliases, e.g. [ '-v', '-verb' ].  Ignored if +:alias+ is specified
+#   - +:alias+ (::String) An alias, e.g. '-v'
+#   - +:aliases+ (::Array) An array of aliases, e.g. [ '-v', '-verb' ].  Ignored if +:alias+ is specified
 #   - +:default_value+ The default value for the option
 #   - +:default+ [DEPRECATED] Alternative to +:default_value+
 #   - +:extras+ An application-defined object, usually a hash of custom attributes
-#   - +:help+ [::String] A help string
-#   - +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+.
-#   - +:values_range+ [::Array] An array defining the accepted values for the option
+#   - +:help+ (::String) A help string
+#   - +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+.
+#   - +:values_range+ (::Array) An array defining the accepted values for the option
 #   - +:values+ [DEPRECATED] Alternative to +:values_range+
 def CLASP.Option(name, options = {})
 

data/lib/clasp/version.rb

@@ -51,7 +51,7 @@
 module CLASP
 
 	# Current version of the CLASP.Ruby library
-	VERSION				=	'0.19.1'
+	VERSION				=	'0.19.1.1'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clasp-ruby
 version: !ruby/object:Gem::Version
-  version: 0.19.1
+  version: 0.19.1.1
 platform: ruby
 authors:
 - Matt Wilson