[ ruby-Patches-9177 ] optparse.rb patch to fix and enhance the separator handling

Patches item #9177, was opened at 2007-03-11 03:21
You can respond by visiting: 
http://rubyforge.org/tracker/?func=detail&atid=1700&aid=9177&group_id=426

Category: Ruby1.9
Group: None
Status: Open
Resolution: None
Priority: 3
Submitted By: Tom Pollard (wtpollard)
Assigned to: Nobody (None)
Summary: optparse.rb patch to fix and enhance the separator handling

Initial Comment:
Hi,

I've attached a patch for optparse.rb that fixes two bugs and adds an alias and one simple feature.  Specifically, the patch

1. fixes a bug in OptionParser::List#summarize (in the trunk - it's ok in 1.8) that caused the method to fail when a list of switches contained a separator string (because String objects no longer respond to :each in 1.9),

2. fixes OptionParser#separator so that it correctly handles strings containing newlines,

3. introduces 'text' as an alias for the 'separator' method, since the latter doesn't sound appropriate for adding a paragraph of text at a time, and

4. adds a 'bottom_text' method, which causes the given text to appear /after/ the option summary.

The first bug fix is self-explanatory, I think.  The fix for this is only required in 1.9, but the patched code works fine in 1.8, too.

In the current version of optparse.rb (in 1.8 and the trunk), the separator() method can only handle a single line of text correctly; when given a multiline string, the text ends up being displayed double-spaced, because an extra newline is appended to each line of the text.  I've modified the separator() method to split its input string into lines, and append them individually to the top list of switches.  In principle, the output formatter could possibly have been modified to handle multiline strings, but my change is simpler and less likely to have undesirable side effects.

The proposed alias isn't a big deal, but the method name 'separator' strongly
implies that it's intended to accept only a single line of text.  I thought it looked funny to introduce a paragraph of explanatory text into the option summary using a method called 'separator'.  An alias of 'text' suits this usage more naturally.

Finally, it's not possible to add text that follows the 'tail' group of switches (specified using the on_tail() method) using the separator() method.  OptionParser organizes the user's switches into three lists: the 'top' list, the 'base' list, and the default list.  The separator() method adds text only to 'top' list, and so this text will always appear before any switches added using the on_tail() method.  To add a paragraph of text that follows the option summary, I've introduced a bottom_text() method, which adds the given text to the 'default' list, which is processed after the tail switches.  I think people will find this useful (as I do), to add general words of explanation about the use of the options and non-option command line arguments.

I've tested this patch in 1.8 and in the trunk; I think it should be safe in both contexts.  

Thanks for considering this,

Tom
 

----------------------------------------------------------------------

You can respond by visiting: 
http://rubyforge.org/tracker/?func=detail&atid=1700&aid=9177&group_id=426