ruby-changes:66946
From: Burdette <ko1@a...>
Date: Wed, 28 Jul 2021 20:14:30 +0900 (JST)
Subject: [ruby-changes:66946] 43af561e08 (master): [ruby/optparse] Rdoc for help (https://github.com/ruby/optparse/pull/21)
https://git.ruby-lang.org/ruby.git/commit/?id=43af561e08 From 43af561e0878ca856513edd3db56ce7dff8e7fe3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Mon, 12 Apr 2021 20:33:19 -0500 Subject: [ruby/optparse] Rdoc for help (https://github.com/ruby/optparse/pull/21) https://github.com/ruby/optparse/commit/d07cb96a96 --- doc/optparse/ruby/help.rb | 21 +++++++ doc/optparse/ruby/help_banner.rb | 7 +++ doc/optparse/ruby/help_format.rb | 25 ++++++++ doc/optparse/ruby/help_program_name.rb | 7 +++ doc/optparse/tutorial.rdoc | 105 +++++++++++++++++++++++++++++++++ 5 files changed, 165 insertions(+) create mode 100644 doc/optparse/ruby/help.rb create mode 100644 doc/optparse/ruby/help_banner.rb create mode 100644 doc/optparse/ruby/help_format.rb create mode 100644 doc/optparse/ruby/help_program_name.rb diff --git a/doc/optparse/ruby/help.rb b/doc/optparse/ruby/help.rb new file mode 100644 index 0000000..72f1b93 --- /dev/null +++ b/doc/optparse/ruby/help.rb @@ -0,0 +1,21 @@ https://github.com/ruby/ruby/blob/trunk/doc/optparse/ruby/help.rb#L1 +require 'optparse' +parser = OptionParser.new +parser.on( + '-x', '--xxx', + 'Adipiscing elit. Aenean commodo ligula eget.', + 'Aenean massa. Cum sociis natoque penatibus', + ) +parser.on( + '-y', '--yyy YYY', + 'Lorem ipsum dolor sit amet, consectetuer.' +) +parser.on( + '-z', '--zzz [ZZZ]', + 'Et magnis dis parturient montes, nascetur', + 'ridiculus mus. Donec quam felis, ultricies', + 'nec, pellentesque eu, pretium quis, sem.', + ) +parser.parse! + + + diff --git a/doc/optparse/ruby/help_banner.rb b/doc/optparse/ruby/help_banner.rb new file mode 100644 index 0000000..0943a3e --- /dev/null +++ b/doc/optparse/ruby/help_banner.rb @@ -0,0 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/doc/optparse/ruby/help_banner.rb#L1 +require 'optparse' +parser = OptionParser.new +parser.banner = "Usage: ruby help_banner.rb" +parser.parse! + + + diff --git a/doc/optparse/ruby/help_format.rb b/doc/optparse/ruby/help_format.rb new file mode 100644 index 0000000..a2f1e85 --- /dev/null +++ b/doc/optparse/ruby/help_format.rb @@ -0,0 +1,25 @@ https://github.com/ruby/ruby/blob/trunk/doc/optparse/ruby/help_format.rb#L1 +require 'optparse' +parser = OptionParser.new( + 'ruby help_format.rb [options]', # Banner + 20, # Width of options field + ' ' * 2 # Indentation +) +parser.on( + '-x', '--xxx', + 'Adipiscing elit. Aenean commodo ligula eget.', + 'Aenean massa. Cum sociis natoque penatibus', + ) +parser.on( + '-y', '--yyy YYY', + 'Lorem ipsum dolor sit amet, consectetuer.' +) +parser.on( + '-z', '--zzz [ZZZ]', + 'Et magnis dis parturient montes, nascetur', + 'ridiculus mus. Donec quam felis, ultricies', + 'nec, pellentesque eu, pretium quis, sem.', + ) +parser.parse! + + + diff --git a/doc/optparse/ruby/help_program_name.rb b/doc/optparse/ruby/help_program_name.rb new file mode 100644 index 0000000..7b3fbff --- /dev/null +++ b/doc/optparse/ruby/help_program_name.rb @@ -0,0 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/doc/optparse/ruby/help_program_name.rb#L1 +require 'optparse' +parser = OptionParser.new +parser.program_name = 'help_program_name.rb' +parser.parse! + + + diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index ad8486d..a701462 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -50,6 +50,43 @@ The class also has: https://github.com/ruby/ruby/blob/trunk/doc/optparse/tutorial.rdoc#L50 - {Checking for Missing Options}[#label-Checking+for+Missing+Options] - {Default Values for Options}[#label-Default+Values+for+Options] - {Argument Converters}[#label-Argument+Converters] +- {Help}[#label-Help] + +=== To Begin With + +To use \OptionParser: + +1. Require the \OptionParser code. +2. Create an \OptionParser object. +3. Define one or more options. +4. Parse the command line. + +File +basic.rb+ defines three options, <tt>-x</tt>, +<tt>-y</tt>, and <tt>-z</tt>, each with a descriptive string, +and each with a block. + + :include: ruby/basic.rb + +From these defined options, the parser automatically builds help text: + + $ ruby basic.rb --help + Usage: basic [options] + -x Whether to X + -y Whether to Y + -z Whether to Z + +When an option is found during parsing, +the block defined for the option is called with the argument value. + +Executions: + + $ ruby basic.rb -x -z + ["x", true] + ["z", true] + $ ruby basic.rb -z -y -x + ["z", true] + ["y", true] + ["x", true] === To Begin With @@ -422,3 +459,71 @@ Executions: https://github.com/ruby/ruby/blob/trunk/doc/optparse/tutorial.rdoc#L459 You can also define custom converters. See {Argument Converters}[./argument_converters_rdoc.html] for both built-in and custom converters. + +=== Help + +\OptionParser makes automatically generated help text available. + +The help text consists of: + +- A banner, showing the usage. +- Option short and long names. +- Option dummy argument names. +- Option descriptions. + +Example code: + + :include: ruby/help.rb + +The option names and dummy argument names are defined as described above. + +The option description consists of the strings that are not themselves option names; +An option can have more than one description string. +Execution: + + Usage: help [options] + -x, --xxx Adipiscing elit. Aenean commodo ligula eget. + Aenean massa. Cum sociis natoque penatibus + -y, --yyy YYY Lorem ipsum dolor sit amet, consectetuer. + -z, --zzz [ZZZ] Et magnis dis parturient montes, nascetur + ridiculus mus. Donec quam felis, ultricies + nec, pellentesque eu, pretium quis, sem. + +The program name is included in the default banner: +<tt>Usage: #{program_name} [options]</tt>; +you can change the program name. + + :include: ruby/help_program_name.rb + +Execution: + + $ ruby help_program_name.rb --help + Usage: help_program_name.rb [options] + +You can also change the entire banner. + + :include: ruby/help_banner.rb + +Execution: + + $ ruby help_banner.rb --help + Usage: ruby help_banner.rb + +By default, the option names are indented 4 spaces +and the width of the option-names field is 32 spaces. + +You can change these values, along with the banner, +by passing parameters to OptionParser.new. + + :include: ruby/help_format.rb + +Execution: + + $ ruby help_format.rb --help + ruby help_format.rb [options] + -x, --xxx Adipiscing elit. Aenean commodo ligula eget. + Aenean massa. Cum sociis natoque penatibus + -y, --yyy YYY Lorem ipsum dolor sit amet, consectetuer. + -z, --zzz [ZZZ] Et magnis dis parturient montes, nascetur + ridiculus mus. Donec quam felis, ultricies + nec, pellentesque eu, pretium quis, sem. -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/