class OptionParser - Documentation for Ruby 4.0
Description: class OptionParser: tutorial. rdoc].
Keywords: ruby,class,OptionParser

🔍

No recent searches

# class OptionParser

## `OptionParser`

### New to `OptionParser`?

See the Tutorial.

### 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 |parser|
      parser.banner = "Usage: example.rb [options]"

      parser.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 |parser|
          parser.banner = "Usage: example.rb [options]"

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

          parser.on("-h", "--help", "Prints this help") do
            puts parser
            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:

    $ ruby optparse-test.rb -r
    optparse-test.rb:9:in '<main>': missing argument: -r (OptionParser::MissingArgument)
    $ 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` (need to require `optparse/date`)

- `DateTime` – Anything accepted by `DateTime.parse` (need to require `optparse/date`)

- `Time` – Anything accepted by `Time.httpdate` or `Time.parse` (need to require `optparse/time`)

- `URI` – Anything accepted by `URI.parse` (need to require `optparse/uri`)

- `Shellwords` – Anything accepted by `Shellwords.shellwords` (need to require `optparse/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 below.

#### 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:

    $ ruby optparse-test.rb  -t nonsense
    ... invalid argument: -t nonsense (OptionParser::InvalidArgument)
    $ ruby optparse-test.rb  -t 10-11-12
    2010-11-12 00:00:00 -0500
    $ 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!

Used:

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

### Store options to a `Hash`

The `into` option of `order`, `parse` and so on methods stores command line options into a `Hash`.

    require 'optparse'

    options = {}
    OptionParser.new do |parser|
      parser.on('-a')
      parser.on('-b NUM', Integer)
      parser.on('-v', '--verbose')
    end.parse!(into: options)

    p options

Used:

    $ ruby optparse-test.rb -a
    {:a=>true}
    $ ruby optparse-test.rb -a -v
    {:a=>true, :verbose=>true}
    $ ruby optparse-test.rb -a -b 100
    {:a=>true, :b=>100}

### 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, along with the accompanying Tutorial, 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`.

VERSION

  The version string

Version

  An alias for compatibility

### 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.

raise_unknown [RW]

Whether to raise at unknown option.

release [W]

Release code

require_exact [RW]

Whether to require that options match exactly (disallows providing abbreviated long option as short option).

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)
Source

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

See `accept`.

getopts (*args, symbolize_names: false)
Source

    # File lib/optparse.rb, line 1939
    def self.getopts(*args, symbolize_names: false)
      new.getopts(*args, symbolize_names: symbolize_names)
    end

See `getopts`.

inc (arg, default = nil)
Source

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

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

new (banner = nil, width = 32, indent = ' ' * 4) { |self| ... }
Source

    # File lib/optparse.rb, line 1182
    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
      @require_exact = false
      @raise_unknown = true
      add_officious
      yield self if block_given?
    end

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

`banner`

  Banner message.

`width`

  Summary width.

`indent`

  Summary indent.

reject (*args, &blk)
Source

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

See `reject`.

show_version (*pkgs)
Source

    # File lib/optparse/version.rb, line 10
    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

Shows version string in packages if `Version` is defined.

`pkgs`

  package list

terminate (arg = nil)
Source

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

See `terminate`.

top ()
Source

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

Returns the global top option list.

Do not use directly.

with (*args, &block)
Source

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

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.

### Public Instance Methods

abort (mesg = $!)
Source

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

Shows message with the program name then aborts.

`mesg`

  Message, defaulted to +$!+.

See `Kernel#abort`.

Calls superclass method `Kernel#abort`
accept (*args, &blk)
Source

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

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)

additional_message (typ, opt)
Source

    # File lib/optparse.rb, line 1987
    def additional_message(typ, opt)
      return unless typ and opt and defined?(DidYouMean::SpellChecker)
      all_candidates = []
      visit(:get_candidates, typ) do |candidates|
        all_candidates.concat(candidates)
      end
      all_candidates.select! {|cand| cand.is_a?(String) }
      checker = DidYouMean::SpellChecker.new(dictionary: all_candidates)
      DidYouMean.formatter.message_for(all_candidates & checker.correct(opt))
    end

Returns additional info.

banner ()
Source

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

Heading banner preceding summary.

base ()
Source

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

Subject of `on_tail`.

candidate (word)
Source

    # File lib/optparse.rb, line 2001
    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

Return candidates for `word`.

def_head_option
Alias for: define_head
def_option
Alias for: define
def_tail_option
Alias for: define_tail
define(*params, &block)
Source

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

Creates an option from the given parameters `params`. See Parameters for New Options.

The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. See Option Handlers.

Also aliased as: def_option
define_by_keywords(options, method, **params)
Source

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

Creates an option from the given parameters `params`. See Parameters for New Options.

The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. See Option Handlers.

Defines options which set in to options for keyword parameters of method.

Parameters for each keywords are given as elements of params.

define_head(*params, &block)
Source

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

Creates an option from the given parameters `params`. See Parameters for New Options.

The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. See Option Handlers.

Also aliased as: def_head_option
define_tail(*params, &block)
Source

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

Creates an option from the given parameters `params`. See Parameters for New Options.

The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. See Option Handlers.

Also aliased as: def_tail_option
environment (env = File.basename($0, '.*'), **keywords)
Source

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

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

`env` defaults to the basename of the program.

getopts (*args, symbolize_names: false, **keywords)
Source

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

      result = {}
      setter = (symbolize_names ?
                  ->(name, val) {result[name.to_sym] = val}
                : ->(name, val) {result[name] = val})

      single_options.scan(/(.)(:)?/) do |opt, val|
        if val
          setter[opt, nil]
          define("-#{opt} VAL")
        else
          setter[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
          setter[opt, (val unless val.empty?)]
          define("--#{opt}=#{result[opt] || "VAL"}", *[desc].compact)
        else
          setter[opt, false]
          define("--#{opt}", *[desc].compact)
        end
      end

      parse_in_order(argv, setter, **keywords)
      result
    end

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

Option `symbolize_names` (boolean) specifies whether returned `Hash` keys should be Symbols; defaults to `false` (use Strings).

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

help ()
Source

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

Returns option summary string.

Also aliased as: to_s
inc (*args)
Source

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

See self.inc

load (filename = nil, **keywords)
Source

    # File lib/optparse.rb, line 2042
    def load(filename = nil, **keywords)
      unless filename
        basename = File.basename($0, '.*')
        return true if load(File.expand_path("~/.options/#{basename}"), **keywords) rescue nil
        basename << ".options"
        if !(xdg = ENV['XDG_CONFIG_HOME']) or xdg.empty?
          # https://specifications.freedesktop.org/basedir-spec/latest/#variables
          #
          # If $XDG_CONFIG_HOME is either not set or empty, a default
          # equal to $HOME/.config should be used.
          xdg = ['~/.config', true]
        end
        return [
          xdg,

          *ENV['XDG_CONFIG_DIRS']&.split(File::PATH_SEPARATOR),

          # Haiku
          ['~/config/settings', true],
        ].any? {|dir, expand|
          next if !dir or dir.empty?
          filename = File.join(dir, basename)
          filename = File.expand_path(filename) if expand
          load(filename, **keywords) rescue nil
        }
      end
      begin
        parse(*File.readlines(filename, chomp: true), **keywords)
        true
      rescue Errno::ENOENT, Errno::ENOTDIR
        false
      end
    end

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, then the basename with ‘.options’ suffix under XDG and Haiku standard places.

The optional `into` keyword argument works exactly like that accepted in method `parse`.

make_switch(params, block = nil)
Source

    # File lib/optparse.rb, line 1473
    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
      values = nil

      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 !Completion.completable?(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, Set
          if Array === o
            o, v = o.partition {|v,| Completion.completable?(v)}
            values = notwice(v, values, 'values') unless v.empty?
            next if o.empty?
          end
          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 Range
          values = notwice(o, values, 'values')
        when Module
          raise ArgumentError, "unsupported argument type: #{o}", ParseError.filter_backtrace(caller(4))
        when *ArgumentStyle.keys
          style = notwice(ArgumentStyle[o], style, 'style')
        when /\A--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 /\A--\[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 /\A--([^\[\]=\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 /\A-(\[\^?\]?(?:[^\\\]]|\\.)*\])(.+)?/
          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 /\A-(.)(.+)?/
          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 /\A=/
          style = notwice(default_style.guess(arg = o), style, 'style')
          default_pattern, conv = search(:atype, Object) unless default_pattern
        else
          desc.push(o) if o && !o.empty?
        end
      end

      default_pattern, conv = search(:atype, default_style.pattern) unless default_pattern
      if Range === values and klass
        unless (!values.begin or klass === values.begin) and
              (!values.end or klass === values.end)
          raise ArgumentError, "range does not match class"
        end
      end
      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, values)
      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, values)
      end
      return s, short, long,
        (not_style.new(not_pattern, not_conv, sdesc, ldesc, nil, desc, block) if not_style),
        nolong
    end

Creates an option from the given parameters `params`. See Parameters for New Options.

The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. See Option Handlers.

new () { |self| ... }
Source

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

Pushes a new `List`.

If a block is given, yields `self` and returns the result of the block, otherwise returns `self`.

on(*params, &block)
Source

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

Creates an option from the given parameters `params`. See Parameters for New Options.

The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. See Option Handlers.

on_head(*params, &block)
Source

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

Creates an option from the given parameters `params`. See Parameters for New Options.

The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. See Option Handlers.

The new option is added at the head of the summary.

on_tail(*params, &block)
Source

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

Creates an option from the given parameters `params`. See Parameters for New Options.

The block, if given, is the handler for the created option. When the option is encountered during command-line parsing, the block is called with the argument given for the option, if any. See Option Handlers.

The new option is added at the tail of the summary.

order (*argv, **keywords, &nonopt)
Source

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

Parses command line arguments `argv` in order. When a block is given, each non-option argument is yielded. When optional `into` keyword argument is provided, the parsed option values are stored there via `[]=` method (so it can be `Hash`, or `OpenStruct`, or other similar object).

Returns the rest of `argv` left unparsed.

order! (argv = default_argv, into: nil, **keywords, &nonopt)
Source

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

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

parse (*argv, **keywords)
Source

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

Parses command line arguments `argv` in order when environment variable POSIXLY_CORRECT is set, and in permutation mode otherwise. When optional `into` keyword argument is provided, the parsed option values are stored there via `[]=` method (so it can be `Hash`, or `OpenStruct`, or other similar object).

parse! (argv = default_argv, **keywords)
Source

    # File lib/optparse.rb, line 1874
    def parse!(argv = default_argv, **keywords)
      if ENV.include?('POSIXLY_CORRECT')
        order!(argv, **keywords)
      else
        permute!(argv, **keywords)
      end
    end

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

permute (*argv, **keywords)
Source

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

Parses command line arguments `argv` in permutation mode and returns list of non-option arguments. When optional `into` keyword argument is provided, the parsed option values are stored there via `[]=` method (so it can be `Hash`, or `OpenStruct`, or other similar object).

permute! (argv = default_argv, **keywords)
Source

    # File lib/optparse.rb, line 1851
    def permute!(argv = default_argv, **keywords)
      nonopts = []
      order!(argv, **keywords) {|nonopt| nonopts << nonopt}
      argv[0, 0] = nonopts
      argv
    end

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

program_name ()
Source

    # File lib/optparse.rb, line 1294
    def program_name
      @program_name || strip_ext(File.basename($0))
    end

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

reject (*args, &blk)
Source

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

Directs to reject specified class argument.

`type`

  Argument class specifier, any object including Class.

    reject(type)

release ()
Source

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

Release code

remove ()
Source

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

Removes the last `List`.

separator (string)
Source

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

Add separator in summary.

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

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

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.

terminate (arg = nil)
Source

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

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

to_a ()
Source

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

Returns option summary list.

to_s ()
Alias for: help
top ()
Source

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

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

ver ()
Source

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

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

version ()
Source

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

`Version`

warn (mesg = $!)
Source

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

Shows warning message with the program name

`mesg`

  Message, defaulted to +$!+.

See `Kernel#warn`.

Calls superclass method `Kernel#warn`