clasp-ruby 0.10.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d272de686d9352ca5f798e3235b78a1b2711516e
+  data.tar.gz: 5b40f0eb1d2ec82edd4c04ae06457b09d5e7bce1
+SHA512:
+  metadata.gz: d61b6ece12b65f7fd2fe310f092468006ed8af5dca6ccc2db06ce6d3fc1e5205869ab53379d0ef270bf65b6291e870905bab19773e1e8b363472acf2e8e73d72
+  data.tar.gz: 67c1a12d8fd6389712d03e4ca48360bf6bbf6b3d445e54792112d9ddb0bb8915b6c951b2fa1c679b58ebcd87501eb70dbf3c8dff7a795d82f2c7bcc8e8e1ff9b

data/LICENSE

@@ -0,0 +1,30 @@
+CLASP.Ruby
+
+Copyright (c) 2008-2016, Matthew Wilson and Synesis Software
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+* list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+* this list of conditions and the following disclaimer in the documentation
+* and/or other materials provided with the distribution.
+
+* Neither the names of the copyright holder nor the names of its contributors
+* may be used to endorse or promote products derived from this software without
+* specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/README.md

@@ -0,0 +1,186 @@
+# CLASP.Ruby
+
+## Installation & usage
+
+Install using `gem install clasp-ruby` or add it to your `Gemfile`.
+
+## Description
+
+**CLASP** stands for **C**\ommand-**L**\ine **A**\rgument **S**\orting and
+**P**\arsing. The first \CLASP library was a C library with a C++ wrapper. There
+have been several implementations in other languages. **CLASP.Ruby** is the
+Ruby version.
+
+All \CLASP libraries provide the following facilities to **C**\ommand **L**\ine
+**I**\nterface (**CLI**) programs:
+
+### Command-line parsing
+
+All **CLASP** libraries discriminate between three types of command-line arguments:
+
+ * *flags* are hyphen-prefixed arguments that are either present or absent, and hence have a boolean nature;
+ * *options* are hyphen-prefixed arguments that are given values; and
+ * *values* are non-hyphen-prefixed arguments that represent values.
+
+For example, in the command line
+
+	`myprog --all -c --opt1=val1 infile outfile`
+
+there are:
+
+ * two *flags*, `--all` and `-c`;
+ * one *option* called `--opt1`, which has the value `val1`; and
+ * two *values* `infile` and `outfile`.
+
+*Flags* and *options* may have alias. If the alias for `--all` is `-a` and the alias for `--opt1` is `-o` then the following command-line is exactly equivalent to the previous one:
+
+	`myprog -a -c -o val1 infile outfile`
+
+One-letter *flags* may be combined. Hence, the following command-line is exactly equivalent to the previous ones:
+
+	`myprog -ac -o val1 infile outfile`
+
+Option aliases may specify a value. If the alias `-v1` means `--opt1=val1` then the following command-line is exactly equivalent to the previous ones:
+
+	`myprog -ac -v1 infile outfile`
+
+Option aliases that are one letter may be combined with one-letter flags. If the alias `-v` means `--opt1=val1` then the following command-line is exactly equivalent to the previous ones:
+
+	`myprog -acv infile outfile`
+
+UNIX standard arguments confer specific meanings:
+
+ * `--help` means that the program should show the usage/help information and terminate;
+ * `--version` means that the program should show the version information and terminate;
+ * `--` means that all subsequent arguments should be treated as values, regardless of any hyphen-prefixes or embedded `=` signs.
+
+### Declarative specification of the flags and options for a CLI
+
+To support such above special processing, \CLASP libraries provide facilities
+for declarative specification of command-line *flags* and *options*, and
+aliases thereof. For the previous example, the **CLASP.Ruby** code would look
+like the following:
+
+```ruby
+
+# file: cr-example.rb
+
+PROGRAM_VERSION = '0.1.2'
+
+Aliases = [
+
+	CLASP.Flag('--all', alias: '-a', help: 'processes all item types'),
+	CLASP.Flag('-c', help: 'count the processed items'),
+	CLASP.Option('--opt1', alias: '-o', help: 'an option of some kind', values_range: %w{ val1, val2 }),
+	CLASP.Option('--opt1=val1', alias: '-v'),
+
+	# see next section for why these two are here
+	CLASP::Flag.Help,
+	CLASP::Flag.Version,
+]
+
+# assuming the command-line `myprog -acv infile outfile`
+Args = CLASP::Arguments.new(ARGV, Aliases)
+
+puts Args.flags.size                # => 2
+puts Args.flags[0].name             # => "--all"
+puts Args.flags[1].name             # => "-c"
+
+puts Args.options.size              # => 1
+puts Args.options[0].name           # => "--opt1"
+puts Args.options[0].value          # => "val1"
+
+puts Args.values.size               # => 2
+puts Args.values[0]                 # => "infile"
+puts Args.values[1]                 # => "outfile"
+
+```
+
+### Utility functions for displaying usage and version information
+
+There are aspects common to all CLI programs, such as responding to `--help` and `--version`. All **\CLASP** libraries provide facilities to assist the programmer: **CLASP.Ruby** provides the two module methods CLASP.show_usage() and CLASP.show_version(), as shown in the following code extending the example above:
+
+```ruby
+
+Args.flags.each do |f|
+
+	case f.name
+	when CLASP::Flag.Help.name
+
+		CLASP.show_usage(Aliases, exit: 0, values: '<input-file> <output-file>')
+	when CLASP::Flag.Version.name
+
+		CLASP.show_version(Aliases, exit: 0, version: PROGRAM_VERSION)
+	when '--all'
+
+		# do something appropriate to `--all`
+
+	. . .
+
+```
+
+Given the command
+
+	`./cr-example.rb --help`
+
+then the program will output the following
+
+```
+USAGE: cr-example.rb [ ... flags and options ... ] <input-file> <output-file>
+
+flags/options:
+
+	-a
+	--all
+		processes all item types
+
+	-c
+		count the processed items
+
+	-v --opt1=val1
+	-o <value>
+	--opt1=<value>
+		an option of some kind where <value> one of:
+			val1,
+			val2
+
+	--help
+		shows this help and terminates
+
+	--version
+		shows version and terminates
+
+```
+
+and given the command
+
+	`./cr-example.rb --version`
+
+then the program will output the following
+
+```
+cr-example.rb 0.1.2
+```
+
+## Where to get help
+
+[GitHub Page](https://github.com/synesissoftware/CLASP.Ruby "GitHub Page")
+
+## Contribution guidelines
+
+Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/CLASP.Ruby.
+
+## Related projects
+
+**CLASP.Ruby** is inspired by the [C/C++ CLASP library](https://github.com/synesissoftware/CLASP), which is documented in the articles:
+
+ * _An Introduction to \CLASP_, Matthew Wilson, [CVu](http://accu.org/index.php/journals/c77/), January 2012;
+ * _[Anatomy of a CLI Program written in C](http://synesis.com.au/publishing/software-anatomies/anatomy-of-a-cli-program-written-in-c.html)_, Matthew Wilson, [CVu](http://accu.org/index.php/journals/c77/), September 2012; and
+ * _[Anatomy of a CLI Program written in C++](http://synesis.com.au/publishing/software-anatomies/anatomy-of-a-cli-program-written-in-c++.html)_, Matthew Wilson, [CVu](http://accu.org/index.php/journals/c77/), September 2015.
+
+**CLASP.Ruby** is used in the **[libCLImate.Ruby](https://github.com/synesissoftware/libCLImate.Ruby)** library.
+
+## License
+
+**CLASP.Ruby** is released under the 3-clause BSD license. See LICENSE for details.
+

data/examples/cr-example.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/ruby
+
+#############################################################################
+# File:         examples/cr-example.rb
+#
+# Purpose:      COMPLETE_ME
+#
+# Created:      11 06 2016
+# Updated:      11 06 2016
+#
+# Author:       Matthew Wilson
+#
+#############################################################################
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'clasp'
+
+PROGRAM_VERSION = '0.1.2'
+
+Aliases = [
+
+	CLASP.Flag('--all', alias: '-a', help: 'processes all item types'),
+	CLASP.Flag('-c', help: 'count the processed items'),
+	CLASP.Option('--opt1', alias: '-o', help: 'an option of some kind', values_range: %w{ val1, val2 }),
+	CLASP.Option('--opt1=val1', alias: '-v'),
+
+	# see next section for why these two are here
+	CLASP::Flag.Help,
+	CLASP::Flag.Version,
+]
+
+Args = CLASP::Arguments.new(ARGV, Aliases)
+
+Args.flags.each do |f|
+
+	case f.name
+	when CLASP::Flag.Help.name
+
+		CLASP.show_usage(Aliases, exit: 0, values: '<input-file> <output-file>')
+	when CLASP::Flag.Version.name
+
+		CLASP.show_version(Aliases, exit: 0, version: PROGRAM_VERSION)
+	when '--all'
+
+		;
+	end
+end
+
+puts Args.flags.size
+puts Args.flags[0].name
+puts Args.flags[1].name
+puts
+
+puts Args.options.size
+puts Args.options[0].name
+puts Args.options[0].value
+puts
+
+puts Args.values.size
+puts Args.values[0]
+puts Args.values[1]
+puts

data/lib/clasp-ruby.rb

@@ -0,0 +1,51 @@
+
+# ######################################################################## #
+# File:         clasp-ruby.rb
+#
+# Purpose:      Top-level source for CLASP.ruby library [alternate]
+#
+# Created:      13th October 2014
+# Updated:      10th June 2016
+#
+# Home:         http://github.com/synesissoftware/CLASP.Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2014-2016, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+# clasp-ruby.rb -> clasp/clasp.rb
+require 'clasp/clasp'
+
+# ############################## end of file ############################# #
+

data/lib/clasp.rb

@@ -0,0 +1,51 @@
+
+# ######################################################################## #
+# File:         clasp.rb
+#
+# Purpose:      Top-level source for CLASP.ruby library
+#
+# Created:      13th October 2014
+# Updated:      10th June 2016
+#
+# Home:         http://github.com/synesissoftware/CLASP.Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2014-2016, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+# clasp.rb -> clasp/clasp.rb
+require 'clasp/clasp'
+
+# ############################## end of file ############################# #
+

data/lib/clasp/aliases.rb

@@ -0,0 +1,256 @@
+
+# ######################################################################## #
+# File:         clasp/aliases.rb
+#
+# Purpose:      Alias classes
+#
+# Created:      25th October 2014
+# Updated:      10th June 2016
+#
+# Home:         http://github.com/synesissoftware/CLASP.Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2014-2016, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+
+
+# ######################################################################## #
+# module
+
+=begin
+=end
+
+module CLASP
+
+# ######################################################################## #
+# classes
+
+# A class that represents the specification for a command-line flag
+class Flag
+
+	# Creates a Flag instance from the given name, aliases, and help
+	#
+	# === 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+.
+	def initialize(name, aliases, help, extras = nil)
+
+		@name			=	name
+		@aliases		=	(aliases || []).select { |a| a and not a.empty? }
+		@help			=	help
+		@extras			=	extras || {}
+	end
+
+	# The flag's name string
+	attr_reader	:name
+	# The flag's aliases array
+	attr_reader	:aliases
+	# The flag's help string
+	attr_reader	:help
+	# The flag's extras
+	attr_reader :extras
+
+	# String form of the flag
+	def to_s
+
+		"{#{name}; aliases=#{aliases.join(', ')}; help='#{help}'; extras=#{extras}}"
+	end
+
+  private
+	@@Help_		=	self.new('--help', [], 'shows this help and terminates')
+	@@Version_	=	self.new('--version', [], 'shows version and terminates')
+  public
+	# An instance of Flag that provides default '--help' information
+	def self.Help(extras = nil)
+
+		h = @@Help_
+
+		return self.new(h.name, h.aliases, h.help, extras) if extras
+
+		h
+	end
+
+	# An instance of Flag that provides default '--version' information
+	def self.Version(extras = nil)
+
+		h = @@Version_
+
+		return self.new(h.name, h.aliases, h.help, extras) if extras
+
+		h
+	end
+end
+
+# A class that represents the specification for a command-line option
+class Option
+
+	# Creates an Option instance from the given name, aliases, help,
+	# values_range, and default_value
+	#
+	# === 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+.
+	#   - +extras+:: An application-defined additional parameter. If +nil+, it is assigned an empty +Hash+.
+	def initialize(name, aliases, help, values_range, default_value, extras = nil)
+
+		@name			=	name
+		@aliases		=	(aliases || []).select { |a| a and not a.empty? }
+		@help			=	help
+		@values_range	=	values_range || []
+		@default_value	=	default_value
+		@extras			=	extras || {}
+	end
+
+	# The option's name string
+	attr_reader	:name
+	# The option's aliases array
+	attr_reader	:aliases
+	# The option's help string
+	attr_reader	:help
+	# The range of values supported by the option
+	attr_reader	:values_range
+	# The default value of the option
+	attr_reader	:default_value
+	# The flag's extras
+	attr_reader :extras
+
+	# String form of the option
+	def to_s
+
+		"{#{name}; aliases=#{aliases.join(', ')}; values_range=[ #{values_range.join(', ')} ]; default_value='#{default_value}'; help='#{help}'; extras=#{extras}}"
+	end
+end
+
+# ######################################################################## #
+# functions
+
+# Generator method that obtains a CLASP::Flag according to the given parameters
+def CLASP.Flag(name, options = {})
+
+	aliases	=	nil
+	help	=	nil
+	extras	=	nil
+
+	options.each do |k, v|
+
+		case	k
+		when	Symbol
+			case	k
+			when	:alias
+
+				aliases	=	[ v ]
+			when	:aliases
+
+				aliases	=	v
+			when	:help
+
+				help	=	v
+			when	:extras
+
+				extras	=	v
+			else
+
+				raise ArgumentError, "invalid option for flag: '#{k}' => '#{v}'"
+			end
+		else
+
+			raise ArgumentError, "invalid option type for flag: '#{k}' (#{k.class}) => '#{v}'"
+		end
+	end
+
+	CLASP::Flag.new(name, aliases, help, extras)
+end
+
+# Generator method that obtains a CLASP::Option according to the given parameters
+def CLASP.Option(name, options = {})
+
+	aliases			=	nil
+	help			=	nil
+	values_range	=	nil
+	default_value	=	nil
+	extras			=	nil
+
+	options.each do |k, v|
+
+		case	k
+		when	Symbol
+			case	k
+			when	:alias
+
+				aliases	=	[ v ]
+			when	:aliases
+
+				aliases	=	v
+			when	:help
+
+				help	=	v
+			when	:values_range, :values
+
+				values_range	=	v
+			when	:default_value, :default
+
+				default_value	=	v
+			when	:extras
+
+				extras	=	v
+			else
+
+				raise ArgumentError, "invalid option for flag: '#{k}' => '#{v}'"
+			end
+		else
+
+			raise ArgumentError, "invalid option type for flag: '#{k}' (#{k.class}) => '#{v}'"
+		end
+	end
+
+	CLASP::Option.new(name, aliases, help, values_range, default_value, extras)
+end
+
+# ######################################################################## #
+# module
+
+end # module CLASP
+
+# ############################## end of file ############################# #
+