--- !ruby/object:RI::ClassDescription attributes: [] class_methods: [] comment: - !ruby/struct:SM::Flow::H level: 2 text: Developer Documentation (not for RDoc output) - !ruby/struct:SM::Flow::H level: 3 text: Class tree - !ruby/object:SM::Flow::LIST contents: - !ruby/struct:SM::Flow::LI label: "-" body: "OptionParser:: front end" - !ruby/struct:SM::Flow::LI label: "-" body: "OptionParser::Switch:: each switches" - !ruby/struct:SM::Flow::LI label: "-" body: "OptionParser::List:: options list" - !ruby/struct:SM::Flow::LI label: "-" body: "OptionParser::ParseError:: errors on parsing" - !ruby/object:SM::Flow::LIST contents: - !ruby/struct:SM::Flow::LI label: "-" body: OptionParser::AmbiguousOption - !ruby/struct:SM::Flow::LI label: "-" body: OptionParser::NeedlessArgument - !ruby/struct:SM::Flow::LI label: "-" body: OptionParser::MissingArgument - !ruby/struct:SM::Flow::LI label: "-" body: OptionParser::InvalidOption - !ruby/struct:SM::Flow::LI label: "-" body: OptionParser::InvalidArgument - !ruby/object:SM::Flow::LIST contents: - !ruby/struct:SM::Flow::LI label: "-" body: OptionParser::AmbiguousArgument type: :BULLET type: :BULLET type: :BULLET - !ruby/struct:SM::Flow::H level: 3 text: Object relationship diagram - !ruby/struct:SM::Flow::VERB body: " +--------------+\n | OptionParser |<>-----+\n +--------------+ | +--------+\n | ,-| Switch |\n on_head -------->+---------------+ / +--------+\n accept/reject -->| List |<|>-\n | |<|>- +----------+\n on ------------->+---------------+ `-| argument |\n : : | class |\n +---------------+ |==========|\n on_tail -------->| | |pattern |\n +---------------+ |----------|\n OptionParser.accept ->| DefaultList | |converter |\n reject |(shared between| +----------+\n | all instances)|\n +---------------+\n" - !ruby/struct:SM::Flow::H level: 2 text: OptionParser - !ruby/struct:SM::Flow::H level: 3 text: Introduction - !ruby/struct:SM::Flow::P body: 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. - !ruby/struct:SM::Flow::H level: 3 text: Features - !ruby/object:SM::Flow::LIST contents: - !ruby/struct:SM::Flow::LI label: "1." body: The argument specification and the code to handle it are written in the same place. - !ruby/struct:SM::Flow::LI label: "2." body: It can output an option summary; you don't need to maintain this string separately. - !ruby/struct:SM::Flow::LI label: "3." body: Optional and mandatory arguments are specified very gracefully. - !ruby/struct:SM::Flow::LI label: "4." body: Arguments can be automatically converted to a specified class. - !ruby/struct:SM::Flow::LI label: "5." body: Arguments can be restricted to a certain set. type: :NUMBER - !ruby/struct:SM::Flow::P body: All of these features are demonstrated in the examples below. - !ruby/struct:SM::Flow::H level: 3 text: Minimal example - !ruby/struct:SM::Flow::VERB body: " require 'optparse'\n\n options = {}\n OptionParser.new do |opts|\n opts.banner = "Usage: example.rb [options]"\n\n opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|\n options[:verbose] = v\n end\n end.parse!\n\n p options\n p ARGV\n" - !ruby/struct:SM::Flow::H level: 3 text: Complete example - !ruby/struct:SM::Flow::P body: 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. - !ruby/struct:SM::Flow::VERB body: " require 'optparse'\n require 'optparse/time'\n require 'ostruct'\n require 'pp'\n\n class OptparseExample\n\n CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]\n CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }\n\n #\n # Return a structure describing the options.\n #\n def self.parse(args)\n # The options specified on the command line will be collected in options.\n # We set default values here.\n options = OpenStruct.new\n options.library = []\n options.inplace = false\n options.encoding = "utf8"\n options.transfer_type = :auto\n options.verbose = false\n\n opts = OptionParser.new do |opts|\n opts.banner = "Usage: example.rb [options]"\n\n opts.separator ""\n opts.separator "Specific options:"\n\n # Mandatory argument.\n opts.on("-r", "--require LIBRARY",\n "Require the LIBRARY before executing your script") do |lib|\n options.library << lib\n end\n\n # Optional argument; multi-line description.\n opts.on("-i", "--inplace [EXTENSION]",\n "Edit ARGV files in place",\n " (make backup if EXTENSION supplied)") do |ext|\n options.inplace = true\n options.extension = ext || ''\n options.extension.sub!(/\\A\\.?(?=.)/, ".") # Ensure extension begins with dot.\n end\n\n # Cast 'delay' argument to a Float.\n opts.on("--delay N", Float, "Delay N seconds before executing") do |n|\n options.delay = n\n end\n\n # Cast 'time' argument to a Time object.\n opts.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|\n options.time = time\n end\n\n # Cast to octal integer.\n opts.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,\n "Specify record separator (default \\0)") do |rs|\n options.record_separator = rs\n end\n\n # List of arguments.\n opts.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|\n options.list = list\n end\n\n # Keyword completion. We are specifying a specific set of arguments (CODES\n # and CODE_ALIASES - notice the latter is a Hash), and the user may provide\n # the shortest unambiguous text.\n code_list = (CODE_ALIASES.keys + CODES).join(',')\n opts.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",\n " (#{code_list})") do |encoding|\n options.encoding = encoding\n end\n\n # Optional argument with keyword completion.\n opts.on("--type [TYPE]", [:text, :binary, :auto],\n "Select transfer type (text, binary, auto)") do |t|\n options.transfer_type = t\n end\n\n # Boolean switch.\n opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|\n options.verbose = v\n end\n\n opts.separator ""\n opts.separator "Common options:"\n\n # No argument, shows at tail. This will print an options summary.\n # Try it and see!\n opts.on_tail("-h", "--help", "Show this message") do\n puts opts\n exit\n end\n\n # Another typical switch to print the version.\n opts.on_tail("--version", "Show version") do\n puts OptionParser::Version.join('.')\n exit\n end\n end\n\n opts.parse!(args)\n options\n end # parse()\n\n end # class OptparseExample\n\n options = OptparseExample.parse(ARGV)\n pp options\n" - !ruby/struct:SM::Flow::H level: 3 text: Further documentation - !ruby/struct:SM::Flow::P body: The above examples should be enough to learn how to use this class. If you have any questions, email me (gsinclair@soyabean.com.au) and I will update this document. constants: [] full_name: OptionParser includes: [] instance_methods: - !ruby/object:RI::MethodSummary name: switch_name name: OptionParser superclass: Object