From: "bkuhlmann (Brooke Kuhlmann) via ruby-core" <ruby-core@...>
Date: 2024-03-08T00:42:33+00:00
Subject: [ruby-core:117086] [Ruby master Bug#20328] optparse omits the option's description in the --help output if the description is an Array

Issue #20328 has been updated by bkuhlmann (Brooke Kuhlmann).


The confusion is with the array (third argument) used with your `--multiline-opt` option. If you change it to the following, you'll get the desired result:

``` ruby
opts.on "-m", "--multiline-opt", "Line one", "Line two"
```

The reason this happens is because the method signature for `#on` is `*args, &block` which means all arguments *must be in the correct position* (this isn't entirely true because some positions are optional, though, but is a decent rule to follow). In your implementation, use of `['Line one', 'Line two']` is ignored because `--multiline-opt` is considered a *flag* since it takes no arguments. This might help:

``` ruby
require "optparse"

parser = OptionParser.new do |opts|
  opts.on("-a", %w[One Two]) { |value| puts value }
  opts.on("-b OPTION", %w[One Two]) { |value| puts value }
  opts.on("-c", "One", "Two") { |value| puts value }
end

parser.parse ["-a"]
parser.parse ["-b", "One"]
parser.parse ["-c"]
parser.parse ["--help"]

# true
# One
# true
# Usage: demo [options]
#     -a
#     -b OPTION
#     -c                               One
#                                      Two
```

Notice how both the `-a` and `-c` options are *flags* (booleans) but only `-c` prints the ancillary text you are looking for. This is because you can have multiple lines of ancillary text as long as they are splatted the end of the argument list. In the case of the `-b` option, if you supplied a value other than "One" or "Two", you'd end up with a `OptionParser::InvalidArgument` error because the `%w[One Two]` array restricts what value is *allowed*.

���� If it helps, I detail all of this -- and more -- in this [article](https://alchemists.io/articles/ruby_option_parser).


----------------------------------------
Bug #20328: optparse omits the option's description in the --help output if the description is an Array
https://bugs.ruby-lang.org/issues/20328#change-107160

* Author: postmodern (Hal Brodigan)
* Status: Open
* ruby -v: ruby 3.2.2 (2023-03-30 revision e51014f9c0) [x86_64-linux]
* Backport: 3.0: UNKNOWN, 3.1: UNKNOWN, 3.2: UNKNOWN, 3.3: UNKNOWN
----------------------------------------
If you define an option using `OptionParser#on`, but give the option's description as a multi-line Array, then the option's description is omitted from the `--help` output.

## Steps To Reproduce

```ruby
#!/usr/bin/env ruby

require 'optparse'

optparser = OptionParser.new do |opts|
  opts.banner = 'usage: test.rb [options]'

  opts.on('-o', '--opt [OPT]', 'Line one') do |opt|
  end

  opts.on('-m', '--multiline-opt', ['Line one', 'Line two']) do |test|
  end

  opts.on('-h', '--help', 'Prints this help') do
    puts opts
    exit
  end
end

optparser.parse(['--help'])
```

### Expected result

```
usage: test.rb [options]
    -o, --opt [OPT]                  Line one
    -m, --multiline-opt              Line one
                                     Line two
    -h, --help                       Prints this help
```

### Actual Result

```
usage: test.rb [options]
    -o, --opt [OPT]                  Line one
    -m, --multiline-opt
    -h, --help                       Prints this help
```

or an `ArgumentError` should be raised if Array descriptions are not allowed/supported.

## Version Info

Tested against optparse 0.1.0, 0.2.0, 0.3.1, and the master branch.



-- 
https://bugs.ruby-lang.org/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/postorius/lists/ruby-core.ml.ruby-lang.org/