clasp-ruby 0.23.0.1 → 0.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e021c90f3ea92340418a827f98a4fcb3c3f1369b023b0374f90e224acb8f01c
-  data.tar.gz: 62ed469712505ebbf289e7b642e48525f37f21dc1223cf8f13dca107f3b1a1f4
+  metadata.gz: 20c2f03782787016c1a8d5d2f2ef4ec5278578571f4a806e38cbaceb83ba0f0c
+  data.tar.gz: 6e6c1f2fadf64a6afd4a09e0126663f2526bcf1b56e3f311cc3e7d91cd50990a
 SHA512:
-  metadata.gz: 462eca92c73b9eefd0846cb64567d1b2071570789c0beb6cc0802e443e1e6a3c762ec39f57e438781d0b53e8d31310dc765a8e108d77ff989795d24bae7c1239
-  data.tar.gz: e7b1b47f51ea4e724412e2ffa634a1e8e47118f00f32b133735656c98f0e9b18c3286b1b77ba7e409545340e248b50c187c1939e6275a34ee36025ad17eb7b81
+  metadata.gz: 10a26aab12d7e303be72ef78547bbb3035820112f41bc26542370c8071dcb09e392c4c05fd60c20e9cdc915683a2efeffc828ca90e2829b0d96597f09d6d510d
+  data.tar.gz: 25ee3bff884c3e50385686e1d7a37a520fbc10538d716b720a4bd95528f044adc5133c35358192703ca3218681532b8b9cda8a0d84b0a7d59ed83e7877938ca6

data/README.md

@@ -1,32 +1,40 @@
-# CLASP.Ruby
+# CLASP.Ruby <!-- omit in toc -->
 Command-Line Argument Sorting and Parsing, for Ruby
 
 [![Gem Version](https://badge.fury.io/rb/clasp-ruby.svg)](https://badge.fury.io/rb/clasp-ruby)
 
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [Installation](#installation)
-3. [Components](#components)
-4. [Examples](#examples)
-5. [Project Information](#project-information)
+## Table of Contents <!-- omit in toc -->
+
+- [Introduction](#introduction)
+    - [libCLImate.Ruby](#libclimateruby)
+- [Installation](#installation)
+- [Components](#components)
+    - [Command-line parsing](#command-line-parsing)
+    - [Declarative specification of the flags and options for a CLI](#declarative-specification-of-the-flags-and-options-for-a-cli)
+    - [Utility functions for displaying usage and version information](#utility-functions-for-displaying-usage-and-version-information)
+- [Examples](#examples)
+- [Project Information](#project-information)
+    - [Where to get help](#where-to-get-help)
+    - [Contribution guidelines](#contribution-guidelines)
+    - [Related projects](#related-projects)
+    - [License](#license)
 
 ## Introduction
 
-**CLASP** stands for Command-Line Argument Sorting and
-Parsing. 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.
+**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 (see project [**CLASP**](https://github.com/synesissoftware/CLASP/)). There have been several implementations in other languages (as listed in [Relation projects](#related-projects)). **CLASP.Ruby** is the Ruby version.
+
+All **CLASP** libraries provide the facilities to **C**ommand **L**ine **I**nterface (**CLI**) programs as described in detail below.
+
+### libCLImate.Ruby
 
-All CLASP libraries provide the facilities to **C**ommand **L**ine
-**I**nterface (**CLI**) programs as described in detail below.
+The [**libCLImate.Ruby**](https://github.com/synesissoftware/libCLImate.Ruby) library is implemented in terms of **CLASP.Ruby** but provides a higher-level abstration as well as several utility functions and the facility to fully specify command-line arguments declaratively in the `__END__` section of a source file. More information and examples provided in the [**libCLImate.Ruby**](https://github.com/synesissoftware/libCLImate.Ruby) project.
 
 ## Installation
 
 Install via **gem** as in:
 
 ```
-	gem install clasp-ruby
+    gem install clasp-ruby
 ```
 
 or add it to your `Gemfile`.
@@ -50,7 +58,7 @@ All **CLASP** libraries discriminate between three types of command-line argumen
 For example, in the command line
 
 ```
-	myprog --all -c --opt1=val1 infile outfile
+    myprog --all -c --opt1=val1 infile outfile
 ```
 
 there are:
@@ -62,25 +70,25 @@ there are:
 *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
+    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
+    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
+    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
+    myprog -acv infile outfile
 ```
 
 UNIX standard arguments confer specific meanings:
@@ -104,14 +112,14 @@ PROGRAM_VERSION = '0.1.2'
 
 Specifications = [
 
-	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.Flag('--opt1=val1', alias: '-v'),
+    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.Flag('--opt1=val1', alias: '-v'),
 
-	# see next section for why these two are here
-	CLASP::Flag.Help,
-	CLASP::Flag.Version,
+    # see next section for why these two are here
+    CLASP::Flag.Help,
+    CLASP::Flag.Version,
 ]
 
 # assuming the command-line `myprog -acv infile outfile`
@@ -139,25 +147,25 @@ There are aspects common to all CLI programs, such as responding to `--help` and
 
 Args.flags.each do |f|
 
-	case f.name
-	when CLASP::Flag.Help.name
+    case f.name
+    when CLASP::Flag.Help.name
 
-		CLASP.show_usage(Specifications, exit: 0, values: '<input-file> <output-file>')
-	when CLASP::Flag.Version.name
+        CLASP.show_usage(Specifications, exit: 0, values: '<input-file> <output-file>')
+    when CLASP::Flag.Version.name
 
-		CLASP.show_version(Specifications, exit: 0, version: PROGRAM_VERSION)
-	when '--all'
+        CLASP.show_version(Specifications, exit: 0, version: PROGRAM_VERSION)
+    when '--all'
 
-		# do something appropriate to `--all`
+        # do something appropriate to `--all`
 
-	. . .
+    . . .
 
 ```
 
 Given the command
 
 ```
-	./cr-example.rb --help
+    ./cr-example.rb --help
 ```
 
 then the program will output the following
@@ -167,32 +175,32 @@ USAGE: cr-example.rb [ ... flags and options ... ] <input-file> <output-file>
 
 flags/options:
 
-	-a
-	--all
-		processes all item types
+    -a
+    --all
+        processes all item types
 
-	-c
-		count the processed items
+    -c
+        count the processed items
 
-	-v --opt1=val1
-	-o <value>
-	--opt1=<value>
-		an option of some kind where <value> one of:
-			val1,
-			val2
+    -v --opt1=val1
+    -o <value>
+    --opt1=<value>
+        an option of some kind where <value> one of:
+            val1,
+            val2
 
-	--help
-		shows this help and terminates
+    --help
+        shows this help and terminates
 
-	--version
-		shows version and terminates
+    --version
+        shows version and terminates
 
 ```
 
 and given the command
 
 ```
-	./cr-example.rb --version
+    ./cr-example.rb --version
 ```
 
 then the program will output the following
@@ -239,3 +247,6 @@ Projects in which **CLASP.Ruby** is used include:
 
 **CLASP.Ruby** is released under the 3-clause BSD license. See LICENSE for details.
 
+
+<!-- ########################### end of file ########################### -->
+

data/examples/cr-example.rb

@@ -11,31 +11,31 @@ PROGRAM_VERSION = '0.1.2'
 
 Specifications = [
 
-	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.Flag('--opt1=val1', alias: '-v'),
-
-	# see next section for why these two are here
-	CLASP::Flag.Help,
-	CLASP::Flag.Version,
+  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.Flag('--opt1=val1', alias: '-v'),
+
+  # see next section for why these two are here
+  CLASP::Flag.Help,
+  CLASP::Flag.Version,
 ]
 
 Args = CLASP::Arguments.new(ARGV, Specifications)
 
 Args.flags.each do |f|
 
-	case f.name
-	when CLASP::Flag.Help.name
+  case f.name
+  when CLASP::Flag.Help.name
 
-		CLASP.show_usage(Specifications, exit: 0, values: '<input-file> <output-file>')
-	when CLASP::Flag.Version.name
+    CLASP.show_usage(Specifications, exit: 0, values: '<input-file> <output-file>')
+  when CLASP::Flag.Version.name
 
-		CLASP.show_version(Specifications, exit: 0, version: PROGRAM_VERSION)
-	when '--all'
+    CLASP.show_version(Specifications, exit: 0, version: PROGRAM_VERSION)
+  when '--all'
 
-		;
-	end
+    ;
+  end
 end
 
 puts Args.flags.size

data/examples/flag_and_option_specifications.md

@@ -35,9 +35,9 @@ Flag_Chatty = CLASP.Flag('--verbosity=chatty', alias: '-c')
 
 Specifications = [
 
-	Flag_Debug,
-	Option_Verbosity,
-	Flag_Chatty,
+    Flag_Debug,
+    Option_Verbosity,
+    Flag_Chatty,
 
     CLASP::FlagSpecification.Help,
     CLASP::FlagSpecification.Version,
@@ -60,12 +60,12 @@ end
 
 if (opt = args.find_option('--verbosity'))
 
-	$stdout.puts "verbosity is specified as: #{opt.value}"
+    $stdout.puts "verbosity is specified as: #{opt.value}"
 end
 
 if args.flags.include?('--debug')
 
-	$stdout.puts 'Debug mode is specified'
+    $stdout.puts 'Debug mode is specified'
 end
 
 
@@ -74,7 +74,7 @@ end
 
 if (unused = args.find_first_unknown())
 
-	$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
+    $stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
 
     exit 1
 end
@@ -120,25 +120,25 @@ 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	*default*
-			quiet
-			silent
-			chatty
-
-	--help
-		shows this help and terminates
-
-	--version
-		shows version and terminates
+    -d
+    --debug
+        runs in Debug mode
+
+    -c --verbosity=chatty
+    -v <value>
+    --verbosity=<value>
+        specifies the verbosity
+        where <value> one of:
+            terse   *default*
+            quiet
+            silent
+            chatty
+
+    --help
+        shows this help and terminates
+
+    --version
+        shows version and terminates
 ```
 
 ### Specify flags and options in long-form

data/examples/flag_and_option_specifications.rb

@@ -12,10 +12,10 @@ ProgramVersion = [ 0, 0, 1 ]
 
 InfoLines = [
 
-    'CLASP.Ruby examples',
-    :version,
-    "Illustrates use of CLASP.Ruby's use of flags, options, and aliases",
-    '',
+  'CLASP.Ruby examples',
+  :version,
+  "Illustrates use of CLASP.Ruby's use of flags, options, and aliases",
+  '',
 ]
 
 # Specify specifications, parse, and checking standard flags
@@ -26,24 +26,24 @@ Flag_Chatty = CLASP.Flag('--verbosity=chatty', alias: '-c')
 
 Specifications = [
 
-	Flag_Debug,
-	Option_Verbosity,
-	Flag_Chatty,
+  Flag_Debug,
+  Option_Verbosity,
+  Flag_Chatty,
 
-    CLASP::FlagSpecification.Help,
-    CLASP::FlagSpecification.Version,
+  CLASP::FlagSpecification.Help,
+  CLASP::FlagSpecification.Version,
 ]
 
 args = CLASP::Arguments.new ARGV, Specifications
 
 if args.flags.include?(CLASP::FlagSpecification.Help)
 
-    CLASP.show_usage(Specifications, exit_code: 0, version: ProgramVersion, stream: $stdout, info_lines: InfoLines, default_indicator: '*default*')
+  CLASP.show_usage(Specifications, exit_code: 0, version: ProgramVersion, stream: $stdout, info_lines: InfoLines, default_indicator: '*default*')
 end
 
 if args.flags.include?('--version')
 
-    CLASP.show_version(Specifications, exit_code: 0, version: ProgramVersion, stream: $stdout)
+  CLASP.show_version(Specifications, exit_code: 0, version: ProgramVersion, stream: $stdout)
 end
 
 
@@ -51,12 +51,12 @@ end
 
 if (opt = args.find_option('--verbosity'))
 
-	$stdout.puts "verbosity is specified as: #{opt.value}"
+  $stdout.puts "verbosity is specified as: #{opt.value}"
 end
 
 if args.flags.include?('--debug')
 
-	$stdout.puts 'Debug mode is specified'
+  $stdout.puts 'Debug mode is specified'
 end
 
 
@@ -65,9 +65,9 @@ end
 
 if (unused = args.find_first_unknown())
 
-	$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
+  $stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
 
-    exit 1
+  exit 1
 end
 
 

data/examples/show_usage_and_version.md

@@ -52,7 +52,7 @@ end
 
 if (unused = args.find_first_unknown())
 
-	$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
+    $stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
 
     sys.exit(1)
 end
@@ -102,11 +102,11 @@ USAGE: show_usage_and_version.rb [ ... flags and options ... ]
 
 flags/options:
 
-	--help
-		Shows usage and terminates
+    --help
+        Shows usage and terminates
 
-	--version
-		Shows version and terminates
+    --version
+        Shows version and terminates
 ```
 
 ### Show version

data/examples/show_usage_and_version.rb

@@ -12,30 +12,30 @@ ProgramVersion = [ 0, 0, 1 ]
 
 InfoLines = [
 
-    'CLASP.Ruby examples',
-    :version,
-    "Illustrates use of CLASP.Ruby's CLASP.show_usage() and CLASP.show_version() methods",
-    '',
+  'CLASP.Ruby examples',
+  :version,
+  "Illustrates use of CLASP.Ruby's CLASP.show_usage() and CLASP.show_version() methods",
+  '',
 ]
 
 # Specify specifications, parse, and checking standard flags
 
 Specifications = [
 
-    CLASP::FlagSpecification.Help,
-    CLASP::FlagSpecification.Version,
+  CLASP::FlagSpecification.Help,
+  CLASP::FlagSpecification.Version,
 ]
 
 args = CLASP::Arguments.new ARGV, Specifications
 
 if args.flags.include?('--help')
 
-    CLASP.show_usage(Specifications, exit_code: 0, version: ProgramVersion, stream: $stdout, info_lines: InfoLines)
+  CLASP.show_usage(Specifications, exit_code: 0, version: ProgramVersion, stream: $stdout, info_lines: InfoLines)
 end
 
 if args.flags.include?('--version')
 
-    CLASP.show_version(Specifications, exit_code: 0, version: ProgramVersion, stream: $stdout)
+  CLASP.show_version(Specifications, exit_code: 0, version: ProgramVersion, stream: $stdout)
 end
 
 
@@ -43,12 +43,11 @@ end
 
 if (unused = args.find_first_unknown())
 
-	$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
+  $stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
 
-    exit 1
+  exit 1
 end
 
 
 $stdout.puts 'no flags specified'
 
-

data/examples/simple_command_line_no_specifications.rb

@@ -25,6 +25,6 @@ puts args.values[0].given_index  # => 1
 puts args.values[1]              # => outfile
 puts args.values[1].given_index  # => 3
 
-# ############################## end of file ############################# #
 
+# ############################## end of file ############################# #