1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

* lib/optparse.rb: Improved documentation.

Browse Source 
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5339 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
gsinclair 2003-12-28 17:31:10 +00:00
parent d5005596bb
commit f42c729a2e
2 changed files with 260 additions and 262 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ChangeLog
View File

@ -1,3 +1,7 @@
Mon Dec 29 02:25:00 2003 Gavin Sinclair <gsinclair@soyabean.com.au>
* lib/optparse.rb: Improved documentation.
Mon Dec 29 02:20:54 2003 Dave Thomas <dave@wireless_3.local.thomases.com> Mon Dec 29 02:20:54 2003 Dave Thomas <dave@wireless_3.local.thomases.com>
* eval.c: Add RDoc for class Proc, Method, UnboundMethod * eval.c: Add RDoc for class Proc, Method, UnboundMethod

518
lib/optparse.rb
View File

@ -4,28 +4,11 @@
# Author:: Nobu Nakada # Author:: Nobu Nakada
# Documentation:: Nobu Nakada and Gavin Sinclair. # Documentation:: Nobu Nakada and Gavin Sinclair.
# #
# See OptionParser for documentation.
#
# # == Developer Documentation (not for RDoc output)
# == OptionParser
#
# === Introduction
#
# OptionParser (in optparse.rb) is a library 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 example below.
# #
# === Class tree # === Class tree
# #
@ -58,10 +41,34 @@
# reject |(shared between| +----------+ # reject |(shared between| +----------+
# | all instances)| # | all instances)|
# +---------------+ # +---------------+
#
# == 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 example below.
#
# === Example # === Example
# #
# The following example is a complete Ruby program. You can run it and see the # The following example is a complete Ruby program. You can run it and see the
# effect of specifying various options. # effect of specifying various options. This is probably the best way to learn
# the features of +optparse+.
# #
# require 'optparse' # require 'optparse'
# require 'optparse/time' # require 'optparse/time'
@ -71,7 +78,7 @@
# class OptparseExample # class OptparseExample
# #
# CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary] # CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
# CODE_ALIASES = {"jis" => "iso-2022-jp", "sjis" => "shift_jis"} # CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
# #
# # # #
# # Return a structure describing the options. # # Return a structure describing the options.
@ -138,7 +145,8 @@
# end # end
# #
# # Optional argument with keyword completion. # # Optional argument with keyword completion.
# opts.on("--type [TYPE]", [:text, :binary, :auto], "Select transfer type (text, binary, auto)") do |t| # opts.on("--type [TYPE]", [:text, :binary, :auto],
# "Select transfer type (text, binary, auto)") do |t|
# options.transfer_type = t # options.transfer_type = t
# end # end
# #
@ -173,9 +181,14 @@
# options = OptparseExample.parse(ARGV) # options = OptparseExample.parse(ARGV)
# pp options # pp options
# #
# Note: if you get errors or strange results from any of the above code, make # Note: some bugs were fixed between 1.8.0 and 1.8.1. If you experience trouble
# sure you have the latest version installed. Some changes have been made since # with the above code, keep this in mind.
# Ruby 1.8.0 was released. #
# === Further documentation
#
# The methods are not individually documented at this stage. The above example
# 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.
# #
class OptionParser class OptionParser
# :stopdoc: # :stopdoc:
@ -191,10 +204,9 @@ class OptionParser
# #
# Keyword completion module. This allows partial arguments to be specified # Keyword completion module. This allows partial arguments to be specified
# and resolved against a list of acceptable values. The average user does not # and resolved against a list of acceptable values.
# need to comprehend this.
# #
module Completion # :nodoc: module Completion
def complete(key, pat = nil) def complete(key, pat = nil)
pat ||= Regexp.new('\A' + Regexp.quote(key).gsub(/\w+\b/, '\&\w*'), pat ||= Regexp.new('\A' + Regexp.quote(key).gsub(/\w+\b/, '\&\w*'),
ignore_case?) ignore_case?)
@ -259,7 +271,10 @@ class OptionParser
# #
# Individual switch class. # Individual switch class. Not important to the user.
#
# Defined within Switch are several Switch-derived classes: NoArgument,
# RequiredArgument, etc.
# #
class Switch class Switch
attr_reader :pattern, :conv, :short, :long, :arg, :desc, :block attr_reader :pattern, :conv, :short, :long, :arg, :desc, :block
@ -299,19 +314,17 @@ class OptionParser
pattern, conv, short, long, arg, desc, block pattern, conv, short, long, arg, desc, block
end end
=begin #
=== Instance methods # OptionParser::Switch#parse_arg(arg) {non-serious error handler}
=end #
=begin private # Parses argument and returns rest of ((|arg|)), and matched portion
--- OptionParser::Switch#parse_arg(arg) {non-serious error handler} # to the argument pattern.
Parses argument and returns rest of ((|arg|)), and matched portion # :Parameters:
to the argument pattern. # : ((|arg|))
:Parameters: # option argument to be parsed.
: ((|arg|)) # : (({block}))
option argument to be parsed. # yields when the pattern doesn't match sub-string.
: (({block})) #
yields when the pattern doesn't match sub-string.
=end #'#"#`#
def parse_arg(arg) def parse_arg(arg)
pattern or return nil, arg pattern or return nil, arg
unless m = pattern.match(arg) unless m = pattern.match(arg)
@ -332,21 +345,22 @@ class OptionParser
end end
private :parse_arg private :parse_arg
=begin private #
--- OptionParser::Switch#conv_arg(arg, val) {semi-error handler} # OptionParser::Switch#conv_arg(arg, val) {semi-error handler}
Parses argument, convert and returns ((|arg|)), ((|block|)) and #
result of conversion. # Parses argument, convert and returns ((|arg|)), ((|block|)) and
: Arguments to ((|@conv|)) # result of conversion.
substrings matched to ((|@pattern|)), ((|$&|)), ((|$1|)), # : Arguments to ((|@conv|))
((|$2|)) and so on. # substrings matched to ((|@pattern|)), ((|$&|)), ((|$1|)),
:Parameters: # ((|$2|)) and so on.
: ((|arg|)) # :Parameters:
argument string follows the switch. # : ((|arg|))
: ((|val|)) # argument string follows the switch.
following argument. # : ((|val|))
: (({block})) # following argument.
(({yields})) at semi-error condition, instead of raises exception. # : (({block}))
=end #'#"#`# # (({yields})) at semi-error condition, instead of raises exception.
#
def conv_arg(arg, val = nil) def conv_arg(arg, val = nil)
if block if block
if conv if conv
@ -361,24 +375,25 @@ class OptionParser
end end
private :conv_arg private :conv_arg
=begin private #
--- OptionParser::Switch#summarize(sdone, ldone, width, max, indent) # OptionParser::Switch#summarize(sdone, ldone, width, max, indent)
Makes summary strings. #
:Parameters: # Makes summary strings.
: ((|sdone|)) # :Parameters:
already summarized short style options keyed hash. # : ((|sdone|))
: ((|ldone|)) # already summarized short style options keyed hash.
already summarized long style options keyed hash. # : ((|ldone|))
: ((|width|)) # already summarized long style options keyed hash.
width of left side, option part. in other word, right side, # : ((|width|))
description part strings start at ((|width|)) column. # width of left side, option part. in other word, right side,
: ((|max|)) # description part strings start at ((|width|)) column.
maximum width of left side, options are filled within ((|max|)) columns. # : ((|max|))
: ((|indent|)) # maximum width of left side, options are filled within ((|max|)) columns.
prefix string indents each summarized lines. # : ((|indent|))
: (({block})) # prefix string indents each summarized lines.
to be passed each lines(without newline). # : (({block}))
=end #'#"#`# # to be passed each lines(without newline).
#
def summarize(sdone = [], ldone = [], width = 1, max = width - 1, indent = "") def summarize(sdone = [], ldone = [], width = 1, max = width - 1, indent = "")
sopts, lopts, s = [], [], nil sopts, lopts, s = [], [], nil
@short.each {|s| sdone.fetch(s) {sopts << s}; sdone[s] = true} if @short @short.each {|s| sdone.fetch(s) {sopts << s}; sdone[s] = true} if @short
@ -410,20 +425,13 @@ class OptionParser
self self
end end
=begin private #
== Switch classes # Switch that takes no arguments.
=end #'#"#`# #
=begin private
=== ((:OptionParser::Switch::NoArgument:))
Switch that takes no arguments.
==== Superclass
((<OptionParser::Switch>))
==== Instance methods
--- OptionParser::Switch::NoArgument#parse
Raises an exception if any arguments given.
=end #'#"#`#
class NoArgument < self class NoArgument < self
#
# Raises an exception if any arguments given.
#
def parse(arg, argv, &error) def parse(arg, argv, &error)
yield(NeedlessArgument, arg) if arg yield(NeedlessArgument, arg) if arg
conv_arg(arg) conv_arg(arg)
@ -435,16 +443,13 @@ Switch that takes no arguments.
end end
end end
=begin private #
=== ((:OptionParser::Switch::RequiredArgument:)) # Switch that takes an argument.
Switch that takes an argument. #
==== Superclass
((<OptionParser::Switch>))
==== Instance methods
--- OptionParser::Switch::RequiredArgument#parse
Raises an exception if argument is not present.
=end #'#"#`#
class RequiredArgument < self class RequiredArgument < self
#
# Raises an exception if argument is not present.
#
def parse(arg, argv, &error) def parse(arg, argv, &error)
unless arg unless arg
raise MissingArgument if argv.empty? raise MissingArgument if argv.empty?
@ -454,16 +459,13 @@ Switch that takes an argument.
end end
end end
=begin private #
=== ((:OptionParser::Switch::OptionalArgument:)) # Switch that can omit argument.
Switch that can omit argument. #
==== Superclass
((<OptionParser::Switch>))
==== Instance methods
--- OptionParser::Switch::OptionalArgument#parse
Parses argument if given, or uses default value.
=end #'#"#`#
class OptionalArgument < self class OptionalArgument < self
#
# Parses argument if given, or uses default value.
#
def parse(arg, argv, &error) def parse(arg, argv, &error)
if arg if arg
conv_arg(*parse_arg(arg, &error)) conv_arg(*parse_arg(arg, &error))
@ -473,7 +475,13 @@ Switch that can omit argument.
end end
end end
#
# ?
#
class PlacedArgument < self class PlacedArgument < self
#
# ?
#
def parse(arg, argv, &error) def parse(arg, argv, &error)
if !(val = arg) and (argv.empty? or /\A-/ =~ (val = argv[0])) if !(val = arg) and (argv.empty? or /\A-/ =~ (val = argv[0]))
return nil, block, nil return nil, block, nil
@ -490,22 +498,28 @@ Switch that can omit argument.
end end
end end
#
=begin # Simple option list providing mapping from short and/or long option
== ((:OptionParser::List:)) # string to ((<OptionParser::Switch>)), and mapping from acceptable
Simple option list providing mapping from short and/or long option # argument to matching pattern and converter pair. Also provides
string to ((<OptionParser::Switch>)), and mapping from acceptable # summary feature.
argument to matching pattern and converter pair. Also provides #
summary feature.
=end #'#"#`#
class List class List
=begin # Map from acceptable argument types to pattern and converter pairs.
=== Class methods attr_reader :atype
=end #'#"#`#
=begin private # Map from short style option switches to actual switch objects.
--- OptionParser::List.new attr_reader :short
Just initializes all instance variables.
=end #'#"#`# # Map from long style option switches to actual switch objects.
attr_reader :long
# List of all switches and summary string.
attr_reader :list
#
# Just initializes all instance variables.
#
def initialize def initialize
@atype = {} @atype = {}
@short = OptionMap.new @short = OptionMap.new
@ -513,27 +527,9 @@ summary feature.
@list = [] @list = []
end end
=begin #
=== Instance methods # See OptionParser.accept.
=end #'#"#`# #
=begin
--- OptionParser::List#atype
Map from acceptable argument types to pattern and converter pairs.
--- OptionParser::List#short
Map from short style option switches to actual switch objects.
--- OptionParser::List#long
Map from long style option switches to actual switch objects.
--- OptionParser::List#list
List of all switches and summary string.
=end #'#"#`#
attr_reader :atype, :short, :long, :list
=begin private
--- OptionParser::List#accept(type[, pattern]) {...}
see ((<OptionParser.accept>)).
--- OptionParser::List#reject(type)
see ((<OptionParser.reject>)).
=end #'#"#`#
def accept(t, pat = /.*/, &block) def accept(t, pat = /.*/, &block)
if pat if pat
pat.respond_to?(:match) or raise TypeError, "has no `match'" pat.respond_to?(:match) or raise TypeError, "has no `match'"
@ -546,24 +542,28 @@ summary feature.
@atype[t] = [pat, block] @atype[t] = [pat, block]
end end
#
# See OptionParser.reject.
#
def reject(t) def reject(t)
@atype.delete(t) @atype.delete(t)
end end
=begin private #
--- OptionParser::List#update(sw, sopts, lopts, nlopts = nil) # OptionParser::List#update(sw, sopts, lopts, nlopts = nil)
Adds ((|sw|)) according to ((|sopts|)), ((|lopts|)) and #
((|nlopts|)). # Adds ((|sw|)) according to ((|sopts|)), ((|lopts|)) and
:Parameters: # ((|nlopts|)).
: ((|sw|)) # :Parameters:
((<OptionParser::Switch>)) instance to be added. # : ((|sw|))
: ((|sopts|)) # ((<OptionParser::Switch>)) instance to be added.
short style options list. # : ((|sopts|))
: ((|lopts|)) # short style options list.
long style options list. # : ((|lopts|))
: ((|nlopts|)) # long style options list.
negated long style options list. # : ((|nlopts|))
=end #'#"#`# # negated long style options list.
#
def update(sw, sopts, lopts, nsw = nil, nlopts = nil) def update(sw, sopts, lopts, nsw = nil, nlopts = nil)
o = nil o = nil
sopts.each {|o| @short[o] = sw} if sopts sopts.each {|o| @short[o] = sw} if sopts
@ -574,44 +574,47 @@ summary feature.
end end
private :update private :update
=begin #
--- OptionParser::List#prepend(switch, short_opts, long_opts, nolong_opts) # OptionParser::List#prepend(switch, short_opts, long_opts, nolong_opts)
Inserts ((|switch|)) at head of the list, and associates short, #
long and negated long options. # Inserts ((|switch|)) at head of the list, and associates short,
--- OptionParser::List#append(switch, short_opts, long_opts, nolong_opts) # long and negated long options.
Appends ((|switch|)) at tail of the list, and associates short,
long and negated long options.
:Parameters:
: ((|switch|))
((<OptionParser::Switch>)) instance to be inserted.
: ((|short_opts|))
list of short style options.
: ((|long_opts|))
list of long style options.
: ((|nolong_opts|))
list of long style options with (({"no-"})) prefix.
=end #'#"#`#
def prepend(*args) def prepend(*args)
update(*args) update(*args)
@list.unshift(args[0]) @list.unshift(args[0])
end end
#
# OptionParser::List#append(switch, short_opts, long_opts, nolong_opts)
#
# Appends ((|switch|)) at tail of the list, and associates short,
# long and negated long options.
# :Parameters:
# : ((|switch|))
# ((<OptionParser::Switch>)) instance to be inserted.
# : ((|short_opts|))
# list of short style options.
# : ((|long_opts|))
# list of long style options.
# : ((|nolong_opts|))
# list of long style options with (({"no-"})) prefix.
def append(*args) def append(*args)
update(*args) update(*args)
@list.push(args[0]) @list.push(args[0])
end end
=begin #
--- OptionParser::List#search(id, key) [{block}] # OptionParser::List#search(id, key) [{block}]
Searches ((|key|)) in ((|id|)) list. #
:Parameters: # Searches ((|key|)) in ((|id|)) list.
: ((|id|)) # :Parameters:
searching list. # : ((|id|))
: ((|k|)) # searching list.
searching key. # : ((|k|))
: (({block})) # searching key.
yielded with the found value when succeeded. # : (({block}))
=end #'#"#`# # yielded with the found value when succeeded.
#
def search(id, key) def search(id, key)
if list = __send__(id) if list = __send__(id)
val = list.fetch(key) {return nil} val = list.fetch(key) {return nil}
@ -620,33 +623,35 @@ summary feature.
end end
end end
=begin #
--- OptionParser::List#complete(id, opt, *pat, &block) # OptionParser::List#complete(id, opt, *pat, &block)
Searches list ((|id|)) for ((|opt|)) and ((|*pat|)). #
:Parameters: # Searches list ((|id|)) for ((|opt|)) and ((|*pat|)).
: ((|id|)) # :Parameters:
searching list. # : ((|id|))
: ((|opt|)) # searching list.
searching key. # : ((|opt|))
: ((|*pat|)) # searching key.
optional pattern for completion. # : ((|*pat|))
: (({block})) # optional pattern for completion.
yielded with the found value when succeeded. # : (({block}))
=end #'#"#`# # yielded with the found value when succeeded.
#
def complete(id, opt, *pat, &block) def complete(id, opt, *pat, &block)
__send__(id).complete(opt, *pat, &block) __send__(id).complete(opt, *pat, &block)
end end
=begin #
--- OptionParser::List#summarize(*args) {...} # OptionParser::List#summarize(*args) {...}
Making summary table, yields the (({block})) with each lines. #
Each elements of (({@list})) should be able to (({summarize})). # Making summary table, yields the (({block})) with each lines.
:Parameters: # Each elements of (({@list})) should be able to (({summarize})).
: ((|args|)) # :Parameters:
passed to elements#summarize through. # : ((|args|))
: (({block})) # passed to elements#summarize through.
to be passed each lines(without newline). # : (({block}))
=end #'#"#`# # to be passed each lines(without newline).
#
def summarize(*args, &block) def summarize(*args, &block)
list.each do |opt| list.each do |opt|
if opt.respond_to?(:summarize) # perhaps OptionParser::Switch if opt.respond_to?(:summarize) # perhaps OptionParser::Switch
@ -660,23 +665,17 @@ summary feature.
end end
end end
#
=begin private # Hash with completion search feature. See Completion module.
== ((:OptionParser::CompletingHash:)) #
(({Hash})) with completion search feature.
=== Superclass
(({Hash}))
=== Including modules
((<OptionParser::Completion>))
=end #'#"#`#
class CompletingHash < Hash class CompletingHash < Hash
include Completion include Completion
=begin private #
=== Instance methods # OptionParser::CompletingHash#match(key)
--- OptionParser::CompletingHash#match(key) #
Completion for hash key. # Completion for hash key.
=end #'#"#`# #
def match(key) def match(key)
return key, *fetch(key) { return key, *fetch(key) {
raise AmbiguousArgument, catch(:ambiguous) {return complete(key)} raise AmbiguousArgument, catch(:ambiguous) {return complete(key)}
@ -684,54 +683,47 @@ summary feature.
end end
end end
#
=begin # OptionParser::ArgumentStyle
== ((:OptionParser:)) # Enumeration of acceptable argument styles; possible values are:
The front-end of (({OptionParser})). # : OptionParser::NO_ARGUMENT
=end #'#"#`# # the switch takes no arguments. ((({:NONE})))
# : OptionParser::REQUIRED_ARGUMENT
# the switch requires an argument. ((({:REQUIRED})))
# : OptionParser::OPTIONAL_ARGUMENT
# the switch requires an optional argument, that is, may take or
# not. ((({:OPTIONAL})))
#
# Use like (({--switch=argument}))(long style) or
# (({-Xargument}))(short style). For short style, only portion
# matched to ((<argument pattern>)) is dealed as argument.
#
=begin # :stopdoc:
=== Constants
=end #'#"#`#
=begin
--- OptionParser::ArgumentStyle
Enumeration of acceptable argument styles; possible values are:
: OptionParser::NO_ARGUMENT
the switch takes no arguments. ((({:NONE})))
: OptionParser::REQUIRED_ARGUMENT
the switch requires an argument. ((({:REQUIRED})))
: OptionParser::OPTIONAL_ARGUMENT
the switch requires an optional argument, that is, may take or
not. ((({:OPTIONAL})))
Use like (({--switch=argument}))(long style) or
(({-Xargument}))(short style). For short style, only portion
matched to ((<argument pattern>)) is dealed as argument.
=end #'#"#`#
ArgumentStyle = {} ArgumentStyle = {}
NoArgument.each {|el| ArgumentStyle[el] = Switch::NoArgument} NoArgument.each {|el| ArgumentStyle[el] = Switch::NoArgument}
RequiredArgument.each {|el| ArgumentStyle[el] = Switch::RequiredArgument} RequiredArgument.each {|el| ArgumentStyle[el] = Switch::RequiredArgument}
OptionalArgument.each {|el| ArgumentStyle[el] = Switch::OptionalArgument} OptionalArgument.each {|el| ArgumentStyle[el] = Switch::OptionalArgument}
ArgumentStyle.freeze ArgumentStyle.freeze
=begin private #
--- OptionParser::DefaultList # OptionParser::DefaultList
Switches common used such as '--', and also provides default #
argument classes # Switches common used such as '--', and also provides default
=end #'#"#`# # argument classes
#
DefaultList = List.new DefaultList = List.new
DefaultList.short['-'] = Switch::NoArgument.new {} DefaultList.short['-'] = Switch::NoArgument.new {}
DefaultList.long[''] = Switch::NoArgument.new {throw :terminate} DefaultList.long[''] = Switch::NoArgument.new {throw :terminate}
=begin undocumented #
=== Default options # Default options, which never appear in option summary.
Default options, which never appear in option summary. # --help
--- --help # Shows option summary.
Shows option summary. # --version
--- --version # Shows version string if (({::Version})) is defined.
Shows version string if (({::Version})) is defined. #
=end #'#"#`#
DefaultList.long['help'] = Switch::NoArgument.new do DefaultList.long['help'] = Switch::NoArgument.new do
puts ARGV.options puts ARGV.options
exit exit
@ -752,9 +744,11 @@ Default options, which never appear in option summary.
exit exit
end end
=begin # :startdoc:
=== Class methods
=end #'#"#`# #
# Class methods
#
=begin =begin
--- OptionParser.with([banner[, width[, indent]]]) [{...}] --- OptionParser.with([banner[, width[, indent]]]) [{...}]