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
