U:RDoc::NormalClass[iI"OptionParser:ET@I" Object;To:RDoc::Markup::Document: @parts[o;;[BS:RDoc::Markup::Heading: leveli: textI"OptionParser;To:RDoc::Markup::BlankLineS; ; i; I"Introduction;T@o:RDoc::Markup::Paragraph;[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 |opts| ;TI"3 opts.banner = "Usage: example.rb [options]" ;TI" ;TI"? opts.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"1 opt_parser = OptionParser.new do |opts| ;TI"7 opts.banner = "Usage: example.rb [options]" ;TI" ;TI"K opts.on("-nNAME", "--name=NAME", "Name to say hello to") do |n| ;TI" args.name = n ;TI" end ;TI" ;TI": opts.on("-h", "--help", "Prints this help") do ;TI" puts opts ;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.;To;;[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"(bash-3.2$ ruby optparse-test.rb -r ;TI"Zoptparse-test.rb:9:in `
': missing argument: -r (OptionParser::MissingArgument) ;TI"3bash-3.2$ 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"/Date -- Anything accepted by +Date.parse+;To;;0;[o; ;[I"6DateTime -- Anything accepted by +DateTime.parse+;To;;0;[o; ;[I"ATime -- Anything accepted by +Time.httpdate+ or +Time.parse+;To;;0;[o; ;[I"-URI -- Anything accepted by +URI.parse+;To;;0;[o; ;[I"?Shellwords -- Anything accepted by +Shellwords.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"' ;TI"*from optparse-test.rb:31:in `
' ;TI"2bash-3.2$ ruby optparse-test.rb -t 10-11-12 ;TI"2010-11-12 00:00:00 -0500 ;TI".bash-3.2$ 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" output:;To;;[ I".bash-3.2$ ruby optparse-test.rb --user 1 ;TI"%# ;TI".bash-3.2$ ruby optparse-test.rb --user 2 ;TI")# ;TI".bash-3.2$ 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"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"QThe above examples should be enough to learn how to use this class. If you ;TI"Dhave 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;TI"W;T;F@[ I" release;TI"W;T;F@[ I"set_banner;F@;F@[ I"set_program_name;F@;F@[ I"set_summary_indent;FI"RW;T;F@[ I"set_summary_width;FI"RW;T;F@[ I"summary_indent;TI"RW;T;F@[ I"summary_width;TI"RW;T;F@[ I" version;TI"W;T;F@[U:RDoc::Constant[iI"DecimalInteger;FI"!OptionParser::DecimalInteger;T00o;;[o; ;[I"8Decimal integer format, to be converted to Integer.;T;@;0@@cRDoc::NormalClass0U;[iI"OctalInteger;FI"OptionParser::OctalInteger;T00o;;[o; ;[I"MRuby/C like octal/hexadecimal/binary integer format, to be converted to ;TI" Integer.;T;@;0@@@0U;[iI"DecimalNumeric;FI"!OptionParser::DecimalNumeric;T00o;;[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;F@[I"each_const;FI"lib/optparse/version.rb;T[I" getopts;F@[I"inc;F@[I"new;T@[I" reject;F@[I"search_const;F@$[I"show_version;F@$[I"terminate;F@[I"top;F@[I" with;F@[:protected[[: private[[I" instance;T[[;[.[I" abort;F@[I" accept;F@[I" banner;F@[I" base;F@[I"candidate;F@[I"def_head_option;F@[I"def_option;F@[I"def_tail_option;F@[I" define;F@[I"define_by_keywords;FI"lib/optparse/kwargs.rb;T[I"define_head;F@[I"define_tail;F@[I"environment;F@[I" getopts;F@[I" help;F@[I"inc;F@[I" load;F@[I"make_switch;F@[I"new;F@[I"on;F@[I" on_head;F@[I" on_tail;F@[I" order;F@[I" order!;F@[I" parse;F@[I" parse!;F@[I" permute;F@[I" permute!;F@[I"program_name;F@[I" reject;F@[I" release;F@[I" remove;F@[I"separator;F@[I"summarize;F@[I"terminate;F@[I" to_a;F@[I" to_s;F@[I"top;F@[I"ver;F@[I" version;F@[I" warn;F@[;[[;[ [I" complete;F@[I" notwice;F@[I" search;F@[I" visit;F@[[U:RDoc::Context::Section[i0o;;[;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/server_command.rb;TI"/lib/rubygems/commands/uninstall_command.rb;TI"+lib/rubygems/install_update_options.rb;TI")lib/rubygems/local_remote_options.rb;T@cRDoc::TopLevel