Quick comment: I don't think we should call anything "seriialize*",
it's too close to Java serialization. I'd use "render".

Gary

On Wed, Sep 25, 2024 at 7:11 AM Claude Warren <cla...@apache.org> wrote:
>
> Some initial code.  Note the "help" package name.  We can discuss keeping
> it or not but it is here to make it easy to see what is new.  Also, some
> methods added to Util.java
>
> https://github.com/Claudenw/commons-cli/tree/Help_formatter_extension/src/main/java/org/apache/commons/cli/help
>
> Overview because I have not written the javadocs yet.
>
>
>    - HelpFormatter -- the replacement for the current help formatter.  Much
>    of the formatting functionality has moved.
>    - Serializer -- a semantic serialization component.  Semantic meaning
>    you serialize things like paragraph, table, header.  Serialize meaning you
>    write a specific serialization format (e.g. text, xhtml, Markdown, etc).
>    Serializers write to any Appendable implementation. (e.g. StringBuilder or
>    Writer)
>    - OptionFormatter -- Handles the formatting of Options (e.g. the '<' and
>    '>' around arg names, '[' and ']' for optional data, etc  Generally does
>    not need to be set.  Defaults match current settings.
>    - TextStyle -- Guidelines for how to display the text.  Serializers are
>    not required to follow the guidelines.  HelpFormatter uses an instance to
>    set the left padding, the maximum width of the display, and the indent for
>    paragraphs.
>    - TableDef a collection of headers, TextStyle (one for each column), and
>    a list of rows.  Where rows are lists of strings one for each column.  The
>    Text style will specify the left padding, max and min text width, indents
>    for continuation lines, text alignment, and whether the column can be
>    scaled (FIXED = no).
>
> In the test classes I added an org.example package that contains an
> AptSerializer as an example for markdown and other cases as well as a
> "WeirdOptionFormat" which defines a completely different table definition
> for the option display.
>
> Generally extension points are:
>
>    - Writing new Serializers. (set with HelpFormatter.Builder)
>    - Creating custom table definitions. (set with HelpFormatter.Builder, or
>    used directly with the Serializer)
>    - Overriding "printHelp" in the AbstractHelpFormatter" to create a
>    custom page.  This may include calling the serializer and creating new
>    tables with definitions for custom argument names for example.
>
>
> I will continue to work on this, getting the javadoc in order and ensuring
> that we have enough test coverage.  Right now you have to run maven with
> the "-Djacoco.skip=true" flag to get past the test coverage issue.
>
> Let me know what you think.
> Claude
>
>
>
> On Mon, Sep 23, 2024 at 10:58 PM Eric Pugh <ep...@opensourceconnections.com>
> wrote:
>
> > Keep us posted!   I would love to contribute a Markdown format.
> >
> > > On Sep 23, 2024, at 7:20 AM, Claude Warren <cla...@xenei.com> wrote:
> > >
> > > I have a system that mostly works.  But implementing XML output requires
> > > StringEscapeUtils from commons-text.  I know we are reluctant to include
> > > other packages.  So my thought is that we provide the XML option as an
> > > example so that we don't include the commons-text in the package.
> > >
> > > My strategy is to separate the formatting into 2 components.
> > >
> > > OptionFormat -- Defines the output format for options.  What gets
> > displayed
> > > on the syntax options, and the option table contents.  I have a default
> > > implementation that provides the same data as the current HelpFormatter
> > one.
> > >
> > > OutputFormat -- Defines the serialization format for the OptionFormat.  I
> > > have two implementations.  Text which outputs the current format,  XML
> > for
> > > xml output option format data,  and APT format in an example.
> > >
> > > My next step is to verify that I can implement the Rat help system.
> > >
> > >
> > >
> > > Imp
> > >
> > > On Fri, Sep 20, 2024 at 12:47 PM Gary Gregory <garydgreg...@gmail.com>
> > > wrote:
> > >
> > >> Looking forward to it 😀
> > >>
> > >> Gary
> > >>
> > >> On Fri, Sep 20, 2024, 3:56 AM Claude Warren <cla...@xenei.com> wrote:
> > >>
> > >>> I have been working on Rat and have a set of classes that output
> > >> markdown.
> > >>> I think I can make CLI HelpFormtter system take a class to output the
> > >> data
> > >>> in any given format.
> > >>>
> > >>> What rat is doing now is writing help to a file and using APT format to
> > >>> include that using Velocity.
> > >>>
> > >>> Gary's point that XML provides broad support, and Eric's point about
> > >>> markdown and the general case for text seems to indicate that
> > >> applications
> > >>> need a way to specify how to format the data, as well as access to the
> > >>> current tooling that makes generating/aggregating the text easier.  I
> > >> will
> > >>> work on this and create a pull request where we can discuss how it
> > works.
> > >>>
> > >>> On Thu, Sep 19, 2024 at 1:00 PM Eric Pugh <
> > >> ep...@opensourceconnections.com
> > >>>>
> > >>> wrote:
> > >>>
> > >>>> I would love to see the ability to output the help docs in a format
> > >> that
> > >>>> could be dropped into documentation.   In Solr we basically cut and
> > >> paste
> > >>>> the -h output into the Reference Guide, it works but it’s ugly and
> > >>> manual.
> > >>>> I’ve been experimenting with some tools that let you run a tool,
> > >> capture
> > >>>> the output, and incorporate that into the help docs.
> > >>>>
> > >>>> Imagine if I had a "-h —output markdown" that gave a nice table
> > >>>> structure?   That could then be incorporated directly into the docs
> > and
> > >>>> generated at build time.
> > >>>>
> > >>>> Honestly, if I had to write my own string handling code to actually do
> > >>> the
> > >>>> output, but the structure was all there, that would be super helpful.
> > >>>>
> > >>>>> On Sep 19, 2024, at 7:36 AM, Gary Gregory <garydgreg...@gmail.com>
> > >>>> wrote:
> > >>>>>
> > >>>>> Hi Claude,
> > >>>>>
> > >>>>> I think it needs to be flexible/complex just enough to support doing
> > >>>> what I
> > >>>>> mentioned. I like XML because once you have that, you can get
> > >> anywhere
> > >>>> else
> > >>>>> with XSL. How do you do transformations in JSON anyway? Has that
> > >> wheel
> > >>>> been
> > >>>>> reinvented? JOLT seems not to have gone anywhere.
> > >>>>>
> > >>>>> Maybe we need a PR to get us started to get done what you need to do.
> > >>> WRT
> > >>>>> formats, at least one can be provided as a test to make sure the code
> > >>> is
> > >>>>> extensible enough.
> > >>>>>
> > >>>>> Gary
> > >>>>>
> > >>>>>
> > >>>>> On Thu, Sep 19, 2024, 6:53 AM Claude Warren <cla...@xenei.com>
> > >> wrote:
> > >>>>>
> > >>>>>> This could get complex fairly quickly.  So a couple of questions:
> > >>>>>>
> > >>>>>> Q: Do we want to create a new commons project or perhaps expand
> > >>>>>> commons-text to contain a simple library for formatting output.  If
> > >> we
> > >>>> do
> > >>>>>> that we would have to include it in commons-cli which I know is
> > >>>>>> undesirable, but if text is small enough it should not be a problem.
> > >>>>>>
> > >>>>>> Q: Do we want to create/support multiple output formatters (e.g.
> > >> XML,
> > >>>>>> XHMTL, Text, markdown)?
> > >>>>>>
> > >>>>>>
> > >>>>>>
> > >>>>>> On Wed, Sep 18, 2024 at 5:40 PM Gary Gregory <
> > >> garydgreg...@gmail.com>
> > >>>>>> wrote:
> > >>>>>>
> > >>>>>>> If we create something new, it would be nice to have example in
> > >> tests
> > >>>>>> that
> > >>>>>>> show rendering to XHTML and XML. This means the abstract superclass
> > >>>>>> should
> > >>>>>>> not assume console output. A site can use its own CSS for styling.
> > >> If
> > >>>> we
> > >>>>>>> are flexible enough we should not need to create yet another thing
> > >> in
> > >>>>>>> the future.
> > >>>>>>>
> > >>>>>>> Gary
> > >>>>>>>
> > >>>>>>> On Wed, Sep 18, 2024, 11:23 AM Claude Warren <cla...@xenei.com>
> > >>> wrote:
> > >>>>>>>
> > >>>>>>>> I think that help formatting really comes down to building a
> > >> textual
> > >>>>>>>> matrix from a list of Options. To do this we need to have several
> > >>>>>> things:
> > >>>>>>>>
> > >>>>>>>>  1. A list of headers (text for the columns in the table)
> > >>>>>>>>  2. The minimum and maximum width for each column. (perhaps as a
> > >> %
> > >>> of
> > >>>>>>>>  the width)
> > >>>>>>>>  3. A method that converts the Option into the columns.
> > >>>>>>>>
> > >>>>>>>>
> > >>>>>>>> Interface TableDef {
> > >>>>>>>>       String header();
> > >>>>>>>>       String footer();
> > >>>>>>>>       List<String> columnHeaders();
> > >>>>>>>>       int[] minimumColumnSize();
> > >>>>>>>>       int[] maximumColumnSize();
> > >>>>>>>>       Iterator<List<String>> rows();
> > >>>>>>>> }
> > >>>>>>>>
> > >>>>>>>> abstract class AbstractHelpFormatter {
> > >>>>>>>>   int width;
> > >>>>>>>>   List<TableDef> tables;
> > >>>>>>>>
> > >>>>>>>>   printUsage(PrintWriter writer, String commandLineSyntax) {
> > >>>>>>>>              // print the command line syntax.
> > >>>>>>>>              for(TableDef table : tables) {
> > >>>>>>>>                  writer.println(table.header())
> > >>>>>>>>                  for(String line :
> > >>>>>>>> formatColumns(table.minimumColumnSize(),
> > >> table.maximumColumnSize(),
> > >>>>>>>> columnHeaders())) {
> > >>>>>>>>                      writer.println(line);
> > >>>>>>>>                  }
> > >>>>>>>>                  Iterator<List<String>> rows = table.rows();
> > >>>>>>>>                  while(rows.hasNext()) {
> > >>>>>>>>                      formatColumns(table.minimumColumnSize(),
> > >>>>>>>> table.maximumColumnSize(), row.next()).forEach(writer::println);
> > >>>>>>>>                  }
> > >>>>>>>>                  writer.println(table.footer())
> > >>>>>>>>             }
> > >>>>>>>>    }
> > >>>>>>>> }
> > >>>>>>>>
> > >>>>>>>> where formatColumns is a static method in HelpFormatter that will
> > >>>>>> produce
> > >>>>>>>> a list of Strings necessary to properly display the wrapped
> > >> columns.
> > >>>>>> Any
> > >>>>>>>> helper functions for formatColumns() would also be public static
> > >> so
> > >>>> that
> > >>>>>>>> they can be reused for other implementations.
> > >>>>>>>>
> > >>>>>>>> The concrete implementation would be the implementation we
> > >> currently
> > >>>>>> have
> > >>>>>>>> adapted to fit this pattern.
> > >>>>>>>>
> > >>>>>>>> I have code like this in the new RAT code.
> > >>>>>>>>
> > >>>>>>>> Does this make sense to you?
> > >>>>>>>>
> > >>>>>>>> Claude
> > >>>>>>>>
> > >>>>>>>>
> > >>>>>>>>
> > >>>>>>>>
> > >>>>>>>> On Wed, Sep 18, 2024 at 2:57 PM Eric Pugh <
> > >>>>>>>> ep...@opensourceconnections.com> wrote:
> > >>>>>>>>
> > >>>>>>>>> In Solr we added some additional formatting methods to our
> > >>> Tool.java
> > >>>>>>>>> interface to help with formatting the various tools that use
> > >>>>>> commons-cli:
> > >>>>>>>>>
> > >>>>>>>>> [image: solr.png]
> > >>>>>>>>>
> > >>>>>>>>> solr/solr/core/src/java/org/apache/solr/cli/Tool.java at main ·
> > >>>>>>>>> apache/solr
> > >>>>>>>>> <
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34
> > >>>>>>>
> > >>>>>>>>> github.com
> > >>>>>>>>> <
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34
> > >>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> <
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34
> > >>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> PackageTool had a very very custom help output that we didn’t
> > >> want
> > >>> to
> > >>>>>>>>> lose when we redid things, so it has a custom getHeader:
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> [image: solr.png]
> > >>>>>>>>>
> > >>>>>>>>> solr/solr/core/src/java/org/apache/solr/cli/PackageTool.java at
> > >>> main
> > >>>> ·
> > >>>>>>>>> apache/solr
> > >>>>>>>>> <
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251
> > >>>>>>>
> > >>>>>>>>> github.com
> > >>>>>>>>> <
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251
> > >>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> <
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251
> > >>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> Whereas CreateTool had a short bit of additional text, and then
> > >> the
> > >>>>>>>>> options:
> > >>>>>>>>>
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/CreateTool.java#L70
> > >>>>>>>>>
> > >>>>>>>>> And our PostLogsTool doesn’t use any of those extra formatting
> > >>>> helpers:
> > >>>>>>>>>
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PostLogsTool.java
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> I do wish this had been part of commons-cli!
> > >>>>>>>>>
> > >>>>>>>>> Eric
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> On Sep 18, 2024, at 9:52 AM, Gary Gregory <
> > >> garydgreg...@gmail.com>
> > >>>>>>>>> wrote:
> > >>>>>>>>>
> > >>>>>>>>> Or a new better formatting class?
> > >>>>>>>>>
> > >>>>>>>>> Gary
> > >>>>>>>>>
> > >>>>>>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cla...@xenei.com>
> > >>>> wrote:
> > >>>>>>>>>
> > >>>>>>>>> After more exploration it seems that HelpFormatter is really not
> > >>>>>> designed
> > >>>>>>>>> to be extended.  I will have to rethink this.  It may make sense
> > >> to
> > >>>>>> make
> > >>>>>>>>> some of the HelpFormatter methods static so that they can be used
> > >>> in
> > >>>>>>>>> other
> > >>>>>>>>> implementations.
> > >>>>>>>>>
> > >>>>>>>>> On Wed, Sep 18, 2024 at 9:29 AM Claude Warren <cla...@xenei.com>
> > >>>>>> wrote:
> > >>>>>>>>>
> > >>>>>>>>> Greetings,
> > >>>>>>>>>
> > >>>>>>>>> I have a case in RAT where we want to append a line to the help
> > >>> text
> > >>>>>> when
> > >>>>>>>>> the option has multiple arguments or when we have defined a
> > >> default
> > >>>>>>>>>
> > >>>>>>>>> value.
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> I have implemented this in a renderOptions() implementation in
> > >> CLI
> > >>>>>> 1.8.0.
> > >>>>>>>>> In both cases we use the Option to check for some state and then
> > >>>> append
> > >>>>>>>>>
> > >>>>>>>>> to
> > >>>>>>>>>
> > >>>>>>>>> the optBuf.
> > >>>>>>>>>
> > >>>>>>>>> I am now migrating to 1.9.0 and have to do the same thing, but
> > >>> 1.9.0
> > >>>>>> adds
> > >>>>>>>>> more functionality to the default renderOptions() method so I
> > >> have
> > >>> to
> > >>>>>>>>> rework my implementation.  However, had I not known this was the
> > >>>> case,
> > >>>>>> I
> > >>>>>>>>> would have missed the changes and we would have had some rather
> > >>>>>>>>>
> > >>>>>>>>> interesting
> > >>>>>>>>>
> > >>>>>>>>> bugs later.
> > >>>>>>>>>
> > >>>>>>>>> What I am proposing is a new parameter to renderOptions().  A
> > >>>>>>>>> "Optional<String> Function<Option>".  If the function returns a
> > >>>> String
> > >>>>>>>>>
> > >>>>>>>>> then
> > >>>>>>>>>
> > >>>>>>>>> it is appended to the optBuf.
> > >>>>>>>>>
> > >>>>>>>>> This method would be called near the end of renderOptions.
> > >>>>>>>>>
> > >>>>>>>>> Thoughts?
> > >>>>>>>>> Claude
> > >>>>>>>>>
> > >>>>>>>>> --
> > >>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> --
> > >>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>> _______________________
> > >>>>>>>>> *Eric Pugh **| *Founder | OpenSource Connections, LLC |
> > >>> 434.466.1467
> > >>>> |
> > >>>>>>>>> http://www.opensourceconnections.com | My Free/Busy
> > >>>>>>>>> <http://tinyurl.com/eric-cal>
> > >>>>>>>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
> > >>>>>>>>> <
> > >>>>>>
> > >>>>
> > >>>
> > >>
> > https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw
> > >>>>>>>
> > >>>>>>>>> This e-mail and all contents, including attachments, is
> > >> considered
> > >>> to
> > >>>>>> be
> > >>>>>>>>> Company Confidential unless explicitly stated otherwise,
> > >> regardless
> > >>>>>>>>> of whether attachments are marked as such.
> > >>>>>>>>>
> > >>>>>>>>>
> > >>>>>>>>
> > >>>>>>>> --
> > >>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> > >>>>>>>>
> > >>>>>>>>
> > >>> ---------------------------------------------------------------------
> > >>>>>>>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> > >>>>>>>> For additional commands, e-mail: dev-h...@commons.apache.org
> > >>>>>>>
> > >>>>>>>
> > >>>>>>
> > >>>>>> --
> > >>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> > >>>>>>
> > >>>>
> > >>>> _______________________
> > >>>> Eric Pugh | Founder | OpenSource Connections, LLC | 434.466.1467 |
> > >>>> http://www.opensourceconnections.com <
> > >>>> http://www.opensourceconnections.com/> | My Free/Busy <
> > >>>> http://tinyurl.com/eric-cal>
> > >>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <
> > >>>>
> > >>>
> > >>
> > https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw
> > >>>>
> > >>>>
> > >>>> This e-mail and all contents, including attachments, is considered to
> > >> be
> > >>>> Company Confidential unless explicitly stated otherwise, regardless of
> > >>>> whether attachments are marked as such.
> > >>>>
> > >>>>
> > >>>
> > >>> --
> > >>> LinkedIn: http://www.linkedin.com/in/claudewarren
> > >>>
> > >>
> > >
> > >
> > > --
> > > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
> > _______________________
> > Eric Pugh | Founder | OpenSource Connections, LLC | 434.466.1467 |
> > http://www.opensourceconnections.com <
> > http://www.opensourceconnections.com/> | My Free/Busy <
> > http://tinyurl.com/eric-cal>
> > Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <
> > https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
> >
> > This e-mail and all contents, including attachments, is considered to be
> > Company Confidential unless explicitly stated otherwise, regardless of
> > whether attachments are marked as such.
> >
> >

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org

Reply via email to