-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Resolve shared mixed_names.rb * Add long option with negation * Show --help for all examples * Table of contents for tutorial * Move argument converters to separate rdoc * Add references to argument_converters.rdoc * Tune up argument converters * Change explicit links to auto-links
- Loading branch information
1 parent
9a2352c
commit c91ed8d
Showing
10 changed files
with
487 additions
and
365 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,362 @@ | ||
== Argument Converters | ||
|
||
An option can specify that its argument is to be converted | ||
from the default \String to an instance of another class. | ||
|
||
=== Contents | ||
|
||
- {Built-In Argument Converters}[#label-Built-In+Argument+Converters] | ||
- {Date}[#label-Date] | ||
- {DateTime}[#label-DateTime] | ||
- {Time}[#label-Time] | ||
- {URI}[#label-URI] | ||
- {Shellwords}[#label-Shellwords] | ||
- {Integer}[#label-Integer] | ||
- {Float}[#label-Float] | ||
- {Numeric}[#label-Numeric] | ||
- {DecimalInteger}[#label-DecimalInteger] | ||
- {OctalInteger}[#label-OctalInteger] | ||
- {DecimalNumeric}[#label-DecimalNumeric] | ||
- {TrueClass}[#label-TrueClass] | ||
- {FalseClass}[#label-FalseClass] | ||
- {Object}[#label-Object] | ||
- {String}[#label-String] | ||
- {Array}[#label-Array] | ||
- {Regexp}[#label-Regexp] | ||
- {Custom Argument Converters}[#label-Custom+Argument+Converters] | ||
|
||
=== Built-In Argument Converters | ||
|
||
\OptionParser has a number of built-in argument converters, | ||
which are demonstrated below. | ||
|
||
==== \Date | ||
|
||
File +date.rb+ | ||
defines an option whose argument is to be converted to a \Date object. | ||
The argument is converted by method Date#parse. | ||
|
||
:include: ruby/date.rb | ||
|
||
Executions: | ||
|
||
$ ruby date.rb --date 2001-02-03 | ||
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date] | ||
$ ruby date.rb --date 20010203 | ||
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date] | ||
$ ruby date.rb --date "3rd Feb 2001" | ||
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date] | ||
|
||
==== \DateTime | ||
|
||
File +datetime.rb+ | ||
defines an option whose argument is to be converted to a \DateTime object. | ||
The argument is converted by method DateTime#parse. | ||
|
||
:include: ruby/datetime.rb | ||
|
||
Executions: | ||
|
||
$ ruby datetime.rb --datetime 2001-02-03T04:05:06+07:00 | ||
[#<DateTime: 2001-02-03T04:05:06+07:00 ((2451943j,75906s,0n),+25200s,2299161j)>, DateTime] | ||
$ ruby datetime.rb --datetime 20010203T040506+0700 | ||
[#<DateTime: 2001-02-03T04:05:06+07:00 ((2451943j,75906s,0n),+25200s,2299161j)>, DateTime] | ||
$ 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] | ||
|
||
==== \Time | ||
|
||
File +time.rb+ | ||
defines an option whose argument is to be converted to a \Time object. | ||
The argument is converted by method Time#httpdate or Time#parse. | ||
|
||
:include: ruby/time.rb | ||
|
||
Executions: | ||
|
||
$ ruby time.rb --time "Thu, 06 Oct 2011 02:26:12 GMT" | ||
[2011-10-06 02:26:12 UTC, Time] | ||
$ ruby time.rb --time 2010-10-31 | ||
[2010-10-31 00:00:00 -0500, Time] | ||
|
||
==== \URI | ||
|
||
File +uri.rb+ | ||
defines an option whose argument is to be converted to a \URI object. | ||
The argument is converted by method URI#parse. | ||
|
||
:include: ruby/uri.rb | ||
|
||
Executions: | ||
|
||
$ ruby uri.rb --uri https://github.com | ||
[#<URI::HTTPS https://github.com>, URI::HTTPS] | ||
$ ruby uri.rb --uri http://github.com | ||
[#<URI::HTTP http://github.com>, URI::HTTP] | ||
$ ruby uri.rb --uri file://~/var | ||
[#<URI::File file://~/var>, URI::File] | ||
|
||
==== \Shellwords | ||
|
||
File +shellwords.rb+ | ||
defines an option whose argument is to be converted to an \Array object by method | ||
Shellwords#shellwords. | ||
|
||
:include: ruby/shellwords.rb | ||
|
||
Executions: | ||
|
||
$ ruby shellwords.rb --shellwords "ruby my_prog.rb | less" | ||
[["ruby", "my_prog.rb", "|", "less"], Array] | ||
$ ruby shellwords.rb --shellwords "here are 'two words'" | ||
[["here", "are", "two words"], Array] | ||
|
||
==== \Integer | ||
|
||
File +integer.rb+ | ||
defines an option whose argument is to be converted to an \Integer object. | ||
The argument is converted by method Kernel#Integer. | ||
|
||
:include: ruby/integer.rb | ||
|
||
Executions: | ||
|
||
$ ruby integer.rb --integer 100 | ||
[100, Integer] | ||
$ ruby integer.rb --integer -100 | ||
[-100, Integer] | ||
$ ruby integer.rb --integer 0100 | ||
[64, Integer] | ||
$ ruby integer.rb --integer 0x100 | ||
[256, Integer] | ||
$ ruby integer.rb --integer 0b100 | ||
[4, Integer] | ||
|
||
==== \Float | ||
|
||
File +float.rb+ | ||
defines an option whose argument is to be converted to a \Float object. | ||
The argument is converted by method Kernel#Float. | ||
|
||
:include: ruby/float.rb | ||
|
||
Executions: | ||
|
||
$ ruby float.rb --float 1 | ||
[1.0, Float] | ||
$ ruby float.rb --float 3.14159 | ||
[3.14159, Float] | ||
$ ruby float.rb --float 1.234E2 | ||
[123.4, Float] | ||
$ ruby float.rb --float 1.234E-2 | ||
[0.01234, Float] | ||
|
||
==== \Numeric | ||
|
||
File +numeric.rb+ | ||
defines an option whose argument is to be converted to an instance | ||
of \Rational, \Float, or \Integer. | ||
The argument is converted by method Kernel#Rational, | ||
Kernel#Float, or Kernel#Integer. | ||
|
||
:include: ruby/numeric.rb | ||
|
||
Executions: | ||
|
||
$ ruby numeric.rb --numeric 1/3 | ||
[(1/3), Rational] | ||
$ ruby numeric.rb --numeric 3.333E-1 | ||
[0.3333, Float] | ||
$ ruby numeric.rb --numeric 3 | ||
[3, Integer] | ||
|
||
==== \DecimalInteger | ||
|
||
File +decimal_integer.rb+ | ||
defines an option whose argument is to be converted to an \Integer object. | ||
The argument is converted by method Kernel#Integer. | ||
|
||
:include: ruby/decimal_integer.rb | ||
|
||
The argument may not be in a binary or hexadecimal format; | ||
a leading zero is ignored (not parsed as octal). | ||
|
||
Executions: | ||
|
||
$ ruby decimal_integer.rb --decimal_integer 100 | ||
[100, Integer] | ||
$ ruby decimal_integer.rb --decimal_integer -100 | ||
[-100, Integer] | ||
$ ruby decimal_integer.rb --decimal_integer 0100 | ||
[100, Integer] | ||
$ ruby decimal_integer.rb --decimal_integer -0100 | ||
[-100, Integer] | ||
|
||
==== \OctalInteger | ||
|
||
File +octal_integer.rb+ | ||
defines an option whose argument is to be converted to an \Integer object. | ||
The argument is converted by method Kernel#Integer. | ||
|
||
:include: ruby/octal_integer.rb | ||
|
||
The argument may not be in a binary or hexadecimal format; | ||
it is parsed as octal, regardless of whether it has a leading zero. | ||
|
||
Executions: | ||
|
||
$ ruby octal_integer.rb --octal_integer 100 | ||
[64, Integer] | ||
$ ruby octal_integer.rb --octal_integer -100 | ||
[-64, Integer] | ||
$ ruby octal_integer.rb --octal_integer 0100 | ||
[64, Integer] | ||
|
||
==== \DecimalNumeric | ||
|
||
File +decimal_numeric.rb+ | ||
defines an option whose argument is to be converted to an \Integer object. | ||
The argument is converted by method {Kernel#Integer | ||
|
||
:include: ruby/decimal_numeric.rb | ||
|
||
The argument may not be in a binary or hexadecimal format; | ||
a leading zero causes the argument to be parsed as octal. | ||
|
||
Executions: | ||
|
||
$ ruby decimal_numeric.rb --decimal_numeric 100 | ||
[100, Integer] | ||
$ ruby decimal_numeric.rb --decimal_numeric -100 | ||
[-100, Integer] | ||
$ ruby decimal_numeric.rb --decimal_numeric 0100 | ||
[64, Integer] | ||
|
||
==== \TrueClass | ||
|
||
File +true_class.rb+ | ||
defines an option whose argument is to be converted to +true+ or +false+. | ||
The argument is evaluated by method Object#nil?. | ||
|
||
:include: ruby/true_class.rb | ||
|
||
The argument may be any of those shown in the examples below. | ||
|
||
Executions: | ||
|
||
$ ruby true_class.rb --true_class true | ||
[true, TrueClass] | ||
$ ruby true_class.rb --true_class yes | ||
[true, TrueClass] | ||
$ ruby true_class.rb --true_class + | ||
[true, TrueClass] | ||
$ ruby true_class.rb --true_class false | ||
[false, FalseClass] | ||
$ ruby true_class.rb --true_class no | ||
[false, FalseClass] | ||
$ ruby true_class.rb --true_class - | ||
[false, FalseClass] | ||
$ ruby true_class.rb --true_class nil | ||
[false, FalseClass] | ||
|
||
==== \FalseClass | ||
|
||
File +false_class.rb+ | ||
defines an option whose argument is to be converted to +true+ or +false+. | ||
The argument is evaluated by method Object#nil?. | ||
|
||
:include: ruby/false_class.rb | ||
|
||
The argument may be any of those shown in the examples below. | ||
|
||
Executions: | ||
|
||
$ ruby false_class.rb --false_class false | ||
[false, FalseClass] | ||
$ ruby false_class.rb --false_class no | ||
[false, FalseClass] | ||
$ ruby false_class.rb --false_class - | ||
[false, FalseClass] | ||
$ ruby false_class.rb --false_class nil | ||
[false, FalseClass] | ||
$ ruby false_class.rb --false_class true | ||
[true, TrueClass] | ||
$ ruby false_class.rb --false_class yes | ||
[true, TrueClass] | ||
$ ruby false_class.rb --false_class + | ||
[true, TrueClass] | ||
|
||
==== \Object | ||
|
||
File +object.rb+ | ||
defines an option whose argument is not to be converted from \String. | ||
|
||
:include: ruby/object.rb | ||
|
||
Executions: | ||
|
||
$ ruby object.rb --object foo | ||
["foo", String] | ||
$ ruby object.rb --object nil | ||
["nil", String] | ||
|
||
==== \String | ||
|
||
File +string.rb+ | ||
defines an option whose argument is not to be converted from \String. | ||
|
||
:include: ruby/string.rb | ||
|
||
Executions: | ||
|
||
$ ruby string.rb --string foo | ||
["foo", String] | ||
$ ruby string.rb --string nil | ||
["nil", String] | ||
|
||
==== \Array | ||
|
||
File +array.rb+ | ||
defines an option whose argument is to be converted from \String | ||
to an array of strings, based on comma-separated substrings. | ||
|
||
:include: ruby/array.rb | ||
|
||
Executions: | ||
|
||
$ ruby array.rb --array "" | ||
[[], Array] | ||
$ ruby array.rb --array foo,bar,baz | ||
[["foo", "bar", "baz"], Array] | ||
$ ruby array.rb --array "foo, bar, baz" | ||
[["foo", " bar", " baz"], Array] | ||
|
||
==== \Regexp | ||
|
||
File +regexp.rb+ | ||
defines an option whose argument is to be converted to a \Regexp object. | ||
|
||
:include: ruby/regexp.rb | ||
|
||
Executions: | ||
|
||
$ ruby regexp.rb --regexp foo | ||
|
||
=== Custom Argument Converters | ||
|
||
You can create custom argument converters. | ||
To create a custom converter, call OptionParser#accept with a class argument, | ||
along with a block that converts the argument and returns the converted value. | ||
|
||
:include: ruby/custom_converter.rb | ||
|
||
Executions: | ||
|
||
$ ruby custom_converter.rb --complex 0 | ||
[(0+0i), Complex] | ||
$ ruby custom_converter.rb --complex 1 | ||
[(1+0i), Complex] | ||
$ ruby custom_converter.rb --complex 1+2i | ||
[(1+2i), Complex] | ||
$ ruby custom_converter.rb --complex 0.3-0.5i | ||
[(0.3-0.5i), Complex] |
Oops, something went wrong.