module Puppet::Util::CommandLine::Trollop
Constants
- FLOAT_RE
Regex for floating point numbers
- PARAM_RE
Regex for parameters
- VERSION
Public Class Methods
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
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
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
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
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
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