Skip to content

Commit 84dfd92

Browse files
BurdetteLamarBurdetteLamar
authored
More on tutorial (#9)
* More on tutorial * More on tutorial * More on tutorial * More on tutorial: clearer example output
1 parent d14bf83 commit 84dfd92

File tree

10 files changed

+133
-54
lines changed

10 files changed

+133
-54
lines changed

‎doc/ruby/long_names.rb

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎doc/ruby/mixed_names.rb

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎doc/ruby/short_names.rb

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎doc/ruby/argv.rb renamed to ‎doc/tutorial/argv.rb

File renamed without changes.

‎doc/tutorial/long_names.rb

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('--xxx') do |value|
4+
p ['-xxx', value]
5+
end
6+
parser.on('--y1%', '--z2#') do |value|
7+
p ['--y1% or --z2#', value]
8+
end
9+
parser.parse!

‎doc/tutorial/mixed_names.rb

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x', '--xxx') do |value|
4+
p ['--xxx', value]
5+
end
6+
parser.on('-y', '--y1%') do |value|
7+
p ['--y1%', value]
8+
end
9+
parser.parse!

‎doc/tutorial/optional_argument.rb

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x [XXX]', '--xxx') do |value|
4+
p ['--xxx', value]
5+
end
6+
parser.on('-y', '--yyy [YYY]') do |value|
7+
p ['--yyy', value]
8+
end
9+
parser.parse!

‎doc/tutorial/required_argument.rb

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x XXX', '--xxx') do |value|
4+
p ['--xxx', value]
5+
end
6+
parser.on('-y', '--y YYY') do |value|
7+
p ['--yyy', value]
8+
end
9+
parser.parse!

‎doc/tutorial/short_names.rb

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x') do |value|
4+
p ['x', value]
5+
end
6+
parser.on('-1', '-%') do |value|
7+
p ['-1 or -%', value]
8+
end
9+
parser.parse!

‎doc/tutorial.rdoc renamed to ‎doc/tutorial/tutorial.rdoc

Lines changed: 88 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ When a Ruby program executes, it captures its command-line arguments
66
and options into variable ARGV.
77
This simple program just prints its \ARGV:
88

9-
:include: ruby/argv.rb
9+
:include: argv.rb
1010

1111
Execution, with arguments and options:
1212

13-
$ ruby doc/ruby/argv.rb foo --bar --baz bat bam
13+
$ ruby argv.rb foo --bar --baz bat bam
1414
["foo", "--bar", "--baz", "bat", "bam"]
1515

1616
The executing program is responsible for parsing and handling
@@ -27,8 +27,10 @@ With \OptionParser, you can define options so that for each option:
2727
- The argument may be restricted to specified _forms_.
2828
- The argument may be restricted to specified _values_.
2929

30-
The class also has a method #summarize that returns a string summary
31-
of all defined options.
30+
The class also has:
31+
32+
- Method #summarize: returns a text summary of the options.
33+
- Method #help: displays automatically-generated help text.
3234

3335
=== Defining Options
3436

@@ -65,23 +67,28 @@ File +short_names.rb+
6567
defines an option with a short name, <tt>-x</tt>,
6668
and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
6769

68-
:include: ruby/short_names.rb
70+
:include: short_names.rb
6971

7072
Executions:
7173

72-
$ ruby doc/ruby/short_names.rb -x
73-
"-x true"
74-
$ ruby doc/ruby/short_names.rb -1
75-
"-1 or -% true"
76-
$ ruby doc/ruby/short_names.rb -%
77-
"-1 or -% true"
74+
$ ruby short_names.rb -x
75+
["x", true]
76+
$ ruby short_names.rb -1
77+
["-1 or -%", true]
78+
$ ruby short_names.rb -%
79+
["-1 or -%", true]
7880

7981
Multiple short names can "share" a hyphen:
8082

8183
$ ruby short_names.rb -x1%
82-
"-x true"
83-
"-1 or -% true"
84-
"-1 or -% true"
84+
["x", true]
85+
["-1 or -%", true]
86+
["-1 or -%", true]
87+
88+
This is a good time to note that giving an undefined option raises an exception:
89+
90+
$ ruby short_names.rb -z
91+
short_names.rb:9:in `<main>': invalid option: -z (OptionParser::InvalidOption)
8592

8693
==== Long Option Names
8794

@@ -92,16 +99,16 @@ File +long_names.rb+
9299
defines an option with a long name, <tt>--xxx</tt>,
93100
and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
94101

95-
:include: ruby/long_names.rb
102+
:include: long_names.rb
96103

97104
Executions:
98105

99106
$ ruby long_names.rb --xxx
100-
"--xxx true"
107+
["-xxx", true]
101108
$ ruby long_names.rb --y1%
102-
"--y1% or -z2# true"
109+
["--y1% or --z2#", true]
103110
$ ruby long_names.rb --z2#
104-
"--y1% or -z2# true"
111+
["--y1% or --z2#", true]
105112

106113
==== Mixing Option Names
107114

@@ -111,15 +118,69 @@ so that a short name is in effect an abbreviation of a long name.
111118
File +mixed_names.rb+
112119
defines options that each have both a short and a long name.
113120

114-
:include: ruby/mixed_names.rb
121+
:include: mixed_names.rb
122+
123+
Executions:
124+
125+
$ ruby mixed_names.rb -x
126+
["--xxx", true]
127+
$ ruby mixed_names.rb --xxx
128+
["--xxx", true]
129+
$ ruby mixed_names.rb -y
130+
["--y1%", true]
131+
$ ruby mixed_names.rb --y1%
132+
["--y1%", true]
133+
134+
=== Option Arguments
135+
136+
An option may take no argument, a required argument, or an optional argument.
137+
138+
==== Option with No Argument
139+
140+
All the examples above define options with no argument.
141+
142+
==== Option with Required Argument
143+
144+
Specify a required argument for an option by adding a dummy word
145+
to its name definition.
146+
147+
File +required_argument.rb+ defines two options;
148+
each has a required argument because the name definition has a following dummy word.
149+
150+
:include: required_argument.rb
151+
152+
When an option is found, the given argument is yielded.
115153

116154
Executions:
117155

118-
$ ruby doc/ruby/mixed_names.rb -x
119-
"--xxx true"
120-
$ ruby doc/ruby/mixed_names.rb --xxx
121-
"--xxx true"
122-
$ ruby doc/ruby/mixed_names.rb -y
123-
"--y1% true"
124-
$ ruby doc/ruby/mixed_names.rb --y1%
125-
"--y1% true"
156+
$ ruby required_argument.rb -x AAA
157+
["--xxx", "AAA"]
158+
$ ruby required_argument.rb -y BBB
159+
["--yyy", "BBB"]
160+
161+
Omitting a required argument raises an error:
162+
163+
$ ruby required_argument.rb -x
164+
required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
165+
166+
==== Option with Optional Argument
167+
168+
Specify an optional argument for an option by adding a dummy word
169+
enclosed in square brackets to its name definition.
170+
171+
File +optional_argument.rb+ defines two options;
172+
each has an optional argument because the name definition has a following dummy word
173+
in square brackets.
174+
175+
:include: optional_argument.rb
176+
177+
When an option with an argument is found, the given argument yielded.
178+
179+
Executions:
180+
181+
$ ruby optional_argument.rb -x AAA
182+
["--xxx", "AAA"]
183+
$ ruby optional_argument.rb -y BBB
184+
["--yyy", "BBB"]
185+
186+
Omitting an optional argument does not raise an error.

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy