Re: Long help lines and wrapping

Bob van der Poel wrote:
> I'm trying to use the Optik package for parsing command line options.
> However, I'm running into a problem overriding its line warping routines.

I trust you meant "wrapping", not "warping" :)

> I'd like the help to print something like:
>
>       options:
>         -p, --pattern   Set pattern. Available patterns are:
>                 'xx'  use the xx pattern
>                 'yy'  use the yy pattern
>                 ... more list of pattern options
>         -z, --zzzz  The Z option
>         ... etc, etc

I have also had cases like this in the past, pre-Optik.  I think it would be
a useful addition.

> Seems that optik thinks it knows better where the new lines should go.

Please don't be snide; all that does is invite people to ignore your
message.

Optik doesn't "think" anything.  It simply doesn't support complex help
text.  It supports single, wrappable paragraphs only.  Support for anything
more complex would have to be implemented, but hasn't been yet.

I don't think special inline syntax is the best way to go.  That would be a
quick & dirty fix that would only complicate matters for the general case
and for any future additions.

Currently, Optik "Option" classes contain a "help" attribute, which is a
string, None, or a special string constant "SUPPRESS"+"HELP".  After
thinking it over a bit, I came up with the following implementation plan:

* Add a new "optik.help.Paragraph" class and subclasses.  Expose them
  in optik/__init__.py for easy import and future stdlib integration.
  Each class would define its own inter-object spacing and formatting
  behavior.

* Change the "optik.Option.help" attribute to contain a list of these
  objects.  Help objects would be restricted to a flat list structure.

* The "help" parameter of the "optik.Option" constructor would accept
  single strings (as now), and would convert them to Paragraph objects.
  It would also accept a list of Paragraph & subclass objects, to allow
  for complex help messages.

* Modify "optik.help.HelpFormatter.format_option" to handle these
  objects.  The "format_option" method would handle inter-paragraph
  spacing.

* The basic Paragraph class would require blank lines between objects.
  The "format" method would simply call "textwrap.wrap" on its data.

* A ListItem subclass would wrap its data, prepend a bullet ("*"),
  but wouldn't require blank lines between objects (of the same class).
  The data would be wrapped and further indented on second and
  subsequent lines (like this text).

* A Literal subclass would also require blank lines between objects,
  but would only indent its data; no line wrapping.  This would allow
  arbitrary help text, unaffected by the Optik code.

So to get the help message wanted, you'd need code like this::

    from optik import OptionParser, Paragraph, ListItem

    parser = OptionParser()
    parser.add_option("-p", "--pattern", metavar="<PATTERN>",
        choices=('xx', 'yy'), help=[
            Paragraph('Set pattern. Available patterns are:'),
            ListItem('"xx": use the xx pattern'),
            ListItem('"yy": use the yy pattern (long explanation here)')])
    ...

Running the script with the "--help" option would result in an option list
like this::

    options:
      -h, --help           show this help message and exit
      -p<PATTERN>, --pattern=<PATTERN>
                           Set pattern. Available patterns are:

                           * "xx": use the xx pattern
                           * "yy": use the yy pattern (long
                             explanation here)

      -z, --zzzz           The Z option

The blank lines could be removed if you're more concerned about vertical
real estate than readability.  I think vertical spacing should be
customizable so that "optik.help.TitledHelpFormatter" remains compatible
with reStructuredText.

If done properly, this could be a transparent, backwards-compatible addition
to Optik with room for future growth.  A quick-fix should not be attempted.
I am not volunteering to do the implementation at this time, but I'll be
glad to help.  He whose itch is strongest should be the first to scratch.

-- 
David Goodger  <[email protected]>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/



-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf