class OptionParser - optparse: Ruby Standard Library Documentation

# 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

### 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) click to toggle source

See `accept`.

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

getopts(*args, symbolize_names: false) click to toggle source

See `getopts`.

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

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

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

    # File optparse.rb, line 1155
    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 optparse.rb, line 1178
    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

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

See `reject`.

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

show_version(*pkgs) click to toggle source

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

`pkgs`

  package list

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

terminate(arg = nil) click to toggle source

See `terminate`.

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

top() click to toggle source

Returns the global top option list.

Do not use directly.

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

### Public Instance Methods

abort(mesg = $!) click to toggle source

Shows message with the program name then aborts.

`mesg`

  Message, defaulted to +$!+.

See Kernel#abort.

Calls superclass method

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

additional_message(typ, opt) click to toggle source

Returns additional info.

    # File optparse.rb, line 1964
    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

banner() click to toggle source

Heading banner preceding summary.

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

candidate(word) click to toggle source

Return candidates for `word`.

    # File optparse.rb, line 1978
    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(*params, &block) click to toggle source

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.

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

Also aliased as: def_option
define_by_keywords(options, method, **params) click to toggle source

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.

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

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

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.

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

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

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.

    # File optparse.rb, line 1650
    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, '.*'), **keywords) 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 2051
    def environment(env = File.basename($0, '.*'), **keywords)
      env = ENV[env] || ENV[env.upcase] or return
      require 'shellwords'
      parse(*Shellwords.shellwords(env), **keywords)
    end

getopts(*args, symbolize_names: false, **keywords) 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

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

    # File optparse.rb, line 1878
    def getopts(*args, symbolize_names: false, **keywords)
      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(:[]=), **keywords)
      symbolize_names ? result.transform_keys(&:to_sym) : result
    end

help() click to toggle source

Returns option summary string.

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

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

See self.inc

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

load(filename = nil, **keywords) 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, 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`.

    # File optparse.rb, line 2019
    def load(filename = nil, **keywords)
      unless filename
        basename = File.basename($0, '.*')
        return true if load(File.expand_path(basename, '~/.options'), **keywords) rescue nil
        basename << ".options"
        return [
          # XDG
          ENV['XDG_CONFIG_HOME'],
          '~/.config',
          *ENV['XDG_CONFIG_DIRS']&.split(File::PATH_SEPARATOR),

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

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

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.

    # File optparse.rb, line 1462
    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) if o && !o.empty?
        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`.

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

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

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

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.

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

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

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.

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

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

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.

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

order(*argv, **keywords, &nonopt) click to toggle source

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.

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

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

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

    # File optparse.rb, line 1701
    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

parse(*argv, **keywords) click to toggle source

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

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

parse!(argv = default_argv, **keywords) click to toggle source

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

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

permute(*argv, **keywords) click to toggle source

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

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

permute!(argv = default_argv, **keywords) click to toggle source

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

    # File optparse.rb, line 1828
    def permute!(argv = default_argv, **keywords)
      nonopts = []
      order!(argv, **keywords, &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 1290
    def program_name
      @program_name || File.basename($0, '.*')
    end

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

Directs to reject specified class argument.

`type`

  Argument class specifier, any object including Class.

    reject(type)

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

release() click to toggle source

Release code

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

remove() click to toggle source

Removes the last `List`.

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

separator(string) click to toggle source

Add separator in summary.

    # File optparse.rb, line 1672
    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 1397
    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

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 1202
    def terminate(arg = nil)
      self.class.terminate(arg)
    end

to_a() click to toggle source

Returns option summary list.

    # File optparse.rb, line 1436
    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 optparse.rb, line 1355
    def top
      @stack[-1]
    end

ver() click to toggle source

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

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

warn(mesg = $!) click to toggle source

Shows warning message with the program name

`mesg`

  Message, defaulted to +$!+.

See Kernel#warn.

Calls superclass method

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