Module: OptimistXL

Defined in:
lib/optimist_xl.rb,
lib/optimist_xl/chronic.rb

Defined Under Namespace

Classes: BooleanOption, ChronicDateOption, CommandlineError, DateArrayOption, DateOption, FloatArrayOption, FloatOption, HelpNeeded, IOArrayOption, IOOption, IntegerArrayOption, IntegerOption, LongNames, Option, Parser, ShortNames, StringArrayOption, StringFlagOption, StringOption, SubcommandParser, SubcommandResult, VersionNeeded

Constant Summary collapse

VERSION =

note: this is duplicated in gemspec please change over there too

"3.3.0"
FLOAT_RE =

Regex for floating point numbers

/^-?((\d+(\.\d+)?)|(\.\d+))([eE][-+]?[\d]+)?$/
PARAM_RE =

Regex for parameters

/^-(-|\.$|[^\d\.])/

Class Method Summary collapse

Class Method Details

.die(arg, msg = nil, error_code = nil) ⇒ Object

Informs the user that their usage of ‘arg’ was wrong, as detailed by ‘msg’, and dies. Example:

options do
  opt :volume, :default => 0.0
end

die :volume, "too loud" if opts[:volume] > 10.0
die :volume, "too soft" if opts[:volume] < 0.1

In the one-argument case, simply print that message, a notice about -h, and die. Example:

options do
  opt :whatever # ...
end

OptimistXL::die "need at least one filename" if ARGV.empty?

An exit code can be provide if needed

OptimistXL::die "need at least one filename", -2 if ARGV.empty?



1411
1412
1413
1414
1415
1416
1417
 
# File 'lib/optimist_xl.rb', line 1411

def die(arg, msg = nil, error_code = nil)
  if @last_parser
    @last_parser.die arg, msg, error_code
  else
    raise ArgumentError, "OptimistXL::die can only be called after OptimistXL::options"
  end
end

.educate ⇒ Object

Displays the help message and dies. Example:

options do
  opt :volume, :default => 0.0
  banner <<-EOS
Usage:
       #$0 [options] <name>
where [options] are:
EOS
end

OptimistXL::educate if ARGV.empty?



1431
1432
1433
1434
1435
1436
1437
1438
 
# File 'lib/optimist_xl.rb', line 1431

def educate
  if @last_parser
    @last_parser.educate
    exit
  else
    raise ArgumentError, "OptimistXL::educate can only be called after OptimistXL::options"
  end
end

.options(args = ARGV, *a, &b) ⇒ Object

Because OptimistXL::options uses a default argument for args, you must pass that argument when using the settings feature.

See more examples at optimist.rubyforge.org.



1347
1348
1349
1350
 
# File 'lib/optimist_xl.rb', line 1347

def options(args = ARGV, *a, &b)
  @last_parser = Parser.new(*a, &b)
  with_standard_exception_handling(@last_parser) { @last_parser.parse args }
end

.with_standard_exception_handling(parser) ⇒ Object

If OptimistXL::options doesn’t do quite what you want, you can create a Parser object and call Parser#parse on it. That method will throw CommandlineError, HelpNeeded and VersionNeeded exceptions when necessary; if you want to have these handled for you in the standard manner (e.g. show the help and then exit upon an HelpNeeded exception), call your code from within a block passed to this method.

Note that this method will call System#exit after handling an exception!

Usage example:

require 'optimist'
p = OptimistXL::Parser.new do
  opt :monkey, "Use monkey mode"                     # a flag --monkey, defaulting to false
  opt :goat, "Use goat mode", :default => true       # a flag --goat, defaulting to true
end

opts = OptimistXL::with_standard_exception_handling p do
  o = p.parse ARGV
  raise OptimistXL::HelpNeeded if ARGV.empty? # show help screen
  o
end

Requires passing in the parser object.



1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
 
# File 'lib/optimist_xl.rb', line 1377

def with_standard_exception_handling(parser)
  yield
rescue CommandlineError => e
  parser.die(e.message, nil, e.error_code)
rescue HelpNeeded => e
  e.parser.educate
  exit
rescue VersionNeeded
  puts parser.version
  exit
end