clasp-ruby 0.20.1 → 0.22.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: f92b789f37af02b75b9644ff0d68c2f8dc1fb37bed7372f85a2e3076bda3318c
-  data.tar.gz: 915b038fa26a675ff5adef533286ed89dd1637cab521d9d187eb2cc28eb60405
+SHA1:
+  metadata.gz: bdf2add70e2d8e134e6759718fabde89ecb5c158
+  data.tar.gz: dcf9e41a17a28f53406daef64bdba1f614f2a080
 SHA512:
-  metadata.gz: 14b4ed81618a5564af21068ed04f8443cb0e699763f3489d91deae285bf3e7b2e5a8b77e0331185cec751659772ddd6d54a3a93ac1ee98aaf05f0a11c12d78b4
-  data.tar.gz: 90b82b5a6b1553c540f8904dbc4c2b3fe7257a0c177fbb4cacc4004af9e46470f5f0af8e119a635cf25062ab1b41a7bee54c9c4a512e74a48807b9cda4da4779
+  metadata.gz: d329ce03d0057446f877425faec12da111253f0bb51dbcd0d1e619d0f3e7f5dcc781b20b18ffbb65eb796011b3021d208e1d391881754ec3ecd61e6efad49186
+  data.tar.gz: 63873b0a897f4d854d6f4c80e5605cd68ebecdb4591361662cfa075292ac9c4a69ae8aa8f09ab97446db675fe5611cca41bc7ea83f01853bafb55722b5093fee

data/README.md

@@ -1,9 +1,27 @@
 # CLASP.Ruby
-Command-Line Argument Sorting and Parsing for Ruby
+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)
 
-## Installation & usage
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Installation](#installation)
+3. [Components](#components)
+4. [Examples](#examples)
+5. [Project Information](#project-information)
+
+## 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.
+
+All CLASP libraries provide the facilities to **C**ommand **L**ine
+**I**nterface (**CLI**) programs as described in detail below.
+
+## Installation
 
 Install via **gem** as in:
 
@@ -19,19 +37,7 @@ Use via **require**, as in:
 require 'clasp'
 ```
 
-## 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).
-
-## 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:
+## Components
 
 ### Command-line parsing
 
@@ -101,7 +107,7 @@ 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.Option('--opt1=val1', alias: '-v'),
+	CLASP.Flag('--opt1=val1', alias: '-v'),
 
 	# see next section for why these two are here
 	CLASP::Flag.Help,
@@ -195,15 +201,21 @@ then the program will output the following
 cr-example.rb 0.1.2
 ```
 
-## Where to get help
+## 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).
+
+## Project Information
+
+### Where to get help
 
 [GitHub Page](https://github.com/synesissoftware/CLASP.Ruby "GitHub Page")
 
-## Contribution guidelines
+### Contribution guidelines
 
 Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/CLASP.Ruby.
 
-## Related projects
+### Related projects
 
 **CLASP.Ruby** is inspired by the [C/C++ CLASP library](https://github.com/synesissoftware/CLASP), which is documented in the articles:
 
@@ -211,9 +223,19 @@ Defect reports, feature requests, and pull requests are welcome on https://githu
  * _[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.
+Other CLASP libraries include:
+
+* [**CLASP**](https://github.com/synesissoftware/CLASP/)
+* [**CLASP.Go**](https://github.com/synesissoftware/CLASP.Go/)
+* [**CLASP.js**](https://github.com/synesissoftware/CLASP.js/)
+* [**CLASP.NET**](https://github.com/synesissoftware/CLASP.NET/)
+* [**CLASP.Python**](https://github.com/synesissoftware/CLASP.Python/)
+
+Projects in which **CLASP.Ruby** is used include:
+
+* [**libCLImate.Ruby**](https://github.com/synesissoftware/libCLImate.Ruby)
 
-## License
+### License
 
 **CLASP.Ruby** is released under the 3-clause BSD license. See LICENSE for details.
 

data/examples/cr-example.rb

@@ -1,16 +1,7 @@
 #!/usr/bin/ruby
 
-#############################################################################
-# File:         examples/cr-example.rb
+# 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')
 
@@ -23,7 +14,7 @@ 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.Option('--opt1=val1', alias: '-v'),
+	CLASP.Flag('--opt1=val1', alias: '-v'),
 
 	# see next section for why these two are here
 	CLASP::Flag.Help,

data/examples/flag_and_option_specifications.md

@@ -201,4 +201,19 @@ verbosity is specified as: chatty
 Debug mode is specified
 ```
 
+### Utilise the default value for verbosity
+
+If executed with the arguments
+
+```
+    ruby examples/flag_and_option_specifications.rb -d --verbosity=
+```
+
+it gives the output:
+
+```
+verbosity is specified as: terse
+Debug mode is specified
+```
+
 

data/lib/clasp/arguments.rb

@@ -6,7 +6,7 @@
 #               CLASP.Ruby
 #
 # Created:      14th February 2014
-# Updated:      19th April 2019
+# Updated:      20th April 2019
 #
 # Home:         http://github.com/synesissoftware/CLASP.Ruby
 #
@@ -46,7 +46,8 @@
 
 
 
-require File.join(File.dirname(__FILE__), 'specifications.rb')
+require File.join(File.dirname(__FILE__), 'specifications')
+require File.join(File.dirname(__FILE__), 'util', 'value_parser')
 
 require 'yaml'
 
@@ -104,6 +105,7 @@ class Arguments
 			@name
 		end
 
+		# @!visibility private
 		def eql?(rhs) # :nodoc:
 
 			return false if rhs.nil?
@@ -114,6 +116,7 @@ class Arguments
 			false
 		end
 
+		# @!visibility private
 		def ==(rhs) # :nodoc:
 
 			return false if rhs.nil?
@@ -134,17 +137,40 @@ class Arguments
 	# Class that represents a parsed option
 	class OptionArgument
 
+		include ::CLASP::Util::ValueParser
+
 		# @!visibility private
 		#
 		# [PRIVATE] This method is subject to changed between versions and
 		# should not be called directly from application code
 		def initialize(arg, given_index, given_name, resolved_name, argument_spec, given_hyphens, given_label, value, extras) # :nodoc:
 
-			actual_value			=	value
+			resolved_value			=	nil
+
+			if argument_spec
+
+				case constraint = (argument_spec.constraint || {})
+=begin
+				when Proc
+
+					resolved_value = value_from_Proc(constraint, value, arg, given_index, given_name, argument_spec, extras)
+=end
+				when Hash
+
+					if constraint.empty?
+
+						resolved_value	=	(value || '').empty? ? argument_spec.default_value : value
+					else
+
+						resolved_value	=	value_from_Hash(constraint, value, arg, given_index, given_name, argument_spec, extras)
+					end
+				else
 
-			if value.nil? && argument_spec
+					warn "unexpected constraint on argument specification #{argument_spec} when parsing argument '#{arg}'"
+				end
+			else
 
-				actual_value = argument_spec.default_value
+				resolved_value		=	value
 			end
 
 			@arg					=	arg
@@ -153,7 +179,8 @@ class Arguments
 			@argument_specification	=	argument_spec
 			@given_hyphens			=	given_hyphens
 			@given_label			=	given_label
-			@value					=	actual_value
+			@given_value			=	value
+			@value					=	resolved_value
 			@name					=	resolved_name || given_name
 			@extras					=	extras.nil? ? {} : extras
 		end
@@ -170,7 +197,9 @@ class Arguments
 		attr_reader :given_label
 		# (String) The resolved name of the argument
 		attr_reader :name
-		# (String) The value of the option
+		# (String) The given value of the option
+		attr_reader :given_value
+		# (????) The value of the option, which may be of a type other than string subject to the option specification's constraint
 		attr_reader :value
 		# (Object, Hash) The extras associated with the argument
 		attr_reader :extras
@@ -178,6 +207,7 @@ class Arguments
 		# [DEPRECATED] Use +argument_specification+
 		def argument_alias; @argument_specification; end
 
+		# @!visibility private
 		def eql?(rhs) # :nodoc:
 
 			return false if rhs.nil?
@@ -188,6 +218,7 @@ class Arguments
 			false
 		end
 
+		# @!visibility private
 		def ==(rhs) # :nodoc:
 
 			return false if rhs.nil?
@@ -454,7 +485,7 @@ class Arguments
 		values	=	[]
 
 		forced_value		=	false
-		want_option_value	=	false
+		pending_option		=	nil
 
 		argv.each_with_index do |arg, index|
 
@@ -559,15 +590,22 @@ class Arguments
 
 					if argument_spec and argument_spec.is_a? CLASP::OptionSpecification and not value
 
-						want_option_value = true
-						options << OptionArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, nil, argument_spec ? argument_spec.extras : nil)
+						pending_option = {
+
+							arg:			arg,
+							index:			index,
+							given_name:		given_name,
+							resolved_name:	resolved_name,
+							argument_spec:	argument_spec,
+							hyphens_size:	hyphens.size,
+							given_label:	given_label,
+							extras:			argument_spec ? argument_spec.extras : nil,
+						}
 					elsif value
 
-						want_option_value = false
 						options << OptionArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, value, argument_spec ? argument_spec.extras : nil)
 					else
 
-						want_option_value = false
 						flags << FlagArgument.new(arg, index, given_name, resolved_name, argument_spec, hyphens.size, given_label, argument_spec ? argument_spec.extras : nil)
 					end
 
@@ -575,20 +613,31 @@ class Arguments
 				end
 			end
 
-			if want_option_value and not forced_value
+			if pending_option
 
-				option	=	options[-1]
-				option.instance_eval("@value='#{arg}'")
-				want_option_value = false
-			else
+				value = forced_value ? nil : arg
 
-				arg		=	arg.dup
-				arg_ix	=	::Integer === index ? index : index.dup
+				options << OptionArgument.new(pending_option[:arg], pending_option[:index], pending_option[:given_name], pending_option[:resolved_name], pending_option[:argument_spec], pending_option[:hyphens_size], pending_option[:given_label], value, pending_option[:extras])
 
-				arg.define_singleton_method(:given_index) { arg_ix }
+				pending_option = nil
 
-				values << arg
+				next unless forced_value
 			end
+
+			arg		=	arg.dup
+			arg_ix	=	::Integer === index ? index : index.dup
+
+			arg.define_singleton_method(:given_index) { arg_ix }
+
+			values << arg
+		end
+
+		if pending_option
+
+			value = nil
+
+			options << OptionArgument.new(pending_option[:arg], pending_option[:index], pending_option[:given_name], pending_option[:resolved_name], pending_option[:argument_spec], pending_option[:hyphens_size], pending_option[:given_label], value, pending_option[:extras])
+
 		end
 
 		return flags, options, values

data/lib/clasp/clasp.rb

@@ -50,6 +50,15 @@ require 'clasp/specifications'
 require 'clasp/cli'
 require 'clasp/version'
 
+module CLASP
+
+	# TBC (but is a shorthand for calling +Arguments.new()+
+	def self.parse(argv = ARGV, specifications = nil, options = {})
+
+		return Arguments.new(argv, specifications, options)
+	end
+end # module CLASP
+
 # ############################## end of file ############################# #
 
 

data/lib/clasp/cli.rb

@@ -60,45 +60,49 @@ module CLASP
 =end
 
 # :stopdoc:
-module CLI_helpers_
 
-	module Constants
+# @!visibility private
+module CLI_helpers_ # :nodoc: all
 
+	# @!visibility private
+	module Constants # :nodoc: all
+
+		# @!visibility private
 		VALID_ALIAS_TYPES			=	[ FlagSpecification, OptionSpecification, AliasSpecification ]
+		# @!visibility private
 		VALID_ALIAS_TYPES_STRING	=	VALID_ALIAS_TYPES[0...-1].join(', ') + ', or ' + VALID_ALIAS_TYPES[-1].to_s
 	end # module Constants
 
-# :nodoc:
-def self.generate_version_string_ options
+	# @!visibility private
+	def self.generate_version_string_ options # :nodoc:
 
-	program_name	=	options[:program_name] || File.basename($0)
+		program_name	=	options[:program_name] || File.basename($0)
 
-	version_prefix	=	options[:version_prefix]
+		version_prefix	=	options[:version_prefix]
 
-	if options[:version]
+		if options[:version]
 
-		case	options[:version]
-		when	::Array
-			version	=	options[:version].join('.')
+			case	options[:version]
+			when	::Array
+				version	=	options[:version].join('.')
+			else
+				version = options[:version]
+			end
 		else
-			version = options[:version]
-		end
-	else
 
-		version_major	=	options[:version_major] or raise ArgumentError, "options must specify :version or :version_major [ + :version_minor [ + :version_revision [ + :version_build ]]]"
-		version_minor	=	options[:version_minor]
-		version_rev		=	options[:version_revision]
-		version_build	=	options[:version_build]
+			version_major	=	options[:version_major] or raise ArgumentError, "options must specify :version or :version_major [ + :version_minor [ + :version_revision [ + :version_build ]]]"
+			version_minor	=	options[:version_minor]
+			version_rev		=	options[:version_revision]
+			version_build	=	options[:version_build]
 
-		version			=	version_major.to_s
-		version			+=	".#{version_minor}" if version_minor
-		version			+=	".#{version_rev}" if version_rev
-		version			+=	".#{version_build}" if version_build
-	end
-
-	"#{program_name} #{version_prefix}#{version}"
-end
+			version			=	version_major.to_s
+			version			+=	".#{version_minor}" if version_minor
+			version			+=	".#{version_rev}" if version_rev
+			version			+=	".#{version_build}" if version_build
+		end
 
+		"#{program_name} #{version_prefix}#{version}"
+	end
 end # module CLI_helpers_
 
 # ######################################################################## #

data/lib/clasp/specifications.rb

@@ -5,7 +5,7 @@
 # Purpose:      Argument specification classes
 #
 # Created:      25th October 2014
-# Updated:      19th April 2019
+# Updated:      29th April 2019
 #
 # Home:         http://github.com/synesissoftware/CLASP.Ruby
 #
@@ -57,8 +57,40 @@ module CLASP
 # ######################################################################## #
 # classes
 
+# @!visibility private
+class SpecificationBase # :nodoc: all
+
+	private
+	# @!visibility private
+	def check_arity_(blk, range, label) # :nodoc:
+
+		raise ArgumentError, "block must be a #{Proc}; #{blk.class} given" unless blk.nil? || Proc === blk
+
+		if blk
+
+			case blk.arity
+			when range
+
+				;
+			else
+
+				msg = "wrong arity for #{label}"
+
+				if $DEBUG
+
+					raise ArgumentError, msg
+				else
+
+					warn msg
+				end
+			end
+		end
+	end
+	public
+end
+
 # A class that represents the specification for a command-line flag
-class FlagSpecification
+class FlagSpecification < SpecificationBase
 
 	# Creates a FlagSpecification instance from the given name, aliases, and help
 	#
@@ -69,12 +101,19 @@ class FlagSpecification
 	#   - +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)
+	#
+	# * *Block* An optional block that is called when a matching flag argument is found
+	#
+	# *NOTE:* Users should prefer the +CLASP::Flag()+ method
+	def initialize(name, aliases, help, extras = nil, &blk)
+
+		check_arity_(blk, 0..3, "flag")
 
 		@name			=	name
 		@aliases		=	(aliases || []).select { |a| a and not a.empty? }
 		@help			=	help
 		@extras			=	extras || {}
+		@action			=	blk
 	end
 
 	# The flag's name string
@@ -86,12 +125,24 @@ class FlagSpecification
 	# The flag's extras
 	attr_reader :extras
 
+	# (Proc) The procedure
+	attr_reader :action
+
+	# @!visibility private
+	def action=(blk) # :nodoc: all
+
+		check_arity_(blk, 0..3, "flag")
+
+		@action = blk
+	end
+
 	# String form of the flag
 	def to_s
 
 		"{#{name}; aliases=#{aliases.join(', ')}; help='#{help}'; extras=#{extras}}"
 	end
 
+	# @!visibility private
 	def eql? rhs # :nodoc:
 
 		case rhs
@@ -132,28 +183,38 @@ class FlagSpecification
 	@@Version_	=	self.new('--version', [], 'shows version and terminates')
   public
 	# An instance of FlagSpecification that provides default '--help' information
-	def self.Help(extras = nil)
+	#
+	# If you wish to specify +extras+ or attach a block, you may do so
+	def self.Help(extras = nil, &blk)
 
 		h = @@Help_
 
-		return self.new(h.name, h.aliases, h.help, extras) if extras
+		if extras || blk
+
+			return self.new(h.name, h.aliases, h.help, extras, &blk)
+		end
 
 		h
 	end
 
 	# An instance of FlagSpecification that provides default '--version' information
-	def self.Version(extras = nil)
+	#
+	# If you wish to specify +extras+ or attach a block, you may do so
+	def self.Version(extras = nil, &blk)
 
 		h = @@Version_
 
-		return self.new(h.name, h.aliases, h.help, extras) if extras
+		if extras || blk
+
+			return self.new(h.name, h.aliases, h.help, extras, &blk)
+		end
 
 		h
 	end
 end
 
 # A class that represents the specification for a command-line option
-class OptionSpecification
+class OptionSpecification < SpecificationBase
 
 	# Creates an OptionSpecification instance from the given name, aliases, help,
 	# values_range, and default_value
@@ -168,8 +229,15 @@ class OptionSpecification
 	#   - +default_value+ (+String+) The default value of the option, which will be used in the case where an option is specified without a value. May be +nil+
 	#   - +required+ (boolean) Whether the option is required. May be +nil+
 	#   - +required_message+ (::String) Message to be used when reporting that a required option is missing. May be +nil+ in which case a message of the form "<option-name> not specified; use --help for usage". If begins with the nul character ("\0"), then is used in the place of the <option-name> and placed into the rest of the standard form message
+	#   - +constraint+ (Hash) Constraint to be applied to the parsed values of options matching this specification. NOTE: only integer constraints are supported in the current version
 	#   - +extras+ An application-defined additional parameter. If +nil+, it is assigned an empty +Hash+
-	def initialize(name, aliases, help, values_range, default_value, required, required_message, extras = nil)
+	#
+	# * *Block* An optional block that is called when a matching option argument is found
+	#
+	# *NOTE:* Users should prefer the +CLASP::Option()+ method
+	def initialize(name, aliases, help, values_range, default_value, required, required_message, constraint, extras = nil, &blk)
+
+		check_arity_(blk, 0..3, "option")
 
 		@name				=	name
 		@aliases			=	(aliases || []).select { |a| a and not a.empty? }
@@ -178,7 +246,9 @@ class OptionSpecification
 		@default_value		=	default_value
 		@required			=	required
 		@required_message	=	nil
+		@constraint			=	constraint || {}
 		@extras				=	extras || {}
+		@action				=	blk
 
 		rm_name				=	nil
 
@@ -213,18 +283,31 @@ class OptionSpecification
 	attr_reader	:default_value
 	# Indicates whether the option is required
 	def required?; @required; end
-	# The message to be used when reporting that a required option is
-	# missing
+	# The message to be used when reporting that a required option is missing
 	attr_reader	:required_message
+	# The value constraint
+	attr_reader :constraint
 	# The option's extras
 	attr_reader :extras
 
+	# (Proc) The procedure
+	attr_reader :action
+
+	# @!visibility private
+	def action=(blk) # :nodoc: all
+
+		check_arity_(blk, 0..3, "flag")
+
+		@action = blk
+	end
+
 	# String form of the option
 	def to_s
 
-		"{#{name}; aliases=#{aliases.join(', ')}; values_range=[ #{values_range.join(', ')} ]; default_value='#{default_value}'; help='#{help}'; required?=#{required?}; extras=#{extras}}"
+		"{#{name}; aliases=#{aliases.join(', ')}; values_range=[ #{values_range.join(', ')} ]; default_value='#{default_value}'; help='#{help}'; required?=#{required?}; required_message=#{required_message}; constraint=#{constraint}; extras=#{extras}}"
 	end
 
+	# @!visibility private
 	def eql? rhs # :nodoc:
 
 		case rhs
@@ -309,7 +392,9 @@ end
 #   - +:aliases+ (::Array) An array of aliases, e.g. [ '-v', '-verb' ]. Ignored if +:alias+ is specified
 #   - +:extras+ An application-defined object, usually a hash of custom attributes
 #   - +:help+ (::String) A help string
-def CLASP.Flag(name, options = {})
+#
+# * *Block* An optional block that is called when a matching flag argument is found
+def CLASP.Flag(name, options = {}, &blk)
 
 	aliases	=	nil
 	help	=	nil
@@ -342,7 +427,7 @@ def CLASP.Flag(name, options = {})
 		end
 	end
 
-	CLASP::FlagSpecification.new(name, aliases, help, extras)
+	CLASP::FlagSpecification.new(name, aliases, help, extras, &blk)
 end
 
 # Generator method that obtains a CLASP::OptionSpecification according to the given
@@ -364,9 +449,12 @@ end
 #   - +required+ (boolean) Whether the option is required. May be +nil+
 #   - +required_message+ (::String) Message to be used when reporting that a required option is missing. May be +nil+ in which case a message of the form "<option-name> not specified; use --help for usage". If begins with the nul character ("\0"), then is used in the place of the <option-name> and placed into the rest of the standard form message
 #   - +extras+ An application-defined additional parameter. If +nil+, it is assigned an empty +Hash+.
+#   - +constraint+ (Hash) Constraint to be applied to the parsed values of options matching this specification. NOTE: only integer constraints are supported in the current version
 #   - +:values_range+ (::Array) An array defining the accepted values for the option
 #   - +:values+ [DEPRECATED] Alternative to +:values_range+
-def CLASP.Option(name, options = {})
+#
+# * *Block* An optional block that is called when a matching option argument is found
+def CLASP.Option(name, options = {}, &blk)
 
 	aliases			=	nil
 	help			=	nil
@@ -374,6 +462,7 @@ def CLASP.Option(name, options = {})
 	default_value	=	nil
 	required		=	false
 	require_message	=	nil
+	constraint		=	nil
 	extras			=	nil
 
 	options.each do |k, v|
@@ -405,6 +494,9 @@ def CLASP.Option(name, options = {})
 			when	:extras
 
 				extras	=	v
+			when	:constraint
+
+				constraint	=	v
 			else
 
 				raise ArgumentError, "invalid option for option: '#{k}' => '#{v}'"
@@ -415,7 +507,7 @@ def CLASP.Option(name, options = {})
 		end
 	end
 
-	CLASP::OptionSpecification.new(name, aliases, help, values_range, default_value, required, require_message, extras)
+	CLASP::OptionSpecification.new(name, aliases, help, values_range, default_value, required, require_message, constraint, extras, &blk)
 end
 
 def CLASP.Alias(name, *args)