10000 Beginnings of tutorial · ruby/optparse@f209276 · GitHub
[go: up one dir, main page]
Skip to content

Commit f209276

Browse files
BurdetteLamarnobu
BurdetteLamar
authored and
nobu
committed
Beginnings of tutorial
1 parent 4a70d8d commit f209276

File tree

6 files changed

+155
-1
lines changed

6 files changed

+155
-1
lines changed

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
/.yardoc
33
/_yardoc/
44
/coverage/
5-
/doc/
5+
/rdoc/
66
/logs/
77
/pkg/
88
/spec/reports/

‎doc/ruby/argv.rb

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
p ARGV
2+

‎doc/ruby/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 |option|
4+
p "--xxx #{option}"
5+
end
6+
parser.on('--y1%', '--z2#') do |option|
7+
p "--y1% or --z2# #{option}"
8+
end
9+
parser.parse!

‎doc/ruby/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 |option|
4+
p "--xxx #{option}"
5+
end
6+
parser.on('-y', '--y1%') do |option|
7+
p "--y1% #{option}"
8+
end
9+
parser.parse!

‎doc/ruby/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 |option|
4+
p "-x #{option}"
5+
end
6+
parser.on('-1', '-%') do |option|
7+
p "-1 or -% #{option}"
8+
end
9+
parser.parse!

‎doc/tutorial.rdoc

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
== Tutorial
2+
3+
=== Why OptionParser?
4+
5+
When a Ruby program executes, it captures its command-line arguments
6+
and options into variable ARGV.
7+
This simple program just prints its \ARGV:
8+
9+
:include: ruby/argv.rb
10+
11+
Execution, with arguments and options:
12+
13+
$ ruby doc/ruby/argv.rb foo --bar --baz bat bam
14+
["foo", "--bar", "--baz", "bat", "bam"]
15+
16+
The executing program is responsible for parsing and handling
17+
the command-line options.
18+
19+
OptionParser offers methods for parsing and handling those options.
20+
21+
With \OptionParser, you can define options so that for each option:
22+
23+
- The code that defines the option and code that handles that option
24+
are in the same place.
25+
- The option may take no argument, a required argument, or an optional argument.
26+
- The argument may be automatically converted to a specified class.
27+
- The argument may be restricted to specified _forms_.
28+
- The argument may be restricted to specified _values_.
29+
30+
The class also has a method #summarize that returns a string summary
31+
of all defined options.
32+
33+
=== Defining Options
34+
35+
A common way to define an option in \OptionParser
36+
is with instance method OptionParser#on.
37+
38+
The method may be called with any number of arguments
39+
(whose order does not matter),
40+
and may also have a trailing optional keyword argument +into+.
41+
42+
The given arguments determine the characteristics of the new option.
43+
These may include:
44+
45+
- One or more short option names.
46+
- One or more long option names.
47+
- Whether the option takes no argument, an optional argument, or a required argument.
48+
- Acceptable _forms_ for the argument.
49+
- Acceptable _values_ for the argument.
50+
- A proc or method to be called when the parser encounters the option.
51+
- String descriptions for the option.
52+
53+
=== Option Names
54+
55+
You can give an option one or more names of two types:
56+
57+
- Short (1-character) name, beginning with one hyphen (<tt>-</tt>).
58+
- Long (multi-character) name, beginning with two hyphens (<tt>--</tt>).
59+
60+
==== Short Option Names
61+
62+
A short option name consists of a hyphen and a single character.
63+
64+
File +short_names.rb+
65+
defines an option with a short name, <tt>-x</tt>,
66+
and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
67+
68+
:include: ruby/short_names.rb
69+
70+
Executions:
71+
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"
78+
79+
Multiple short names can "share" a hyphen:
80+
81+
$ ruby short_names.rb -x1%
82+
"-x true"
83+
"-1 or -% true"
84+
"-1 or -% true"
85+
86+
==== Long Option Names
87+
88+
A long option name consists of two hyphens and a one or more characters
89+
(usually two or more characters).
90+
91+
File +long_names.rb+
92+
defines an option with a long name, <tt>--xxx</tt>,
93+
and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
94+
95+
:include: ruby/long_names.rb
96+
97+
Executions:
98+
99+
$ ruby long_names.rb --xxx
100+
"--xxx true"
101+
$ ruby long_names.rb --y1%
102+
"--y1% or -z2# true"
103+
$ ruby long_names.rb --z2#
104+
"--y1% or -z2# true"
105+
106+
==== Mixing Option Names
107+
108+
Many developers like to mix short and long option names,
109+
so that a short name is in effect an abbreviation of a long name.
110+
111+
File +mixed_names.rb+
112+
defines options that each have both a short and a long name.
113+
114+
:include: ruby/mixed_names.rb
115+
116+
Executions:
117+
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"

0 commit comments

Comments
 (0)
0