clasp-ruby 0.15.2 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c21f8a690de12605745b8001539ad68e6782bf45
-  data.tar.gz: f293ce2cb5788ab18e26717fc46189b21e7ac1a7
+  metadata.gz: 0d2393ba0de2e70168bc58f88cdf73b9d4f5e748
+  data.tar.gz: 60463d18965a903998197c5f0b1dd9cb4bb10836
 SHA512:
-  metadata.gz: c39760c3a529ac09b824dd7e8211f95967f7d2278584b45885b12f4bda825375a8af94825d1b05dba8b292d5ca1404dcc868042d9bc5926fce2186a69fdf7f7f
-  data.tar.gz: f64a8b1a004295b65411d939ccf5f50065954432668f618e35f76b9376ab7162d4792f110d7bb04a1f5ee812092accabe0447895746ebcd3b51bae6f08edc5f1
+  metadata.gz: 7b3aa22592465766c7486b75b538b66436c27b67cc502c6d7eb29e2aa59eb9cf160ef0c043409ed4acbaeb406e6952e050152b2ff1dbbd729f735924fbea33ff
+  data.tar.gz: e6e14d4f75a31553b3a40394b0b4cbd1920f2cbf6ee630c43d9f2301dcfe4a96d85257f669ea76f9770f1f8e472357336cc53fe43788a44531f7447a1955e9b6

data/examples/flag_and_option_aliases.md

@@ -0,0 +1,203 @@
+# CLASP.Ruby Example - **show_usage_and_version**
+
+## Summary
+
+Example illustrating various kinds of *flag* and *option* aliases, including the combination of short-names.
+
+## Source
+
+```ruby
+#!/usr/bin/env ruby
+
+# examples/flag_and_option_aliases.rb
+
+# requires
+
+require 'clasp'
+
+# constants
+
+ProgramVersion = [ 0, 0, 1 ]
+
+InfoLines = [
+
+    'CLASP.Ruby examples',
+    :version,
+    "Illustrates use of CLASP.Ruby's use of flags, options, and aliases",
+    '',
+]
+
+# Specify aliases, parse, and checking standard flags
+
+Flag_Debug = CLASP.Flag('--debug', alias: '-d', help: 'runs in Debug mode')
+Option_Verbosity = CLASP.Option('--verbosity', alias: '-v', help: 'specifies the verbosity', values: [ 'terse', 'quiet', 'silent', 'chatty' ])
+Flag_Chatty = CLASP.Flag('--verbosity=chatty', alias: '-c')
+
+Aliases = [
+
+	Flag_Debug,
+	Option_Verbosity,
+	Flag_Chatty,
+
+    CLASP::FlagAlias.Help,
+    CLASP::FlagAlias.Version,
+]
+
+args = CLASP::Arguments.new ARGV, Aliases
+
+if args.flags.include?(CLASP::FlagAlias.Help)
+
+    CLASP.show_usage(Aliases, exit_code: 0, version: ProgramVersion, stream: $stdout, info_lines: InfoLines)
+end
+
+if args.flags.include?('--version')
+
+    CLASP.show_version(Aliases, exit_code: 0, version: ProgramVersion, stream: $stdout)
+end
+
+
+# Program-specific processing of flags/options
+
+if (opt = args.find_option('--verbosity'))
+
+	$stdout.puts "verbosity is specified as: #{opt.value}"
+end
+
+if args.flags.include?('--debug')
+
+	$stdout.puts 'Debug mode is specified'
+end
+
+
+
+# Check for any unrecognised flags or options
+
+if (unused = args.find_first_unknown())
+
+	$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
+
+    sys.exit(1)
+end
+```
+
+## Usage
+
+### No arguments
+
+If executed with no arguments
+
+```
+    ruby examples/flag_and_option_aliases.rb
+```
+
+or (in a Unix shell):
+
+```
+    ./examples/flag_and_option_aliases.rb
+```
+
+it gives the output:
+
+```
+```
+
+### Show usage
+
+If executed with the arguments
+
+```
+    ruby examples/flag_and_option_aliases.rb --help
+```
+
+it gives the output:
+
+```
+CLASP.Ruby examples
+flag_and_option_aliases.rb 0.0.1
+Illustrates use of CLASP.Ruby's use of flags, options, and aliases
+
+USAGE: flag_and_option_aliases.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 this help and terminates
+
+	--version
+		shows version and terminates
+```
+
+### Specify flags and options in long-form
+
+If executed with the arguments
+
+```
+    ruby examples/flag_and_option_aliases.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_aliases.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_aliases.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_aliases.rb -dc
+```
+
+it gives the (same) output:
+
+```
+verbosity is specified as: chatty
+Debug mode is specified
+```
+

data/examples/flag_and_option_aliases.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+
+# examples/flag_and_option_aliases.rb
+
+# requires
+
+require 'clasp'
+
+# constants
+
+ProgramVersion = [ 0, 0, 1 ]
+
+InfoLines = [
+
+    'CLASP.Ruby examples',
+    :version,
+    "Illustrates use of CLASP.Ruby's use of flags, options, and aliases",
+    '',
+]
+
+# Specify aliases, parse, and checking standard flags
+
+Flag_Debug = CLASP.Flag('--debug', alias: '-d', help: 'runs in Debug mode')
+Option_Verbosity = CLASP.Option('--verbosity', alias: '-v', help: 'specifies the verbosity', values: [ 'terse', 'quiet', 'silent', 'chatty' ])
+Flag_Chatty = CLASP.Flag('--verbosity=chatty', alias: '-c')
+
+Aliases = [
+
+	Flag_Debug,
+	Option_Verbosity,
+	Flag_Chatty,
+
+    CLASP::FlagAlias.Help,
+    CLASP::FlagAlias.Version,
+]
+
+args = CLASP::Arguments.new ARGV, Aliases
+
+if args.flags.include?(CLASP::FlagAlias.Help)
+
+    CLASP.show_usage(Aliases, exit_code: 0, version: ProgramVersion, stream: $stdout, info_lines: InfoLines)
+end
+
+if args.flags.include?('--version')
+
+    CLASP.show_version(Aliases, exit_code: 0, version: ProgramVersion, stream: $stdout)
+end
+
+
+# Program-specific processing of flags/options
+
+if (opt = args.find_option('--verbosity'))
+
+	$stdout.puts "verbosity is specified as: #{opt.value}"
+end
+
+if args.flags.include?('--debug')
+
+	$stdout.puts 'Debug mode is specified'
+end
+
+
+
+# Check for any unrecognised flags or options
+
+if (unused = args.find_first_unknown())
+
+	$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
+
+    exit 1
+end
+
+
+

data/examples/show_usage_and_version.md

@@ -0,0 +1,141 @@
+# CLASP.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 'clasp'
+
+# constants
+
+ProgramVersion = [ 0, 0, 1 ]
+
+InfoLines = [
+
+    'CLASP.Ruby examples',
+    :version,
+    "Illustrates use of CLASP.Ruby's CLASP.show_usage() and CLASP.show_version() methods",
+    '',
+]
+
+# Specify aliases, parse, and checking standard flags
+
+Aliases = [
+
+    CLASP::FlagAlias.Help,
+    CLASP::FlagAlias.Version,
+]
+
+args = CLASP::Arguments.new ARGV, Aliases
+
+if args.flags.include?('--help')
+
+    CLASP.show_usage(Aliases, exit_code: 0, version: ProgramVersion, stream: $stdout, info_lines: InfoLines)
+end
+
+if args.flags.include?('--version')
+
+    CLASP.show_version(Aliases, exit_code: 0, version: ProgramVersion, stream: $stdout)
+end
+
+
+# Check for any unrecognised flags or options
+
+if (unused = args.find_first_unknown())
+
+	$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
+
+    sys.exit(1)
+end
+
+
+$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:
+
+```
+CLASP.Ruby examples
+show_usage_and_version.rb 0.0.1
+Illustrates use of CLASP.Ruby's show_usage() and show_version() methods
+
+USAGE: show_usage_and_version.rb [ ... flags and options ... ]
+
+flags/options:
+
+	--help
+		Shows usage 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,54 @@
+#!/usr/bin/env ruby
+
+# examples/show_usage_and_version.rb
+
+# requires
+
+require 'clasp'
+
+# constants
+
+ProgramVersion = [ 0, 0, 1 ]
+
+InfoLines = [
+
+    'CLASP.Ruby examples',
+    :version,
+    "Illustrates use of CLASP.Ruby's CLASP.show_usage() and CLASP.show_version() methods",
+    '',
+]
+
+# Specify aliases, parse, and checking standard flags
+
+Aliases = [
+
+    CLASP::FlagAlias.Help,
+    CLASP::FlagAlias.Version,
+]
+
+args = CLASP::Arguments.new ARGV, Aliases
+
+if args.flags.include?('--help')
+
+    CLASP.show_usage(Aliases, exit_code: 0, version: ProgramVersion, stream: $stdout, info_lines: InfoLines)
+end
+
+if args.flags.include?('--version')
+
+    CLASP.show_version(Aliases, exit_code: 0, version: ProgramVersion, stream: $stdout)
+end
+
+
+# Check for any unrecognised flags or options
+
+if (unused = args.find_first_unknown())
+
+	$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
+
+    exit 1
+end
+
+
+$stdout.puts 'no flags specified'
+
+

data/lib/clasp/arguments.rb

@@ -205,6 +205,7 @@ class Arguments
 
 		init_opts[:mutate_argv] = true unless init_opts.has_key? :mutate_argv
 
+		@program_name		=	init_opts[:program_name] || Arguments.derive_program_name_
 
 		@argv				=	argv
 		argv				=	argv.dup
@@ -268,6 +269,11 @@ class Arguments
 	end
 
 	private
+	def self.derive_program_name_
+
+		$0
+	end
+
 	def self.parse(argv, aliases)
 
 		flags	=	[]
@@ -427,6 +433,8 @@ class Arguments
 	# unchanged copy of the original array of arguments passed to new
 	attr_reader :argv_original_copy
 
+	attr_reader :program_name
+
 
 	# finds the first unknown flag or option; +nil+ if all used
 	def find_first_unknown options = {}
@@ -452,6 +460,42 @@ class Arguments
 		nil
 	end
 
+	# Searches for a flag that matches the given id, returning the flag if
+	# found; +nil+ otherwise
+	#
+	# === Signature
+	#
+	# * *Parameters*:
+	#  - +id+:: (String, CLASP::Flag) The name of a flag, or the flag
+	#     itself
+	def find_flag(id)
+
+		flags.each do |flag|
+
+			return flag if flag == id
+		end
+
+		nil
+	end
+
+	# Searches for a option that matches the given id, returning the option
+	# if found; +nil+ otherwise
+	#
+	# === Signature
+	#
+	# * *Parameters*:
+	#  - +id+:: (String, CLASP::Flag) The name of a option, or the option
+	#     itself
+	def find_option(id)
+
+		options.each do |option|
+
+			return option if option == id
+		end
+
+		nil
+	end
+
 	# #################################################################### #
 	# backwards-compatible
 

data/lib/clasp/cli.rb

@@ -5,7 +5,7 @@
 # Purpose:      Command-line interface
 #
 # Created:      27th July 2015
-# Updated:      14th February 2019
+# Updated:      19th March 2019
 #
 # Home:         http://github.com/synesissoftware/CLASP.Ruby
 #
@@ -244,7 +244,9 @@ def self.show_usage aliases, options={}
 		end
 	end
 
-	exit options[:exit] if options[:exit]
+	exit_code		=	options[:exit_code] || options[:exit]
+
+	exit exit_code if exit_code
 end
 
 # Displays version for the program according to the given aliases and options
@@ -281,7 +283,9 @@ def self.show_version aliases, options = {}
 
 	stream.puts version_string
 
-	exit options[:exit] if options[:exit]
+	exit_code		=	options[:exit_code] || options[:exit]
+
+	exit exit_code if exit_code
 end
 
 # ######################################################################## #

data/lib/clasp/version.rb

@@ -51,7 +51,7 @@
 module CLASP
 
 	# Current version of the CLASP.Ruby library
-	VERSION				=	'0.15.2'
+	VERSION				=	'0.16.0'
 
 	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.15.2
+  version: 0.16.0
 platform: ruby
 authors:
 - Matt Wilson
@@ -35,6 +35,10 @@ files:
 - LICENSE
 - README.md
 - examples/cr-example.rb
+- examples/flag_and_option_aliases.md
+- examples/flag_and_option_aliases.rb
+- examples/show_usage_and_version.md
+- examples/show_usage_and_version.rb
 - lib/clasp-ruby.rb
 - lib/clasp.rb
 - lib/clasp/aliases.rb