[ruby/optparse] [DOC] Mark up constant and method names as code

https://github.com/ruby/optparse/commit/e8bee0be8f
This commit is contained in:
Nobuyoshi Nakada 2023-07-30 11:24:59 +09:00 committed by git
parent 67be453d9d
commit dfad14d83f
4 changed files with 71 additions and 71 deletions

View File

@ -1,7 +1,7 @@
== Argument Converters == Argument Converters
An option can specify that its argument is to be converted An option can specify that its argument is to be converted
from the default \String to an instance of another class. from the default +String+ to an instance of another class.
=== Contents === Contents
@ -27,13 +27,13 @@ from the default \String to an instance of another class.
=== Built-In Argument Converters === Built-In Argument Converters
\OptionParser has a number of built-in argument converters, +OptionParser+ has a number of built-in argument converters,
which are demonstrated below. which are demonstrated below.
==== \Date ==== +Date+
File +date.rb+ File +date.rb+
defines an option whose argument is to be converted to a \Date object. defines an option whose argument is to be converted to a +Date+ object.
The argument is converted by method Date#parse. The argument is converted by method Date#parse.
:include: ruby/date.rb :include: ruby/date.rb
@ -47,10 +47,10 @@ Executions:
$ ruby date.rb --date "3rd Feb 2001" $ ruby date.rb --date "3rd Feb 2001"
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date] [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
==== \DateTime ==== +DateTime+
File +datetime.rb+ File +datetime.rb+
defines an option whose argument is to be converted to a \DateTime object. defines an option whose argument is to be converted to a +DateTime+ object.
The argument is converted by method DateTime#parse. The argument is converted by method DateTime#parse.
:include: ruby/datetime.rb :include: ruby/datetime.rb
@ -64,10 +64,10 @@ Executions:
$ ruby datetime.rb --datetime "3rd Feb 2001 04:05:06 PM" $ ruby datetime.rb --datetime "3rd Feb 2001 04:05:06 PM"
[#<DateTime: 2001-02-03T16:05:06+00:00 ((2451944j,57906s,0n),+0s,2299161j)>, DateTime] [#<DateTime: 2001-02-03T16:05:06+00:00 ((2451944j,57906s,0n),+0s,2299161j)>, DateTime]
==== \Time ==== +Time+
File +time.rb+ File +time.rb+
defines an option whose argument is to be converted to a \Time object. defines an option whose argument is to be converted to a +Time+ object.
The argument is converted by method Time#httpdate or Time#parse. The argument is converted by method Time#httpdate or Time#parse.
:include: ruby/time.rb :include: ruby/time.rb
@ -79,10 +79,10 @@ Executions:
$ ruby time.rb --time 2010-10-31 $ ruby time.rb --time 2010-10-31
[2010-10-31 00:00:00 -0500, Time] [2010-10-31 00:00:00 -0500, Time]
==== \URI ==== +URI+
File +uri.rb+ File +uri.rb+
defines an option whose argument is to be converted to a \URI object. defines an option whose argument is to be converted to a +URI+ object.
The argument is converted by method URI#parse. The argument is converted by method URI#parse.
:include: ruby/uri.rb :include: ruby/uri.rb
@ -96,10 +96,10 @@ Executions:
$ ruby uri.rb --uri file://~/var $ ruby uri.rb --uri file://~/var
[#<URI::File file://~/var>, URI::File] [#<URI::File file://~/var>, URI::File]
==== \Shellwords ==== +Shellwords+
File +shellwords.rb+ File +shellwords.rb+
defines an option whose argument is to be converted to an \Array object by method defines an option whose argument is to be converted to an +Array+ object by method
Shellwords#shellwords. Shellwords#shellwords.
:include: ruby/shellwords.rb :include: ruby/shellwords.rb
@ -111,10 +111,10 @@ Executions:
$ ruby shellwords.rb --shellwords "here are 'two words'" $ ruby shellwords.rb --shellwords "here are 'two words'"
[["here", "are", "two words"], Array] [["here", "are", "two words"], Array]
==== \Integer ==== +Integer+
File +integer.rb+ File +integer.rb+
defines an option whose argument is to be converted to an \Integer object. defines an option whose argument is to be converted to an +Integer+ object.
The argument is converted by method Kernel#Integer. The argument is converted by method Kernel#Integer.
:include: ruby/integer.rb :include: ruby/integer.rb
@ -132,10 +132,10 @@ Executions:
$ ruby integer.rb --integer 0b100 $ ruby integer.rb --integer 0b100
[4, Integer] [4, Integer]
==== \Float ==== +Float+
File +float.rb+ File +float.rb+
defines an option whose argument is to be converted to a \Float object. defines an option whose argument is to be converted to a +Float+ object.
The argument is converted by method Kernel#Float. The argument is converted by method Kernel#Float.
:include: ruby/float.rb :include: ruby/float.rb
@ -151,11 +151,11 @@ Executions:
$ ruby float.rb --float 1.234E-2 $ ruby float.rb --float 1.234E-2
[0.01234, Float] [0.01234, Float]
==== \Numeric ==== +Numeric+
File +numeric.rb+ File +numeric.rb+
defines an option whose argument is to be converted to an instance defines an option whose argument is to be converted to an instance
of \Rational, \Float, or \Integer. of +Rational+, +Float+, or +Integer+.
The argument is converted by method Kernel#Rational, The argument is converted by method Kernel#Rational,
Kernel#Float, or Kernel#Integer. Kernel#Float, or Kernel#Integer.
@ -170,10 +170,10 @@ Executions:
$ ruby numeric.rb --numeric 3 $ ruby numeric.rb --numeric 3
[3, Integer] [3, Integer]
==== \DecimalInteger ==== +DecimalInteger+
File +decimal_integer.rb+ File +decimal_integer.rb+
defines an option whose argument is to be converted to an \Integer object. defines an option whose argument is to be converted to an +Integer+ object.
The argument is converted by method Kernel#Integer. The argument is converted by method Kernel#Integer.
:include: ruby/decimal_integer.rb :include: ruby/decimal_integer.rb
@ -192,10 +192,10 @@ Executions:
$ ruby decimal_integer.rb --decimal_integer -0100 $ ruby decimal_integer.rb --decimal_integer -0100
[-100, Integer] [-100, Integer]
==== \OctalInteger ==== +OctalInteger+
File +octal_integer.rb+ File +octal_integer.rb+
defines an option whose argument is to be converted to an \Integer object. defines an option whose argument is to be converted to an +Integer+ object.
The argument is converted by method Kernel#Integer. The argument is converted by method Kernel#Integer.
:include: ruby/octal_integer.rb :include: ruby/octal_integer.rb
@ -212,10 +212,10 @@ Executions:
$ ruby octal_integer.rb --octal_integer 0100 $ ruby octal_integer.rb --octal_integer 0100
[64, Integer] [64, Integer]
==== \DecimalNumeric ==== +DecimalNumeric+
File +decimal_numeric.rb+ File +decimal_numeric.rb+
defines an option whose argument is to be converted to an \Integer object. defines an option whose argument is to be converted to an +Integer+ object.
The argument is converted by method Kernel#Integer The argument is converted by method Kernel#Integer
:include: ruby/decimal_numeric.rb :include: ruby/decimal_numeric.rb
@ -232,7 +232,7 @@ Executions:
$ ruby decimal_numeric.rb --decimal_numeric 0100 $ ruby decimal_numeric.rb --decimal_numeric 0100
[64, Integer] [64, Integer]
==== \TrueClass ==== +TrueClass+
File +true_class.rb+ File +true_class.rb+
defines an option whose argument is to be converted to +true+ or +false+. defines an option whose argument is to be converted to +true+ or +false+.
@ -259,7 +259,7 @@ Executions:
$ ruby true_class.rb --true_class nil $ ruby true_class.rb --true_class nil
[false, FalseClass] [false, FalseClass]
==== \FalseClass ==== +FalseClass+
File +false_class.rb+ File +false_class.rb+
defines an option whose argument is to be converted to +true+ or +false+. defines an option whose argument is to be converted to +true+ or +false+.
@ -286,10 +286,10 @@ Executions:
$ ruby false_class.rb --false_class + $ ruby false_class.rb --false_class +
[true, TrueClass] [true, TrueClass]
==== \Object ==== +Object+
File +object.rb+ File +object.rb+
defines an option whose argument is not to be converted from \String. defines an option whose argument is not to be converted from +String+.
:include: ruby/object.rb :include: ruby/object.rb
@ -300,10 +300,10 @@ Executions:
$ ruby object.rb --object nil $ ruby object.rb --object nil
["nil", String] ["nil", String]
==== \String ==== +String+
File +string.rb+ File +string.rb+
defines an option whose argument is not to be converted from \String. defines an option whose argument is not to be converted from +String+.
:include: ruby/string.rb :include: ruby/string.rb
@ -314,10 +314,10 @@ Executions:
$ ruby string.rb --string nil $ ruby string.rb --string nil
["nil", String] ["nil", String]
==== \Array ==== +Array+
File +array.rb+ File +array.rb+
defines an option whose argument is to be converted from \String defines an option whose argument is to be converted from +String+
to an array of strings, based on comma-separated substrings. to an array of strings, based on comma-separated substrings.
:include: ruby/array.rb :include: ruby/array.rb
@ -331,10 +331,10 @@ Executions:
$ ruby array.rb --array "foo, bar, baz" $ ruby array.rb --array "foo, bar, baz"
[["foo", " bar", " baz"], Array] [["foo", " bar", " baz"], Array]
==== \Regexp ==== +Regexp+
File +regexp.rb+ File +regexp.rb+
defines an option whose argument is to be converted to a \Regexp object. defines an option whose argument is to be converted to a +Regexp+ object.
:include: ruby/regexp.rb :include: ruby/regexp.rb
@ -352,7 +352,7 @@ To create a custom converter, call OptionParser#accept with:
- A block that accepts the argument and returns the converted value. - A block that accepts the argument and returns the converted value.
This custom converter accepts any argument and converts it, This custom converter accepts any argument and converts it,
if possible, to a \Complex object. if possible, to a +Complex+ object.
:include: ruby/custom_converter.rb :include: ruby/custom_converter.rb

View File

@ -1,6 +1,6 @@
== Parameters for New Options == Parameters for New Options
Option-creating methods in \OptionParser Option-creating methods in +OptionParser+
accept arguments that determine the behavior of a new option: accept arguments that determine the behavior of a new option:
- OptionParser#on - OptionParser#on
@ -405,7 +405,7 @@ Executions:
=== Argument Converters === Argument Converters
An option can specify that its argument is to be converted An option can specify that its argument is to be converted
from the default \String to an instance of another class. from the default +String+ to an instance of another class.
There are a number of built-in converters. There are a number of built-in converters.
You can also define custom converters. You can also define custom converters.

View File

@ -1,10 +1,10 @@
== Tutorial == Tutorial
=== Why \OptionParser? === Why +OptionParser+?
When a Ruby program executes, it captures its command-line arguments When a Ruby program executes, it captures its command-line arguments
and options into variable ARGV. and options into variable ARGV.
This simple program just prints its \ARGV: This simple program just prints its +ARGV+:
:include: ruby/argv.rb :include: ruby/argv.rb
@ -18,7 +18,7 @@ the command-line options.
OptionParser offers methods for parsing and handling those options. OptionParser offers methods for parsing and handling those options.
With \OptionParser, you can define options so that for each option: With +OptionParser+, you can define options so that for each option:
- The code that defines the option and code that handles that option - The code that defines the option and code that handles that option
are in the same place. are in the same place.
@ -66,10 +66,10 @@ The class also has method #help, which displays automatically-generated help tex
=== To Begin With === To Begin With
To use \OptionParser: To use +OptionParser+:
1. Require the \OptionParser code. 1. Require the +OptionParser+ code.
2. Create an \OptionParser object. 2. Create an +OptionParser+ object.
3. Define one or more options. 3. Define one or more options.
4. Parse the command line. 4. Parse the command line.
@ -92,9 +92,9 @@ the block defined for the option is called with the argument value.
An invalid option raises an exception. An invalid option raises an exception.
Method #parse!, which is used most often in this tutorial, Method #parse!, which is used most often in this tutorial,
removes from \ARGV the options and arguments it finds, removes from +ARGV+ the options and arguments it finds,
leaving other non-option arguments for the program to handle on its own. leaving other non-option arguments for the program to handle on its own.
The method returns the possibly-reduced \ARGV array. The method returns the possibly-reduced +ARGV+ array.
Executions: Executions:
@ -115,7 +115,7 @@ Executions:
=== Defining Options === Defining Options
A common way to define an option in \OptionParser A common way to define an option in +OptionParser+
is with instance method OptionParser#on. is with instance method OptionParser#on.
The method may be called with any number of arguments The method may be called with any number of arguments
@ -522,11 +522,11 @@ Executions:
=== Argument Converters === Argument Converters
An option can specify that its argument is to be converted An option can specify that its argument is to be converted
from the default \String to an instance of another class. from the default +String+ to an instance of another class.
There are a number of built-in converters. There are a number of built-in converters.
Example: File +date.rb+ Example: File +date.rb+
defines an option whose argument is to be converted to a \Date object. defines an option whose argument is to be converted to a +Date+ object.
The argument is converted by method Date#parse. The argument is converted by method Date#parse.
:include: ruby/date.rb :include: ruby/date.rb
@ -546,7 +546,7 @@ for both built-in and custom converters.
=== Help === Help
\OptionParser makes automatically generated help text available. +OptionParser+ makes automatically generated help text available.
The help text consists of: The help text consists of:
@ -614,16 +614,16 @@ Execution:
=== Top List and Base List === Top List and Base List
An \OptionParser object maintains a stack of \OptionParser::List objects, An +OptionParser+ object maintains a stack of +OptionParser::List+ objects,
each of which has a collection of zero or more options. each of which has a collection of zero or more options.
It is unlikely that you'll need to add or take away from that stack. It is unlikely that you'll need to add or take away from that stack.
The stack includes: The stack includes:
- The <em>top list</em>, given by \OptionParser#top. - The <em>top list</em>, given by +OptionParser#top+.
- The <em>base list</em>, given by \OptionParser#base. - The <em>base list</em>, given by +OptionParser#base+.
When \OptionParser builds its help text, the options in the top list When +OptionParser+ builds its help text, the options in the top list
precede those in the base list. precede those in the base list.
=== Defining Options === Defining Options
@ -632,31 +632,31 @@ Option-defining methods allow you to create an option, and also append/prepend i
to the top list or append it to the base list. to the top list or append it to the base list.
Each of these next three methods accepts a sequence of parameter arguments and a block, Each of these next three methods accepts a sequence of parameter arguments and a block,
creates an option object using method \Option#make_switch (see below), creates an option object using method +Option#make_switch+ (see below),
and returns the created option: and returns the created option:
- \Method \OptionParser#define appends the created option to the top list. - \Method +OptionParser#define+ appends the created option to the top list.
- \Method \OptionParser#define_head prepends the created option to the top list. - \Method +OptionParser#define_head+ prepends the created option to the top list.
- \Method \OptionParser#define_tail appends the created option to the base list. - \Method +OptionParser#define_tail+ appends the created option to the base list.
These next three methods are identical to the three above, These next three methods are identical to the three above,
except for their return values: except for their return values:
- \Method \OptionParser#on is identical to method \OptionParser#define, - \Method +OptionParser#on+ is identical to method +OptionParser#define+,
except that it returns the parser object +self+. except that it returns the parser object +self+.
- \Method \OptionParser#on_head is identical to method \OptionParser#define_head, - \Method +OptionParser#on_head+ is identical to method +OptionParser#define_head+,
except that it returns the parser object +self+. except that it returns the parser object +self+.
- \Method \OptionParser#on_tail is identical to method \OptionParser#define_tail, - \Method +OptionParser#on_tail+ is identical to method +OptionParser#define_tail+,
except that it returns the parser object +self+. except that it returns the parser object +self+.
Though you may never need to call it directly, Though you may never need to call it directly,
here's the core method for defining an option: here's the core method for defining an option:
- \Method \OptionParser#make_switch accepts an array of parameters and a block. - \Method +OptionParser#make_switch+ accepts an array of parameters and a block.
See {Parameters for New Options}[optparse/option_params.rdoc]. See {Parameters for New Options}[optparse/option_params.rdoc].
This method is unlike others here in that it: This method is unlike others here in that it:
- Accepts an <em>array of parameters</em>; - Accepts an <em>array of parameters</em>;
@ -668,7 +668,7 @@ here's the core method for defining an option:
=== Parsing === Parsing
\OptionParser has six instance methods for parsing. +OptionParser+ has six instance methods for parsing.
Three have names ending with a "bang" (<tt>!</tt>): Three have names ending with a "bang" (<tt>!</tt>):
@ -699,9 +699,9 @@ Each of these methods:
(see {Keyword Argument into}[#label-Keyword+Argument+into]). (see {Keyword Argument into}[#label-Keyword+Argument+into]).
- Returns +argv+, possibly with some elements removed. - Returns +argv+, possibly with some elements removed.
==== \Method parse! ==== \Method +parse!+
\Method parse!: \Method +parse!+:
- Accepts an optional array of string arguments +argv+; - Accepts an optional array of string arguments +argv+;
if not given, +argv+ defaults to the value of OptionParser#default_argv, if not given, +argv+ defaults to the value of OptionParser#default_argv,
@ -756,9 +756,9 @@ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined:
["--xxx", true] ["--xxx", true]
Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array) Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)
==== \Method parse ==== \Method +parse+
\Method parse: \Method +parse+:
- Accepts an array of string arguments - Accepts an array of string arguments
_or_ zero or more string arguments. _or_ zero or more string arguments.
@ -810,25 +810,25 @@ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined:
["--xxx", true] ["--xxx", true]
Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array) Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)
==== \Method order! ==== \Method +order!+
Calling method OptionParser#order! gives exactly the same result as Calling method OptionParser#order! gives exactly the same result as
calling method OptionParser#parse! with environment variable calling method OptionParser#parse! with environment variable
+POSIXLY_CORRECT+ defined. +POSIXLY_CORRECT+ defined.
==== \Method order ==== \Method +order+
Calling method OptionParser#order gives exactly the same result as Calling method OptionParser#order gives exactly the same result as
calling method OptionParser#parse with environment variable calling method OptionParser#parse with environment variable
+POSIXLY_CORRECT+ defined. +POSIXLY_CORRECT+ defined.
==== \Method permute! ==== \Method +permute!+
Calling method OptionParser#permute! gives exactly the same result as Calling method OptionParser#permute! gives exactly the same result as
calling method OptionParser#parse! with environment variable calling method OptionParser#parse! with environment variable
+POSIXLY_CORRECT+ _not_ defined. +POSIXLY_CORRECT+ _not_ defined.
==== \Method permute ==== \Method +permute+
Calling method OptionParser#permute gives exactly the same result as Calling method OptionParser#permute gives exactly the same result as
calling method OptionParser#parse with environment variable calling method OptionParser#parse with environment variable

View File

@ -48,7 +48,7 @@
# #
# == OptionParser # == OptionParser
# #
# === New to \OptionParser? # === New to +OptionParser+?
# #
# See the {Tutorial}[optparse/tutorial.rdoc]. # See the {Tutorial}[optparse/tutorial.rdoc].
# #