Re: [CLI] [DISCUSS] Help formatter extension proposal
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
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
> 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 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
> >> 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 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 columnHeaders();
> int[] minimumColumnSize();
> int[] maximumColumnSize();
> Iterator> rows();
> }
>
> abstract class AbstractHelpFormatter {
> int width;
> List 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> 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
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Looking forward to it 😀
Gary
On Fri, Sep 20, 2024, 3:56 AM Claude Warren 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 >
> 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
> > 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 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
> > >> 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
> 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 columnHeaders();
> > int[] minimumColumnSize();
> > int[] maximumColumnSize();
> > Iterator> rows();
> > }
> >
> > abstract class AbstractHelpFormatter {
> > int width;
> > List 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> 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 H
[lang][LANG-1172] Back and forth on LocaleUtils.toLocale()
Hi All, Following up on this as LANG-1172 changed the previously declared contract of this method. Prior to 2.13, the logic and javadocs clearly stated that the separator must be underscore, but with this change it now also excepts dash. Javadocs from 2.12: "This method validates the input strictly. The language code must be lowercase. The country code must be uppercase. The separator must be an underscore. The length must be correct.” This changed the contract and breaks code that were previous using this method to verify that their locale strings did not have dash, which was sometimes done to differentiate between locales and language tags. However, the new behavior implies that locales and language tags are fully interchangeable, which is also not the case. While I agree it would be useful to have a method that supported conversion of both representations, it would be better to provide that as a new method rather than break the existing contract. TY Josh Gary D. Gregory - Wednesday, September 4, 2024 6:51:00 AM PDT [lang][LANG-1172] Back and forth on LocaleUtils.toLocale() Hi All, I'd like to settle on the implementation of LocaleUtils.toLocale() one way or another and clearly document expectations. What should we do? Please see: - https://issues.apache.org/jira/browse/LANG-1172 - https://github.com/apache/commons-lang/pull/766 - https://github.com/apache/commons-lang/pull/1271 TY! Gary
[VOTE] Release Apache Commons CSV 1.12.0 based on RC1
We have fixed a few bugs and added enhancements since Apache Commons CSV 1.11.0 was released, so I would like to release Apache Commons CSV 1.12.0. Apache Commons CSV 1.12.0 RC1 is available for review here: https://dist.apache.org/repos/dist/dev/commons/csv/1.12.0-RC1 (svn revision 71787) The Git tag commons-csv-1.12.0-RC1 commit for this RC is 67f0d6b30465d817a341b2e9cd31660a646e980c which you can browse here: https://gitbox.apache.org/repos/asf?p=commons-csv.git;a=commit;h=67f0d6b30465d817a341b2e9cd31660a646e980c You may checkout this tag using: git clone https://gitbox.apache.org/repos/asf/commons-csv.git --branch commons-csv-1.12.0-RC1 commons-csv-1.12.0-RC1 Maven artifacts are here: https://repository.apache.org/content/repositories/orgapachecommons-1780/org/apache/commons/commons-csv/1.12.0/ These are the artifacts and their hashes: #Release SHA-512s #Sat Sep 21 02:03:24 UTC 2024 commons-csv-1.12.0-bin.tar.gz=45980075c560c22cdfc776f8cace320a0ae08ca398b328931032e77b36ce863159df5b878d5ee66a3722a80f1a68821aefdd09119ad68132ac6942acd271f4f4 commons-csv-1.12.0-bin.zip=a031cc6b07478bd78584620537ce7d229981afbdd1eb4ddcccd8579ce8132372245e529af68ca0f2c1d3fec6b937a14721c61f26e9ee59f3f58bf190ab2f597e commons-csv-1.12.0-bom.json=a543d07fa191180306810a4b13277fb33942be1d7f810de9477823e8ad109e2e4f40562ff2470c973ea6df3b27b00e22259f21c20613b5aa848e1db0a24e7b7c commons-csv-1.12.0-bom.xml=0ebe7616fbf098e814973579f6229575315dfda1d4edc514d67fbbe7681393f51c39c786daf2cd61828395a461b17cdba52297cd25d9a6ea2866b10fa7ae4fff commons-csv-1.12.0-javadoc.jar=1c18f708c96f18a57da3af7bf388d5e52e6096983cc984327e57076bafbdd67dd70c98b8e4ca1dd9063722fbe7b2bcb93329b154541695866a1abf8583e1c78b commons-csv-1.12.0-sources.jar=51565b1802618de0def0ad963b92ea2d5b715ecd9b30cbc006252821329a93335cf575dd0576f9a85bbf109ee7c546740d90b3c277354dff9b4555fb097e6f36 commons-csv-1.12.0-src.tar.gz=67d8fd651a9785825b2f13c5f6bd95e0f2649ef9f65ec6889a2f9fcb34bd7a2a8c2b2df06e71eb0bcb1d0063953696daadbe06cf87624714682f0c3235fe7d11 commons-csv-1.12.0-src.zip=00c87a08c53ecf55b7e6c959ef910604d04826dfd633921946bd97e3428a6dbc1c84a31735493698a6dc4802bf41fc7e33cff16d5cde4802d5050e22382eed2b commons-csv-1.12.0-test-sources.jar=3f09d2e51878580bccc04d01f561791ce62617d232881d2b2c609f4cb72c688becacc747c986bfd3217010db5d83bfd8f96f8438d00e2cf5d1bfa5f91915d702 commons-csv-1.12.0-tests.jar=c0a7b570d0a2aeb2fd28c4237f260ed738396ab7531d770471abe47b89e602cf75e0248b122e6a410a52645dd059ea4b602ddb290252b989cb802ed88b04533a org.apache.commons_commons-csv-1.12.0.spdx.json=eb4ef1d3ee51acbb9f0ea3bc51ad5bc9c5a027538f165d7bc46502dc4a479552c9730b65181ec8a251a34cfd6e1541cdbdc8c6d01a1b8f466a4c01237551916b I have tested this with 'mvn' and 'mvn -e -V -Prelease -Ptest-deploy -P jacoco -P japicmp clean package site deploy' using: openjdk version "17.0.12" 2024-07-16 OpenJDK Runtime Environment Homebrew (build 17.0.12+0) OpenJDK 64-Bit Server VM Homebrew (build 17.0.12+0, mixed mode, sharing) Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937) Maven home: /usr/local/Cellar/maven/3.9.9/libexec Java version: 17.0.12, vendor: Homebrew, runtime: /usr/local/Cellar/openjdk@17/17.0.12/libexec/openjdk.jdk/Contents/Home Default locale: en_US, platform encoding: UTF-8 OS name: "mac os x", version: "14.6.1", arch: "x86_64", family: "mac" Darwin 23.6.0 Darwin Kernel Version 23.6.0: Mon Jul 29 21:13:00 PDT 2024; root:xnu-10063.141.2~1/RELEASE_X86_64 x86_64 Details of changes since 1.11.0 are in the release notes: https://dist.apache.org/repos/dist/dev/commons/csv/1.12.0-RC1/RELEASE-NOTES.txt https://dist.apache.org/repos/dist/dev/commons/csv/1.12.0-RC1/site/changes-report.html Site: https://dist.apache.org/repos/dist/dev/commons/csv/1.12.0-RC1/site/index.html (note some *relative* links are broken and the 1.12.0 directories are not yet created - these will be OK once the site is deployed.) JApiCmp Report (compared to 1.11.0): https://dist.apache.org/repos/dist/dev/commons/csv/1.12.0-RC1/site/japicmp.html RAT Report: https://dist.apache.org/repos/dist/dev/commons/csv/1.12.0-RC1/site/rat-report.html KEYS: https://downloads.apache.org/commons/KEYS Please review the release candidate and vote. This vote will close no sooner than 72 hours from now. [ ] +1 Release these artifacts [ ] +0 OK, but... [ ] -0 OK, but really should fix... [ ] -1 I oppose this release because... Thank you, Gary Gregory, Release Manager (using key 86fdc7e2a11262cb) The following is intended as a helper and refresher for reviewers. Validating a release candidate == These guidelines are NOT complete. Requirements: Git, Java, Maven. You can validate a release from a release candidate (RC) tag as follows. 1a) Clone and checkout the RC tag git clone https://gitbox.apache.org/repos/asf/commons-csv.git --branch commons-csv-1.12.0-RC1 commons-csv-1.12.0-RC1 cd commons-csv-1.12.0-RC1 1b) Download and unpack the source archive
