# 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, line 811
    def die arg, msg=nil
      if @last_parser
        @last_parser.die arg, msg
      else
        raise ArgumentError, "Trollop::die can only be called after Trollop::options"
      end
    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, line 747
    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 ::options doesn’t do quite what you want, you can create a Parser object and call Puppet::Util::CommandLine::Trollop::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, line 777
    def with_standard_exception_handling parser
      begin
        yield
      rescue CommandlineError => e
        $stderr.puts "Error: #{e.message}."
        $stderr.puts "Try --help for help."
        exit(-1)
      rescue HelpNeeded
        parser.educate
        exit
      rescue VersionNeeded
        puts parser.version
        exit
      end
    end