1#@!#!123s

: / proc / self / root / opt / alt / ruby34 / share / ri / system / OptionParser /
Filename : cdesc-OptionParser.ri
back
U:RDoc::NormalClass[iI"OptionParser:ET@I"Object;To:RDoc::Markup::Document:@parts[o;;[QS:RDoc::Markup::Heading:
leveli:	textI"OptionParser;To:RDoc::Markup::BlankLine�S;	;
i;I"New to +OptionParser+?;T@o:RDoc::Markup::Paragraph;[I"0See the {Tutorial}[optparse/tutorial.rdoc].;T@S;	;
i;I"Introduction;T@o;
;[I"POptionParser is a class for command-line option analysis.  It is much more ;TI"Tadvanced, yet also easier to use, than GetoptLong, and is a more Ruby-oriented ;TI"solution.;T@S;	;
i;I"
Features;T@o:RDoc::Markup::List:
@type:NUMBER:@items[
o:RDoc::Markup::ListItem:@label0;[o;
;[I"MThe argument specification and the code to handle it are written in the ;TI"same place.;To;;0;[o;
;[I"MIt can output an option summary; you don't need to maintain this string ;TI"separately.;To;;0;[o;
;[I"DOptional and mandatory arguments are specified very gracefully.;To;;0;[o;
;[I"CArguments can be automatically converted to a specified class.;To;;0;[o;
;[I"2Arguments can be restricted to a certain set.;T@o;
;[I"HAll of these features are demonstrated in the examples below.  See ;TI")#make_switch for full documentation.;T@S;	;
i;I"Minimal example;T@o:RDoc::Markup::Verbatim;[I"require 'optparse'
;TI"
;TI"options = {}
;TI""OptionParser.new do |parser|
;TI"5  parser.banner = "Usage: example.rb [options]"
;TI"
;TI"A  parser.on("-v", "--[no-]verbose", "Run verbosely") do |v|
;TI"    options[:verbose] = v
;TI"  end
;TI"end.parse!
;TI"
;TI"p options
;TI"p ARGV
;T:@format0S;	;
i;I"Generating Help;T@o;
;[I"ROptionParser can be used to automatically generate help for the commands you ;TI"write:;T@o;;[$I"require 'optparse'
;TI"
;TI"!Options = Struct.new(:name)
;TI"
;TI"class Parser
;TI"  def self.parse(options)
;TI"%    args = Options.new("world")
;TI"
;TI"3    opt_parser = OptionParser.new do |parser|
;TI"9      parser.banner = "Usage: example.rb [options]"
;TI"
;TI"M      parser.on("-nNAME", "--name=NAME", "Name to say hello to") do |n|
;TI"        args.name = n
;TI"      end
;TI"
;TI"<      parser.on("-h", "--help", "Prints this help") do
;TI"        puts parser
;TI"        exit
;TI"      end
;TI"
    end
;TI"
;TI"$    opt_parser.parse!(options)
;TI"    return args
;TI"  end
;TI"	end
;TI"'options = Parser.parse %w[--help]
;TI"
;TI"	#=>
;TI"&   # Usage: example.rb [options]
;TI"D   #     -n, --name=NAME                  Name to say hello to
;TI"@   #     -h, --help                       Prints this help
;T;0S;	;
i;I"Required Arguments;T@o;
;[I"WFor options that require an argument, option specification strings may include an ;TI"Roption name in all caps. If an option is used without the required argument, ;TI"!an exception will be raised.;T@o;;[I"require 'optparse'
;TI"
;TI"options = {}
;TI""OptionParser.new do |parser|
;TI",  parser.on("-r", "--require LIBRARY",
;TI"N            "Require the LIBRARY before executing your script") do |lib|
;TI"%    puts "You required #{lib}!"
;TI"  end
;TI"end.parse!
;T;0o;
;[I"
Used:;T@o;;[	I" $ ruby optparse-test.rb -r
;TI"Zoptparse-test.rb:9:in `<main>': missing argument: -r (OptionParser::MissingArgument)
;TI"+$ ruby optparse-test.rb -r my-library
;TI"You required my-library!
;T;0S;	;
i;I"Type Coercion;T@o;
;[I"HOptionParser supports the ability to coerce command line arguments ;TI"into objects for us.;T@o;
;[I">OptionParser comes with a few ready-to-use kinds of type ;TI"coercion. They are:;T@o;;:BULLET;[o;;0;[o;
;[I"QDate  -- Anything accepted by +Date.parse+ (need to require +optparse/date+);To;;0;[o;
;[I"XDateTime -- Anything accepted by +DateTime.parse+ (need to require +optparse/date+);To;;0;[o;
;[I"cTime -- Anything accepted by +Time.httpdate+ or +Time.parse+ (need to require +optparse/time+);To;;0;[o;
;[I"NURI  -- Anything accepted by +URI.parse+ (need to require +optparse/uri+);To;;0;[o;
;[I"gShellwords -- Anything accepted by +Shellwords.shellwords+ (need to require +optparse/shellwords+);To;;0;[o;
;[I"#String -- Any non-empty string;To;;0;[o;
;[I"DInteger -- Any integer. Will convert octal. (e.g. 124, -3, 040);To;;0;[o;
;[I"2Float -- Any float. (e.g. 10, 3.14, -100E+13);To;;0;[o;
;[I"=Numeric -- Any integer, float, or rational (1, 3.4, 1/3);To;;0;[o;
;[I";DecimalInteger -- Like +Integer+, but no octal format.;To;;0;[o;
;[I";OctalInteger -- Like +Integer+, but no decimal format.;To;;0;[o;
;[I"0DecimalNumeric -- Decimal integer or float.;To;;0;[o;
;[I"<TrueClass --  Accepts '+, yes, true, -, no, false' and ;TI"defaults as +true+;To;;0;[o;
;[I"?FalseClass -- Same as +TrueClass+, but defaults to +false+;To;;0;[o;
;[I"3Array -- Strings separated by ',' (e.g. 1,2,3);To;;0;[o;
;[I":Regexp -- Regular expressions. Also includes options.;T@o;
;[I"BWe can also add our own coercions, which we will cover below.;T@S;	;
i	;I"Using Built-in Conversions;T@o;
;[
I"OAs an example, the built-in +Time+ conversion is used. The other built-in ;TI")conversions behave in the same way. ;TI"5OptionParser will attempt to parse the argument ;TI"Bas a +Time+. If it succeeds, that time will be passed to the ;TI";handler block. Otherwise, an exception will be raised.;T@o;;[I"require 'optparse'
;TI"require 'optparse/time'
;TI""OptionParser.new do |parser|
;TI"Y  parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
;TI"    p time
;TI"  end
;TI"end.parse!
;T;0o;
;[I"
Used:;T@o;;[I"*$ ruby optparse-test.rb  -t nonsense
;TI"G... invalid argument: -t nonsense (OptionParser::InvalidArgument)
;TI"*$ ruby optparse-test.rb  -t 10-11-12
;TI"2010-11-12 00:00:00 -0500
;TI"&$ ruby optparse-test.rb  -t 9:30
;TI"2014-08-13 09:30:00 -0400
;T;0S;	;
i	;I" Creating Custom Conversions;T@o;
;[I"KThe +accept+ method on OptionParser may be used to create converters. ;TI"PIt specifies which conversion block to call whenever a class is specified. ;TI"\The example below uses it to fetch a +User+ object before the +on+ handler receives it.;T@o;;[I"require 'optparse'
;TI"
;TI"#User = Struct.new(:id, :name)
;TI"
;TI"def find_user id
;TI"<  not_found = ->{ raise "No User Found for id #{id}" }
;TI"  [ User.new(1, "Sam"),
;TI"9    User.new(2, "Gandalf") ].find(not_found) do |u|
;TI"    u.id == id
;TI"  end
;TI"	end
;TI"
;TI"op = OptionParser.new
;TI""op.accept(User) do |user_id|
;TI"  find_user user_id.to_i
;TI"	end
;TI"
;TI"(op.on("--user ID", User) do |user|
;TI"  puts user
;TI"	end
;TI"
;TI"op.parse!
;T;0o;
;[I"
Used:;T@o;;[I"&$ ruby optparse-test.rb --user 1
;TI"%#<struct User id=1, name="Sam">
;TI"&$ ruby optparse-test.rb --user 2
;TI")#<struct User id=2, name="Gandalf">
;TI"&$ ruby optparse-test.rb --user 3
;TI"Xoptparse-test.rb:15:in `block in find_user': No User Found for id 3 (RuntimeError)
;T;0S;	;
i;I"Store options to a Hash;T@o;
;[I"eThe +into+ option of +order+, +parse+ and so on methods stores command line options into a Hash.;T@o;;[I"require 'optparse'
;TI"
;TI"options = {}
;TI""OptionParser.new do |parser|
;TI"  parser.on('-a')
;TI"$  parser.on('-b NUM', Integer)
;TI"$  parser.on('-v', '--verbose')
;TI"end.parse!(into: options)
;TI"
;TI"p options
;T;0o;
;[I"
Used:;T@o;;[I" $ ruby optparse-test.rb -a
;TI"{:a=>true}
;TI"#$ ruby optparse-test.rb -a -v
;TI" {:a=>true, :verbose=>true}
;TI"'$ ruby optparse-test.rb -a -b 100
;TI"{:a=>true, :b=>100}
;T;0S;	;
i;I"Complete example;T@o;
;[I"SThe following example is a complete Ruby program.  You can run it and see the ;TI"Seffect of specifying various options.  This is probably the best way to learn ;TI" the features of +optparse+.;T@o;;[�I"require 'optparse'
;TI"require 'optparse/time'
;TI"require 'ostruct'
;TI"require 'pp'
;TI"
;TI"class OptparseExample
;TI"  Version = '1.0.0'
;TI"
;TI"<  CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
;TI"H  CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
;TI"
;TI"  class ScriptOptions
;TI"F    attr_accessor :library, :inplace, :encoding, :transfer_type,
;TI"O                  :verbose, :extension, :delay, :time, :record_separator,
;TI"                  :list
;TI"
;TI"    def initialize
;TI"      self.library = []
;TI"       self.inplace = false
;TI""      self.encoding = "utf8"
;TI"&      self.transfer_type = :auto
;TI"       self.verbose = false
;TI"
    end
;TI"
;TI"$    def define_options(parser)
;TI"9      parser.banner = "Usage: example.rb [options]"
;TI"      parser.separator ""
;TI"0      parser.separator "Specific options:"
;TI"
;TI"$      # add additional options
;TI"*      perform_inplace_option(parser)
;TI"*      delay_execution_option(parser)
;TI"*      execute_at_time_option(parser)
;TI"3      specify_record_separator_option(parser)
;TI"'      list_example_option(parser)
;TI"+      specify_encoding_option(parser)
;TI"K      optional_option_argument_with_keyword_completion_option(parser)
;TI"*      boolean_verbose_option(parser)
;TI"
;TI"      parser.separator ""
;TI".      parser.separator "Common options:"
;TI"N      # No argument, shows at tail.  This will print an options summary.
;TI"      # Try it and see!
;TI"B      parser.on_tail("-h", "--help", "Show this message") do
;TI"        puts parser
;TI"        exit
;TI"      end
;TI":      # Another typical switch to print the version.
;TI":      parser.on_tail("--version", "Show version") do
;TI"        puts Version
;TI"        exit
;TI"      end
;TI"
    end
;TI"
;TI",    def perform_inplace_option(parser)
;TI"3      # Specifies an optional option argument
;TI"4      parser.on("-i", "--inplace [EXTENSION]",
;TI"1                "Edit ARGV files in place",
;TI"E                "(make backup if EXTENSION supplied)") do |ext|
;TI"!        self.inplace = true
;TI"(        self.extension = ext || ''
;TI"Y        self.extension.sub!(/\A\.?(?=.)/, ".")  # Ensure extension begins with dot.
;TI"      end
;TI"
    end
;TI"
;TI",    def delay_execution_option(parser)
;TI"/      # Cast 'delay' argument to a Float.
;TI"T      parser.on("--delay N", Float, "Delay N seconds before executing") do |n|
;TI"        self.delay = n
;TI"      end
;TI"
    end
;TI"
;TI",    def execute_at_time_option(parser)
;TI"4      # Cast 'time' argument to a Time object.
;TI"]      parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
;TI"        self.time = time
;TI"      end
;TI"
    end
;TI"
;TI"5    def specify_record_separator_option(parser)
;TI"$      # Cast to octal integer.
;TI"H      parser.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,
;TI"G                "Specify record separator (default \\0)") do |rs|
;TI"(        self.record_separator = rs
;TI"      end
;TI"
    end
;TI"
;TI")    def list_example_option(parser)
;TI"       # List of arguments.
;TI"U      parser.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
;TI"        self.list = list
;TI"      end
;TI"
    end
;TI"
;TI"-    def specify_encoding_option(parser)
;TI"W      # Keyword completion.  We are specifying a specific set of arguments (CODES
;TI"W      # and CODE_ALIASES - notice the latter is a Hash), and the user may provide
;TI",      # the shortest unambiguous text.
;TI">      code_list = (CODE_ALIASES.keys + CODES).join(', ')
;TI"L      parser.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
;TI"5                "(#{code_list})") do |encoding|
;TI"&        self.encoding = encoding
;TI"      end
;TI"
    end
;TI"
;TI"M    def optional_option_argument_with_keyword_completion_option(parser)
;TI"H      # Optional '--type' option argument with keyword completion.
;TI"?      parser.on("--type [TYPE]", [:text, :binary, :auto],
;TI"I                "Select transfer type (text, binary, auto)") do |t|
;TI"$        self.transfer_type = t
;TI"      end
;TI"
    end
;TI"
;TI",    def boolean_verbose_option(parser)
;TI"      # Boolean switch.
;TI"E      parser.on("-v", "--[no-]verbose", "Run verbosely") do |v|
;TI"        self.verbose = v
;TI"      end
;TI"
    end
;TI"  end
;TI"
;TI"	  #
;TI"4  # Return a structure describing the options.
;TI"	  #
;TI"  def parse(args)
;TI"J    # The options specified on the command line will be collected in
;TI"    # *options*.
;TI"
;TI"&    @options = ScriptOptions.new
;TI".    @args = OptionParser.new do |parser|
;TI"+      @options.define_options(parser)
;TI"      parser.parse!(args)
;TI"
    end
;TI"    @options
;TI"  end
;TI"
;TI"%  attr_reader :parser, :options
;TI""end  # class OptparseExample
;TI"
;TI"#example = OptparseExample.new
;TI"#options = example.parse(ARGV)
;TI""pp options # example.options
;TI"
pp ARGV
;T;0S;	;
i;I"Shell Completion;T@o;
;[I"AFor modern shells (e.g. bash, zsh, etc.), you can use shell ;TI")completion for command line options.;T@S;	;
i;I"Further documentation;T@o;
;[	I"5The above examples, along with the accompanying ;TI"){Tutorial}[optparse/tutorial.rdoc], ;TI"6should be enough to learn how to use this class. ;TI"KIf you have any questions, file a ticket at http://bugs.ruby-lang.org.;T:
@fileI"lib/optparse.rb;T:0@omit_headings_from_table_of_contents_below0o;;[�;I"lib/optparse/kwargs.rb;T;0;0;0[[
I"banner;TI"W;T:publicFI"lib/optparse.rb;T[
I"default_argv;TI"RW;T;F@�[
I"program_name;T@�;F@�[
I"raise_unknown;T@;F@�[
I"release;T@�;F@�[
I"require_exact;T@;F@�[
I"set_banner;T@�;F@�[
I"set_program_name;T@�;F@�[
I"set_summary_indent;T@;F@�[
I"set_summary_width;T@;F@�[
I"summary_indent;T@;F@�[
I"summary_width;T@;F@�[
I"version;T@�;F@�[	U:RDoc::Constant[i�I"Version;TI"OptionParser::Version;T;0o;;[o;
;[I"The version string;T;@�;0@�@cRDoc::NormalClass0U;[i�I"DecimalInteger;TI"!OptionParser::DecimalInteger;T;0o;;[o;
;[I"8Decimal integer format, to be converted to Integer.;T;@�;0@�@@"0U;[i�I"OctalInteger;TI"OptionParser::OctalInteger;T;0o;;[o;
;[I"MRuby/C like octal/hexadecimal/binary integer format, to be converted to ;TI"
Integer.;T;@�;0@�@@"0U;[i�I"DecimalNumeric;TI"!OptionParser::DecimalNumeric;T;0o;;[o;
;[I"IDecimal integer/float number format, to be converted to Integer for ;TI",integer format, Float for float format.;T;@�;0@�@@"0[�[[I"
class;T[[;[[I"accept;T@�[I"getopts;T@�[I"inc;T@�[I"new;T@�[I"reject;T@�[I"show_version;TI"lib/optparse/version.rb;T[I"terminate;T@�[I"top;T@�[I"	with;T@�[:protected[�[:private[�[I"
instance;T[[;[/[I"
abort;T@�[I"accept;T@�[I"additional_message;T@�[I"banner;T@�[I"	base;T@�[I"candidate;T@�[I"def_head_option;T@�[I"def_option;T@�[I"def_tail_option;T@�[I"define;T@�[I"define_by_keywords;TI"lib/optparse/kwargs.rb;T[I"define_head;T@�[I"define_tail;T@�[I"environment;T@�[I"getopts;T@�[I"	help;T@�[I"inc;T@�[I"	load;T@�[I"make_switch;T@�[I"new;T@�[I"on;T@�[I"on_head;T@�[I"on_tail;T@�[I"
order;T@�[I"order!;T@�[I"
parse;T@�[I"parse!;T@�[I"permute;T@�[I"
permute!;T@�[I"program_name;T@�[I"reject;T@�[I"release;T@�[I"remove;T@�[I"separator;T@�[I"summarize;T@�[I"terminate;T@�[I"	to_a;T@�[I"	to_s;T@�[I"top;T@�[I"ver;T@�[I"version;T@�[I"	warn;T@�[;[�[;[�[�[U:RDoc::Context::Section[i�0o;;[�;0;0[@�I"lib/optparse/ac.rb;TI"lib/optparse/date.rb;T@�I"lib/optparse/time.rb;TI"lib/rdoc/options.rb;TI"*lib/rubygems/commands/cert_command.rb;TI"/lib/rubygems/commands/uninstall_command.rb;TI"lib/rubygems/gem_runner.rb;TI"+lib/rubygems/install_update_options.rb;TI")lib/rubygems/local_remote_options.rb;TI"$lib/rubygems/security_option.rb;T@�cRDoc::TopLevel