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

- `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 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

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

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

    # File lib/optparse/version.rb, line 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 lib/optparse.rb, line 1813
    def self.getopts(*args)
      new.getopts(*args)
    end

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

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

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

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

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

`banner`

  Banner message.

`width`

  Summary width.

`indent`

  Summary indent.

    # File lib/optparse.rb, line 1143
    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 lib/optparse.rb, line 1203
    def self.reject(*args, &blk) top.reject(*args, &blk) end

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

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

top() click to toggle source

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

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

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

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

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

### Public Instance Methods

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

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

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

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

`t`

  Argument class specifier, any object including `Class`.

`pat`

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

    accept(t, pat, &block)

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

additional_message(typ, opt) click to toggle source

Returns additional info.

    # File lib/optparse.rb, line 1864
    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 lib/optparse.rb, line 1235
    def banner
      unless @banner
        @banner = +"Usage: #{program_name} [options]"
        visit(:add_banner, @banner)
      end
      @banner
    end

base() click to toggle source

Subject of `on_tail`.

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

candidate(word) click to toggle source

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

    # File lib/optparse/kwargs.rb, line 10
    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(*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 lib/optparse.rb, line 1561
    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 lib/optparse.rb, line 1584
    def define_tail(*opts, &block)
      base.append(*(sw = make_switch(opts, block)))
      sw[0]
    end

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

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

`env` defaults to the basename of the program.

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

getopts(*args) click to toggle source

Wrapper method for getopts.rb.

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

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

      result = {}

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

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

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

help() click to toggle source

Returns option summary string.

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

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

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

load(filename = nil, into: 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, 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 lib/optparse.rb, line 1916
    def load(filename = nil, into: nil)
      unless filename
        basename = File.basename($0, '.*')
        return true if load(File.expand_path(basename, '~/.options'), into: into) 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), into: into) rescue nil
        }
      end
      begin
        parse(*File.readlines(filename, chomp: true), into: into)
        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 lib/optparse.rb, line 1402
    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`.

    # File lib/optparse.rb, line 1312
    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 lib/optparse.rb, line 1550
    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 lib/optparse.rb, line 1573
    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 lib/optparse.rb, line 1597
    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. 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 lib/optparse.rb, line 1619
    def order(*argv, into: nil, &nonopt)
      argv = argv[0].dup if argv.size == 1 and Array === argv[0]
      order!(argv, into: into, &nonopt)
    end

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

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

    # File lib/optparse.rb, line 1628
    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. 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 lib/optparse.rb, line 1751
    def parse(*argv, into: nil)
      argv = argv[0].dup if argv.size == 1 and Array === argv[0]
      parse!(argv, into: into)
    end

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

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

    # File lib/optparse.rb, line 1760
    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. 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 lib/optparse.rb, line 1728
    def permute(*argv, into: nil)
      argv = argv[0].dup if argv.size == 1 and Array === argv[0]
      permute!(argv, into: into)
    end

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

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

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

program_name() click to toggle source

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

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

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

Directs to reject specified class argument.

`t`

  Argument class specifier, any object including `Class`.

    reject(t)

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

release() click to toggle source

Release code

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

remove() click to toggle source

Removes the last `List`.

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

separator(string) click to toggle source

Add separator in summary.

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

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

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

`to`

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

`width`

  Width of left side, defaults to @summary_width.

`max`

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

`indent`

  Indentation, defaults to @summary_indent.

    # File lib/optparse.rb, line 1337
    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 lib/optparse.rb, line 1167
    def terminate(arg = nil)
      self.class.terminate(arg)
    end

to_a() click to toggle source

Returns option summary list.

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

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

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

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

ver() click to toggle source

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

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

version() click to toggle source

`Version`

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

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

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