summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ruby/long_names.rb9
-rw-r--r--doc/ruby/mixed_names.rb9
-rw-r--r--doc/ruby/short_names.rb9
-rw-r--r--doc/tutorial/argv.rb (renamed from doc/ruby/argv.rb)0
-rw-r--r--doc/tutorial/long_names.rb9
-rw-r--r--doc/tutorial/mixed_names.rb9
-rw-r--r--doc/tutorial/optional_argument.rb9
-rw-r--r--doc/tutorial/required_argument.rb9
-rw-r--r--doc/tutorial/short_names.rb9
-rw-r--r--doc/tutorial/tutorial.rdoc (renamed from doc/tutorial.rdoc)115
10 files changed, 133 insertions, 54 deletions
diff --git a/doc/ruby/long_names.rb b/doc/ruby/long_names.rb
deleted file mode 100644
index e36152d097..0000000000
--- a/doc/ruby/long_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--xxx') do |option|
- p "--xxx #{option}"
-end
-parser.on('--y1%', '--z2#') do |option|
- p "--y1% or --z2# #{option}"
-end
-parser.parse!
diff --git a/doc/ruby/mixed_names.rb b/doc/ruby/mixed_names.rb
deleted file mode 100644
index b8f3ac9819..0000000000
--- a/doc/ruby/mixed_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x', '--xxx') do |option|
- p "--xxx #{option}"
-end
-parser.on('-y', '--y1%') do |option|
- p "--y1% #{option}"
-end
-parser.parse!
diff --git a/doc/ruby/short_names.rb b/doc/ruby/short_names.rb
deleted file mode 100644
index 0dc35b789b..0000000000
--- a/doc/ruby/short_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x') do |option|
- p "-x #{option}"
-end
-parser.on('-1', '-%') do |option|
- p "-1 or -% #{option}"
-end
-parser.parse!
diff --git a/doc/ruby/argv.rb b/doc/tutorial/argv.rb
index 12495cfa1f..12495cfa1f 100644
--- a/doc/ruby/argv.rb
+++ b/doc/tutorial/argv.rb
diff --git a/doc/tutorial/long_names.rb b/doc/tutorial/long_names.rb
new file mode 100644
index 0000000000..a34b3382c2
--- /dev/null
+++ b/doc/tutorial/long_names.rb
@@ -0,0 +1,9 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('--xxx') do |value|
+ p ['-xxx', value]
+end
+parser.on('--y1%', '--z2#') do |value|
+ p ['--y1% or --z2#', value]
+end
+parser.parse!
diff --git a/doc/tutorial/mixed_names.rb b/doc/tutorial/mixed_names.rb
new file mode 100644
index 0000000000..e886049821
--- /dev/null
+++ b/doc/tutorial/mixed_names.rb
@@ -0,0 +1,9 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x', '--xxx') do |value|
+ p ['--xxx', value]
+end
+parser.on('-y', '--y1%') do |value|
+ p ['--y1%', value]
+end
+parser.parse!
diff --git a/doc/tutorial/optional_argument.rb b/doc/tutorial/optional_argument.rb
new file mode 100644
index 0000000000..ebff2f466d
--- /dev/null
+++ b/doc/tutorial/optional_argument.rb
@@ -0,0 +1,9 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x [XXX]', '--xxx') do |value|
+ p ['--xxx', value]
+end
+parser.on('-y', '--yyy [YYY]') do |value|
+ p ['--yyy', value]
+end
+parser.parse!
diff --git a/doc/tutorial/required_argument.rb b/doc/tutorial/required_argument.rb
new file mode 100644
index 0000000000..7a5a868265
--- /dev/null
+++ b/doc/tutorial/required_argument.rb
@@ -0,0 +1,9 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x XXX', '--xxx') do |value|
+ p ['--xxx', value]
+end
+parser.on('-y', '--y YYY') do |value|
+ p ['--yyy', value]
+end
+parser.parse!
diff --git a/doc/tutorial/short_names.rb b/doc/tutorial/short_names.rb
new file mode 100644
index 0000000000..6581dfe19a
--- /dev/null
+++ b/doc/tutorial/short_names.rb
@@ -0,0 +1,9 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x') do |value|
+ p ['x', value]
+end
+parser.on('-1', '-%') do |value|
+ p ['-1 or -%', value]
+end
+parser.parse!
diff --git a/doc/tutorial.rdoc b/doc/tutorial/tutorial.rdoc
index 3f60b462d6..60ead0a6c6 100644
--- a/doc/tutorial.rdoc
+++ b/doc/tutorial/tutorial.rdoc
@@ -6,11 +6,11 @@ When a Ruby program executes, it captures its command-line arguments
and options into variable ARGV.
This simple program just prints its \ARGV:
- :include: ruby/argv.rb
+ :include: argv.rb
Execution, with arguments and options:
- $ ruby doc/ruby/argv.rb foo --bar --baz bat bam
+ $ ruby argv.rb foo --bar --baz bat bam
["foo", "--bar", "--baz", "bat", "bam"]
The executing program is responsible for parsing and handling
@@ -27,8 +27,10 @@ With \OptionParser, you can define options so that for each option:
- The argument may be restricted to specified _forms_.
- The argument may be restricted to specified _values_.
-The class also has a method #summarize that returns a string summary
-of all defined options.
+The class also has:
+
+- Method #summarize: returns a text summary of the options.
+- Method #help: displays automatically-generated help text.
=== Defining Options
@@ -65,23 +67,28 @@ File +short_names.rb+
defines an option with a short name, <tt>-x</tt>,
and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
- :include: ruby/short_names.rb
+ :include: short_names.rb
Executions:
- $ ruby doc/ruby/short_names.rb -x
- "-x true"
- $ ruby doc/ruby/short_names.rb -1
- "-1 or -% true"
- $ ruby doc/ruby/short_names.rb -%
- "-1 or -% true"
+ $ ruby short_names.rb -x
+ ["x", true]
+ $ ruby short_names.rb -1
+ ["-1 or -%", true]
+ $ ruby short_names.rb -%
+ ["-1 or -%", true]
Multiple short names can "share" a hyphen:
$ ruby short_names.rb -x1%
- "-x true"
- "-1 or -% true"
- "-1 or -% true"
+ ["x", true]
+ ["-1 or -%", true]
+ ["-1 or -%", true]
+
+This is a good time to note that giving an undefined option raises an exception:
+
+ $ ruby short_names.rb -z
+ short_names.rb:9:in `<main>': invalid option: -z (OptionParser::InvalidOption)
==== Long Option Names
@@ -92,16 +99,16 @@ File +long_names.rb+
defines an option with a long name, <tt>--xxx</tt>,
and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
- :include: ruby/long_names.rb
+ :include: long_names.rb
Executions:
$ ruby long_names.rb --xxx
- "--xxx true"
+ ["-xxx", true]
$ ruby long_names.rb --y1%
- "--y1% or -z2# true"
+ ["--y1% or --z2#", true]
$ ruby long_names.rb --z2#
- "--y1% or -z2# true"
+ ["--y1% or --z2#", true]
==== Mixing Option Names
@@ -111,15 +118,69 @@ so that a short name is in effect an abbreviation of a long name.
File +mixed_names.rb+
defines options that each have both a short and a long name.
- :include: ruby/mixed_names.rb
+ :include: mixed_names.rb
+
+Executions:
+
+ $ ruby mixed_names.rb -x
+ ["--xxx", true]
+ $ ruby mixed_names.rb --xxx
+ ["--xxx", true]
+ $ ruby mixed_names.rb -y
+ ["--y1%", true]
+ $ ruby mixed_names.rb --y1%
+ ["--y1%", true]
+
+=== Option Arguments
+
+An option may take no argument, a required argument, or an optional argument.
+
+==== Option with No Argument
+
+All the examples above define options with no argument.
+
+==== Option with Required Argument
+
+Specify a required argument for an option by adding a dummy word
+to its name definition.
+
+File +required_argument.rb+ defines two options;
+each has a required argument because the name definition has a following dummy word.
+
+ :include: required_argument.rb
+
+When an option is found, the given argument is yielded.
Executions:
- $ ruby doc/ruby/mixed_names.rb -x
- "--xxx true"
- $ ruby doc/ruby/mixed_names.rb --xxx
- "--xxx true"
- $ ruby doc/ruby/mixed_names.rb -y
- "--y1% true"
- $ ruby doc/ruby/mixed_names.rb --y1%
- "--y1% true"
+ $ ruby required_argument.rb -x AAA
+ ["--xxx", "AAA"]
+ $ ruby required_argument.rb -y BBB
+ ["--yyy", "BBB"]
+
+Omitting a required argument raises an error:
+
+ $ ruby required_argument.rb -x
+ required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
+
+==== Option with Optional Argument
+
+Specify an optional argument for an option by adding a dummy word
+enclosed in square brackets to its name definition.
+
+File +optional_argument.rb+ defines two options;
+each has an optional argument because the name definition has a following dummy word
+in square brackets.
+
+ :include: optional_argument.rb
+
+When an option with an argument is found, the given argument yielded.
+
+Executions:
+
+ $ ruby optional_argument.rb -x AAA
+ ["--xxx", "AAA"]
+ $ ruby optional_argument.rb -y BBB
+ ["--yyy", "BBB"]
+
+Omitting an optional argument does not raise an error.