module Puppet::Util::CommandLine::Trollop

Constants

FLOAT_RE

Regex for floating point numbers

PARAM_RE

Regex for parameters

VERSION

Public Class Methods

die(arg, msg=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

Trollop::die "need at least one filename" if ARGV.empty?
    # File lib/puppet/util/command_line/trollop.rb
811 def die arg, msg=nil
812   if @last_parser
813     @last_parser.die arg, msg
814   else
815     #TRANSLATORS 'Trollop' is the name of a module and 'die' and 'options' are methods in it and should not be translated.
816     raise ArgumentError, _("Trollop::die can only be called after Trollop::options")
817   end
818 end
options(args=ARGV, *a, &b) click to toggle source

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 “<option name>_given” will also be set in the hash.

Example:

require 'trollop'
opts = Trollop::options 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
  opt :num_limbs, "Number of limbs", :default => 4   # an integer --num-limbs <i>, defaulting to 4
  opt :num_thumbs, "Number of thumbs", :type => :int # an integer --num-thumbs <i>, defaulting to nil
end

## if called with no arguments
p opts # => { :monkey => false, :goat => true, :num_limbs => 4, :num_thumbs => nil }

## if called with --monkey
p opts # => {:monkey_given=>true, :monkey=>true, :goat=>true, :num_limbs=>4, :help=>false, :num_thumbs=>nil}

See more examples at trollop.rubyforge.org.

    # File lib/puppet/util/command_line/trollop.rb
747 def options args=ARGV, *a, &b
748   @last_parser = Parser.new(*a, &b)
749   with_standard_exception_handling(@last_parser) { @last_parser.parse args }
750 end
with_standard_exception_handling(parser) { || ... } click to toggle source

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.

    # File lib/puppet/util/command_line/trollop.rb
777 def with_standard_exception_handling parser
778   begin
779     yield
780   rescue CommandlineError => e
781     $stderr.puts _("Error: %{value0}.") % { value0: e.message }
782     $stderr.puts _("Try --help for help.")
783     exit(-1)
784   rescue HelpNeeded
785     parser.educate
786     exit
787   rescue VersionNeeded
788     puts parser.version
789     exit
790   end
791 end

Private Instance Methods

die(arg, msg=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

Trollop::die "need at least one filename" if ARGV.empty?
    # File lib/puppet/util/command_line/trollop.rb
811 def die arg, msg=nil
812   if @last_parser
813     @last_parser.die arg, msg
814   else
815     #TRANSLATORS 'Trollop' is the name of a module and 'die' and 'options' are methods in it and should not be translated.
816     raise ArgumentError, _("Trollop::die can only be called after Trollop::options")
817   end
818 end
options(args=ARGV, *a, &b) click to toggle source

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 “<option name>_given” will also be set in the hash.

Example:

require 'trollop'
opts = Trollop::options 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
  opt :num_limbs, "Number of limbs", :default => 4   # an integer --num-limbs <i>, defaulting to 4
  opt :num_thumbs, "Number of thumbs", :type => :int # an integer --num-thumbs <i>, defaulting to nil
end

## if called with no arguments
p opts # => { :monkey => false, :goat => true, :num_limbs => 4, :num_thumbs => nil }

## if called with --monkey
p opts # => {:monkey_given=>true, :monkey=>true, :goat=>true, :num_limbs=>4, :help=>false, :num_thumbs=>nil}

See more examples at trollop.rubyforge.org.

    # File lib/puppet/util/command_line/trollop.rb
747 def options args=ARGV, *a, &b
748   @last_parser = Parser.new(*a, &b)
749   with_standard_exception_handling(@last_parser) { @last_parser.parse args }
750 end
with_standard_exception_handling(parser) { || ... } click to toggle source

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.

    # File lib/puppet/util/command_line/trollop.rb
777 def with_standard_exception_handling parser
778   begin
779     yield
780   rescue CommandlineError => e
781     $stderr.puts _("Error: %{value0}.") % { value0: e.message }
782     $stderr.puts _("Try --help for help.")
783     exit(-1)
784   rescue HelpNeeded
785     parser.educate
786     exit
787   rescue VersionNeeded
788     puts parser.version
789     exit
790   end
791 end