module OptimistXL

Constants

FLOAT_RE

Regex for floating point numbers

PARAM_RE

Regex for parameters

VERSION

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

Public Class Methods

die(arg, msg = nil, error_code = nil) click to toggle source

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?
# 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() click to toggle source

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?
# 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) click to toggle source
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.

# 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) { || ... } click to toggle source

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.

# 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

Private Instance Methods

die(arg, msg = nil, error_code = nil) click to toggle source

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?
# 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() click to toggle source

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?
# 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) click to toggle source
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.

# 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) { || ... } click to toggle source

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.

# 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