.\" DO NOT MODIFY THIS FILE! it was generated by rd2
.TH optparse 1 "August 2001"
.SH Summary
.PP
Library for command line option analysis.
features:

.IP 1.
It is possible <option switch of a short form and a long form> to
    exist together. It is also possible in one to bring the switch of
    a short form together.
.IP 2.
It is possible to write bringing specification and the handler of
    the switch together respectively in one place.
.IP 3.
The argument of the switch is converted into the class which
    automatically specifies it.
.IP 4.
The option summary can be made.
.IP 5.
The option can be added on the way later.

.PP
.SH Class tree
.PP
.TP
.B
\(bu OptionParser front end
.TP
.B
\(bu OptionParser::Switch each switches
.TP
.B
\(bu OptionParser::List options list
.TP
.B
\(bu OptionParser::ParseError errors on parsing
.TP
.B
\(bu OptionParser::AmbiguousOption
.TP
.B
\(bu OptionParser::NeedlessArgument
.TP
.B
\(bu OptionParser::MissingArgument
.TP
.B
\(bu OptionParser::InvalidOption
.TP
.B
\(bu OptionParser::InvalidArgument
.TP
.B
\(bu OptionParser::AmbiguousArgument
.SH Object relations
.PP
.nf
\&    +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&    | OptionParser |<>\-\-\-\-\-+
\&    +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+       |          	         +\-\-\-\-\-\-\-\-+
\&                           |          	       ,\-| Switch |
\&         on_head \-\-\-\-\-\-\-\->+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+    /  +\-\-\-\-\-\-\-\-+
\&         accept/reject \-\->| List        	 |<|>\-
\&                          |             	 |<|>\-  +\-\-\-\-\-\-\-\-\-\-+
\&         on \-\-\-\-\-\-\-\-\-\-\-\-\->+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+    `\-| argument |
\&                          :             	 :      |  class   |
\&                          +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+      |==========|
\&         on_tail \-\-\-\-\-\-\-\->|             	 |      |pattern   |
\&                          +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+      |\-\-\-\-\-\-\-\-\-\-|
\&    OptionParser.accept \->| DefaultList 	 |      |converter |
\&                 reject   |(shared between|      +\-\-\-\-\-\-\-\-\-\-+
\&                          | all instances)|
\&                          +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.fi
.SH Classes & Modules
.PP
.SH OptionParser::Switch
.PP
Individual switch class.
.SH Instance methods
.PP

.TP
.fi
.B
OptionParser::Switch#parse(arg, val) {semi\-error handler}
Parses argument, convert and returns arg, block and
result of conversion.


.TP
.fi
.B
Arguments to @conv

substrings matched to @pattern, $&, $1,
$2 and so on.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
arg

argument string follows the switch.


.TP
.fi
.B
val

following argument.


.TP
.fi
.B
\&\fBblock\fP

\&\fByields\fP at semi\-error condition, instead of raises exception.
.SH 
.PP
Simple option list providing mapping from short and/or long option
string to OptionParser::Switch, and mapping from acceptable
argument to matching pattern and converter pair.  Also provides
summary feature.
.SH Class methods
.PP
.SH Instance methods
.PP

.TP
.fi
.B
OptionParser::List#atype
Map from acceptable argument types to pattern and converter pairs.


.TP
.fi
.B
OptionParser::List#short
Map from short style option switches to actual switch objects.


.TP
.fi
.B
OptionParser::List#long
Map from long style option switches to actual switch objects.


.TP
.fi
.B
OptionParser::List#list
List of all switches and summary string.

.TP
.fi
.B
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.


.TP
.fi
.B
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.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
switch

OptionParser::Switch instance to be inserted.


.TP
.fi
.B
short_opts

list of short style options.


.TP
.fi
.B
long_opts

list of long style options.


.TP
.fi
.B
nolong_opts

list of long style options with \&\fB"no\-"\fP prefix.

.TP
.fi
.B
OptionParser::List#search(id, key) [{block}]
Searches key in id list.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
id

searching list.


.TP
.fi
.B
k

searching key.


.TP
.fi
.B
\&\fBBlock\fP

yielded with the found value when succeeded.

.TP
.fi
.B
OptionParser::List#complete(id, opt, *pat, &block)
Searches list id for opt and *pat.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
id

searching list.


.TP
.fi
.B
opt

searching key.


.TP
.fi
.B
*pat

optional pattern for completion.


.TP
.fi
.B
\&\fBBlock\fP

yielded with the found value when succeeded.

.TP
.fi
.B
OptionParser::List#summarize(*args) {...}
Making summary table, yields the \&\fBblock\fP with each lines.
Each elements of \&\fB@list\fP should be able to \&\fBsummarize\fP.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
args

passed to elements#summarize through.


.TP
.fi
.B
\&\fBblock\fP

to be passed each lines(without newline).
.SH 
.PP
The front\-end of \&\fBOptionParser\fP.
.SH Constants
.PP

.TP
.fi
.B
OptionParser::ArgumentStyle
Enumeration of acceptable argument styles; possible values are:


.TP
.fi
.B
OptionParser::NO_ARGUMENT

the switch takes no arguments. (\&\fB:NONE\fP) 


.TP
.fi
.B
OptionParser::REQUIRED_ARGUMENT

the switch requires an argument. (\&\fB:REQUIRED\fP)


.TP
.fi
.B
OptionParser::OPTIONAL_ARGUMENT

the switch requires an optional argument, that is, may take or
not. (\&\fB:OPTIONAL\fP)

Use like \&\fB\-\-switch=argument\fP(long style) or
\&\fB\-Xargument\fP(short style). For short style, only portion
matched to argument pattern is dealed as argument.
.SH Class methods
.PP

.TP
.fi
.B
OptionParser.with([banner[, width[, indent]]]) [{...}]
Initializes new instance, and evaluates the block in context of
the instance if called as iterator.  This behavior is equivalent
to older \&\fBnew\fP.  This is \fIdeprecated\fP method.

cf. OptionParser.new


.TP
.fi
.B
Parameters:


.TP
.fi
.B
banner

banner message.


.TP
.fi
.B
width

summary width.


.TP
.fi
.B
indent

summary indent.


.TP
.fi
.B
\&\fBBlock\fP

to be evaluated in the new instance context.

.TP
.fi
.B
OptionParser.inc(arg[, default])

.TP
.fi
.B
OptionParser#inc(arg[, default])
Returns incremented value of default according to arg.

.TP
.fi
.B
OptionParser.new([banner[, width[, indent]]]) [{...}]
Initializes the instance, and yields itself if called as iterator.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
banner

banner message.


.TP
.fi
.B
width

summary width.


.TP
.fi
.B
indent

summary indent.


.TP
.fi
.B
\&\fBBlock\fP

to be evaluated in the new instance context.

.TP
.fi
.B
OptionParser.terminate([arg])
Terminates option parsing. Optional parameter arg would be
pushed back if given.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
arg

string pushed back to be first non\-option argument

.TP
.fi
.B
OptionParser.accept(t, [pat]) {...}

.TP
.fi
.B
OptionParser#accept(t, [pat]) {...}
Directs to accept specified class argument.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
t

argument class specifier, any object including Class.


.TP
.fi
.B
pat

pattern for argument, defaulted to t if it respond to \&\fBmatch\fP.


.TP
.fi
.B
\&\fBBlock\fP

receives argument string and should be convert to desired class.

.TP
.fi
.B
OptionParser.reject(t)

.TP
.fi
.B
OptionParser#reject(t)
Directs to reject specified class argument.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
t

argument class specifier, any object including Class.
.SH Instance methods
.PP

.TP
.fi
.B
OptionParser#banner

.TP
.fi
.B
OptionParser#banner=(heading)
Heading banner preceding summary.


.TP
.fi
.B
OptionParser#summary_width

.TP
.fi
.B
OptionParser#summary_width=(width)
Width for option list portion of summary. Must be \&\fBNumeric\fP.


.TP
.fi
.B
OptionParser#summary_indent

.TP
.fi
.B
OptionParser#summary_indent=(indent)
Indentation for summary. Must be \&\fBString\fP (or have \&\fB+ String\fP).


.TP
.fi
.B
OptionParser#program_name

.TP
.fi
.B
OptionParser#program_name=(name)
Program name to be emitted in error message and default banner,
defaulted to \&\fB$0\fP.

.TP
.fi
.B
OptionParser#version

.TP
.fi
.B
OptionParser#version=(ver)
Version.


.TP
.fi
.B
OptionParser#release

.TP
.fi
.B
OptionParser#release=(rel)
Release code.


.TP
.fi
.B
OptionParser#ver
Returns version string from program_name, \&\fBversion\fP and
\&\fBrelease\fP.

.TP
.fi
.B
OptionParser#top
Subject of on/on_head, accept/reject.

.TP
.fi
.B
OptionParser#base
Subject of on_tail.

.TP
.fi
.B
OptionParser#new
Pushes a new \&\fBList\fP.

.TP
.fi
.B
OptionParser#remove
Removes the last \&\fBList\fP.

.TP
.fi
.B
OptionParser#summarize(to = [], width = @summary_width, max = width \- 1, indent = @summary_indent)
Puts option summary into to, and returns to.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
to

output destination, which must have method <<. Defaulted to \&\fB[]\fP.


.TP
.fi
.B
width

width of left side. Defaulted to @summary_width


.TP
.fi
.B
max

maximum length allowed for left side. Defaulted to \&\fBwidth \- 1\fP


.TP
.fi
.B
indent

indentation. Defaulted to @summary_indent


.TP
.fi
.B
\&\fBBlock\fP

yields with each line if called as iterator.

.TP
.fi
.B
OptionParser#to_str

.TP
.fi
.B
OptionParser#to_s
Returns option summary string.

.TP
.fi
.B
OptionParser#to_a
Returns option summary list.

.TP
.fi
.B
OptionParser#switch
Creates OptionParser::Switch.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
*opts

option definition:


.TP
.fi
.B
argument style

see OptionParser::ArgumentStyle


.TP
.fi
.B
argument pattern

acceptable option argument format, must pre\-defined with
OptionParser.accept or OptionParser#accept, or
\&\fBRegexp\fP. This can appear once or assigned as \&\fBString\fP
if not present, otherwise causes exception \&\fBArgumentError\fP.

cf. Acceptable argument classes.


.TP
.fi
.B
Hash


.TP
.fi
.B
Array

possible argument values.


.TP
.fi
.B
Proc


.TP
.fi
.B
Method

alternative way to give the \fIhandler\fP.


.TP
.fi
.B
"\-\-switch=MANDATORY", "\-\-switch[=OPTIONAL]", "\-\-switch"

specifies long style switch that takes \fImandatory\fP,
\fIoptional\fP and \fIno\fP argument, respectively.


.TP
.fi
.B
"\-xMANDATORY", "\-x[OPTIONAL]", "\-x"

specifies short style switch that takes \fImandatory\fP,
\fIoptional\fP and \fIno\fP argument, respectively.


.TP
.fi
.B
"\-[a\-z]MANDATORY", "\-[a\-z][OPTIONAL]", "\-[a\-z]"

special form short style switch that matches character
range(not fullset of regular expression).


.TP
.fi
.B
"=MANDATORY", "=[OPTIONAL]"

argument style and description.


.TP
.fi
.B
"description", ...

\fIdescription\fP for this option.


.TP
.fi
.B
\&\fBBlock\fP

\fIhandler\fP to convert option argument to arbitrary \&\fBClass\fP.

.TP
.fi
.B
OptionParser#on(*opts) [{...}]

.TP
.fi
.B
OptionParser#def_option(*opts) [{...}]

.TP
.fi
.B
OptionParser#on_head(*opts) [{...}]

.TP
.fi
.B
OptionParser#def_head_option(*opts) [{...}]

.TP
.fi
.B
OptionParser#on_tail(*opts) [{...}]

.TP
.fi
.B
OptionParser#def_tail_option(*opts) [{...}]
Defines option switch and handler. \&\fBon_head\fP, \&\fBdef_head_option\fP
and \&\fBon_tail\fP, \&\fBdef_tail_option\fP put the switch at head
and tail of summary, respectively.

cf. OptionParser#switch.

.TP
.fi
.B
OptionParser#order(*argv) [{...}]

.TP
.fi
.B
OptionParser#order!([argv = ARGV]) [{...}]
Parses argv in order. When non\-option argument encountered,
yields it if called as iterator, otherwise terminates the parse
process.
Returns rest of argv left unparsed.

\&\fBorder!\fP takes argument array itself, and removes switches
destructively.
Defaults to parse ARGV.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
argv

command line arguments to be parsed.


.TP
.fi
.B
\&\fBBlock\fP

called with each non\-option argument.

.TP
.fi
.B
OptionParser#permute(*argv)

.TP
.fi
.B
OptionParser#permute!([argv = ARGV])
Parses argv in permutation mode, and returns list of
non\-option arguments.

\&\fBpermute!\fP takes argument array itself, and removes switches
destructively.
Defaults to parse ARGV.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
argv

command line arguments to be parsed.

.TP
.fi
.B
OptionParser#parse(*argv)

.TP
.fi
.B
OptionParser#parse!([argv = ARGV])
Parses argv in order when environment variable \&\fBPOSIXLY_CORRECT\fP
is set, otherwise permutation mode

\&\fBparse!\fP takes argument array itself, and removes switches
destructively.
Defaults to parse ARGV.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
argv

command line arguments to be parsed.
.SH Acceptable argument classes
.PP

.TP
.fi
.B
Object

any string, and no conversion. this is fall\-back.

.TP
.fi
.B
String

any none\-empty string, and no conversion.

.TP
.fi
.B
Integer

Ruby/C\-like integer, octal for \&\fB0\-7\fP sequence, binary for
\&\fB0b\fP, hexadecimal for \&\fB0x\fP, and decimal for others; with
optional sign prefix. Converts to \&\fBInteger\fP.

.TP
.fi
.B
Float

Float number format, and converts to \&\fBFloat\fP.

.TP
.fi
.B
Numeric

Generic numeric format, and converts to \&\fBInteger\fP for integer
format, \&\fBFloat\fP for float format.

.TP
.fi
.B
OptionParser::DecimalInteger

Decimal integer format, to be converted to \&\fBInteger\fP.

.TP
.fi
.B
OptionParser::OctalInteger

Ruby/C like octal/hexadecimal/binary integer format, to be converted
to \&\fBInteger\fP.

.TP
.fi
.B
OptionParser::DecimalNumeric

Decimal integer/float number format, to be converted to
\&\fBInteger\fP for integer format, \&\fBFloat\fP for float format.

.TP
.fi
.B
TrueClass

Boolean switch, which means whether it is present or not, whether it
is absent or not with prefix \&\fBno\-\fP, or it takes an argument
\&\fByes/no/true/false/+/\-\fP.


.TP
.fi
.B
FalseClass

Similar to TrueClass, but defaulted to \&\fBfalse\fP.

.TP
.fi
.B
Array

List of strings separated by ","
.SH Exceptions
.PP
.SH 
.PP
Base class of exceptions from OptionParser
.SH Superclass
.PP
\&\fBRuntimeError\fP
.SH Constants
.PP

.TP
.fi
.B
OptionParser::ParseError::Reason

Reason caused error.
.SH Instance methods
.PP

.TP
.fi
.B
OptionParser::ParseError#recover(argv)
Push backs erred argument(s) to argv.


.TP
.fi
.B
OptionParser::ParseError#reason
Returns error reason. Override this to I18N.


.TP
.fi
.B
OptionParser::ParseError#inspect
Returns inspection string.


.TP
.fi
.B
OptionParser::ParseError#message

.TP
.fi
.B
OptionParser::ParseError#to_s

.TP
.fi
.B
OptionParser::ParseError#to_str
Default stringizing method to emit standard error message.
.SH 
.PP
Raises when encountered ambiguously completable string.
.SH Superclass
.PP
OptionParser::ParseError
.SH 
.PP
Raises when encountered argument for switch defined as which takes no
argument.
.SH Superclass
.PP
OptionParser::ParseError
.SH 
.PP
Raises when no argument found for switch defined as which needs
argument.
.SH Superclass
.PP
OptionParser::ParseError
.SH 
.PP
Raises when undefined switch.
.SH Superclass
.PP
OptionParser::ParseError
.SH 
.PP
Raises when the given argument does not match required format.
.SH Superclass
.PP
OptionParser::ParseError
.SH 
.PP
Raises when the given argument word can't completed uniquely.
.SH Superclass
.PP
OptionParser::InvalidArgument
.SH Miscellaneous
.PP
.SH 
.PP
Extends command line arguments array to parse itself.

.TP
.fi
.B
OptionParser::Arguable#options=(opt)
Sets OptionParser object, when opt is \&\fBfalse\fP or
\&\fBnil\fP, methods OptionParser::Arguable#options and
OptionParser::Arguable#options= are undefined.  Thus, there
is no ways to access the OptionParser object via the
receiver object.

.TP
.fi
.B
OptionParser::Arguable#options
Actual OptionParser object, automatically created if not
yet.

If called as iterator, yields with the OptionParser object
and returns the result of the block. In this case, rescues any
OptionParser::ParseError exceptions in the block, just emits
error message to STDERR and returns \&\fBnil\fP.


.TP
.fi
.B
Parameters:


.TP
.fi
.B
\&\fBblock\fP

Yielded with the OptionParser instance.

.TP
.fi
.B
OptionParser::Arguable#order!

.TP
.fi
.B
OptionParser::Arguable#permute!

.TP
.fi
.B
OptionParser::Arguable#parse!
Parses self destructively, and returns self just contains
rest arguments left without parsed.
.SH OptionParser::Acceptables
.PP
Acceptable argument classes.  Now contains \&\fBDecimalInteger\fP,
\&\fBOctalInteger\fP and \&\fBDecimalNumeric\fP.
see Acceptable argument classes.