libclimate-ruby 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 353fcd858d3ab427e53c1a9413dd95b84a51ce60
-  data.tar.gz: 4e6800354074160420024c735c9c74c25479b61e
+  metadata.gz: 60fb29259bdb557a306c02a204cf7b801695aea7
+  data.tar.gz: 599e221a43e094f0a88ddea9d99a4a87812c78db
 SHA512:
-  metadata.gz: 66435e1e61927c1c2cb3f8deeff70622ef6fe11d7829597fcdebf3e4310fde56c3d80d084cf29261f82f8914d344d97168e51a1de274f1c1a44560e44e411a10
-  data.tar.gz: 56b07a2b44395c8e0c72e7c6c553285a2f4de427a1cfc2268c49b7e8ac33ab9978de755f9c188eb0e4504f19d054b00db3ffd0c5b54c3fda40e33a99b958ce64
+  metadata.gz: b537e1f71fb463e8f60197e0e3174607fdcaa49afcd9f4beb1cd7c86f04ff6b72e61cea87e27725bc3dce9803906872345a293aea2ac704348195dfcc4b2b6b6
+  data.tar.gz: a62dbfe4a7bc2fef06ab0dee37c6351c04118170432e2109a828d3515ada0e19910b88e8f2d9b93d38e18867685b34e8e8e80f3cdb901ade0f9089456e325ad7

data/README.md

@@ -17,7 +17,8 @@ libCLImate, for Ruby
 1. [Introduction](#introduction)
 2. [Installation](#installation)
 3. [Components](#components)
-4. [Project Information](#project-information)
+4. [Examples](#examples)
+5. [Project Information](#project-information)
 
 ## Installation
 
@@ -29,16 +30,22 @@ Install via **gem** as in:
 
 or add it to your `Gemfile`.
 
-Use via **require***, as in:
+Use via **require**, as in:
 
 ```Ruby
-require 'libclimate-ruby'
+require 'libclimate'
 ```
 
 ## Components
 
 T.B.C.
 
+## Examples
+
+Examples are provided in the ```examples``` directory, along with a markdown description for each. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md).
+
+It is instructive to see how much more succinct they are than those (offering precisely the same functionality) presented in [**CLASP.Ruby**](https://github.com/synesissoftware/CLASP.Ruby).
+
 ## Project Information
 
 ### Where to get help
@@ -58,12 +65,12 @@ Defect reports, feature requests, and pull requests are welcome on https://githu
 
 ### Related projects
 
-* [**libCLImate C/C++](https://github.com/synesissoftware/libCLImate.Ruby)
 * [**CLASP**](https://github.com/synesissoftware/CLASP/)
 * [**CLASP.Go**](https://github.com/synesissoftware/CLASP.Go/)
 * [**CLASP.js**](https://github.com/synesissoftware/CLASP.js/)
 * [**CLASP.Ruby**](https://github.com/synesissoftware/CLASP.Ruby/)
-* [xqsr3](https://github.com/synesissoftware.com/libCLImate.Ruby-xml/)
+* [**libCLImate** (C/C++)](https://github.com/synesissoftware/libCLImate.Ruby)
+* [**xqsr3**](https://github.com/synesissoftware.com/libCLImate.Ruby-xml/)
 
 ### License
 

data/examples/flag_and_option_specifications.md

@@ -0,0 +1,181 @@
+# libCLImate.Ruby Example - **show_usage_and_version**
+
+## Summary
+
+Example illustrating various kinds of *flag* and *option* specifications, including the combination of short-names.
+
+## Source
+
+```ruby
+#!/usr/bin/env ruby
+
+# examples/flag_and_option_specifications.rb
+
+# requires
+
+require 'libclimate'
+
+# Specify specifications, parse, and checking standard flags
+
+options = {}
+climate = LibCLImate::Climate.new do |cl|
+
+	cl.add_flag('--debug', alias: '-d', help: 'runs in Debug mode') do
+
+		options[:debug] = true
+	end
+	cl.add_option('--verbosity', alias: '-v', help: 'specifies the verbosity', values: [ 'terse', 'quiet', 'silent', 'chatty' ]) do |o, a|
+
+		options[:verbosity] = o.value
+	end
+	cl.add_alias('--verbosity=chatty', '-c')
+
+	cl.version = [ 0, 0, 1 ]
+
+	cl.info_lines =  [
+
+		'libCLImate.Ruby examples',
+		:version,
+		"Illustrates use of libCLImate.Ruby's specification of flags, options, and specifications",
+		'',
+	]
+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
+```
+
+## Usage
+
+### No arguments
+
+If executed with no arguments
+
+```
+    ruby examples/flag_and_option_specifications.rb
+```
+
+or (in a Unix shell):
+
+```
+    ./examples/flag_and_option_specifications.rb
+```
+
+it gives the output:
+
+```
+```
+
+### Show usage
+
+If executed with the arguments
+
+```
+    ruby examples/flag_and_option_specifications.rb --help
+```
+
+it gives the output:
+
+```
+libCLImate.Ruby examples
+flag_and_option_specifications.rb 0.0.1
+Illustrates use of libCLImate.Ruby's specification of flags, options, and specifications
+
+USAGE: flag_and_option_specifications.rb [ ... flags and options ... ]
+
+flags/options:
+
+	-d
+	--debug
+		runs in Debug mode
+
+	-c --verbosity=chatty
+	-v <value>
+	--verbosity=<value>
+		specifies the verbosity
+		where <value> one of:
+			terse
+			quiet
+			silent
+			chatty
+
+	--help
+		Shows usage and terminates
+
+	--version
+		Shows version and terminates
+```
+
+### Specify flags and options in long-form
+
+If executed with the arguments
+
+```
+    ruby examples/flag_and_option_specifications.rb --debug --verbosity=silent
+```
+
+it gives the output:
+
+```
+verbosity is specified as: silent
+Debug mode is specified
+```
+
+### Specify flags and options in short-form
+
+If executed with the arguments
+
+```
+    ruby examples/flag_and_option_specifications.rb -v silent -d
+```
+
+it gives the (same) output:
+
+```
+verbosity is specified as: silent
+Debug mode is specified
+```
+
+### Specify flags and options in short-form, including an alias for an option-with-value
+
+If executed with the arguments
+
+```
+    ruby examples/flag_and_option_specifications.rb -c -d
+```
+
+it gives the output:
+
+```
+verbosity is specified as: chatty
+Debug mode is specified
+```
+
+### Specify flags and options with combined short-form
+
+If executed with the arguments
+
+```
+    ruby examples/flag_and_option_specifications.rb -dc
+```
+
+it gives the (same) output:
+
+```
+verbosity is specified as: chatty
+Debug mode is specified
+```
+

data/examples/flag_and_option_specifications.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+# examples/flag_and_option_specifications.rb
+
+# requires
+
+require 'libclimate'
+
+# Specify specifications, parse, and checking standard flags
+
+options = {}
+climate = LibCLImate::Climate.new do |cl|
+
+	cl.add_flag('--debug', alias: '-d', help: 'runs in Debug mode') do
+
+		options[:debug] = true
+	end
+	cl.add_option('--verbosity', alias: '-v', help: 'specifies the verbosity', values: [ 'terse', 'quiet', 'silent', 'chatty' ]) do |o, a|
+
+		options[:verbosity] = o.value
+	end
+	cl.add_alias('--verbosity=chatty', '-c')
+
+	cl.version = [ 0, 0, 1 ]
+
+	cl.info_lines =  [
+
+		'libCLImate.Ruby examples',
+		:version,
+		"Illustrates use of libCLImate.Ruby's specification of flags, options, and specifications",
+		'',
+	]
+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
+
+
+
+

data/examples/show_usage_and_version.md

@@ -0,0 +1,117 @@
+# libCLImate.Ruby Example - **show_usage_and_version**
+
+## Summary
+
+Simple example supporting ```--help``` and ```--version```.
+
+## Source
+
+```ruby
+#!/usr/bin/env ruby
+
+# examples/show_usage_and_version.rb
+
+# requires
+
+require 'libclimate'
+
+# Specify specifications, parse, and checking standard flags
+
+climate = LibCLImate::Climate.new do |cl|
+
+	cl.version = [ 0, 0, 1 ]
+
+	cl.info_lines =  [
+
+		'libCLImate.Ruby examples',
+		:version,
+		"Illustrates use of libCLImate.Ruby's automatic support for '--help' and '--version'",
+		'',
+	]
+end
+
+climate.run ARGV
+
+
+
+$stdout.puts 'no flags specified'
+```
+
+## Usage
+
+### No arguments
+
+If executed with no arguments
+
+```
+    ruby examples/show_usage_and_version.rb
+```
+
+or (in a Unix shell):
+
+```
+    ./examples/show_usage_and_version.rb
+```
+
+it gives the output:
+
+```
+no flags specified
+```
+
+### Show usage
+
+If executed with the arguments
+
+```
+    ruby examples/show_usage_and_version.rb --help
+```
+
+it gives the output:
+
+```
+libCLImate.Ruby examples
+show_usage_and_version.rb 0.0.1
+Illustrates use of libCLImate.Ruby's automatic support for '--help' and '--version'
+
+USAGE: show_usage_and_version.rb [ ... flags and options ... ]
+
+flags/options:
+
+	--help
+		shows this help and terminates
+
+	--version
+		shows version and terminates
+```
+
+### Show version
+
+If executed with the arguments
+
+```
+    ruby examples/show_usage_and_version.rb --version
+```
+
+it gives the output:
+
+```
+show_usage_and_version.rb 0.0.1
+```
+
+### Unknown option
+
+If executed with the arguments
+
+```
+    ruby examples/show_usage_and_version.rb --unknown=value
+```
+
+it gives the output (on the standard error stream):
+
+```
+show_usage_and_version.rb: unrecognised flag/option: --unknown=value
+```
+
+with an exit code of 1
+

data/examples/show_usage_and_version.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+# examples/show_usage_and_version.rb
+
+# requires
+
+require 'libclimate'
+
+# Specify specifications, parse, and checking standard flags
+
+climate = LibCLImate::Climate.new do |cl|
+
+	cl.version = [ 0, 0, 1 ]
+
+	cl.info_lines =  [
+
+		'libCLImate.Ruby examples',
+		:version,
+		"Illustrates use of libCLImate.Ruby's automatic support for '--help' and '--version'",
+		'',
+	]
+end
+
+climate.run ARGV
+
+
+
+$stdout.puts 'no flags specified'
+
+

data/lib/libclimate/climate.rb

@@ -5,7 +5,7 @@
 # Purpose:      Definition of the ::LibCLImate::Climate class
 #
 # Created:      13th July 2015
-# Updated:      12th March 2019
+# Updated:      10th April 2019
 #
 # Home:         http://github.com/synesissoftware/libCLImate.Ruby
 #
@@ -171,12 +171,12 @@ class Climate
 		options[:values] = usage_values if usage_values
 		options[:flags_and_options] = flags_and_options if flags_and_options
 
-		CLASP.show_usage aliases, options
+		CLASP.show_usage specifications, options
 	end
 
 	def show_version_
 
-		CLASP.show_version aliases, stream: stdout, program_name: program_name, version: version, exit: exit_on_usage ? 0 : nil
+		CLASP.show_version specifications, stream: stdout, program_name: program_name, version: version, exit: exit_on_usage ? 0 : nil
 	end
 
 	def infer_version_ ctxt
@@ -272,9 +272,9 @@ class Climate
 	#
 	# * *Options*:
 	#   - +:no_help_flag+:: (boolean) Prevents the use of the
-	#     +CLASP::Flag.Help+ flag-alias
+	#     +CLASP::Flag.Help+ flag-specification
 	#   - +:no_version_flag+:: (boolean) Prevents the use of the
-	#     +CLASP::Flag.Version+ flag-alias
+	#     +CLASP::Flag.Version+ flag-specification
 	#   - +:program_name+:: (::String) An explicit program-name, which is
 	#     inferred from +$0+ if this is +nil+
 	#   - +:version+:: A version specification. If not specified, this is
@@ -301,7 +301,7 @@ class Climate
 			pr_name	=	(pr_name =~ /\.(?:bat|cmd|rb|sh)$/) ? "#$`(#$&)" : pr_name
 		end
 
-		@aliases			=	[]
+		@specifications		=	[]
 		@ignore_unknown		=	false
 		@exit_on_unknown	=	true
 		@exit_on_missing	=	true
@@ -317,8 +317,8 @@ class Climate
 		version_context		=	options[:version_context]
 		@version			=	options[:version] || infer_version_(version_context)
 
-		@aliases << CLASP::Flag.Help(handle: proc { show_usage_ }) unless options[:no_help_flag]
-		@aliases << CLASP::Flag.Version(handle: proc { show_version_ }) unless options[:no_version_flag]
+		@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]
 
 		yield self if block_given?
 	end
@@ -332,9 +332,11 @@ class Climate
 		@program_name	=	name
 	end
 
-	# An array of aliases attached to the climate instance, whose contents should be modified by adding (or removing) CLASP aliases
-	# @return (::Array) The aliases
-	attr_reader :aliases
+	# An array of specifications attached to the climate instance, whose contents should be modified by adding (or removing) CLASP specifications
+	# @return (::Array) The specifications
+	attr_reader :specifications
+	# [DEPRECATED] Instead, use +specifications+
+	def aliases; specifications; end
 	# Indicates whether exit will be called (with non-zero exit code) when a
 	# required command-line option is missing
 	# @return (boolean)
@@ -400,7 +402,7 @@ class Climate
 
 		raise ArgumentError, "argv may not be nil" if argv.nil?
 
-		arguments	=	CLASP::Arguments.new argv, aliases
+		arguments	=	CLASP::Arguments.new argv, specifications
 		flags		=	arguments.flags
 		options		=	arguments.options
 		values		=	arguments.values.to_a
@@ -430,7 +432,7 @@ class Climate
 
 		flags.each do |f|
 
-			al = aliases.detect do |a|
+			al = specifications.detect do |a|
 
 				a.kind_of?(::CLASP::Flag) && f.name == a.name
 			end
@@ -492,7 +494,7 @@ class Climate
 
 		options.each do |o|
 
-			al = aliases.detect do |a|
+			al = specifications.detect do |a|
 
 				a.kind_of?(::CLASP::Option) && o.name == a.name
 			end
@@ -555,16 +557,16 @@ class Climate
 
 		# now police any required options
 
-		required_aliases = aliases.select do |a|
+		required_specifications = specifications.select do |a|
 
 			a.kind_of?(::CLASP::Option) && a.required?
 		end
 
-		required_aliases = Hash[required_aliases.map { |a| [ a.name, a ] }]
+		required_specifications = Hash[required_specifications.map { |a| [ a.name, a ] }]
 
 		given_options = Hash[results[:options][:given].map { |o| [ o.name, o ]}]
 
-		required_aliases.each do |k, a|
+		required_specifications.each do |k, a|
 
 			unless given_options.has_key? k
 
@@ -720,7 +722,7 @@ class Climate
 		msg
 	end
 
-	# Adds a flag to +aliases+
+	# Adds a flag to +specifications+
 	#
 	# === Signature
 	#
@@ -729,24 +731,24 @@ class Climate
 	#   - +options+:: An options hash, containing any of the following options.
 	#
 	# * *Options*
-	#   - +:help+:: 
-	#   - +:alias+:: 
-	#   - +:aliases+:: 
-	#   - +:extras+:: 
+	#   - +:help+::
+	#   - +:alias+::
+	#   - +:specifications+::
+	#   - +:extras+::
 	def add_flag(name_or_flag, options={}, &block)
 
 		check_parameter name_or_flag, 'name_or_flag', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::Flag ]
 
 		if ::CLASP::Flag === name_or_flag
 
-			aliases << name_or_flag
+			specifications << name_or_flag
 		else
 
-			aliases << CLASP.Flag(name_or_flag, **options, &block)
+			specifications << CLASP.Flag(name_or_flag, **options, &block)
 		end
 	end
 
-	# Adds an option to +aliases+
+	# Adds an option to +specifications+
 	#
 	# === Signature
 	#
@@ -755,42 +757,42 @@ class Climate
 	#   - +options+:: An options hash, containing any of the following options.
 	#
 	# * *Options*
-	#   - +:alias+:: 
-	#   - +:aliases+:: 
-	#   - +:help+:: 
-	#   - +:values_range+:: 
-	#   - +:default_value+:: 
-	#   - +:extras+:: 
+	#   - +:alias+::
+	#   - +:specifications+::
+	#   - +:help+::
+	#   - +:values_range+::
+	#   - +:default_value+::
+	#   - +:extras+::
 	def add_option(name_or_option, options={}, &block)
 
 		check_parameter name_or_option, 'name_or_option', allow_nil: false, types: [ ::String, ::Symbol, ::CLASP::Option ]
 
 		if ::CLASP::Option === name_or_option
 
-			aliases << name_or_option
+			specifications << name_or_option
 		else
 
-			aliases << CLASP.Option(name_or_option, **options, &block)
+			specifications << CLASP.Option(name_or_option, **options, &block)
 		end
 	end
 
-	# Adds an alias to +aliases+
+	# Adds an alias to +specifications+
 	#
 	# === Signature
 	#
 	# * *Parameters*
-	#   - +name_or_alias+:: The flag/option name or the valued option
+	#   - +name_or_specification+:: The flag/option name or the valued option
 	#   - +aliases+:: One or more aliases
 	#
 	# === Examples
 	#
-	# ==== Alias(es) of a flag (single statement)
+	# ==== Specification(s) of a flag (single statement)
 	#
 	# +climate.add_flag('--mark-missing', alias: '-x')+
 	#
 	# +climate.add_flag('--absolute-path', aliases: [ '-abs', '-p' ])+
 	#
-	# ==== Alias(es) of a flag (multiple statements)
+	# ==== Specification(s) of a flag (multiple statements)
 	#
 	# +climate.add_flag('--mark-missing')+
 	# +climate.add_alias('--mark-missing', '-x')+
@@ -798,35 +800,35 @@ class Climate
 	# +climate.add_flag('--absolute-path')+
 	# +climate.add_alias('--absolute-path', '-abs', '-p')+
 	#
-	# ==== Alias(es) of an option (single statement)
+	# ==== Specification(s) of an option (single statement)
 	#
 	# +climate.add_option('--add-patterns', alias: '-p')+
 	#
-	# ==== Alias(es) of an option (multiple statements)
+	# ==== Specification(s) of an option (multiple statements)
 	#
 	# +climate.add_option('--add-patterns')+
 	# +climate.add_alias('--add-patterns', '-p')+
 	#
-	# ==== Alias of a valued option (which has to be multiple statements)
+	# ==== Specification of a valued option (which has to be multiple statements)
 	#
 	# +climate.add_option('--verbosity')+
 	# +climate.add_alias('--verbosity=succinct', '-s')+
 	# +climate.add_alias('--verbosity=verbose', '-v')+
-	def add_alias(name_or_alias, *aliases)
+	def add_alias(name_or_specification, *aliases)
 
-		check_parameter name_or_alias, 'name_or_alias', 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::Flag, ::CLASP::Option ]
 		raise ArgumentError, "must supply at least one alias" if aliases.empty?
 
-		case name_or_alias
+		case name_or_specification
 		when ::CLASP::Flag
 
-			self.aliases << name_or_alias
+			self.specifications << name_or_specification
 		when ::CLASP::Option
 
-			self.aliases << name_or_alias
+			self.specifications << name_or_specification
 		else
 
-			self.aliases << CLASP.Alias(name_or_alias, aliases: aliases)
+			self.specifications << CLASP.Alias(name_or_specification, aliases: aliases)
 		end
 	end
 end # class Climate

data/lib/libclimate/version.rb

@@ -4,7 +4,7 @@
 # Purpose:      Version for libclimate.Ruby library
 #
 # Created:      13th July 2015
-# Updated:      12th March 2019
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/libCLImate.Ruby
 #
@@ -43,7 +43,7 @@
 module LibCLImate
 
 	# Current version of the libCLImate.Ruby library
-	VERSION					=	'0.11.0'
+	VERSION					=	'0.12.0'
 
 	private
 	VERSION_PARTS_			=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/test/scratch/{aliases.rb → specifications.rb}

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
 
 #############################################################################
-# File:         test/scratch/aliases.rb
+# File:         test/scratch/specifications.rb
 #
-# Purpose:      Demonstrates use of aliases in options and flags
+# Purpose:      Demonstrates use of specifications in options and flags
 #
 # Created:      7th February 2018
 # Updated:      7th February 2018
@@ -22,10 +22,10 @@ require 'libclimate'
 # ##########################################################
 # constants
 
-PROGRAM_VER_MAJOR               =   0
-PROGRAM_VER_MINOR               =   1
-PROGRAM_VER_REVISION            =   1
-PROGRAM_VER_BUILD               =   1
+PROGRAM_VER_MAJOR	=	0
+PROGRAM_VER_MINOR	=	1
+PROGRAM_VER_PATCH	=	2
+PROGRAM_VER_BUILD	=	1
 
 # ##########################################################
 # command-line parsing
@@ -43,7 +43,15 @@ r = LibCLImate::Climate.new do |cl|
 	cl.info_lines = [
 
 		:version,
-		'demonstrates use of aliases',
+		'demonstrates use of specifications',
+	]
+
+	cl.version = [
+
+		PROGRAM_VER_MAJOR,
+		PROGRAM_VER_MINOR,
+		PROGRAM_VER_PATCH,
+		PROGRAM_VER_BUILD,
 	]
 end.run
 

data/test/unit/tc_minimal.rb

@@ -371,7 +371,7 @@ class Test_Climate_minimal < Test::Unit::TestCase
 			climate.add_option('--verbosity', alias: '-v', help: 'determines level of verbose operation', required: true)
 		end
 
-		assert climate.aliases[2].required?
+		assert climate.specifications[2].required?
 
 		r = climate.run %w{ -v 2 }
 
@@ -418,7 +418,7 @@ class Test_Climate_minimal < Test::Unit::TestCase
 
 		r = climate.run %w{ }
 
-		assert climate.aliases[2].required?
+		assert climate.specifications[2].required?
 
 		assert_not_nil r
 		assert_kind_of ::Hash, r
@@ -468,7 +468,7 @@ class Test_Climate_minimal < Test::Unit::TestCase
 
 		r = climate.run %w{ }
 
-		assert climate.aliases[2].required?
+		assert climate.specifications[2].required?
 
 		assert_not_nil r
 		assert_kind_of ::Hash, r
@@ -518,7 +518,7 @@ class Test_Climate_minimal < Test::Unit::TestCase
 
 		r = climate.run %w{ }
 
-		assert climate.aliases[2].required?
+		assert climate.specifications[2].required?
 
 		assert_not_nil r
 		assert_kind_of ::Hash, r

data/test/unit/tc_minimal_CLASP.rb

@@ -223,8 +223,8 @@ class Test_Climate_minimal_CLASP < Test::Unit::TestCase
 
 			bl = false#proc { is_verbose = true }
 
-			climate.aliases << CLASP.Flag('--succinct', alias: '-s', help: 'operates succinctly')
-			climate.aliases << CLASP.Flag('--verbose', alias: '-v', help: 'operates verbosely', extras: { :handle => proc { is_verbose = true }})
+			climate.add_flag('--succinct', alias: '-s', help: 'operates succinctly')
+			climate.add_flag('--verbose', alias: '-v', help: 'operates verbosely', extras: { :handle => proc { is_verbose = true }})
 		end
 
 		argv = %w{ --help --verbose --succinct }
@@ -281,7 +281,7 @@ class Test_Climate_minimal_CLASP < Test::Unit::TestCase
 			climate.stdout = str
 			climate.exit_on_usage = false
 
-			climate.aliases << CLASP.Flag('--verbose', alias: '-v', help: 'operates verbosely', extras: { handle: proc { is_verbose = true }})
+			climate.add_flag('--verbose', alias: '-v', help: 'operates verbosely', extras: { handle: proc { is_verbose = true }})
 		end
 
 		argv = %w{ --verbose }
@@ -325,7 +325,7 @@ class Test_Climate_minimal_CLASP < Test::Unit::TestCase
 			climate.stdout = str
 			climate.exit_on_usage = false
 
-			climate.aliases << CLASP.Option('--verbosity', alias: '-v', help: 'determines level of verbose operation', extras: { handle: proc { |o| verbosity = o.value }})
+			climate.add_option('--verbosity', alias: '-v', help: 'determines level of verbose operation', extras: { handle: proc { |o| verbosity = o.value }})
 		end
 
 		argv = %w{ -v 2 }

data/test/unit/{tc_test_aliases.rb → tc_test_specifications.rb}

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 #
-# test aliases
+# test specifications
 
 $:.unshift File.join(File.dirname(__FILE__), '../..', 'lib')
 
@@ -15,7 +15,7 @@ require 'stringio'
 
 class Test_Climate_minimal < Test::Unit::TestCase
 
-	def test_option_with_flag_aliases
+	def test_option_with_flag_specifications
 
 		options	=	{}
 
@@ -44,7 +44,7 @@ class Test_Climate_minimal < Test::Unit::TestCase
 			assert_equal 'action1', options[:action]
 		end
 
-		# invoke via option alias
+		# invoke via option specification
 		begin
 			options = {}
 
@@ -57,7 +57,7 @@ class Test_Climate_minimal < Test::Unit::TestCase
 			assert_equal 'action2', options[:action]
 		end
 
-		# invoke via flag alias
+		# invoke via flag specification
 		begin
 			options = {}
 
@@ -70,7 +70,7 @@ class Test_Climate_minimal < Test::Unit::TestCase
 			assert_equal 'change', options[:action]
 		end
 
-		# invoke via flag alias
+		# invoke via flag specification
 		begin
 			options = {}
 

data/test/unit/tc_with_blocks_CLASP.rb

@@ -21,7 +21,7 @@ class Test_Climate_with_blocks_CLASP < Test::Unit::TestCase
 
 		climate = LibCLImate::Climate.new do |climate|
 
-			climate.aliases << CLASP.Flag('--verbose') { is_verbose = true }
+			climate.add_flag('--verbose') { is_verbose = true }
 		end
 
 		argv = %w{ --verbose }
@@ -37,7 +37,7 @@ class Test_Climate_with_blocks_CLASP < Test::Unit::TestCase
 
 		climate = LibCLImate::Climate.new do |climate|
 
-			climate.aliases << CLASP.Option('--flavour') { |o|  flavour = o.value }
+			climate.add_option('--flavour') { |o|  flavour = o.value }
 		end
 
 		argv = %w{ --flavour=blueberry }

metadata

@@ -1,41 +1,41 @@
 --- !ruby/object:Gem::Specification
 name: libclimate-ruby
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-19 00:00:00.000000000 Z
+date: 2019-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clasp-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: xqsr3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.31'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.31'
 description: |2+
@@ -45,26 +45,30 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
+- examples/flag_and_option_specifications.md
+- examples/flag_and_option_specifications.rb
+- examples/show_usage_and_version.md
+- examples/show_usage_and_version.rb
+- lib/libclimate.rb
 - lib/libclimate/climate.rb
 - lib/libclimate/libclimate.rb
 - lib/libclimate/version.rb
-- lib/libclimate.rb
-- test/scratch/aliases.rb
 - test/scratch/blankzeroes.rb
+- test/scratch/specifications.rb
 - test/unit/tc_abort.rb
 - test/unit/tc_infer_version.rb
 - test/unit/tc_minimal.rb
 - test/unit/tc_minimal_CLASP.rb
-- test/unit/tc_test_aliases.rb
+- test/unit/tc_test_specifications.rb
 - test/unit/tc_values.rb
 - test/unit/tc_with_blocks.rb
 - test/unit/tc_with_blocks_CLASP.rb
 - test/unit/ts_all.rb
-- README.md
-- LICENSE
 homepage: http://www.libclimate.org/
 licenses:
-- Modified BSD
+- BSD-3-Clause
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -72,17 +76,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ~>
+  - - "~>"
     - !ruby/object:Gem::Version
       version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14.1
+rubygems_version: 2.2.5
 signing_key: 
 specification_version: 4
 summary: libCLImate.Ruby