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. > >
