From 1bad4bdf524fc07be8ece1dc784fdbedc07d8a97 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 10 Apr 2021 16:30:19 -0500 Subject: [ruby/optparse] More on tutorial (#16) - Added example in "Argument Converters"; it doesn't seem right for a tutorial to have no example in one of its topics (and instead just linking elsewhere). - Added section "Command-Line Abbreviations." - Added section "Keyword Argument into," showing how to: - Collect options. - Check for missing options. - Provide option defaults. https://github.com/ruby/optparse/commit/39d39676c4 --- doc/tutorial.rdoc | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 133 insertions(+), 3 deletions(-) (limited to 'doc/tutorial.rdoc') diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index 42e0d1e3ac..7721dc60a2 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -39,10 +39,15 @@ The class also has: - {Short Option Names}[#label-Short+Option+Names] - {Long Option Names}[#label-Long+Option+Names] - {Mixing Option Names}[#label-Mixing+Option+Names] + - {Command-Line Abbreviations}[#label-Command-Line+Abbreviations] - {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] +- {Keyword Argument into}[#label-Keyword+Argument+into] + - {Collecting Options}[#label-Collecting+Options] + - {Checking for Missing Options}[#label-Checking+for+Missing+Options] + - {Default Values for Options}[#label-Default+Values+for+Options] - {Argument Converters}[#label-Argument+Converters] === Defining Options @@ -185,6 +190,47 @@ Executions: $ ruby mixed_names.rb --zzz BAT ["--zzz", "BAT"] +==== Command-Line Abbreviations + +By default, abbreviations for command-line option names are allowed. +An abbreviated option is valid if it is unique among abbreviated option names. + + :include: ruby/abbreviation.rb + +Executions: + + $ ruby abbreviation.rb --help + Usage: abbreviation [options] + -n, --dry-run + -d, --draft + $ ruby abbreviation.rb -n + ["--dry-run", true] + $ ruby abbreviation.rb --dry-run + ["--dry-run", true] + $ ruby abbreviation.rb -d + ["--draft", true] + $ ruby abbreviation.rb --draft + ["--draft", true] + $ ruby abbreviation.rb --d + abbreviation.rb:9:in `
': ambiguous option: --d (OptionParser::AmbiguousOption) + $ ruby abbreviation.rb --dr + abbreviation.rb:9:in `
': ambiguous option: --dr (OptionParser::AmbiguousOption) + $ ruby abbreviation.rb --dry + ["--dry-run", true] + $ ruby abbreviation.rb --dra + ["--draft", true] + +You can disable abbreviation using method +require_exact+. + + :include: ruby/no_abbreviation.rb + +Executions: + + $ ruby no_abbreviation.rb --dry-ru + no_abbreviation.rb:10:in `
': invalid option: --dry-ru (OptionParser::InvalidOption) + $ ruby no_abbreviation.rb --dry-run + ["--dry-run", true] + === Option Arguments An option may take no argument, a required argument, or an optional argument. @@ -247,12 +293,96 @@ Executions: Omitting an optional argument does not raise an error. +=== Keyword Argument +into+ + +In parsing options, you can add keyword option +into+ with a hash-like argument; +each parsed option will be added as a name/value pair. + +This is useful for: + +- Collecting options. +- Checking for missing options. +- Providing default values for options. + +==== Collecting Options + +Use keyword argument +into+ to collect options. + + :include: ruby/collected_options.rb + +Executions: + + $ ruby collected_options.rb --help + Usage: into [options] + -x, --xxx Short and long, no argument + -y, --yyyYYY Short and long, required argument + -z, --zzz [ZZZ] Short and long, optional argument + $ ruby collected_options.rb --xxx + {:xxx=>true} + $ ruby collected_options.rb --xxx --yyy FOO + {:xxx=>true, :yyy=>"FOO"} + $ ruby collected_options.rb --xxx --yyy FOO --zzz Bar + {:xxx=>true, :yyy=>"FOO", :zzz=>"Bar"} + $ ruby collected_options.rb --xxx --yyy FOO --yyy BAR + {:xxx=>true, :yyy=>"BAR"} + +Note in the last execution that the argument value for option --yyy +was overwritten. + +==== Checking for Missing Options + +Use the collected options to check for missing options. + + :include: ruby/missing_options.rb + +Executions: + + $ ruby missing_options.rb --help + Usage: missing_options [options] + -x, --xxx Short and long, no argument + -y, --yyyYYY Short and long, required argument + -z, --zzz [ZZZ] Short and long, optional argument + $ ruby missing_options.rb --yyy FOO + missing_options.rb:11:in `
': Missing required options: [:xxx, :zzz] (RuntimeError) + +==== Default Values for Options + +Initialize the +into+ argument to define default values for options. + + :include: ruby/default_values.rb + +Executions: + + $ ruby default_values.rb --help + Usage: default_values [options] + -x, --xxx Short and long, no argument + -y, --yyyYYY Short and long, required argument + -z, --zzz [ZZZ] Short and long, optional argument + $ ruby default_values.rb --yyy FOO + {:yyy=>"FOO", :zzz=>"BBB"} + + === 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]. +Example: 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] + $ ruby date.rb --date 20010203 + [#, Date] + $ ruby date.rb --date "3rd Feb 2001" + [#, Date] + +You can also define custom converters. +See {Argument Converters}[./argument_converters_rdoc.html] +for both built-in and custom converters. -- cgit v1.2.3