module Clasp
Main module for CLASP
.Ruby library
Examples¶ ↑
Simple command-line, no specifications¶ ↑
argv = %w{ --show-all=true infile -c outfile } args = CLASP::Arguments.new(argv) puts args.flags.size # => 1 puts args.flags[0] # => -c puts args.flags[0].name # => -c puts args.flags[0].inspect # => #<CLASP::Arguments::FlagArgument:0x007f87e18d4530 @arg="-c", @given_index=2, @given_name="-c", @argument_specification=nil, @given_hyphens=1, @given_label="c", @name="-c", @extras={}> puts args.options.size # => 1 puts args.options[0] # => --show-all=true puts args.options[0].name # => --show-all puts args.options[0].value # => true puts args.options[0].inspect # => #<CLASP::Arguments::OptionArgument:0x007f87e18d4940 @arg="--show-all=true", @given_index=0, @given_name="--show-all", @argument_specification=nil, @given_hyphens=2, @given_label="show-all", @value="true", @name="--show-all", @extras={}> puts args.values.size # => 2 puts args.values[0] # => infile puts args.values[0].given_index # => 1 puts args.values[1] # => outfile puts args.values[1].given_index # => 3
Use of the special double-slash flag to treat all subsequent arguments as values¶ ↑
argv = %w{ --show-all=true -- infile outfile -c } args = CLASP::Arguments.new(argv) puts args.flags.size # => 0 puts args.options.size # => 1 puts args.options[0] # => --show-all puts args.options[0].inspect # => #<CLASP::Arguments::OptionArgument:0x007fd23aa3aca0 @arg="--show-all=true", @given_index=0, @given_name="--show-all", @argument_specification=nil, @given_hyphens=2, @given_label="show-all", @value="true", @name="--show-all", @extras={}> puts args.values.size # => 3 puts args.values[0] # => infile puts args.values[1] # => outfile puts args.values[2] # => "-c"
Use of flag short forms¶ ↑
specifications = [ CLASP.Flag('--verbose', alias: '-v'), CLASP.Flag('--trace-output', aliases: [ '-t', '--trace' ]), ] argv = %w{ -trace -v } args = CLASP::Arguments.new(argv, specifications) puts args.flags.size # => 2 puts args.flags[0].name # => --trace-output puts args.flags[1].name # => --verbose puts args.options.size # => 0 puts args.values.size # => 0
Use of flag single short forms combined¶ ↑
specifications = [ CLASP.Flag('--expand', alias: '-x'), CLASP.Flag('--verbose', alias: '-v'), CLASP.Flag('--trace-output', aliases: [ '-t', '--trace' ]), ] argv = %w{ -tvx } args = CLASP::Arguments.new(argv, specifications) puts args.flags.size # => 3 puts args.options.size # => 0 puts args.values.size # => 0
Use of option short form¶ ↑
specifications = [ CLASP.Option('--show-all', alias: '-a'), ] argv = %w{ -c -a true infile outfile } args = CLASP::Arguments.new(argv, specifications) puts args.flags.size # => 1 puts args.flags[0] # => -c puts args.flags[0].inspect # => #<CLASP::Arguments::FlagArgument:0x007f8593b0ddd8 @arg="-c", @given_index=0, @given_name="-c", @argument_specification=nil, @given_hyphens=1, @given_label="c", @name="-c", @extras={}> puts args.options.size # => 1 puts args.options[0] # => --show-all puts args.options[0].inspect # => "#<CLASP::Arguments::OptionArgument:0x007f8593b0db80 @arg="-a", @given_index=1, @given_name="-a", @argument_specification=#<CLASP::OptionArgument:0x007f8593b2ea10 @name="--show-all", @aliases=["-a"], @help=nil, @values_range=[], @default_value=nil, @extras={}>, @given_hyphens=1, @given_label="a", @value="true", @name="--show-all", @extras={}>" puts args.values.size # => 2 puts args.values[0] # => infile puts args.values[1] # => outfile
Classes of interest¶ ↑
Functions of interest¶ ↑
-
::CLASP#show_version()
Constants
- Alias
A class that represents an explicit alias for a flag or an option
- Flag
A class that represents the specification for a command-line flag
- FlagAlias
A class that represents the specification for a command-line flag
- Option
A class that represents the specification for a command-line option
- OptionAlias
A class that represents the specification for a command-line option
- VERSION
Current version of the
CLASP
.Ruby library
Public Class Methods
# File lib/clasp/specifications.rb, line 513 def CLASP.Alias(name, *args) options = args.pop if args[-1].is_a?(::Hash) options ||= {} if options[:alias] aliases = [ options[:alias] ] elsif options[:aliases] aliases = options[:aliases] else aliases = args end CLASP::AliasSpecification.new name, aliases end
Generator method that obtains a CLASP::FlagSpecification
according to the given parameters
Signature¶ ↑
-
Parameters:
-
name
(::String) The flag name, e.g. '–verbose' -
options
(::Hash) An options hash, containing any of the following options:
-
-
Options:
-
:alias
(::String) An alias, e.g. '-v' -
: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
-
-
Block An optional block that is called when a matching flag argument is found
# File lib/clasp/specifications.rb, line 397 def CLASP.Flag(name, options = {}, &blk) aliases = nil help = nil extras = nil options.each do |k, v| case k when Symbol case k when :alias aliases = [ v ] if v when :aliases aliases = v unless aliases 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::FlagSpecification.new(name, aliases, help, extras, &blk) end
Generator method that obtains a CLASP::OptionSpecification
according to the given parameters
Signature¶ ↑
-
Parameters:
-
name
(::String) The flag name, e.g. '–verbose' -
options
(::Hash) An options hash, containing any of the following options:
-
-
Options:
-
:alias
(::String) An alias, e.g. '-v' -
:aliases
(::Array) An array of aliases, e.g. [ '-v', '-verb' ]. Ignored if:alias
is specified -
:default_value
The default value for the option -
:default
[DEPRECATED] Alternative to:default_value
-
:extras
An application-defined object, usually a hash of custom attributes -
:help
(::String) A help string -
required
(boolean) Whether the option is required. May benil
-
required_message
(::String) Message to be used when reporting that a required option is missing. May benil
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. Ifnil
, it is assigned an emptyHash
. -
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
-
-
Block An optional block that is called when a matching option argument is found
# File lib/clasp/specifications.rb, line 457 def CLASP.Option(name, options = {}, &blk) aliases = nil help = nil values_range = nil default_value = nil required = false require_message = nil constraint = nil extras = nil options.each do |k, v| case k when Symbol case k when :alias aliases = [ v ] if v when :aliases aliases = v unless aliases when :help help = v when :values_range, :values values_range = v when :default_value, :default default_value = v when :required required = v when :required_message require_message = v when :extras extras = v when :constraint constraint = v else raise ArgumentError, "invalid option for option: '#{k}' => '#{v}'" end else raise ArgumentError, "invalid option type for option: '#{k}' (#{k.class}) => '#{v}'" end end CLASP::OptionSpecification.new(name, aliases, help, values_range, default_value, required, require_message, constraint, extras, &blk) end
TBC (but is a shorthand for calling +Arguments.new()+
# File lib/clasp/clasp.rb, line 56 def self.parse(argv = ARGV, specifications = nil, options = {}) return Arguments.new(argv, specifications, options) end
Displays usage for the program according to the given specifications and options
Signature¶ ↑
-
Parameters:
-
specifications
(Array
) The arguments array. May not benil
. Defaults toARGV
. -
options
An options hash, containing any of the following options.
-
-
Options:
-
:exit
a program exit code;exit()
not called if not specified (ornil
). -
:program_name
program name; inferred from$0
if not specified. -
:stream
output stream;$stdout
if not specified. -
:suppress_blank_lines_between_options
does exactly what it says on the tin. -
:values
appends this string to USAGE line if specified. -
:flags_and_options
inserts a custom string instead of the default string'[ ... flags and options ... ]'
. -
:info_lines
inserts 0+ information lines prior to the usage. -
:default_indicator
(String) a string placed after the matching value in the listing of an option's range of values. Defaults to “(default)”. Ifnil
default is used. If empty string no indication given
-
# File lib/clasp/cli.rb, line 133 def self.show_usage specifications, options={} options ||= {} raise ArgumentError, "specifications may not be nil" if specifications.nil? raise TypeError, "specifications must be an array or must respond to each, reject and select" unless ::Array === specifications || (specifications.respond_to?(:each) && specifications.respond_to?(:reject) && specifications.respond_to?(:select)) constants = CLI_helpers_::Constants specifications.each { |s| raise ::TypeError, "each element in specifications array must be one of the types #{constants::VALID_ALIAS_TYPES_STRING}" unless constants::VALID_ALIAS_TYPES.any? { |c| c === s } } alias_dups = {} specifications.each { |s| s.aliases.each { |aa| warn "WARNING: alias '#{aa}' is already used for specification '#{s}'" if alias_dups.has_key? aa; alias_dups[aa] = s; } } suppress_blanks = options[:suppress_blank_lines_between_options] || ENV['SUPPRESS_BLANK_LINES_BETWEEN_OPTIONS'] stream = options[:stream] || $stdout program_name = options[:program_name] || File.basename($0) info_lines = options[:info_lines] case info_lines when ::Array ; when ::NilClass info_lines = [] else info_lines = [ info_lines ] unless [ :each, :empty? ].all? { |m| info_lines.respond_to? m } end info_lines = info_lines.map do |line| case line when :version CLI_helpers_.generate_version_string_ options else line end end values = options[:values] || '' values = " #{values}" if !values.empty? && ' ' != values[0] flags_and_options = options[:flags_and_options] || ' [ ... flags and options ... ]' flags_and_options = " #{flags_and_options}" if !flags_and_options.empty? && ' ' != flags_and_options[0] default_indicator = options[:default_indicator] || '(default)' default_indicator = nil if default_indicator.empty? # sift the specifications to sort out which are value-option # specifications (VOAs) voas = {} specifications.select { |s| s.name =~ /^-+[a-zA-Z0-3_-]+[=:].+/ }.each do |s| s.name =~ /^(-+[a-zA-Z0-3_-]+)[=:](.+)$/ voas[$1] = [] unless voas.has_key? $1 voas[$1] << [ s, $2 ] end fas = {} specifications.select { |s| AliasSpecification === s }.each do |s| fas[s.name] = [] unless fas.has_key? $1 fas[s.name] << s end specifications = specifications.reject { |s| s.name =~ /^-+[a-zA-Z0-3_-]+[=:].+/ } info_lines.each { |info_line| stream.puts info_line } unless info_lines.empty? stream.puts "USAGE: #{program_name}#{flags_and_options}#{values}" stream.puts unless specifications.empty? stream.puts "flags/options:" stream.puts specifications.each do |s| case s when AliasSpecification next when FlagSpecification if fas.has_key? s.name fas[s.name].each do |fa| fa.aliases.each { |al| stream.puts "\t#{al}" } end end s.aliases.each { |al| stream.puts "\t#{al}" } stream.puts "\t#{s.name}" stream.puts "\t\t#{s.help}" when OptionSpecification if voas.has_key? s.name voas[s.name].each do |ar| ar[0].aliases.each { |al| stream.puts "\t#{al} #{ar[0].name}" } end end s.aliases.each { |al| stream.puts "\t#{al} <value>" } stream.puts "\t#{s.name}=<value>" stream.puts "\t\t#{s.help}" unless s.values_range.empty? d = s.default_value stream.puts "\t\twhere <value> one of:" s.values_range.each do |v| if default_indicator && v == d stream.puts "\t\t\t#{v}\t#{default_indicator}" else stream.puts "\t\t\t#{v}" end end end end stream.puts unless suppress_blanks end end exit_code = options[:exit_code] || options[:exit] exit exit_code if exit_code end
Displays version for the program according to the given specifications and options
Signature¶ ↑
-
Parameters:
-
specifications
(Array
) The arguments array. May not benil
. Defaults toARGV
. -
options
An options hash, containing any of the following options.
-
-
Options:
-
:exit
a program exit code;exit()
not called if not specified (ornil
). -
:program_name
program name; inferred from$0
if not specified. -
:stream
output stream;$stdout
if not specified. -
:version
an array (of N elements, each of which will be separated by a period '.'), or a string. Must be specified if not:version_major
. -
:version_major
a number or string. Only considered and must be specified if:version
is not. -
:version_minor
a number or string. Only considered if:version
is not. -
:version_revision
a number or string. Only considered if:version
is not. -
:version_build
a number or string. Only considered if:version
is not. -
:version_prefix
optional string to prefix the version number(s).
-
# File lib/clasp/cli.rb, line 290 def self.show_version specifications, options = {} options ||= {} raise ArgumentError, "specifications may not be nil" if specifications.nil? raise TypeError, "specifications must be an array or must respond to each, reject and select" unless ::Array === specifications || (specifications.respond_to?(:each) && specifications.respond_to?(:reject) && specifications.respond_to?(:select)) constants = CLI_helpers_::Constants specifications.each { |s| raise ::TypeError, "each element in specifications array must be one of the types #{constants::VALID_ALIAS_TYPES_STRING}" unless constants::VALID_ALIAS_TYPES.any? { |c| c === s } } stream = options[:stream] || $stdout version_string = CLI_helpers_.generate_version_string_ options stream.puts version_string exit_code = options[:exit_code] || options[:exit] exit exit_code if exit_code end