libclimate-ruby 0.12.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b097608f416fda5a16bf34588903e669cd37abc259c8e971c65087de88dbd1e
-  data.tar.gz: 3dd3938b2ea4fc8f8b2d632787b048d8c8a75fd575a1df4262c60007fea989fb
+  metadata.gz: 6c5040323c276e22e2dcf86fbebf1e66bf159904d9a28e764ff913aed1d9a508
+  data.tar.gz: 9551c44bc9ca7bb1f69783d8c6b1e5ae0288548140dcd86023cd80df6fa98c14
 SHA512:
-  metadata.gz: 23fa6d636ea3bc4bae684ab3adaae3abb12ea3c6dc634c48fd69098016f7fad816b87e07c50291a136e0ea4e9bb4ec41d816f7a155428ae6a213db184cd45705
-  data.tar.gz: 17ae81db2053520808553a12cabf97c96369ffbf027039bc53c689ea05c1933ec4aff888b957f262432209cd980f6da3c28557c24874cb759d29c31a5a8a3c8d
+  metadata.gz: 158c64020110e066c1f57be6c4820e9519bed9fccee5883b903dd8d8f4c49d91f971bcfef8e2ff3fd416e6074be0149562098305b56a7cd705aa2619199c7620
+  data.tar.gz: 7672ba94c8724a7504f12d589ff20e703b31eb5ae5e27e6f1878ba8136a8ab2f0749e307b5d00ef11cfca277641c3c3479808c0a2d2406be1247abe887ae3f93

data/examples/flag_and_option_specifications.from_DATA.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+
+# examples/flag_and_option_specifications.from_DATA.rb
+
+
+# requires
+
+require 'libclimate'
+
+
+# constants
+
+PROGRAM_VERSION = '0.0.1'
+
+
+# Specify aliases, parse, and checking standard flags
+
+options = {}
+climate = LibCLImate::Climate.load DATA do |cl|
+
+	cl.on_flag('--debug') { options[:debug] = true }
+
+	cl.on_option('--verbosity') { |o, a| options[:verbosity] = o.value }
+end
+
+r = climate.run ARGV
+
+
+# Program-specific processing of flags/options
+
+if options[:verbosity]
+
+	$stdout.puts "verbosity is specified as: #{options[:verbosity]}"
+end
+
+if options[:debug]
+
+	$stdout.puts 'Debug mode is specified'
+end
+
+
+__END__
+---
+libclimate:
+  clasp:
+    specifications:
+    - flag:
+        name:  --debug
+        alias:  -d
+        help:  runs in Debug mode
+        required:  false
+    - option:
+        name:  --verbosity
+        help:  specifies the verbosity
+        values:
+        - silent
+        - quiet
+        - terse
+        - chatty
+        - verbose
+    - alias:
+        resolved:  --verbosity=chatty
+        aliases:
+        - --chatty
+        - -c
+  constrain_values: !ruby/range 1..2
+  exit_on_missing: true
+  flags_and_options: "[... flags/options ...]"
+  usage_values: "<directory-1> [ <directory-2> ]"
+  value_names:
+  - directory-1
+  - directory-2
+  info_lines:
+  - libCLImate.Ruby examples
+  - :version
+  - Illustrates use of libCLImate.Ruby's specification of flags, options, and aliases, from DATA
+  -
+  version:
+  - 0
+  - 3
+  - "4"
+

data/lib/libclimate/climate.rb

@@ -44,6 +44,8 @@ require 'clasp'
 require 'xqsr3/extensions/io'
 require 'xqsr3/quality/parameter_checking'
 
+require 'yaml'
+
 =begin
 =end
 
@@ -166,6 +168,11 @@ class Climate
 	#:stopdoc:
 
 	private
+	module Climate_Constants_
+
+		GIVEN_SPECS_ = "_Given_Specs_01B59422_8407_4c89_9432_8160C52BD5AD"
+	end # module Climate_Constants_
+
 	def show_usage_
 
 		options	=	{}
@@ -262,10 +269,166 @@ class Climate
 
 		nil
 	end
+
+	def self.check_type_(v, types)
+
+		return true if v.nil?
+
+		types = [ types ] unless Array === types
+
+		return true if types.empty?
+
+		types.each do |type|
+
+			if false
+
+				;
+			elsif :boolean == type
+
+				return true if [ TrueClass, FalseClass ].include? v.class
+			elsif type.is_a?(Class)
+
+				return true if v.is_a?(type)
+			elsif type.is_a?(Array)
+
+				t0 = type[0]
+
+				if t0
+
+					#return true if v.is_a?
+				else
+
+					# Can be array of anything
+
+					return true if v.is_a?(Array)
+				end
+			else
+
+				warn "Cannot validate type of '#{v}' (#{v.class}) against type specification '#{type}'"
+			end
+		end
+
+		false
+	end
+
+	def self.lookup_element_(h, types, name, path)
+
+		if h.has_key?(name)
+
+			r = h[name]
+
+			unless self.check_type_(r, types)
+
+				raise TypeError, "element '#{name}' is of type '#{r.class}' and '#{types}' is required"
+			end
+
+			return r
+		end
+
+		nil
+	end
+
+	def self.require_element_(h, types, name, path)
+
+		unless h.has_key?(name)
+
+			if (path || '').empty?
+
+				raise ArgumentError, "missing top-level element '#{name}' in load configuration"
+			else
+
+				raise ArgumentError, "missing element '#{path}/#{name}' in load configuration"
+			end
+		else
+
+			r = h[name]
+
+			unless self.check_type_(r, types)
+
+				raise TypeError, "element '#{name}' is of type '#{r.class}' and '#{types}' is required"
+			end
+
+			return r
+		end
+	end
 	#:startdoc:
 
 	public
 
+	# Loads an instance of the class, 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
+	#
+	# * *Options:*
+	#   - +:no_help_flag+ (boolean) Prevents the use of the +CLASP::Flag.Help+ flag-specification
+	#   - +:no_version_flag+ (boolean) Prevents the use of the +CLASP::Flag.Version+ flag-specification
+	#   - +:program_name+ (::String) An explicit program-name, which is inferred from +$0+ if this is +nil+
+	#   - +:version+ (String, [Integer], [String]) A version specification. If not specified, this is inferred
+	#   - +:version_context+ Object or class that defines a context for searching the version. Ignored if +:version+ is specified
+	#
+	# * *Block* An optional block that receives the initialising Climate instance, allowing the user to modify the attributes.
+	def self.load source, options = (options_defaulted_ = {}), &blk
+
+		check_parameter options, 'options', allow_nil: true, type: ::Hash
+
+		options ||= {}
+
+		h = nil
+
+		case source
+		when ::IO
+
+			h = YAML.load source.read
+		when ::Hash
+
+			h = source
+		else
+
+			if source.respond_to?(:to_hash)
+
+				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
+
+		_libclimate				=	require_element_(h, Hash, 'libclimate', nil)
+		_exit_on_missing		=	lookup_element_(_libclimate, :boolean, 'exit_on_missing', 'libclimate')
+		_ignore_unknown			=	lookup_element_(_libclimate, :boolean, 'ignore_unknown', 'libclimate')
+		_exit_on_unknown		=	lookup_element_(_libclimate, :boolean, 'exit_on_unknown', 'libclimate')
+		_exit_on_usage			=	lookup_element_(_libclimate, :boolean, 'exit_on_usage', 'libclimate')
+		_info_lines				=	lookup_element_(_libclimate, Array, 'info_lines', 'libclimate')
+		_program_name			=	lookup_element_(_libclimate, String, 'program_name', 'libclimate')
+		_constrain_values		=	lookup_element_(_libclimate, [ Integer, Range ], 'constrain_values', 'libclimate')
+		_flags_and_options		=	lookup_element_(_libclimate, String, 'flags_and_options', 'libclimate')
+		_usage_values			=	lookup_element_(_libclimate, String, 'usage_values', 'libclimate')
+		_value_names			=	lookup_element_(_libclimate, Array, 'value_names', 'libclimate')
+		_version				=	lookup_element_(_libclimate, [ String, [] ], 'version', 'libclimate')
+
+		specs					=	CLASP::Arguments.load_specifications _libclimate, options
+
+		cl						=	Climate.new(options.merge(Climate_Constants_::GIVEN_SPECS_ => specs), &blk)
+
+		cl.exit_on_missing		=	_exit_on_missing unless _exit_on_missing.nil?
+		cl.ignore_unknown		=	_ignore_unknown unless _ignore_unknown.nil?
+		cl.exit_on_unknown		=	_exit_on_unknown unless _exit_on_unknown.nil?
+		cl.exit_on_usage		=	_exit_on_usage unless _exit_on_usage.nil?
+		cl.info_lines			=	_info_lines unless _info_lines.nil?
+		cl.program_name			=	_program_name unless _program_name.nil?
+		cl.constrain_values		=	_constrain_values unless _constrain_values.nil?
+		cl.flags_and_options	=	_flags_and_options unless _flags_and_options.nil?
+		cl.usage_values			=	_usage_values unless _usage_values.nil?
+		cl.value_names			=	_value_names unless _value_names.nil?
+		cl.version				=	_version unless _version.nil?
+
+		cl
+	end
+
 	# Creates an instance of the Climate class.
 	#
 	# === Signature
@@ -280,8 +443,8 @@ class Climate
 	#   - +:version+ (String, [Integer], [String]) A version specification. If not specified, this is inferred
 	#   - +:version_context+ Object or class that defines a context for searching the version. Ignored if +:version+ is specified
 	#
-	# * *Block* An optional block which receives the constructing instance, allowing the user to modify the attributes.
-	def initialize(options={}) # :yields: climate
+	# * *Block* An optional block that receives the initialising Climate instance, allowing the user to modify the attributes.
+	def initialize(options={}, &blk) # :yields: climate
 
 		check_parameter options, 'options', allow_nil: true, type: ::Hash
 
@@ -299,6 +462,8 @@ class Climate
 			pr_name	=	(pr_name =~ /\.(?:bat|cmd|rb|sh)$/) ? "#$`(#$&)" : pr_name
 		end
 
+		given_specs			=	options[Climate_Constants_::GIVEN_SPECS_]
+
 		@specifications		=	[]
 		@ignore_unknown		=	false
 		@exit_on_unknown	=	true
@@ -318,6 +483,8 @@ class Climate
 		@specifications << CLASP::Flag.Help(handle: proc { show_usage_ }) unless options[:no_help_flag]
 		@specifications << CLASP::Flag.Version(handle: proc { show_version_ }) unless options[:no_version_flag]
 
+		@specifications	=	@specifications + given_specs if given_specs
+
 		yield self if block_given?
 	end
 
@@ -386,6 +553,13 @@ class Climate
 		raise ArgumentError, "argv may not be nil" if argv.nil?
 
 		arguments	=	CLASP::Arguments.new argv, specifications
+
+		run_ argv, arguments
+	end
+
+	private
+	def run_ argv, arguments # :nodoc:
+
 		flags		=	arguments.flags
 		options		=	arguments.options
 		values		=	arguments.values.to_a
@@ -594,7 +768,7 @@ class Climate
 					message = "wrong number of values: #{values.size} given, #{values_constraint} required; use --help for usage"
 				end
 
-				if exit_on_unknown
+				if exit_on_missing
 
 					self.abort message
 				else
@@ -619,7 +793,7 @@ class Climate
 					message = "wrong number of values: #{values.size} givens, #{values_constraint.begin} - #{values_constraint.end - (values_constraint.exclude_end? ? 1 : 0)} required; use --help for usage"
 				end
 
-				if exit_on_unknown
+				if exit_on_missing
 
 					self.abort message
 				else
@@ -661,6 +835,7 @@ class Climate
 
 		results
 	end
+	public
 
 	# Calls abort() with the given message prefixed by the program_name
 	#
@@ -719,20 +894,22 @@ class Climate
 	#   - +:help+ (String) Description string used when writing response to "+--help+" flag
 	#   - +:required+ (boolean) Indicates whether the flag is required, causing #run to fail with appropriate message if the flag is not specified in the command-line arguments
 	#
+	# * *Block* An optional block that is invoked when the parsed command-line contains the given flag, receiving the argument and the alias
+	#
 	# === Examples
 	#
 	# ==== Specification(s) of a flag (single statement)
 	#
-	def add_flag(name_or_flag, options={}, &block)
+	def add_flag(name_or_flag, options={}, &blk)
 
-		check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::Flag ]
+		check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ]
 
 		if ::CLASP::Flag === name_or_flag
 
 			specifications << name_or_flag
 		else
 
-			specifications << CLASP.Flag(name_or_flag, **options, &block)
+			specifications << CLASP.Flag(name_or_flag, **options, &blk)
 		end
 	end
 
@@ -750,16 +927,19 @@ class Climate
 	#   - +:help+ (String) Description string used when writing response to "+--help+" flag
 	#   - +:values_range+ ([String]) An array of strings representing the valid/expected values used when writing response to "+--help+" flag. NOTE: the current version does not validate against these values, but a future version may do so
 	#   - +:default_value+ (String) The default version used when, say, for the option +--my-opt+ the command-line contain the argument "+--my-opt=+"
-	def add_option(name_or_option, options={}, &block)
+	#
+	# * *Block* An optional block that is invoked when the parsed command-line contains the given option, receiving the argument and the alias
+	#
+	def add_option(name_or_option, options={}, &blk)
 
-		check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::Option ]
+		check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ]
 
 		if ::CLASP::Option === name_or_option
 
 			specifications << name_or_option
 		else
 
-			specifications << CLASP.Option(name_or_option, **options, &block)
+			specifications << CLASP.Option(name_or_option, **options, &blk)
 		end
 	end
 
@@ -803,7 +983,7 @@ class Climate
 	#  climate.add_alias('--verbosity=verbose', '-v')
 	def add_alias(name_or_specification, *aliases)
 
-		check_parameter name_or_specification, 'name_or_specification', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::Flag, ::CLASP::Option ]
+		check_parameter name_or_specification, 'name_or_specification', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification, ::CLASP::OptionSpecification ]
 		raise ArgumentError, "must supply at least one alias" if aliases.empty?
 
 		case name_or_specification
@@ -818,6 +998,80 @@ class Climate
 			self.specifications << CLASP.Alias(name_or_specification, aliases: aliases)
 		end
 	end
+
+	# Attaches a block to an already-registered flag
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +name_or_flag+ (String, ::CLASP::FlagSpecification) The flag name or instance of CLASP::FlagSpecification
+	#   - +options+ (Hash) An options hash, containing any of the following options. No options are recognised currently
+	#
+	# * *Options:*
+	#
+	# * *Block* A required block that is invoked when the parsed command-line contains the given flag, receiving the argument and the alias
+	#
+	def on_flag(name_or_flag, options={}, &blk)
+
+		check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::FlagSpecification ]
+
+		raise ArgumentError, "on_flag() requires a block to be given" unless block_given?
+
+		specifications.each do |spec|
+
+			case spec
+			when CLASP::FlagSpecification
+
+				if spec == name_or_flag
+
+					spec.action = blk
+
+					return true
+				end
+			end
+		end
+
+		warn "The Climate instance does not contain a FlagSpecification matching '#{name_or_flag}' (#{name_or_flag.class})"
+
+		false
+	end
+
+	# Attaches a block to an already-registered option
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +name_or_option+ (String, ::CLASP::OptionSpecification) The option name or instance of CLASP::OptionSpecification
+	#   - +options+ (Hash) An options hash, containing any of the following options. No options are recognised currently
+	#
+	# * *Options:*
+	#
+	# * *Block* A required block that is invoked when the parsed command-line contains the given option, receiving the argument and the alias
+	#
+	def on_option(name_or_option, options={}, &blk)
+
+		check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::OptionSpecification ]
+
+		raise ArgumentError, "on_option() requires a block to be given" unless block_given?
+
+		specifications.each do |spec|
+
+			case spec
+			when CLASP::OptionSpecification
+
+				if spec == name_or_option
+
+					spec.action = blk
+
+					return true
+				end
+			end
+		end
+
+		warn "The Climate instance does not contain an OptionSpecification matching '#{name_or_option}' (#{name_or_option.class})"
+
+		false
+	end
 end # class Climate
 end # module LibCLImate
 

data/lib/libclimate/version.rb

@@ -43,7 +43,7 @@
 module LibCLImate
 
 	# Current version of the libCLImate.Ruby library
-	VERSION					=	'0.12.2'
+	VERSION					=	'0.13.0'
 
 	private
 	VERSION_PARTS_			=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libclimate-ruby
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.13.0
 platform: ruby
 authors:
 - Matt Wilson
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.19'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.19'
 - !ruby/object:Gem::Dependency
   name: xqsr3
   requirement: !ruby/object:Gem::Requirement
@@ -46,6 +46,7 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- examples/flag_and_option_specifications.from_DATA.rb
 - examples/flag_and_option_specifications.md
 - examples/flag_and_option_specifications.rb
 - examples/show_usage_and_version.md