Module: CLASP
- Defined in:
- lib/clasp/doc_.rb,
lib/clasp/cli.rb,
lib/clasp/aliases.rb,
lib/clasp/version.rb,
lib/clasp/arguments.rb
Overview
Main module for CLASP.Ruby library
Examples
Simple command-line, no aliases
argv = %w{ --show-all=true infile -c outfile }
args = CLASP::Arguments.new(argv)
puts args.flags.size # => 1
puts args.flags[0] # => "#<CLASP::Arguments::Flag:0x007fd23aa3aa98 @arg="-c", @given_index=1, @given_name="-c", @argument_alias=nil, @given_hyphens=1, @given_label="c", @name="-c", @extras={}>"
puts args..size # => 1
puts args.[0] # => "#<CLASP::Arguments::Option:0x007fd23aa3aca0 @arg="--show-all=true", @given_index=0, @given_name="--show-all", @argument_alias=nil, @given_hyphens=2, @given_label="show-all", @value="true", @name="--show-all", @extras={}>"
puts args.[0].value # => "true"
puts args.values.size # => 2
puts args.values[0] # => "infile"
puts args.values[1] # => "outfile"
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..size # => 1
puts args.[0] # => "#<CLASP::Arguments::Option:0x007fd23aa3aca0 @arg="--show-all=true", @given_index=0, @given_name="--show-all", @argument_alias=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
aliases = [
CLASP.Flag('--verbose', alias: '-v'),
CLASP.Flag('--trace-output', aliases: [ '-t', '--trace' ]),
]
argv = %w{ -trace -v }
args = CLASP::Arguments.new(argv, aliases)
puts args.flags.size # => 2
puts args.flags[0].name # => "--trace-output"
puts args.flags[1].name # => "--verbose"
puts args..size # => 0
puts args.values.size # => 0
Use of flag single short forms combined
aliases = [
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, aliases)
puts args.flags.size # => 3
puts args..size # => 0
puts args.values.size # => 0
Use of option short form
aliases = [
CLASP.Option('--show-all', alias: '-a'),
]
argv = %w{ -c -a true infile outfile }
args = CLASP::Arguments.new(argv, aliases)
puts args.flags.size # => 1
puts args.flags[0] # => "#<CLASP::Arguments::Flag:0x007f8593b0ddd8 @arg="-c", @given_index=0, @given_name="-c", @argument_alias=nil, @given_hyphens=1, @given_label="c", @name="-c", @extras={}>"
puts args..size # => 1
puts args.[0] # => "#<CLASP::Arguments::Option:0x007f8593b0db80 @arg="-a", @given_index=1, @given_name="-a", @argument_alias=#<CLASP::Option: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
-
::CLASP::Arguments
-
::CLASP::Flag
-
::CLASP::Option
Functions of interest
-
::CLASP.show_version()
-
::CLASP#show_version()
-
::CLASP::show_version()
Defined Under Namespace
Modules: CLI_helpers_ Classes: Arguments, Flag, Option
Constant Summary collapse
- VERSION =
Current version of the CLASP.Ruby library
'0.10.3'
- VERSION_MAJOR =
Major version of the CLASP.Ruby library
VERSION_PARTS_[0]
- VERSION_MINOR =
Minor version of the CLASP.Ruby library
VERSION_PARTS_[1]
- VERSION_REVISION =
Revision version of the CLASP.Ruby library
VERSION_PARTS_[2]
Class Method Summary collapse
-
.Flag(name, options = {}) ⇒ Object
Generator method that obtains a CLASP::Flag according to the given parameters.
-
.Option(name, options = {}) ⇒ Object
Generator method that obtains a CLASP::Option according to the given parameters.
-
.show_usage(aliases, options = {}) ⇒ Object
Displays usage for the program according to the given aliases and options.
-
.show_version(aliases, options = {}) ⇒ Object
Displays version for the program according to the given aliases and options.
Class Method Details
.Flag(name, options = {}) ⇒ Object
Generator method that obtains a CLASP::Flag according to the given parameters
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 |
# File 'lib/clasp/aliases.rb', line 169 def CLASP.Flag(name, = {}) aliases = nil help = nil extras = nil .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 |
.Option(name, options = {}) ⇒ Object
Generator method that obtains a CLASP::Option according to the given parameters
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 |
# File 'lib/clasp/aliases.rb', line 206 def CLASP.Option(name, = {}) aliases = nil help = nil values_range = nil default_value = nil extras = nil .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 |
.show_usage(aliases, options = {}) ⇒ Object
Displays usage for the program according to the given aliases and options
Signature
-
Parameters:
aliases
-
(
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.
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 |
# File 'lib/clasp/cli.rb', line 122 def self.show_usage aliases, ={} ||= {} raise ArgumentError, "aliases may not be nil" if aliases.nil? raise TypeError, "aliases must be an array or must respond to each, reject and select" unless ::Array === aliases || (aliases.respond_to?(:each) && aliases.respond_to?(:reject) && aliases.respond_to?(:select)) aliases.each { |a| raise TypeError, "each element in aliases must be a Flag or an Option" unless a.is_a?(::CLASP::Flag) || a.is_a?(::CLASP::Option) } alias_dups = {} aliases.each { |a| a.aliases.each { |aa| warn "WARNING: alias '#{aa}' is already used for alias '#{a}'" if alias_dups.has_key? aa; alias_dups[aa] = a; } } suppress_blanks = [:suppress_blank_lines_between_options] || ENV['SUPPRESS_BLANK_LINES_BETWEEN_OPTIONS'] stream = [:stream] || $stdout program_name = [:program_name] || File.basename($0) info_lines = [: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.map! do |line| case line when :version CLI_helpers_.generate_version_string_ else line end end values = [:values] || '' values = " #{values}" if !values.empty? && ' ' != values[0] = [:flags_and_options] || ' [ ... flags and options ... ]' = " #{}" if !.empty? && ' ' != [0] # sift the aliases to sort out which are value-option aliases (VOAs) voas = {} aliases.select { |a| a.name =~ /^-+[a-zA-Z0-3_-]+[=:].+/ }.each do |a| a.name =~ /^(-+[a-zA-Z0-3_-]+)[=:](.+)$/ voas[$1] = [] unless voas.has_key? $1 voas[$1] << [ a, $2 ] end aliases = aliases.reject { |a| a.name =~ /^-+[a-zA-Z0-3_-]+[=:].+/ } info_lines.each { |info_line| stream.puts info_line } unless info_lines.empty? stream.puts "USAGE: #{program_name}#{}#{values}" stream.puts unless aliases.empty? stream.puts "flags/options:" stream.puts aliases.each do |a| case a when Flag a.aliases.each { |al| stream.puts "\t#{al}" } stream.puts "\t#{a.name}" stream.puts "\t\t#{a.help}" when Option if voas.has_key? a.name voas[a.name].each do |ar| ar[0].aliases.each { |al| stream.puts "\t#{al} #{ar[0].name}" } end end a.aliases.each { |al| stream.puts "\t#{al} <value>" } stream.puts "\t#{a.name}=<value>" stream.puts "\t\t#{a.help}" unless a.values_range.empty? stream.puts "\t\twhere <value> one of:" a.values_range.each { |v| stream.puts "\t\t\t#{v}" } end end stream.puts unless suppress_blanks end end exit [:exit] if [:exit] end |
.show_version(aliases, options = {}) ⇒ Object
Displays version for the program according to the given aliases and options
Signature
-
Parameters:
aliases
-
(
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).
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 |
# File 'lib/clasp/cli.rb', line 239 def self.show_version aliases, = {} ||= {} raise ArgumentError, "aliases may not be nil" if aliases.nil? raise TypeError, "aliases must be an array or must respond to each, reject and select" unless ::Array === aliases || (aliases.respond_to?(:each) && aliases.respond_to?(:reject) && aliases.respond_to?(:select)) aliases.each { |a| raise TypeError, "each element in aliases must be a Flag or an Option" unless a.is_a?(::CLASP::Flag) || a.is_a?(::CLASP::Option) } stream = [:stream] || $stdout version_string = CLI_helpers_.generate_version_string_ stream.puts version_string exit [:exit] if [:exit] end |