Class: Object (Ruby 2.2.4)
Description: Class : Object - Ruby 2.2.4

- Home
- Core 2.2.4
- Std-lib 2.2.4
- Downloads

Support for the Ruby 2.2 series has ended. See here for reference.

### Home Classes Methods

### In Files

- optparse.rb

### Parent

BasicObject

### Class/Module Index

Quicksearch

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

No matching classes.

# Object

### Constants

OptParse

  ## OptionParser¶ ↑

  ### Introduction¶ ↑

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

  ### Features¶ ↑

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

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

  3. Optional and mandatory arguments are specified very gracefully.

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

  5. Arguments can be restricted to a certain set.

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

  ### Minimal example¶ ↑

      require 'optparse'

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

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

      p options
      p ARGV

  ### Generating Help¶ ↑

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

      require 'optparse'

      Options = Struct.new(:name)

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

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

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

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

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

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

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

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

        #
        # Return a structure describing the options.
        #
        def self.parse(args)
          # The options specified on the command line will be collected in *options*.
          # We set default values here.
          options = OpenStruct.new
          options.library = []
          options.inplace = false
          options.encoding = "utf8"
          options.transfer_type = :auto
          options.verbose = false

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

            opts.separator ""
            opts.separator "Specific options:"

            # Mandatory argument.
            opts.on("-r", "--require LIBRARY",
                    "Require the LIBRARY before executing your script") do |lib|
              options.library << lib
            end

            # Optional argument; multi-line description.
            opts.on("-i", "--inplace [EXTENSION]",
                    "Edit ARGV files in place",
                    "  (make backup if EXTENSION supplied)") do |ext|
              options.inplace = true
              options.extension = ext || ''
              options.extension.sub!(/\A\.?(?=.)/, ".")  # Ensure extension begins with dot.
            end

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

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

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

            # List of arguments.
            opts.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
              options.list = list
            end

            # 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(',')
            opts.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
                    "  (#{code_list})") do |encoding|
              options.encoding = encoding
            end

            # Optional argument with keyword completion.
            opts.on("--type [TYPE]", [:text, :binary, :auto],
                    "Select transfer type (text, binary, auto)") do |t|
              options.transfer_type = t
            end

            # Boolean switch.
            opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
              options.verbose = v
            end

            opts.separator ""
            opts.separator "Common options:"

            # No argument, shows at tail.  This will print an options summary.
            # Try it and see!
            opts.on_tail("-h", "--help", "Show this message") do
              puts opts
              exit
            end

            # Another typical switch to print the version.
            opts.on_tail("--version", "Show version") do
              puts ::Version.join('.')
              exit
            end
          end

          opt_parser.parse!(args)
          options
        end  # parse()

      end  # class OptparseExample

      options = OptparseExample.parse(ARGV)
      pp options
      pp ARGV

  ### Shell Completion¶ ↑

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

  ### Further documentation¶ ↑

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