Module: Ncio::Trollop

Defined in:
lib/ncio/trollop.rb

Defined Under Namespace

Classes: CommandlineError, HelpNeeded, Parser, VersionNeeded

Constant Summary collapse

VERSION =

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

"2.1.2"
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

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



832
833
834
835
836
837
838
 
# File 'lib/ncio/trollop.rb', line 832

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

.educate ⇒ Object

Displays the help message and dies. Example:

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

Trollop::educate if ARGV.empty?



852
853
854
855
856
857
858
859
 
# File 'lib/ncio/trollop.rb', line 852

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

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

The easy, syntactic-sugary entry method into Trollop. Creates a Parser, passes the block to it, then parses +args+ with it, handling any errors or requests for help or version information appropriately (and then exiting). Modifies +args+ in place. Returns a hash of option values.

The block passed in should contain zero or more calls to +opt+ (Parser#opt), zero or more calls to +text+ (Parser#text), and probably a call to +version+ (Parser#version).

The returned block contains a value for every option specified with +opt+. The value will be the value given on the commandline, or the default value if the option was not specified on the commandline. For every option specified on the commandline, a key "

Example:

require 'trollop' opts = Trollop::options do opt :monkey, "Use monkey mode" # a flag --monkey, defaulting to false opt :name, "Monkey name", :type => :string # a string --name , defaulting to nil opt :num_limbs, "Number of limbs", :default => 4 # an integer --num-limbs , defaulting to 4 end

## if called with no arguments p opts # => :name=>nil, :num_limbs=>4, :help=>false

## if called with --monkey p opts # => :name=>nil, :num_limbs=>4, :help=>false, :monkey_given=>true

See more examples at http://trollop.rubyforge.org.



772
773
774
775
 
# File 'lib/ncio/trollop.rb', line 772

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 Trollop::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 'trollop' p = Trollop::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 = Trollop::with_standard_exception_handling p do o = p.parse ARGV raise Trollop::HelpNeeded if ARGV.empty? # show help screen o end

Requires passing in the parser object.



802
803
804
805
806
807
808
809
810
811
812
 
# File 'lib/ncio/trollop.rb', line 802

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