Class: OptionParser (Ruby 2.5.7)
Description: Class : OptionParser - Ruby 2.5.7

### Home Classes Methods

### In Files

- optparse.rb
- optparse/ac.rb
- optparse/date.rb
- optparse/kwargs.rb
- optparse/time.rb

### Parent

Object

### Namespace

- MODULE OptionParser::Acceptables
- MODULE OptionParser::Arguable
- MODULE OptionParser::Completion
- CLASS OptionParser::AC
- CLASS OptionParser::AmbiguousArgument
- CLASS OptionParser::AmbiguousOption
- CLASS OptionParser::CompletingHash
- CLASS OptionParser::InvalidArgument
- CLASS OptionParser::InvalidOption
- CLASS OptionParser::List
- CLASS OptionParser::MissingArgument
- CLASS OptionParser::NeedlessArgument
- CLASS OptionParser::OptionMap
- CLASS OptionParser::ParseError
- CLASS OptionParser::Switch

### Methods

- ::accept
- ::each_const
- ::getopts
- ::inc
- ::new
- ::reject
- ::search_const
- ::show_version
- ::terminate
- ::top
- ::with
- #abort
- #accept
- #banner
- #base
- #candidate
- #def_head_option
- #def_option
- #def_tail_option
- #define
- #define_by_keywords
- #define_head
- #define_tail
- #environment
- #getopts
- #help
- #inc
- #load
- #make_switch
- #new
- #on
- #on_head
- #on_tail
- #order
- #order!
- #parse
- #parse!
- #permute
- #permute!
- #program_name
- #reject
- #release
- #remove
- #separator
- #summarize
- #terminate
- #to_a
- #to_s
- #top
- #ver
- #version
- #warn

### Class/Module Index

Quicksearch

- Object
- OptionParser
- OptionParser::AC
- OptionParser::Acceptables
- OptionParser::AmbiguousArgument
- OptionParser::AmbiguousOption
- OptionParser::Arguable
- OptionParser::CompletingHash
- OptionParser::Completion
- OptionParser::InvalidArgument
- OptionParser::InvalidOption
- OptionParser::List
- OptionParser::MissingArgument
- OptionParser::NeedlessArgument
- OptionParser::OptionMap
- OptionParser::ParseError
- OptionParser::Switch
- OptionParser::Switch::NoArgument
- OptionParser::Switch::OptionalArgument
- OptionParser::Switch::PlacedArgument
- OptionParser::Switch::RequiredArgument

No matching classes.

# 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 optparse.rb, line 1099
    def self.accept(*args, &blk) top.accept(*args, &blk) end

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

                   # File optparse/version.rb, line 50
    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 optparse.rb, line 1697
    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 optparse.rb, line 1035
    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) 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 optparse.rb, line 1054
    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 optparse.rb, line 1112
    def self.reject(*args, &blk) top.reject(*args, &blk) end

search_const(klass, name) click to toggle source

                   # File optparse/version.rb, line 60
    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 optparse/version.rb, line 5
    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 optparse.rb, line 1079
    def self.terminate(arg = nil)
      throw :terminate, arg
    end

top() click to toggle source

                   # File optparse.rb, line 1084
    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 optparse.rb, line 1026
    def self.with(*args, &block)
      opts = new(*args)
      opts.instance_eval(&block)
      opts
    end

### Public Instance Methods

abort(mesg = $!) click to toggle source

                   # File optparse.rb, line 1193
    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 optparse.rb, line 1095
    def accept(*args, &blk) top.accept(*args, &blk) end

banner() click to toggle source

Heading banner preceding summary.

                   # File optparse.rb, line 1137
    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 optparse.rb, line 1207
    def base
      @stack[1]
    end

candidate(word) click to toggle source

                   # File optparse.rb, line 1744
    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) click to toggle source
Alias for: define_head
def_option(*opts, &block) click to toggle source
Alias for: define
def_tail_option(*opts, &block) click to toggle source
Alias for: define_tail
define(*opts, &block) click to toggle source

                   # File optparse.rb, line 1465
    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 optparse/kwargs.rb, line 5
    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 optparse.rb, line 1480
    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 optparse.rb, line 1494
    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 optparse.rb, line 1801
    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 optparse.rb, line 1662
    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 optparse.rb, line 1248
    def help; summarize("#{banner}".sub(/\n?\z/, "\n")) end

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

                   # File optparse.rb, line 1043
    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 optparse.rb, line 1781
    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 `OptionParser.accept` or `OptionParser#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 optparse.rb, line 1332
    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() click to toggle source

Pushes a new `List`.

                   # File optparse.rb, line 1214
    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 optparse.rb, line 1474
    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 optparse.rb, line 1488
    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 optparse.rb, line 1502
    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 optparse.rb, line 1521
    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 optparse.rb, line 1530
    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 optparse.rb, line 1635
    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 optparse.rb, line 1644
    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 optparse.rb, line 1615
    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 optparse.rb, line 1624
    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 optparse.rb, line 1149
    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 optparse.rb, line 1108
    def reject(*args, &blk) top.reject(*args, &blk) end

release() click to toggle source

Release code

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

remove() click to toggle source

Removes the last `List`.

                   # File optparse.rb, line 1226
    def remove
      @stack.pop
    end

separator(string) click to toggle source

Add separator in summary.

                   # File optparse.rb, line 1511
    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 optparse.rb, line 1239
    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 optparse.rb, line 1076
    def terminate(arg = nil)
      self.class.terminate(arg)
    end

to_a() click to toggle source

Returns option summary list.

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

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

Subject of `on` / `on_head`, `accept` / `reject`

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

ver() click to toggle source

Returns version string from `program_name`, version and release.

                   # File optparse.rb, line 1181
    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 optparse.rb, line 1167
    def version
      @version || (defined?(::Version) && ::Version)
    end

warn(mesg = $!) click to toggle source

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