Class: MSpecOptions
Overview
MSpecOptions provides a parser for command line options. It also provides a composable set of options from which the runner scripts can select for their particular functionality.
Defined Under Namespace
Classes: OptionError, ParseError
Instance Attribute Summary collapse
-
#banner ⇒ Object
Returns the value of attribute banner.
-
#config ⇒ Object
Returns the value of attribute config.
-
#options ⇒ Object
Returns the value of attribute options.
-
#width ⇒ Object
Returns the value of attribute width.
Instance Method Summary collapse
- #action_filters ⇒ Object
- #actions ⇒ Object
-
#add(short, long, arg, description, block) ⇒ Object
Adds documentation text for an option and adds an
MSpecOption
instance to the list of registered options. - #background ⇒ Object
- #chdir ⇒ Object
-
#configure(&block) ⇒ Object
The methods below provide groups of options that are composed by the particular runners to provide their functionality.
- #debug ⇒ Object
-
#doc(str) ⇒ Object
Adds a string of documentation text inline in the text generated from the options.
- #filters ⇒ Object
- #formatters ⇒ Object
-
#help(&block) ⇒ Object
Convenience method for providing -h, –help options.
-
#initialize(banner = "", width = 30, config = nil) {|_self| ... } ⇒ MSpecOptions
constructor
A new instance of MSpecOptions.
- #interrupt ⇒ Object
-
#match?(opt) ⇒ Boolean
Searches all registered options to find a match for
opt
. - #name ⇒ Object
-
#on(*args, &block) ⇒ Object
Registers an option.
-
#on_extra(&block) ⇒ Object
Stores a block that will be called with unrecognized options.
-
#parse(argv = ARGV) ⇒ Object
Parses an array of command line entries, calling blocks for registered options.
- #prefix ⇒ Object
- #pretend ⇒ Object
-
#process(argv, entry, opt, arg) ⇒ Object
Processes an option.
- #randomize ⇒ Object
- #repeat ⇒ Object
-
#split(str, n) ⇒ Object
Splits a string at
n
characters into theopt
and therest
. - #targets ⇒ Object
-
#to_s ⇒ Object
Returns a string representation of the options and doc strings.
- #unguarded ⇒ Object
- #verbose ⇒ Object
- #verify ⇒ Object
-
#version(version, &block) ⇒ Object
Convenience method for providing -v, –version options.
Constructor Details
#initialize(banner = "", width = 30, config = nil) {|_self| ... } ⇒ MSpecOptions
Returns a new instance of MSpecOptions.
35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
# File 'lib/mspec/utils/options.rb', line 35 def initialize(="", width=30, config=nil) @banner = @config = config @width = width @options = [] @doc = [] @extra = [] @on_extra = lambda { |x| raise ParseError, "Unrecognized option: #{x}" if x[0] == ?- @extra << x } yield self if block_given? end |
Instance Attribute Details
#banner ⇒ Object
Returns the value of attribute banner.
33 34 35 |
# File 'lib/mspec/utils/options.rb', line 33 def @banner end |
#config ⇒ Object
Returns the value of attribute config.
33 34 35 |
# File 'lib/mspec/utils/options.rb', line 33 def config @config end |
#options ⇒ Object
Returns the value of attribute options.
33 34 35 |
# File 'lib/mspec/utils/options.rb', line 33 def @options end |
#width ⇒ Object
Returns the value of attribute width.
33 34 35 |
# File 'lib/mspec/utils/options.rb', line 33 def width @width end |
Instance Method Details
#action_filters ⇒ Object
451 452 453 454 455 456 457 458 459 460 |
# File 'lib/mspec/utils/options.rb', line 451 def action_filters on("-K", "--action-tag", "TAG", "Spec descriptions marked with TAG will trigger the specified action") do |o| config[:atags] << o end on("-S", "--action-string", "STR", "Spec descriptions matching STR will trigger the specified action") do |o| config[:astrings] << o end end |
#actions ⇒ Object
462 463 464 465 466 467 468 469 470 471 |
# File 'lib/mspec/utils/options.rb', line 462 def actions on("--spec-debug", "Invoke the debugger when a spec description matches (see -K, -S)") do config[:debugger] = true end on("--spec-gdb", "Invoke Gdb when a spec description matches (see -K, -S)") do config[:gdb] = true end end |
#add(short, long, arg, description, block) ⇒ Object
Adds documentation text for an option and adds an MSpecOption
instance to the list of registered options.
82 83 84 85 86 87 |
# File 'lib/mspec/utils/options.rb', line 82 def add(short, long, arg, description, block) s = short ? short.dup : " " s << (short ? ", " : " ") if long doc " #{s}#{long} #{arg}".ljust(@width-1) + " #{description}" @options << MSpecOption.new(short, long, arg, description, block) end |
#background ⇒ Object
376 377 378 379 380 381 |
# File 'lib/mspec/utils/options.rb', line 376 def background on("--background", "Enable guard for specs that may hang in background processes") do MSpec.register_mode :background end end |
#chdir ⇒ Object
356 357 358 359 360 361 |
# File 'lib/mspec/utils/options.rb', line 356 def chdir on("-C", "--chdir", "DIR", "Change the working directory to DIR before running specs") do |d| Dir.chdir d end end |
#configure(&block) ⇒ Object
The methods below provide groups of options that are composed by the particular runners to provide their functionality
196 197 198 199 |
# File 'lib/mspec/utils/options.rb', line 196 def configure(&block) on("-B", "--config", "FILE", "Load FILE containing configuration options", &block) end |
#debug ⇒ Object
473 474 475 476 477 478 |
# File 'lib/mspec/utils/options.rb', line 473 def debug on("-d", "--debug", "Set MSpec debugging flag for more verbose output") do $MSPEC_DEBUG = true end end |
#doc(str) ⇒ Object
Adds a string of documentation text inline in the text generated from the options. See #on and #add.
166 167 168 |
# File 'lib/mspec/utils/options.rb', line 166 def doc(str) @doc << str end |
#filters ⇒ Object
321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 |
# File 'lib/mspec/utils/options.rb', line 321 def filters on("-e", "--example", "STR", "Run examples with descriptions matching STR") do |o| config[:includes] << o end on("-E", "--exclude", "STR", "Exclude examples with descriptions matching STR") do |o| config[:excludes] << o end on("-p", "--pattern", "PATTERN", "Run examples with descriptions matching PATTERN") do |o| config[:patterns] << Regexp.new(o) end on("-P", "--excl-pattern", "PATTERN", "Exclude examples with descriptions matching PATTERN") do |o| config[:xpatterns] << Regexp.new(o) end on("-g", "--tag", "TAG", "Run examples with descriptions matching ones tagged with TAG") do |o| config[:tags] << o end on("-G", "--excl-tag", "TAG", "Exclude examples with descriptions matching ones tagged with TAG") do |o| config[:xtags] << o end on("-w", "--profile", "FILE", "Run examples for methods listed in the profile FILE") do |f| config[:profiles] << f end on("-W", "--excl-profile", "FILE", "Exclude examples for methods listed in the profile FILE") do |f| config[:xprofiles] << f end end |
#formatters ⇒ Object
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 |
# File 'lib/mspec/utils/options.rb', line 267 def formatters on("-f", "--format", "FORMAT", "Formatter for reporting, where FORMAT is one of:") do |o| case o when 's', 'spec', 'specdoc' config[:formatter] = SpecdocFormatter when 'h', 'html' config[:formatter] = HtmlFormatter when 'd', 'dot', 'dotted' config[:formatter] = DottedFormatter when 'b', 'describe' config[:formatter] = DescribeFormatter when 'f', 'file' config[:formatter] = FileFormatter when 'u', 'unit', 'unitdiff' config[:formatter] = UnitdiffFormatter when 'm', 'summary' config[:formatter] = SummaryFormatter when 'a', '*', 'spin' config[:formatter] = SpinnerFormatter when 't', 'method' config[:formatter] = MethodFormatter when 'y', 'yaml' config[:formatter] = YamlFormatter when 'p', 'profile' config[:formatter] = ProfileFormatter when 'j', 'junit' config[:formatter] = JUnitFormatter else puts "Unknown format: #{o}" puts @parser exit end end doc "" doc " s, spec, specdoc SpecdocFormatter" doc " h, html, HtmlFormatter" doc " d, dot, dotted DottedFormatter" doc " f, file FileFormatter" doc " u, unit, unitdiff UnitdiffFormatter" doc " m, summary SummaryFormatter" doc " a, *, spin SpinnerFormatter" doc " t, method MethodFormatter" doc " y, yaml YamlFormatter" doc " p, profile ProfileFormatter" doc " j, junit JUnitFormatter\n" on("-o", "--output", "FILE", "Write formatter output to FILE") do |f| config[:output] = f end end |
#help(&block) ⇒ Object
Convenience method for providing -h, –help options.
177 178 179 180 |
# File 'lib/mspec/utils/options.rb', line 177 def help(&block) help = block || lambda { puts self; exit 1 } on "-h", "--help", "Show this message", &help end |
#interrupt ⇒ Object
431 432 433 434 435 |
# File 'lib/mspec/utils/options.rb', line 431 def interrupt on("--int-spec", "Control-C interupts the current spec only") do config[:abort] = false end end |
#match?(opt) ⇒ Boolean
Searches all registered options to find a match for opt
. Returns nil
if no registered options match.
91 92 93 |
# File 'lib/mspec/utils/options.rb', line 91 def match?(opt) @options.find { |o| o.match? opt } end |
#name ⇒ Object
201 202 203 204 205 206 |
# File 'lib/mspec/utils/options.rb', line 201 def name on("-n", "--name", "RUBY_NAME", "Set the value of RUBY_NAME (used to determine the implementation)") do |n| Object.const_set :RUBY_NAME, n end end |
#on(*args, &block) ⇒ Object
Registers an option. Acceptable formats for arguments are:
on "-a", "description"
on "-a", "--abdc", "description"
on "-a", "ARG", "description"
on "--abdc", "ARG", "description"
on "-a", "--abdc", "ARG", "description"
If an block is passed, it will be invoked when the option is matched. Not passing a block is permitted, but nonsensical.
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
# File 'lib/mspec/utils/options.rb', line 60 def on(*args, &block) raise OptionError, "option and description are required" if args.size < 2 description = args.pop short, long, argument = nil args.each do |arg| if arg[0] == ?- if arg[1] == ?- long = arg else short = arg end else argument = arg end end add short, long, argument, description, block end |
#on_extra(&block) ⇒ Object
Stores a block that will be called with unrecognized options
183 184 185 |
# File 'lib/mspec/utils/options.rb', line 183 def on_extra(&block) @on_extra = block end |
#parse(argv = ARGV) ⇒ Object
Parses an array of command line entries, calling blocks for registered options.
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 |
# File 'lib/mspec/utils/options.rb', line 124 def parse(argv=ARGV) argv = Array(argv).dup while entry = argv.shift # collect everything that is not an option if entry[0] != ?- or entry.size < 2 @on_extra[entry] next end # this is a long option if entry[1] == ?- opt, arg = entry.split "=" process argv, entry, opt, arg next end # disambiguate short option group from short option with argument opt, arg, rest = split entry, 2 # process first option option = process argv, entry, opt, arg next unless option and not option.arg? # process the rest of the options while rest.size > 0 opt, arg, rest = split rest, 1 opt = "-" + opt option = process argv, opt, opt, arg break if option.arg? end end @extra rescue ParseError => e puts self puts e exit 1 end |
#prefix ⇒ Object
363 364 365 366 367 |
# File 'lib/mspec/utils/options.rb', line 363 def prefix on("--prefix", "STR", "Prepend STR when resolving spec file names") do |p| config[:prefix] = p end end |
#pretend ⇒ Object
369 370 371 372 373 374 |
# File 'lib/mspec/utils/options.rb', line 369 def pretend on("-Z", "--dry-run", "Invoke formatters and other actions, but don't execute the specs") do MSpec.register_mode :pretend end end |
#process(argv, entry, opt, arg) ⇒ Object
Processes an option. Calles the #on_extra block (or default) for unrecognized options. For registered options, possibly fetches an argument and invokes the option’s block if it is not nil.
98 99 100 101 102 103 104 105 106 107 108 109 110 111 |
# File 'lib/mspec/utils/options.rb', line 98 def process(argv, entry, opt, arg) unless option = match?(opt) @on_extra[entry] else if option.arg? arg = argv.shift if arg.nil? raise ParseError, "No argument provided for #{opt}" unless arg option.block[arg] if option.block else option.block[] if option.block end end option end |
#randomize ⇒ Object
392 393 394 395 396 397 |
# File 'lib/mspec/utils/options.rb', line 392 def randomize on("-H", "--random", "Randomize the list of spec files") do MSpec.randomize end end |
#repeat ⇒ Object
399 400 401 402 403 404 |
# File 'lib/mspec/utils/options.rb', line 399 def repeat on("-R", "--repeat", "NUMBER", "Repeatedly run an example NUMBER times") do |o| MSpec.repeat = o.to_i end end |
#split(str, n) ⇒ Object
Splits a string at n
characters into the opt
and the rest
. The arg
is set to nil
if rest
is an empty string.
115 116 117 118 119 120 |
# File 'lib/mspec/utils/options.rb', line 115 def split(str, n) opt = str[0, n] rest = str[n, str.size] arg = rest == "" ? nil : rest return opt, arg, rest end |
#targets ⇒ Object
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 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 |
# File 'lib/mspec/utils/options.rb', line 208 def targets on("-t", "--target", "TARGET", "Implementation to run the specs, where TARGET is:") do |t| case t when 'r', 'ruby' config[:target] = 'ruby' when 'r19', 'ruby19' config[:target] = 'ruby1.9' when 'x', 'rubinius' config[:target] = './bin/rbx' when 'x18', 'rubinius18' config[:target] = './bin/rbx -X18' when 'x19', 'rubinius19' config[:target] = './bin/rbx -X19' when 'x20', 'rubinius20' config[:target] = './bin/rbx -X20' when 'X', 'rbx' config[:target] = 'rbx' when 'j', 'jruby' config[:target] = 'jruby' when 'i','ironruby' config[:target] = 'ir' when 'm','maglev' config[:target] = 'maglev-ruby' when 't','topaz' config[:target] = 'topaz' else config[:target] = t end end doc "" doc " r or ruby invokes ruby in PATH" doc " r19, ruby19 invokes ruby1.9 in PATH" doc " x or rubinius invokes ./bin/rbx" doc " x18 or rubinius18 invokes ./bin/rbx -X18" doc " x19 or rubinius19 invokes ./bin/rbx -X19" doc " x20 or rubinius20 invokes ./bin/rbx -X20" doc " X or rbx invokes rbx in PATH" doc " j or jruby invokes jruby in PATH" doc " i or ironruby invokes ir in PATH" doc " m or maglev invokes maglev-ruby in PATH" doc " t or topaz invokes topaz in PATH" doc " full path to EXE invokes EXE directly\n" on("-T", "--target-opt", "OPT", "Pass OPT as a flag to the target implementation") do |t| config[:flags] << t end on("-I", "--include", "DIR", "Pass DIR through as the -I option to the target") do |d| config[:includes] << "-I#{d}" end on("-r", "--require", "LIBRARY", "Pass LIBRARY through as the -r option to the target") do |f| config[:requires] << "-r#{f}" end end |
#to_s ⇒ Object
Returns a string representation of the options and doc strings.
188 189 190 |
# File 'lib/mspec/utils/options.rb', line 188 def to_s @banner + "\n\n" + @doc.join("\n") + "\n" end |
#unguarded ⇒ Object
383 384 385 386 387 388 389 390 |
# File 'lib/mspec/utils/options.rb', line 383 def unguarded on("--unguarded", "Turn off all guards") do MSpec.register_mode :unguarded end on("--no-ruby_bug", "Turn off the ruby_bug guard") do MSpec.register_mode :no_ruby_bug end end |
#verbose ⇒ Object
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 |
# File 'lib/mspec/utils/options.rb', line 406 def verbose on("-V", "--verbose", "Output the name of each file processed") do obj = Object.new def obj.start @width = MSpec.retrieve(:files).inject(0) { |max, f| f.size > max ? f.size : max } end def obj.load file = MSpec.retrieve :file print "\n#{file.ljust(@width)}" end MSpec.register :start, obj MSpec.register :load, obj end on("-m", "--marker", "MARKER", "Output MARKER for each file processed") do |o| obj = Object.new obj.instance_variable_set :@marker, o def obj.load print @marker end MSpec.register :load, obj end end |
#verify ⇒ Object
437 438 439 440 441 442 443 444 445 446 447 448 449 |
# File 'lib/mspec/utils/options.rb', line 437 def verify on("--report-on", "GUARD", "Report specs guarded by GUARD") do |g| MSpec.register_mode :report_on SpecGuard.guards << g.to_sym end on("-O", "--report", "Report guarded specs") do MSpec.register_mode :report end on("-Y", "--verify", "Verify that guarded specs pass and fail as expected") do MSpec.register_mode :verify end end |
#version(version, &block) ⇒ Object
Convenience method for providing -v, –version options.
171 172 173 174 |
# File 'lib/mspec/utils/options.rb', line 171 def version(version, &block) show = block || lambda { puts "#{File.basename $0} #{version}"; exit } on "-v", "--version", "Show version", &show end |