# class OptionParser

## OptionParser¶ ↑

### Introduction¶ ↑

OptionParser is a class for command-line option analysis. It is much more advanced, yet also easier to use, than GetoptLong, and is a more Ruby-oriented solution.

### Features¶ ↑

1. The argument specification and the code to handle it are written in the same place.

2. It can output an option summary; you don't need to maintain this string separately.

3. Optional and mandatory arguments are specified very gracefully.

4. Arguments can be automatically converted to a specified class.

5. Arguments can be restricted to a certain set.

All of these features are demonstrated in the examples below. See make_switch for full documentation.

### Minimal example¶ ↑

    require 'optparse'

    options = {}
    OptionParser.new do |opts|
      opts.banner = "Usage: example.rb [options]"

      opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
        options[:verbose] = v
      end
    end.parse!

    p options
    p ARGV

### Generating Help¶ ↑

OptionParser can be used to automatically generate help for the commands you write:

    require 'optparse'

    Options = Struct.new(:name)

    class Parser
      def self.parse(options)
        args = Options.new("world")

        opt_parser = OptionParser.new do |opts|
          opts.banner = "Usage: example.rb [options]"

          opts.on("-nNAME", "--name=NAME", "Name to say hello to") do |n|
            args.name = n
          end

          opts.on("-h", "--help", "Prints this help") do
            puts opts
            exit
          end
        end

        opt_parser.parse!(options)
        return args
      end
    end
    options = Parser.parse %w[--help]

    #=>
       # Usage: example.rb [options]
       #     -n, --name=NAME                  Name to say hello to
       #     -h, --help                       Prints this help

### Required Arguments¶ ↑

For options that require an argument, option specification strings may include an option name in all caps. If an option is used without the required argument, an exception will be raised.

    require 'optparse'

    options = {}
    OptionParser.new do |parser|
      parser.on("-r", "--require LIBRARY",
                "Require the LIBRARY before executing your script") do |lib|
        puts "You required #{lib}!"
      end
    end.parse!

Used:

    bash-3.2$ ruby optparse-test.rb -r
    optparse-test.rb:9:in `<main>': missing argument: -r (OptionParser::MissingArgument)
    bash-3.2$ ruby optparse-test.rb -r my-library
    You required my-library!

### Type Coercion¶ ↑

OptionParser supports the ability to coerce command line arguments into objects for us.

OptionParser comes with a few ready-to-use kinds of type coercion. They are:

- Date – Anything accepted by `Date.parse`

- DateTime – Anything accepted by `DateTime.parse`

- Time – Anything accepted by `Time.httpdate` or `Time.parse`

- URI – Anything accepted by `URI.parse`

- Shellwords – Anything accepted by `Shellwords.shellwords`

- String – Any non-empty string

- Integer – Any integer. Will convert octal. (e.g. 124, -3, 040)

- Float – Any float. (e.g. 10, 3.14, -100E+13)

- Numeric – Any integer, float, or rational (1, 3.4, 1/3)

- DecimalInteger – Like `Integer`, but no octal format.

- OctalInteger – Like `Integer`, but no decimal format.

- DecimalNumeric – Decimal integer or float.

- TrueClass – Accepts '+, yes, true, -, no, false' and defaults as `true`

- FalseClass – Same as `TrueClass`, but defaults to `false`

- Array – Strings separated by ',' (e.g. 1,2,3)

- Regexp – Regular expressions. Also includes options.

We can also add our own coercions, which we will cover soon.

#### Using Built-in Conversions¶ ↑

As an example, the built-in `Time` conversion is used. The other built-in conversions behave in the same way. OptionParser will attempt to parse the argument as a `Time`. If it succeeds, that time will be passed to the handler block. Otherwise, an exception will be raised.

    require 'optparse'
    require 'optparse/time'
    OptionParser.new do |parser|
      parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
        p time
      end
    end.parse!

Used:

    bash-3.2$ ruby optparse-test.rb  -t nonsense
    ... invalid argument: -t nonsense (OptionParser::InvalidArgument)
    from ... time.rb:5:in `block in <top (required)>'
    from optparse-test.rb:31:in `<main>'
    bash-3.2$ ruby optparse-test.rb  -t 10-11-12
    2010-11-12 00:00:00 -0500
    bash-3.2$ ruby optparse-test.rb  -t 9:30
    2014-08-13 09:30:00 -0400

#### Creating Custom Conversions¶ ↑

The `accept` method on OptionParser may be used to create converters. It specifies which conversion block to call whenever a class is specified. The example below uses it to fetch a `User` object before the `on` handler receives it.

    require 'optparse'

    User = Struct.new(:id, :name)

    def find_user id
      not_found = ->{ raise "No User Found for id #{id}" }
      [ User.new(1, "Sam"),
        User.new(2, "Gandalf") ].find(not_found) do |u|
        u.id == id
      end
    end

    op = OptionParser.new
    op.accept(User) do |user_id|
      find_user user_id.to_i
    end

    op.on("--user ID", User) do |user|
      puts user
    end

    op.parse!

output:

    bash-3.2$ ruby optparse-test.rb --user 1
    #<struct User id=1, name="Sam">
    bash-3.2$ ruby optparse-test.rb --user 2
    #<struct User id=2, name="Gandalf">
    bash-3.2$ ruby optparse-test.rb --user 3
    optparse-test.rb:15:in `block in find_user': No User Found for id 3 (RuntimeError)

### Complete example¶ ↑

The following example is a complete Ruby program. You can run it and see the effect of specifying various options. This is probably the best way to learn the features of `optparse`.

    require 'optparse'
    require 'optparse/time'
    require 'ostruct'
    require 'pp'

    class OptparseExample
      Version = '1.0.0'

      CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
      CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }

      class ScriptOptions
        attr_accessor :library, :inplace, :encoding, :transfer_type,
                      :verbose, :extension, :delay, :time, :record_separator,
                      :list

        def initialize
          self.library = []
          self.inplace = false
          self.encoding = "utf8"
          self.transfer_type = :auto
          self.verbose = false
        end

        def define_options(parser)
          parser.banner = "Usage: example.rb [options]"
          parser.separator ""
          parser.separator "Specific options:"

          # add additional options
          perform_inplace_option(parser)
          delay_execution_option(parser)
          execute_at_time_option(parser)
          specify_record_separator_option(parser)
          list_example_option(parser)
          specify_encoding_option(parser)
          optional_option_argument_with_keyword_completion_option(parser)
          boolean_verbose_option(parser)

          parser.separator ""
          parser.separator "Common options:"
          # No argument, shows at tail.  This will print an options summary.
          # Try it and see!
          parser.on_tail("-h", "--help", "Show this message") do
            puts parser
            exit
          end
          # Another typical switch to print the version.
          parser.on_tail("--version", "Show version") do
            puts Version
            exit
          end
        end

        def perform_inplace_option(parser)
          # Specifies an optional option argument
          parser.on("-i", "--inplace [EXTENSION]",
                    "Edit ARGV files in place",
                    "(make backup if EXTENSION supplied)") do |ext|
            self.inplace = true
            self.extension = ext || ''
            self.extension.sub!(/\A\.?(?=.)/, ".")  # Ensure extension begins with dot.
          end
        end

        def delay_execution_option(parser)
          # Cast 'delay' argument to a Float.
          parser.on("--delay N", Float, "Delay N seconds before executing") do |n|
            self.delay = n
          end
        end

        def execute_at_time_option(parser)
          # Cast 'time' argument to a Time object.
          parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
            self.time = time
          end
        end

        def specify_record_separator_option(parser)
          # Cast to octal integer.
          parser.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,
                    "Specify record separator (default \\0)") do |rs|
            self.record_separator = rs
          end
        end

        def list_example_option(parser)
          # List of arguments.
          parser.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
            self.list = list
          end
        end

        def specify_encoding_option(parser)
          # Keyword completion.  We are specifying a specific set of arguments (CODES
          # and CODE_ALIASES - notice the latter is a Hash), and the user may provide
          # the shortest unambiguous text.
          code_list = (CODE_ALIASES.keys + CODES).join(', ')
          parser.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
                    "(#{code_list})") do |encoding|
            self.encoding = encoding
          end
        end

        def optional_option_argument_with_keyword_completion_option(parser)
          # Optional '--type' option argument with keyword completion.
          parser.on("--type [TYPE]", [:text, :binary, :auto],
                    "Select transfer type (text, binary, auto)") do |t|
            self.transfer_type = t
          end
        end

        def boolean_verbose_option(parser)
          # Boolean switch.
          parser.on("-v", "--[no-]verbose", "Run verbosely") do |v|
            self.verbose = v
          end
        end
      end

      #
      # Return a structure describing the options.
      #
      def parse(args)
        # The options specified on the command line will be collected in
        # *options*.

        @options = ScriptOptions.new
        @args = OptionParser.new do |parser|
          @options.define_options(parser)
          parser.parse!(args)
        end
        @options
      end

      attr_reader :parser, :options
    end  # class OptparseExample

    example = OptparseExample.new
    options = example.parse(ARGV)
    pp options # example.options
    pp ARGV

### Shell Completion¶ ↑

For modern shells (e.g. bash, zsh, etc.), you can use shell completion for command line options.

### Further documentation¶ ↑

The above examples should be enough to learn how to use this class. If you have any questions, file a ticket at bugs.ruby-lang.org.

### Constants

DecimalInteger

  Decimal integer format, to be converted to Integer.

DecimalNumeric

  Decimal integer/float number format, to be converted to Integer for integer format, Float for float format.

OctalInteger

  Ruby/C like octal/hexadecimal/binary integer format, to be converted to Integer.

### Attributes

banner[W]

Heading banner preceding summary.

default_argv[RW]

Strings to be parsed in default.

program_name[W]

Program name to be emitted in error message and default banner, defaults to $0.

release[W]

Release code

set_banner[W]

Heading banner preceding summary.

set_program_name[W]

Program name to be emitted in error message and default banner, defaults to $0.

set_summary_indent[RW]

Indentation for summary. Must be String (or have + String method).

set_summary_width[RW]

Width for option list portion of summary. Must be Numeric.

summary_indent[RW]

Indentation for summary. Must be String (or have + String method).

summary_width[RW]

Width for option list portion of summary. Must be Numeric.

version[W]

Version

### Public Class Methods

accept(*args, &blk) click to toggle source

See accept.

    # File lib/optparse.rb, line 1098
    def self.accept(*args, &blk) top.accept(*args, &blk) end

each_const(path, base = ::Object) click to toggle source

    # File lib/optparse/version.rb, line 49
    def each_const(path, base = ::Object)
      path.split(/::|\//).inject(base) do |klass, name|
        raise NameError, path unless Module === klass
        klass.constants.grep(/#{name}/i) do |c|
          klass.const_defined?(c) or next
          klass.const_get(c)
        end
      end
    end

getopts(*args) click to toggle source

See getopts.

    # File lib/optparse.rb, line 1696
    def self.getopts(*args)
      new.getopts(*args)
    end

inc(arg, default = nil) click to toggle source

Returns an incremented value of `default` according to `arg`.

    # File lib/optparse.rb, line 1034
    def self.inc(arg, default = nil)
      case arg
      when Integer
        arg.nonzero?
      when nil
        default.to_i + 1
      end
    end

new(banner = nil, width = 32, indent = ' ' * 4) { |self| ... } click to toggle source

Initializes the instance and yields itself if called with a block.

`banner`

  Banner message.

`width`

  Summary width.

`indent`

  Summary indent.

    # File lib/optparse.rb, line 1053
    def initialize(banner = nil, width = 32, indent = ' ' * 4)
      @stack = [DefaultList, List.new, List.new]
      @program_name = nil
      @banner = banner
      @summary_width = width
      @summary_indent = indent
      @default_argv = ARGV
      add_officious
      yield self if block_given?
    end

reject(*args, &blk) click to toggle source

See reject.

    # File lib/optparse.rb, line 1111
    def self.reject(*args, &blk) top.reject(*args, &blk) end

search_const(klass, name) { |klass, cname, const| ... } click to toggle source

    # File lib/optparse/version.rb, line 59
    def search_const(klass, name)
      klasses = [klass]
      while klass = klasses.shift
        klass.constants.each do |cname|
          klass.const_defined?(cname) or next
          const = klass.const_get(cname)
          yield klass, cname, const if name === cname
          klasses << const if Module === const and const != ::Object
        end
      end
    end

show_version(*pkgs) click to toggle source

    # File lib/optparse/version.rb, line 4
    def show_version(*pkgs)
      progname = ARGV.options.program_name
      result = false
      show = proc do |klass, cname, version|
        str = "#{progname}"
        unless klass == ::Object and cname == :VERSION
          version = version.join(".") if Array === version
          str << ": #{klass}" unless klass == Object
          str << " version #{version}"
        end
        [:Release, :RELEASE].find do |rel|
          if klass.const_defined?(rel)
            str << " (#{klass.const_get(rel)})"
          end
        end
        puts str
        result = true
      end
      if pkgs.size == 1 and pkgs[0] == "all"
        self.search_const(::Object, /\AV(?:ERSION|ersion)\z/) do |klass, cname, version|
          unless cname[1] == ?e and klass.const_defined?(:Version)
            show.call(klass, cname.intern, version)
          end
        end
      else
        pkgs.each do |pkg|
          begin
            pkg = pkg.split(/::|\//).inject(::Object) {|m, c| m.const_get(c)}
            v = case
                when pkg.const_defined?(:Version)
                  pkg.const_get(n = :Version)
                when pkg.const_defined?(:VERSION)
                  pkg.const_get(n = :VERSION)
                else
                  n = nil
                  "unknown"
                end
            show.call(pkg, n, v)
          rescue NameError
          end
        end
      end
      result
    end

terminate(arg = nil) click to toggle source

    # File lib/optparse.rb, line 1078
    def self.terminate(arg = nil)
      throw :terminate, arg
    end

top() click to toggle source

    # File lib/optparse.rb, line 1083
    def self.top() DefaultList end

with(*args, &block) click to toggle source

Initializes a new instance and evaluates the optional block in context of the instance. Arguments `args` are passed to new, see there for description of parameters.

This method is deprecated, its behavior corresponds to the older new method.

    # File lib/optparse.rb, line 1025
    def self.with(*args, &block)
      opts = new(*args)
      opts.instance_eval(&block)
      opts
    end

### Public Instance Methods

abort(mesg = $!) click to toggle source
Calls superclass method Kernel#abort

    # File lib/optparse.rb, line 1192
    def abort(mesg = $!)
      super("#{program_name}: #{mesg}")
    end

accept(*args, &blk) click to toggle source

Directs to accept specified class `t`. The argument string is passed to the block in which it should be converted to the desired class.

`t`

  Argument class specifier, any object including Class.

`pat`

  Pattern for argument, defaults to `t` if it responds to match.

    accept(t, pat, &block)

    # File lib/optparse.rb, line 1094
    def accept(*args, &blk) top.accept(*args, &blk) end

banner() click to toggle source

Heading banner preceding summary.

    # File lib/optparse.rb, line 1136
    def banner
      unless @banner
        @banner = "Usage: #{program_name} [options]"
        visit(:add_banner, @banner)
      end
      @banner
    end

base() click to toggle source

Subject of on_tail.

    # File lib/optparse.rb, line 1206
    def base
      @stack[1]
    end

candidate(word) click to toggle source

    # File lib/optparse.rb, line 1743
    def candidate(word)
      list = []
      case word
      when '-'
        long = short = true
      when /\A--/
        word, arg = word.split(/=/, 2)
        argpat = Completion.regexp(arg, false) if arg and !arg.empty?
        long = true
      when /\A-/
        short = true
      end
      pat = Completion.regexp(word, long)
      visit(:each_option) do |opt|
        next unless Switch === opt
        opts = (long ? opt.long : []) + (short ? opt.short : [])
        opts = Completion.candidate(word, true, pat, &opts.method(:each)).map(&:first) if pat
        if /\A=/ =~ opt.arg
          opts.map! {|sw| sw + "="}
          if arg and CompletingHash === opt.pattern
            if opts = opt.pattern.candidate(arg, false, argpat)
              opts.map!(&:last)
            end
          end
        end
        list.concat(opts)
      end
      list
    end

def_head_option(*opts, &block)
Alias for: define_head
def_option(*opts, &block)
Alias for: define
def_tail_option(*opts, &block)
Alias for: define_tail
define(*opts, &block) click to toggle source

    # File lib/optparse.rb, line 1464
    def define(*opts, &block)
      top.append(*(sw = make_switch(opts, block)))
      sw[0]
    end

Also aliased as: def_option
define_by_keywords(options, meth, **opts) click to toggle source

    # File lib/optparse/kwargs.rb, line 4
    def define_by_keywords(options, meth, **opts)
      meth.parameters.each do |type, name|
        case type
        when :key, :keyreq
          op, cl = *(type == :key ? %w"[ ]" : ["", ""])
          define("--#{name}=#{op}#{name.upcase}#{cl}", *opts[name]) do |o|
            options[name] = o
          end
        end
      end
      options
    end

define_head(*opts, &block) click to toggle source

    # File lib/optparse.rb, line 1479
    def define_head(*opts, &block)
      top.prepend(*(sw = make_switch(opts, block)))
      sw[0]
    end

Also aliased as: def_head_option
define_tail(*opts, &block) click to toggle source

    # File lib/optparse.rb, line 1493
    def define_tail(*opts, &block)
      base.append(*(sw = make_switch(opts, block)))
      sw[0]
    end

Also aliased as: def_tail_option
environment(env = File.basename($0, '.*')) click to toggle source

Parses environment variable `env` or its uppercase with splitting like a shell.

`env` defaults to the basename of the program.

    # File lib/optparse.rb, line 1800
    def environment(env = File.basename($0, '.*'))
      env = ENV[env] || ENV[env.upcase] or return
      require 'shellwords'
      parse(*Shellwords.shellwords(env))
    end

getopts(*args) click to toggle source

Wrapper method for getopts.rb.

    params = ARGV.getopts("ab:", "foo", "bar:", "zot:Z;zot option")
    # params["a"] = true   # -a
    # params["b"] = "1"    # -b1
    # params["foo"] = "1"  # --foo
    # params["bar"] = "x"  # --bar x
    # params["zot"] = "z"  # --zot Z

    # File lib/optparse.rb, line 1661
    def getopts(*args)
      argv = Array === args.first ? args.shift : default_argv
      single_options, *long_options = *args

      result = {}

      single_options.scan(/(.)(:)?/) do |opt, val|
        if val
          result[opt] = nil
          define("-#{opt} VAL")
        else
          result[opt] = false
          define("-#{opt}")
        end
      end if single_options

      long_options.each do |arg|
        arg, desc = arg.split(';', 2)
        opt, val = arg.split(':', 2)
        if val
          result[opt] = val.empty? ? nil : val
          define("--#{opt}=#{result[opt] || "VAL"}", *[desc].compact)
        else
          result[opt] = false
          define("--#{opt}", *[desc].compact)
        end
      end

      parse_in_order(argv, result.method(:[]=))
      result
    end

help() click to toggle source

Returns option summary string.

    # File lib/optparse.rb, line 1247
    def help; summarize("#{banner}".sub(/\n?\z/, "\n")) end

Also aliased as: to_s
inc(*args) click to toggle source

    # File lib/optparse.rb, line 1042
    def inc(*args)
      self.class.inc(*args)
    end

load(filename = nil) click to toggle source

Loads options from file names as `filename`. Does nothing when the file is not present. Returns whether successfully loaded.

`filename` defaults to basename of the program without suffix in a directory ~/.options.

    # File lib/optparse.rb, line 1780
    def load(filename = nil)
      begin
        filename ||= File.expand_path(File.basename($0, '.*'), '~/.options')
      rescue
        return false
      end
      begin
        parse(*IO.readlines(filename).each {|s| s.chomp!})
        true
      rescue Errno::ENOENT, Errno::ENOTDIR
        false
      end
    end

make_switch(opts, block = nil) click to toggle source

Creates an OptionParser::Switch from the parameters. The parsed argument value is passed to the given block, where it can be processed.

See at the beginning of OptionParser for some full examples.

`opts` can include the following elements:

Argument style:

  One of the following:

      :NONE, :REQUIRED, :OPTIONAL

Argument pattern:

  Acceptable option argument format, must be pre-defined with #accept or #accept, or Regexp. This can appear once or assigned as String if not present, otherwise causes an ArgumentError. Examples:

      Float, Time, Array

Possible argument values:

  Hash or Array.

      [:text, :binary, :auto]
      %w[iso-2022-jp shift_jis euc-jp utf8 binary]
      { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }

Long style switch:

  Specifies a long style switch which takes a mandatory, optional or no argument. It's a string of the following form:

      "--switch=MANDATORY" or "--switch MANDATORY"
      "--switch[=OPTIONAL]"
      "--switch"

Short style switch:

  Specifies short style switch which takes a mandatory, optional or no argument. It's a string of the following form:

      "-xMANDATORY"
      "-x[OPTIONAL]"
      "-x"

  There is also a special form which matches character range (not full set of regular expression):

      "-[a-z]MANDATORY"
      "-[a-z][OPTIONAL]"
      "-[a-z]"

Argument style and description:

  Instead of specifying mandatory or optional arguments directly in the switch parameter, this separate parameter can be used.

      "=MANDATORY"
      "=[OPTIONAL]"

Description:

  Description string for the option.

      "Run verbosely"

Handler:

  Handler for the parsed argument value. Either give a block or pass a Proc or Method as an argument.

    # File lib/optparse.rb, line 1331
    def make_switch(opts, block = nil)
      short, long, nolong, style, pattern, conv, not_pattern, not_conv, not_style = [], [], []
      ldesc, sdesc, desc, arg = [], [], []
      default_style = Switch::NoArgument
      default_pattern = nil
      klass = nil
      q, a = nil
      has_arg = false

      opts.each do |o|
        # argument class
        next if search(:atype, o) do |pat, c|
          klass = notwice(o, klass, 'type')
          if not_style and not_style != Switch::NoArgument
            not_pattern, not_conv = pat, c
          else
            default_pattern, conv = pat, c
          end
        end

        # directly specified pattern(any object possible to match)
        if (!(String === o || Symbol === o)) and o.respond_to?(:match)
          pattern = notwice(o, pattern, 'pattern')
          if pattern.respond_to?(:convert)
            conv = pattern.method(:convert).to_proc
          else
            conv = SPLAT_PROC
          end
          next
        end

        # anything others
        case o
        when Proc, Method
          block = notwice(o, block, 'block')
        when Array, Hash
          case pattern
          when CompletingHash
          when nil
            pattern = CompletingHash.new
            conv = pattern.method(:convert).to_proc if pattern.respond_to?(:convert)
          else
            raise ArgumentError, "argument pattern given twice"
          end
          o.each {|pat, *v| pattern[pat] = v.fetch(0) {pat}}
        when Module
          raise ArgumentError, "unsupported argument type: #{o}", ParseError.filter_backtrace(caller(4))
        when *ArgumentStyle.keys
          style = notwice(ArgumentStyle[o], style, 'style')
        when /^--no-([^\[\]=\s]*)(.+)?/
          q, a = $1, $2
          o = notwice(a ? Object : TrueClass, klass, 'type')
          not_pattern, not_conv = search(:atype, o) unless not_style
          not_style = (not_style || default_style).guess(arg = a) if a
          default_style = Switch::NoArgument
          default_pattern, conv = search(:atype, FalseClass) unless default_pattern
          ldesc << "--no-#{q}"
          (q = q.downcase).tr!('_', '-')
          long << "no-#{q}"
          nolong << q
        when /^--\[no-\]([^\[\]=\s]*)(.+)?/
          q, a = $1, $2
          o = notwice(a ? Object : TrueClass, klass, 'type')
          if a
            default_style = default_style.guess(arg = a)
            default_pattern, conv = search(:atype, o) unless default_pattern
          end
          ldesc << "--[no-]#{q}"
          (o = q.downcase).tr!('_', '-')
          long << o
          not_pattern, not_conv = search(:atype, FalseClass) unless not_style
          not_style = Switch::NoArgument
          nolong << "no-#{o}"
        when /^--([^\[\]=\s]*)(.+)?/
          q, a = $1, $2
          if a
            o = notwice(NilClass, klass, 'type')
            default_style = default_style.guess(arg = a)
            default_pattern, conv = search(:atype, o) unless default_pattern
          end
          ldesc << "--#{q}"
          (o = q.downcase).tr!('_', '-')
          long << o
        when /^-(\[\^?\]?(?:[^\\\]]|\\.)*\])(.+)?/
          q, a = $1, $2
          o = notwice(Object, klass, 'type')
          if a
            default_style = default_style.guess(arg = a)
            default_pattern, conv = search(:atype, o) unless default_pattern
          else
            has_arg = true
          end
          sdesc << "-#{q}"
          short << Regexp.new(q)
        when /^-(.)(.+)?/
          q, a = $1, $2
          if a
            o = notwice(NilClass, klass, 'type')
            default_style = default_style.guess(arg = a)
            default_pattern, conv = search(:atype, o) unless default_pattern
          end
          sdesc << "-#{q}"
          short << q
        when /^=/
          style = notwice(default_style.guess(arg = o), style, 'style')
          default_pattern, conv = search(:atype, Object) unless default_pattern
        else
          desc.push(o)
        end
      end

      default_pattern, conv = search(:atype, default_style.pattern) unless default_pattern
      if !(short.empty? and long.empty?)
        if has_arg and default_style == Switch::NoArgument
          default_style = Switch::RequiredArgument
        end
        s = (style || default_style).new(pattern || default_pattern,
                                         conv, sdesc, ldesc, arg, desc, block)
      elsif !block
        if style or pattern
          raise ArgumentError, "no switch given", ParseError.filter_backtrace(caller)
        end
        s = desc
      else
        short << pattern
        s = (style || default_style).new(pattern,
                                         conv, nil, nil, arg, desc, block)
      end
      return s, short, long,
        (not_style.new(not_pattern, not_conv, sdesc, ldesc, nil, desc, block) if not_style),
        nolong
    end

new() { |self| ... } click to toggle source

Pushes a new List.

    # File lib/optparse.rb, line 1213
    def new
      @stack.push(List.new)
      if block_given?
        yield self
      else
        self
      end
    end

on(*opts, &block) click to toggle source

Add option switch and handler. See make_switch for an explanation of parameters.

    # File lib/optparse.rb, line 1473
    def on(*opts, &block)
      define(*opts, &block)
      self
    end

on_head(*opts, &block) click to toggle source

Add option switch like with on, but at head of summary.

    # File lib/optparse.rb, line 1487
    def on_head(*opts, &block)
      define_head(*opts, &block)
      self
    end

on_tail(*opts, &block) click to toggle source

Add option switch like with on, but at tail of summary.

    # File lib/optparse.rb, line 1501
    def on_tail(*opts, &block)
      define_tail(*opts, &block)
      self
    end

order(*argv, into: nil, &nonopt) click to toggle source

Parses command line arguments `argv` in order. When a block is given, each non-option argument is yielded.

Returns the rest of `argv` left unparsed.

    # File lib/optparse.rb, line 1520
    def order(*argv, into: nil, &nonopt)
      argv = argv[0].dup if argv.size == 1 and Array === argv[0]
      order!(argv, into: into, &nonopt)
    end

order!(argv = default_argv, into: nil, &nonopt) click to toggle source

Same as order, but removes switches destructively. Non-option arguments remain in `argv`.

    # File lib/optparse.rb, line 1529
    def order!(argv = default_argv, into: nil, &nonopt)
      setter = ->(name, val) {into[name.to_sym] = val} if into
      parse_in_order(argv, setter, &nonopt)
    end

parse(*argv, into: nil) click to toggle source

Parses command line arguments `argv` in order when environment variable POSIXLY_CORRECT is set, and in permutation mode otherwise.

    # File lib/optparse.rb, line 1634
    def parse(*argv, into: nil)
      argv = argv[0].dup if argv.size == 1 and Array === argv[0]
      parse!(argv, into: into)
    end

parse!(argv = default_argv, into: nil) click to toggle source

Same as parse, but removes switches destructively. Non-option arguments remain in `argv`.

    # File lib/optparse.rb, line 1643
    def parse!(argv = default_argv, into: nil)
      if ENV.include?('POSIXLY_CORRECT')
        order!(argv, into: into)
      else
        permute!(argv, into: into)
      end
    end

permute(*argv, into: nil) click to toggle source

Parses command line arguments `argv` in permutation mode and returns list of non-option arguments.

    # File lib/optparse.rb, line 1614
    def permute(*argv, into: nil)
      argv = argv[0].dup if argv.size == 1 and Array === argv[0]
      permute!(argv, into: into)
    end

permute!(argv = default_argv, into: nil) click to toggle source

Same as permute, but removes switches destructively. Non-option arguments remain in `argv`.

    # File lib/optparse.rb, line 1623
    def permute!(argv = default_argv, into: nil)
      nonopts = []
      order!(argv, into: into, &nonopts.method(:<<))
      argv[0, 0] = nonopts
      argv
    end

program_name() click to toggle source

Program name to be emitted in error message and default banner, defaults to $0.

    # File lib/optparse.rb, line 1148
    def program_name
      @program_name || File.basename($0, '.*')
    end

reject(*args, &blk) click to toggle source

Directs to reject specified class argument.

`t`

  Argument class specifier, any object including Class.

    reject(t)

    # File lib/optparse.rb, line 1107
    def reject(*args, &blk) top.reject(*args, &blk) end

release() click to toggle source

Release code

    # File lib/optparse.rb, line 1173
    def release
      @release || (defined?(::Release) && ::Release) || (defined?(::RELEASE) && ::RELEASE)
    end

remove() click to toggle source

Removes the last List.

    # File lib/optparse.rb, line 1225
    def remove
      @stack.pop
    end

separator(string) click to toggle source

Add separator in summary.

    # File lib/optparse.rb, line 1510
    def separator(string)
      top.append(string, nil, nil)
    end

summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk) click to toggle source

Puts option summary into `to` and returns `to`. Yields each line if a block is given.

`to`

  Output destination, which must have method <<. Defaults to [].

`width`

  Width of left side, defaults to @summary_width.

`max`

  Maximum length allowed for left side, defaults to `width` - 1.

`indent`

  Indentation, defaults to @summary_indent.

    # File lib/optparse.rb, line 1238
    def summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk)
      blk ||= proc {|l| to << (l.index($/, -1) ? l : l + $/)}
      visit(:summarize, {}, {}, width, max, indent, &blk)
      to
    end

terminate(arg = nil) click to toggle source

Terminates option parsing. Optional parameter `arg` is a string pushed back to be the first non-option argument.

    # File lib/optparse.rb, line 1075
    def terminate(arg = nil)
      self.class.terminate(arg)
    end

to_a() click to toggle source

Returns option summary list.

    # File lib/optparse.rb, line 1253
    def to_a; summarize("#{banner}".split(/^/)) end

to_s()
Alias for: help
top() click to toggle source

Subject of on / on_head, accept / reject

    # File lib/optparse.rb, line 1199
    def top
      @stack[-1]
    end

ver() click to toggle source

Returns version string from #program_name, version and release.

    # File lib/optparse.rb, line 1180
    def ver
      if v = version
        str = "#{program_name} #{[v].join('.')}"
        str << " (#{v})" if v = release
        str
      end
    end

version() click to toggle source

Version

    # File lib/optparse.rb, line 1166
    def version
      @version || (defined?(::Version) && ::Version)
    end

warn(mesg = $!) click to toggle source
Calls superclass method Kernel#warn

    # File lib/optparse.rb, line 1188
    def warn(mesg = $!)
      super("#{program_name}: #{mesg}")
    end

### Private Instance Methods

complete(typ, opt, icase = false, *pat) click to toggle source

Completes shortened long style option switch and returns pair of canonical switch and switch descriptor OptionParser::Switch.

`typ`

  Searching table.

`opt`

  Searching key.

`icase`

  Search case insensitive if true.

`pat`

  Optional pattern for completion.

    # File lib/optparse.rb, line 1732
    def complete(typ, opt, icase = false, *pat)
      if pat.empty?
        search(typ, opt) {|sw| return [sw, opt]} # exact match or...
      end
      raise AmbiguousOption, catch(:ambiguous) {
        visit(:complete, typ, opt, icase, *pat) {|o, *sw| return sw}
        raise InvalidOption, opt
      }
    end

notwice(obj, prv, msg) click to toggle source

Checks if an argument is given twice, in which case an ArgumentError is raised. Called from OptionParser#switch only.

`obj`

  New argument.

`prv`

  Previously specified argument.

`msg`

  Exception message.

    # File lib/optparse.rb, line 1263
    def notwice(obj, prv, msg)
      unless !prv or prv == obj
        raise(ArgumentError, "argument #{msg} given twice: #{obj}",
              ParseError.filter_backtrace(caller(2)))
      end
      obj
    end

search(id, key) { |k| ... } click to toggle source

Searches `key` in @stack for `id` hash and returns or yields the result.

    # File lib/optparse.rb, line 1715
    def search(id, key)
      block_given = block_given?
      visit(:search, id, key) do |k|
        return block_given ? yield(k) : k
      end
    end

visit(id, *args, &block) click to toggle source

Traverses @stack, sending each element method `id` with `args` and `block`.

    # File lib/optparse.rb, line 1704
    def visit(id, *args, &block)
      @stack.reverse_each do |el|
        el.send(id, *args, &block)
      end
      nil
    end