From 6f773c786bb7331b0c0f536114ee0f0b6a3579c7 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 9 Apr 2021 12:12:32 -0500 Subject: [PATCH 1/8] Resolve shared mixed_names.rb --- doc/option_params.rdoc | 10 ++++------ doc/ruby/mixed_names.rb | 9 ++++++--- doc/tutorial.rdoc | 18 +++++++++++++++--- 3 files changed, 25 insertions(+), 12 deletions(-) diff --git a/doc/option_params.rdoc b/doc/option_params.rdoc index 98d9630..cfa11b5 100644 --- a/doc/option_params.rdoc +++ b/doc/option_params.rdoc @@ -233,12 +233,10 @@ File +mixed_names.rb+ defines a mixture of short and long names. Executions: $ ruby mixed_names.rb --help - Usage: mixed_names [options] - -x, --xxx Short and long, simple - --yyy yYYY - Short and long, required argument - --zzz zZZZ - Short and long, optional argument +Usage: mixed_names [options] + -x, --xxx Short and long, no argument + -y, --yyyYYY Short and long, required argument + -z, --zzz [ZZZ] Short and long, optional argument $ ruby mixed_names.rb -x ["--xxx", true] $ ruby mixed_names.rb --xxx diff --git a/doc/ruby/mixed_names.rb b/doc/ruby/mixed_names.rb index e886049..67f81e7 100644 --- a/doc/ruby/mixed_names.rb +++ b/doc/ruby/mixed_names.rb @@ -1,9 +1,12 @@ require 'optparse' parser = OptionParser.new -parser.on('-x', '--xxx') do |value| +parser.on('-x', '--xxx', 'Short and long, no argument') do |value| p ['--xxx', value] end -parser.on('-y', '--y1%') do |value| - p ['--y1%', value] +parser.on('-yYYY', '--yyy', 'Short and long, required argument') do |value| + p ['--yyy', value] +end +parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument') do |value| + p ['--zzz', value] end parser.parse! diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index 5e95f20..da410d4 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -127,9 +127,21 @@ Executions: $ ruby mixed_names.rb --xxx ["--xxx", true] $ ruby mixed_names.rb -y - ["--y1%", true] - $ ruby mixed_names.rb --y1% - ["--y1%", true] + mixed_names.rb:12:in `
': missing argument: -y (OptionParser::MissingArgument) + $ ruby mixed_names.rb -y FOO + ["--yyy", "FOO"] + $ ruby mixed_names.rb --yyy + mixed_names.rb:12:in `
': missing argument: --yyy (OptionParser::MissingArgument) + $ ruby mixed_names.rb --yyy BAR + ["--yyy", "BAR"] + $ ruby mixed_names.rb -z + ["--zzz", nil] + $ ruby mixed_names.rb -z BAZ + ["--zzz", "BAZ"] + $ ruby mixed_names.rb --zzz + ["--zzz", nil] + $ ruby mixed_names.rb --zzz BAT + ["--zzz", "BAT"] === Option Arguments From 7f3313ccb27d371ba187e7b0776ab017ec8a1be8 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 9 Apr 2021 12:21:59 -0500 Subject: [PATCH 2/8] Add long option with negation --- doc/option_params.rdoc | 19 +++++++++++++++++++ .../{long_binary.rb => long_with_negation.rb} | 0 doc/tutorial.rdoc | 16 ++++++++++++++++ 3 files changed, 35 insertions(+) rename doc/ruby/{long_binary.rb => long_with_negation.rb} (100%) diff --git a/doc/option_params.rdoc b/doc/option_params.rdoc index cfa11b5..299a6c1 100644 --- a/doc/option_params.rdoc +++ b/doc/option_params.rdoc @@ -29,6 +29,7 @@ Contents: - {Simple Long Names}[#label-Simple+Long+Names] - {Long Names with Required Arguments}[#label-Long+Names+with+Required+Arguments] - {Long Names with Optional Arguments}[#label-Long+Names+with+Optional+Arguments] + - {Long Names with Negation}[#label-Long+Names+with+Negation] - {Mixed Names}[#label-Mixed+Names] - {Argument Styles}[#label-Argument+Styles] - {Argument Values}[#label-Argument+Values] @@ -222,6 +223,24 @@ Executions: $ ruby long_optional.rb --xxx FOO ["--xxx", "FOO"] +===== Long Names with Negation + +A long name may be defined with both positive and negative senses. + +File +long_with_negation.rb+ defines an option that has both senses. + + :include: ruby/long_with_negation.rb + +Executions: + + $ ruby long_with_negation.rb --help + Usage: long_with_negation [options] + --[no-]binary + $ ruby long_with_negation.rb --binary + [true, TrueClass] + $ ruby long_with_negation.rb --no-binary + [false, FalseClass] + ==== Mixed Names An option may have both short and long names. diff --git a/doc/ruby/long_binary.rb b/doc/ruby/long_with_negation.rb similarity index 100% rename from doc/ruby/long_binary.rb rename to doc/ruby/long_with_negation.rb diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index da410d4..ce3db49 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -110,6 +110,22 @@ Executions: $ ruby long_names.rb --z2# ["--y1% or --z2#", true] +A long name may be defined with both positive and negative senses. + +File +long_with_negation.rb+ defines an option that has both senses. + + :include: ruby/long_with_negation.rb + +Executions: + + $ ruby long_with_negation.rb --help + Usage: long_with_negation [options] + --[no-]binary + $ ruby long_with_negation.rb --binary + [true, TrueClass] + $ ruby long_with_negation.rb --no-binary + [false, FalseClass] + ==== Mixing Option Names Many developers like to mix short and long option names, From 06105dce982249855f5538e3811d0bbb13a75c36 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 9 Apr 2021 12:36:36 -0500 Subject: [PATCH 3/8] Show --help for all examples --- doc/option_params.rdoc | 2 +- doc/ruby/long_names.rb | 4 ++-- doc/ruby/long_with_negation.rb | 2 +- doc/ruby/optional_argument.rb | 4 ++-- doc/ruby/required_argument.rb | 4 ++-- doc/ruby/short_names.rb | 4 ++-- doc/tutorial.rdoc | 23 ++++++++++++++++++++++- 7 files changed, 32 insertions(+), 11 deletions(-) diff --git a/doc/option_params.rdoc b/doc/option_params.rdoc index 299a6c1..28f0d84 100644 --- a/doc/option_params.rdoc +++ b/doc/option_params.rdoc @@ -235,7 +235,7 @@ Executions: $ ruby long_with_negation.rb --help Usage: long_with_negation [options] - --[no-]binary + --[no-]binary Long name with negation $ ruby long_with_negation.rb --binary [true, TrueClass] $ ruby long_with_negation.rb --no-binary diff --git a/doc/ruby/long_names.rb b/doc/ruby/long_names.rb index a34b338..a49dbda 100644 --- a/doc/ruby/long_names.rb +++ b/doc/ruby/long_names.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('--xxx') do |value| +parser.on('--xxx', 'Long name') do |value| p ['-xxx', value] end -parser.on('--y1%', '--z2#') do |value| +parser.on('--y1%', '--z2#', "Two long names") do |value| p ['--y1% or --z2#', value] end parser.parse! diff --git a/doc/ruby/long_with_negation.rb b/doc/ruby/long_with_negation.rb index 8ecceca..3f2913c 100644 --- a/doc/ruby/long_with_negation.rb +++ b/doc/ruby/long_with_negation.rb @@ -1,6 +1,6 @@ require 'optparse' parser = OptionParser.new -parser.on('--[no-]binary') do |value| +parser.on('--[no-]binary', 'Long name with negation') do |value| p [value, value.class] end parser.parse! diff --git a/doc/ruby/optional_argument.rb b/doc/ruby/optional_argument.rb index ebff2f4..456368a 100644 --- a/doc/ruby/optional_argument.rb +++ b/doc/ruby/optional_argument.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('-x [XXX]', '--xxx') do |value| +parser.on('-x [XXX]', '--xxx', 'Optional argument via short name') do |value| p ['--xxx', value] end -parser.on('-y', '--yyy [YYY]') do |value| +parser.on('-y', '--yyy [YYY]', 'Optional argument via long name') do |value| p ['--yyy', value] end parser.parse! diff --git a/doc/ruby/required_argument.rb b/doc/ruby/required_argument.rb index 7a5a868..228a492 100644 --- a/doc/ruby/required_argument.rb +++ b/doc/ruby/required_argument.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('-x XXX', '--xxx') do |value| +parser.on('-x XXX', '--xxx', 'Required argument via short name') do |value| p ['--xxx', value] end -parser.on('-y', '--y YYY') do |value| +parser.on('-y', '--y YYY', 'Required argument via long name') do |value| p ['--yyy', value] end parser.parse! diff --git a/doc/ruby/short_names.rb b/doc/ruby/short_names.rb index 6581dfe..4a75651 100644 --- a/doc/ruby/short_names.rb +++ b/doc/ruby/short_names.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('-x') do |value| +parser.on('-x', 'Short name') do |value| p ['x', value] end -parser.on('-1', '-%') do |value| +parser.on('-1', '-%', 'Two short names') do |value| p ['-1 or -%', value] end parser.parse! diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index ce3db49..49f4326 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -71,6 +71,10 @@ and an option with two short names (aliases, in effect) -y and -z--y1% and -- Executions: + $ ruby long_names.rb --help + Usage: long_names [options] + --xxx Long name + --y1%, --z2# Two long names $ ruby long_names.rb --xxx ["-xxx", true] $ ruby long_names.rb --y1% @@ -120,7 +128,7 @@ Executions: $ ruby long_with_negation.rb --help Usage: long_with_negation [options] - --[no-]binary + --[no-]binary Long name with negation $ ruby long_with_negation.rb --binary [true, TrueClass] $ ruby long_with_negation.rb --no-binary @@ -138,6 +146,11 @@ defines options that each have both a short and a long name. Executions: + $ ruby mixed_names.rb --help + Usage: mixed_names [options] + -x, --xxx Short and long, no argument + -y, --yyyYYY Short and long, required argument + -z, --zzz [ZZZ] Short and long, optional argument $ ruby mixed_names.rb -x ["--xxx", true] $ ruby mixed_names.rb --xxx @@ -181,6 +194,10 @@ When an option is found, the given argument is yielded. Executions: +$ ruby required_argument.rb --help +Usage: required_argument [options] + -x, --xxx XXX Required argument via short name + -y, --y YYY Required argument via long name $ ruby required_argument.rb -x AAA ["--xxx", "AAA"] $ ruby required_argument.rb -y BBB @@ -206,6 +223,10 @@ When an option with an argument is found, the given argument yielded. Executions: + $ ruby optional_argument.rb --help + Usage: optional_argument [options] + -x, --xxx [XXX] Optional argument via short name + -y, --yyy [YYY] Optional argument via long name $ ruby optional_argument.rb -x AAA ["--xxx", "AAA"] $ ruby optional_argument.rb -y BBB From 647ff3be56284cad2c74d04628301e498cf1843f Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 9 Apr 2021 12:44:47 -0500 Subject: [PATCH 4/8] Table of contents for tutorial --- doc/tutorial.rdoc | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index 49f4326..0a9e549 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -32,6 +32,18 @@ The class also has: - Method #summarize: returns a text summary of the options. - Method #help: displays automatically-generated help text. +=== Contents + +- {Defining Options}[#label-Defining+Options] +- {Option Names}[#label-Option+Names] + - {Short Option Names}[#label-Short+Option+Names] + - {Long Option Names}[#label-Long+Option+Names] + - {Mixing Option Names}[#label-Mixing+Option+Names] +- {Option Arguments}[#label-Option+Arguments] + - {Option with No Argument}[#label-Option+with+No+Argument] + - {Option with Required Argument}[#label-Option+with+Required+Argument] + - {Option with Optional Argument}[#label-Option+with+Optional+Argument] + === Defining Options A common way to define an option in \OptionParser From da159b46f0c3d3c5f79eef8ac1c0cbf93682b142 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 9 Apr 2021 13:20:09 -0500 Subject: [PATCH 5/8] Move argument converters to separate rdoc --- doc/argument_converters.rdoc | 376 +++++++++++++++++++++++++++++++++++ doc/option_params.rdoc | 346 +------------------------------- doc/ruby/custom_converter.rb | 9 + 3 files changed, 386 insertions(+), 345 deletions(-) create mode 100644 doc/argument_converters.rdoc create mode 100644 doc/ruby/custom_converter.rb diff --git a/doc/argument_converters.rdoc b/doc/argument_converters.rdoc new file mode 100644 index 0000000..c47f137 --- /dev/null +++ b/doc/argument_converters.rdoc @@ -0,0 +1,376 @@ +== 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}[https://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html#method-c-parse]. + + :include: ruby/date.rb + +Executions: + + $ ruby date.rb --date 2001-02-03 + [#, Date] + $ ruby date.rb --date 20010203 + [#, Date] + $ ruby date.rb --date "3rd Feb 2001" + [#, 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}[https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-parse]. + + :include: ruby/datetime.rb + +Executions: + + $ ruby datetime.rb --datetime 2001-02-03T04:05:06+07:00 + [#, DateTime] + $ ruby datetime.rb --datetime 20010203T040506+0700 + [#, DateTime] + $ ruby datetime.rb --datetime "3rd Feb 2001 04:05:06 PM" + [#, 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}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-httpdate] or +{Time.parse}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-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}[https://ruby-doc.org/stdlib-2.7.2/libdoc/uri/rdoc/URI.html#method-c-parse]. + + :include: ruby/uri.rb + +Executions: + + $ ruby uri.rb --uri https://github.com + [#, URI::HTTPS] + $ ruby uri.rb --uri http://github.com + [#, URI::HTTP] + $ ruby uri.rb --uri 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}[https://ruby-doc.org/stdlib-2.7.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-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}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-Rational], +{Kernel.Float}[https://ruby-doc.org/core/Kernel.html#method-i-Float], or +{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-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?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F]. + + :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?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F]. + + :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 may create custom argument converters. +To do so, call OptionParser#accept with a class argument +and a block that converts the argument and returns the converted value. + + :include: custom_converters.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] diff --git a/doc/option_params.rdoc b/doc/option_params.rdoc index 28f0d84..c0c1a86 100644 --- a/doc/option_params.rdoc +++ b/doc/option_params.rdoc @@ -38,23 +38,6 @@ Contents: - {Explicit Values in Hash}[#label-Explicit+Values+in+Hash] - {Argument Value Patterns}[#label-Argument+Value+Patterns] - {Argument Converters}[#label-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] - {Descriptions}[#label-Descriptions] - {Option Handlers}[#label-Option+Handlers] - {Handler Blocks}[#label-Handler+Blocks] @@ -417,334 +400,7 @@ Executions: An option can specify that its argument is to be converted from the default \String to an instance of another class. -\OptionParser has a number of built-in 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}[https://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html#method-c-parse]. - - :include: ruby/date.rb - -Executions: - - $ ruby date.rb --date 2001-02-03 - [#, Date] - $ ruby date.rb --date 20010203 - [#, Date] - $ ruby date.rb --date "3rd Feb 2001" - [#, 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}[https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-parse]. - - :include: ruby/datetime.rb - -Executions: - - $ ruby datetime.rb --datetime 2001-02-03T04:05:06+07:00 - [#, DateTime] - $ ruby datetime.rb --datetime 20010203T040506+0700 - [#, DateTime] - $ ruby datetime.rb --datetime "3rd Feb 2001 04:05:06 PM" - [#, 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}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-httpdate] or -{Time.parse}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-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}[https://ruby-doc.org/stdlib-2.7.2/libdoc/uri/rdoc/URI.html#method-c-parse]. - - :include: ruby/uri.rb - -Executions: - - $ ruby uri.rb --uri https://github.com - [#, URI::HTTPS] - $ ruby uri.rb --uri http://github.com - [#, URI::HTTP] - $ ruby uri.rb --uri 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}[https://ruby-doc.org/stdlib-2.7.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-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}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-Rational], -{Kernel.Float}[https://ruby-doc.org/core/Kernel.html#method-i-Float], or -{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-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}[https://ruby-doc.org/core/Kernel.html#method-i-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?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F]. - - :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?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F]. - - :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 +See {Argument Converters}[./argument_converters_rdoc.html] === Descriptions diff --git a/doc/ruby/custom_converter.rb b/doc/ruby/custom_converter.rb new file mode 100644 index 0000000..029da08 --- /dev/null +++ b/doc/ruby/custom_converter.rb @@ -0,0 +1,9 @@ +require 'optparse/date' +parser = OptionParser.new +parser.accept(Complex) do |value| + value.to_c +end +parser.on('--complex COMPLEX', Complex) do |value| + p [value, value.class] +end +parser.parse! From e45304beb36ce2cf7fa18e6a21a277cbf1097e8d Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 9 Apr 2021 13:29:25 -0500 Subject: [PATCH 6/8] Add references to argument_converters.rdoc --- doc/argument_converters.rdoc | 6 +++--- doc/option_params.rdoc | 5 ++++- doc/tutorial.rdoc | 11 +++++++++++ 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/doc/argument_converters.rdoc b/doc/argument_converters.rdoc index c47f137..9f06f0b 100644 --- a/doc/argument_converters.rdoc +++ b/doc/argument_converters.rdoc @@ -358,9 +358,9 @@ Executions: === Custom Argument Converters -You may create custom argument converters. -To do so, call OptionParser#accept with a class argument -and a block that converts the argument and returns the converted value. +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: custom_converters.rb diff --git a/doc/option_params.rdoc b/doc/option_params.rdoc index c0c1a86..0d06b41 100644 --- a/doc/option_params.rdoc +++ b/doc/option_params.rdoc @@ -400,7 +400,10 @@ Executions: An option can specify that its argument is to be converted from the default \String to an instance of another class. -See {Argument Converters}[./argument_converters_rdoc.html] +There are a number of built-in converters. +You can also define custom converters. + +See {Argument Converters}[./argument_converters_rdoc.html]. === Descriptions diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index 0a9e549..f218ccf 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -43,6 +43,7 @@ The class also has: - {Option with No Argument}[#label-Option+with+No+Argument] - {Option with Required Argument}[#label-Option+with+Required+Argument] - {Option with Optional Argument}[#label-Option+with+Optional+Argument] +- {Argument Converters}[#label-Argument+Converters] === Defining Options @@ -245,3 +246,13 @@ Executions: ["--yyy", "BBB"] Omitting an optional argument does not raise an error. + +=== Argument Converters + +An option can specify that its argument is to be converted +from the default \String to an instance of another class. + +There are a number of built-in converters. +You can also define custom converters. + +See {Argument Converters}[./argument_converters_rdoc.html]. From 7c59da98a9491f9662b26d643d12b7038697b44b Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 9 Apr 2021 13:48:42 -0500 Subject: [PATCH 7/8] Tune up argument converters --- doc/argument_converters.rdoc | 4 ++-- doc/tutorial.rdoc | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/argument_converters.rdoc b/doc/argument_converters.rdoc index 9f06f0b..0000ea0 100644 --- a/doc/argument_converters.rdoc +++ b/doc/argument_converters.rdoc @@ -23,7 +23,7 @@ from the default \String to an instance of another class. - {String}[#label-String] - {Array}[#label-Array] - {Regexp}[#label-Regexp] -= {Custom Argument Converters}[#label-Custom+Argument+Converters] +- {Custom Argument Converters}[#label-Custom+Argument+Converters] === Built-In Argument Converters @@ -362,7 +362,7 @@ 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: custom_converters.rb + :include: ruby/custom_converter.rb Executions: diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index f218ccf..42e0d1e 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -207,10 +207,10 @@ When an option is found, the given argument is yielded. Executions: -$ ruby required_argument.rb --help -Usage: required_argument [options] - -x, --xxx XXX Required argument via short name - -y, --y YYY Required argument via long name + $ ruby required_argument.rb --help + Usage: required_argument [options] + -x, --xxx XXX Required argument via short name + -y, --y YYY Required argument via long name $ ruby required_argument.rb -x AAA ["--xxx", "AAA"] $ ruby required_argument.rb -y BBB From e1b269fbe6fd25d0cbed479eef1c7bac87259cef Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 10 Apr 2021 08:34:39 -0500 Subject: [PATCH 8/8] Change explicit links to auto-links --- doc/argument_converters.rdoc | 42 ++++++++++++------------------------ 1 file changed, 14 insertions(+), 28 deletions(-) diff --git a/doc/argument_converters.rdoc b/doc/argument_converters.rdoc index 0000ea0..fc5a015 100644 --- a/doc/argument_converters.rdoc +++ b/doc/argument_converters.rdoc @@ -34,8 +34,7 @@ which are demonstrated below. File +date.rb+ defines an option whose argument is to be converted to a \Date object. -The argument is converted by method -{Date.parse}[https://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html#method-c-parse]. +The argument is converted by method Date#parse. :include: ruby/date.rb @@ -52,8 +51,7 @@ Executions: File +datetime.rb+ defines an option whose argument is to be converted to a \DateTime object. -The argument is converted by method -{DateTime.parse}[https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-parse]. +The argument is converted by method DateTime#parse. :include: ruby/datetime.rb @@ -70,9 +68,7 @@ Executions: File +time.rb+ defines an option whose argument is to be converted to a \Time object. -The argument is converted by method -{Time.httpdate}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-httpdate] or -{Time.parse}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-parse]. +The argument is converted by method Time#httpdate or Time#parse. :include: ruby/time.rb @@ -87,8 +83,7 @@ Executions: File +uri.rb+ defines an option whose argument is to be converted to a \URI object. -The argument is converted by method -{URI.parse}[https://ruby-doc.org/stdlib-2.7.2/libdoc/uri/rdoc/URI.html#method-c-parse]. +The argument is converted by method URI#parse. :include: ruby/uri.rb @@ -105,7 +100,7 @@ Executions: File +shellwords.rb+ defines an option whose argument is to be converted to an \Array object by method -{Shellwords.shellwords}[https://ruby-doc.org/stdlib-2.7.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-shellwords]. +Shellwords#shellwords. :include: ruby/shellwords.rb @@ -120,8 +115,7 @@ Executions: File +integer.rb+ defines an option whose argument is to be converted to an \Integer object. -The argument is converted by method -{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer]. +The argument is converted by method Kernel#Integer. :include: ruby/integer.rb @@ -142,8 +136,7 @@ Executions: File +float.rb+ defines an option whose argument is to be converted to a \Float object. -The argument is converted by method -{Kernel.Float}[https://ruby-doc.org/core/Kernel.html#method-i-Float]. +The argument is converted by method Kernel#Float. :include: ruby/float.rb @@ -163,10 +156,8 @@ Executions: 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}[https://ruby-doc.org/core/Kernel.html#method-i-Rational], -{Kernel.Float}[https://ruby-doc.org/core/Kernel.html#method-i-Float], or -{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer]. +The argument is converted by method Kernel#Rational, +Kernel#Float, or Kernel#Integer. :include: ruby/numeric.rb @@ -183,8 +174,7 @@ Executions: 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}[https://ruby-doc.org/core/Kernel.html#method-i-Integer]. +The argument is converted by method Kernel#Integer. :include: ruby/decimal_integer.rb @@ -206,8 +196,7 @@ Executions: 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}[https://ruby-doc.org/core/Kernel.html#method-i-Integer]. +The argument is converted by method Kernel#Integer. :include: ruby/octal_integer.rb @@ -227,8 +216,7 @@ Executions: 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}[https://ruby-doc.org/core/Kernel.html#method-i-Integer]. +The argument is converted by method {Kernel#Integer :include: ruby/decimal_numeric.rb @@ -248,8 +236,7 @@ Executions: 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?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F]. +The argument is evaluated by method Object#nil?. :include: ruby/true_class.rb @@ -276,8 +263,7 @@ Executions: 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?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F]. +The argument is evaluated by method Object#nil?. :include: ruby/false_class.rb