lib/optparse.rb in optparse-0.1.1 vs lib/optparse.rb in optparse-0.2.0
- old
+ new
@@ -46,10 +46,14 @@
#
#++
#
# == OptionParser
#
+# === New to \OptionParser?
+#
+# See the {Tutorial}[./doc/optparse/tutorial_rdoc.html].
+#
# === 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.
@@ -238,18 +242,18 @@
#
# The +into+ option of +order+, +parse+ and so on methods stores command line options into a Hash.
#
# require 'optparse'
#
-# params = {}
+# options = {}
# OptionParser.new do |parser|
# parser.on('-a')
# parser.on('-b NUM', Integer)
# parser.on('-v', '--verbose')
-# end.parse!(into: params)
+# end.parse!(into: options)
#
-# p params
+# p options
#
# Used:
#
# $ ruby optparse-test.rb -a
# {:a=>true}
@@ -413,15 +417,17 @@
# 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 http://bugs.ruby-lang.org.
+# The above examples, along with the accompanying
+# {Tutorial}[./doc/optparse/tutorial_rdoc.html],
+# should be enough to learn how to use this class.
+# If you have any questions, file a ticket at http://bugs.ruby-lang.org.
#
class OptionParser
- OptionParser::Version = "0.1.1"
+ OptionParser::Version = "0.2.0"
# :stopdoc:
NoArgument = [NO_ARGUMENT = :NONE, nil].freeze
RequiredArgument = [REQUIRED_ARGUMENT = :REQUIRED, true].freeze
OptionalArgument = [OPTIONAL_ARGUMENT = :OPTIONAL, false].freeze
@@ -545,11 +551,11 @@
#
# Parses +arg+ and returns rest of +arg+ and matched portion to the
# argument pattern. Yields when the pattern doesn't match substring.
#
- def parse_arg(arg)
+ def parse_arg(arg) # :nodoc:
pattern or return nil, [arg]
unless m = pattern.match(arg)
yield(InvalidArgument, arg)
return arg, []
end
@@ -570,11 +576,11 @@
#
# Parses argument, converts and returns +arg+, +block+ and result of
# conversion. Yields at semi-error condition instead of raising an
# exception.
#
- def conv_arg(arg, val = [])
+ def conv_arg(arg, val = []) # :nodoc:
if conv
val = conv.call(*val)
else
val = proc {|v| v}.call(*val)
end
@@ -804,11 +810,11 @@
# +sw+:: OptionParser::Switch instance to be added.
# +sopts+:: Short style option list.
# +lopts+:: Long style option list.
# +nlopts+:: Negated long style options list.
#
- def update(sw, sopts, lopts, nsw = nil, nlopts = nil)
+ def update(sw, sopts, lopts, nsw = nil, nlopts = nil) # :nodoc:
sopts.each {|o| @short[o] = sw} if sopts
lopts.each {|o| @long[o] = sw} if lopts
nlopts.each {|o| @long[o] = nsw} if nsw and nlopts
used = @short.invert.update(@long.invert)
@list.delete_if {|o| Switch === o and !used[o]}
@@ -1298,11 +1304,11 @@
#
# +obj+:: New argument.
# +prv+:: Previously specified argument.
# +msg+:: Exception message.
#
- def notwice(obj, prv, msg)
+ def notwice(obj, prv, msg) # :nodoc:
unless !prv or prv == obj
raise(ArgumentError, "argument #{msg} given twice: #{obj}",
ParseError.filter_backtrace(caller(2)))
end
obj
@@ -1312,69 +1318,12 @@
SPLAT_PROC = proc {|*a| a.length <= 1 ? a.first : a} # :nodoc:
# :call-seq:
# make_switch(params, block = nil)
#
- # Creates an OptionParser::Switch from the parameters. The parsed argument
- # value is passed to the given block, where it can be processed.
+ # :include: ../doc/optparse/creates_option.rdoc
#
- # See at the beginning of OptionParser for some full examples.
- #
- # +params+ can include the following elements:
- #
- # [Argument style:]
- # One of the following:
- # :NONE, :REQUIRED, :OPTIONAL
- #
- # [Argument pattern:]
- # Acceptable option argument format, must be pre-defined with
- # OptionParser.accept or OptionParser#accept, or Regexp. This can appear
- # once or assigned as String if not present, otherwise causes an
- # ArgumentError. Examples:
- # Float, Time, Array
- #
- # [Possible argument values:]
- # Hash or Array.
- # [:text, :binary, :auto]
- # %w[iso-2022-jp shift_jis euc-jp utf8 binary]
- # { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
- #
- # [Long style switch:]
- # Specifies a long style switch which takes a mandatory, optional or no
- # argument. It's a string of the following form:
- # "--switch=MANDATORY" or "--switch MANDATORY"
- # "--switch[=OPTIONAL]"
- # "--switch"
- #
- # [Short style switch:]
- # Specifies short style switch which takes a mandatory, optional or no
- # argument. It's a string of the following form:
- # "-xMANDATORY"
- # "-x[OPTIONAL]"
- # "-x"
- # There is also a special form which matches character range (not full
- # set of regular expression):
- # "-[a-z]MANDATORY"
- # "-[a-z][OPTIONAL]"
- # "-[a-z]"
- #
- # [Argument style and description:]
- # Instead of specifying mandatory or optional arguments directly in the
- # switch parameter, this separate parameter can be used.
- # "=MANDATORY"
- # "=[OPTIONAL]"
- #
- # [Description:]
- # Description string for the option.
- # "Run verbosely"
- # If you give multiple description strings, each string will be printed
- # line by line.
- #
- # [Handler:]
- # Handler for the parsed argument value. Either give a block or pass a
- # Proc or Method as an argument.
- #
def make_switch(opts, block = nil)
short, long, nolong, style, pattern, conv, not_pattern, not_conv, not_style = [], [], []
ldesc, sdesc, desc, arg = [], [], []
default_style = Switch::NoArgument
default_pattern = nil
@@ -1507,60 +1456,69 @@
end
# :call-seq:
# define(*params, &block)
#
+ # :include: ../doc/optparse/creates_option.rdoc
+ #
def define(*opts, &block)
top.append(*(sw = make_switch(opts, block)))
sw[0]
end
# :call-seq:
# on(*params, &block)
#
- # Add option switch and handler. See #make_switch for an explanation of
- # parameters.
+ # :include: ../doc/optparse/creates_option.rdoc
#
def on(*opts, &block)
define(*opts, &block)
self
end
alias def_option define
# :call-seq:
# define_head(*params, &block)
#
+ # :include: ../doc/optparse/creates_option.rdoc
+ #
def define_head(*opts, &block)
top.prepend(*(sw = make_switch(opts, block)))
sw[0]
end
# :call-seq:
# on_head(*params, &block)
#
- # Add option switch like with #on, but at head of summary.
+ # :include: ../doc/optparse/creates_option.rdoc
#
+ # The new option is added at the head of the summary.
+ #
def on_head(*opts, &block)
define_head(*opts, &block)
self
end
alias def_head_option define_head
# :call-seq:
# define_tail(*params, &block)
#
+ # :include: ../doc/optparse/creates_option.rdoc
+ #
def define_tail(*opts, &block)
base.append(*(sw = make_switch(opts, block)))
sw[0]
end
#
# :call-seq:
# on_tail(*params, &block)
#
- # Add option switch like with #on, but at tail of summary.
+ # :include: ../doc/optparse/creates_option.rdoc
#
+ # The new option is added at the tail of the summary.
+ #
def on_tail(*opts, &block)
define_tail(*opts, &block)
self
end
alias def_tail_option define_tail
@@ -1778,22 +1736,22 @@
#
# Traverses @stack, sending each element method +id+ with +args+ and
# +block+.
#
- def visit(id, *args, &block)
+ def visit(id, *args, &block) # :nodoc:
@stack.reverse_each do |el|
el.__send__(id, *args, &block)
end
nil
end
private :visit
#
# Searches +key+ in @stack for +id+ hash and returns or yields the result.
#
- def search(id, key)
+ def search(id, key) # :nodoc:
block_given = block_given?
visit(:search, id, key) do |k|
return block_given ? yield(k) : k
end
end
@@ -1806,10 +1764,10 @@
# +typ+:: Searching table.
# +opt+:: Searching key.
# +icase+:: Search case insensitive if true.
# +pat+:: Optional pattern for completion.
#
- def complete(typ, opt, icase = false, *pat)
+ def complete(typ, opt, icase = false, *pat) # :nodoc:
if pat.empty?
search(typ, opt) {|sw| return [sw, opt]} # exact match or...
end
ambiguous = catch(:ambiguous) {
visit(:complete, typ, opt, icase, *pat) {|o, *sw| return sw}