You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Claude Warren <cl...@xenei.com> on 2024/09/18 08:29:46 UTC
[CLI] [DISCUSS] Help formatter extension proposal
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
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
Hi Eric,
TextStyle and TextHelpAppenndable carry widths.
HTH,
Gary
On Tue, Nov 12, 2024, 7:43 AM Eric Pugh <ep...@opensourceconnections.com>
wrote:
> Working through it… I am hoping to be able to contribute a
> AsciiDocAppendable.
>
> So, here is a question.. How do I set the Width?
> HelpFormatter.setWidth() has gone away, and I can’t quite track where it
> went!
>
>
> > On Nov 10, 2024, at 10:36 AM, Gary Gregory <ga...@gmail.com>
> wrote:
> >
> > Let me know and feel free to create a PR.
> >
> > I can cut a release candidate whenever you are ready.
> >
> > Gary
> >
> > On Sun, Nov 10, 2024, 7:23 AM Eric Pugh <epugh@opensourceconnections.com
> >
> > wrote:
> >
> >> I am starting to poke at the CLI-339 feature.. Looking at the PR,
> >>
> >>
> https://github.com/apache/commons-cli/pull/314/files#diff-c5837d81e3e4f87d5222b1d8caa45c9c9cd2c6edff6ad31e3a0b603f0b64d389
> >> ,
> >> I see the code... I am not quite seeing the big picture however...
> I
> >> am hoping to see some docs on "How to use the new Help Formatter
> >> extensions"...
> >>
> >> It does seem like JavaDocs are our primary documentation format over the
> >> website usage.html page...
> >>
> >> I'm hoping to confirm that what Claude wrote (thank you!!) works the
> way we
> >> want it to before 1.10 goes out!
> >>
> >> On Fri, Oct 4, 2024 at 12:56 PM Claude Warren <cl...@xenei.com> wrote:
> >>
> >>> Thx Gary. I will review this weekend.
> >>>
> >>> On Fri 4 Oct 2024, 15:41 Gary D. Gregory, <gg...@apache.org> wrote:
> >>>
> >>>> Hi all,
> >>>>
> >>>> I wrote a bunch of comments in the PR.
> >>>>
> >>>> Gary
> >>>>
> >>>> On 2024/10/02 10:57:53 Tushar Kapila wrote:
> >>>>> I don't contribute code. But looking at the dictionary meaning Scribe
> >>>> fits.
> >>>>> So my vote is Scribe.
> >>>>>
> >>>>> a word that fits and not confused with existing class/
> >> responsibility?
> >>>>>
> >>>>> verb
> >>>>> 1.
> >>>>> literary
> >>>>> write.
> >>>>> "he scribed a note that he passed to Dan"
> >>>>>
> >>>>> On Wed, 2 Oct 2024, 14:35 Gary Gregory, <ga...@gmail.com>
> >>> wrote:
> >>>>>
> >>>>>> Sorry about that, I'll have a look today or tomorrow.
> >>>>>>
> >>>>>> Gary
> >>>>>>
> >>>>>> On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com>
> >> wrote:
> >>>>>>
> >>>>>>> Not hearing any other ideas and even though I prefer "Scribe" I
> >>> will
> >>>>>> rename
> >>>>>>> the class to "HelpWriter".
> >>>>>>>
> >>>>>>> Thanks everyone for your input.
> >>>>>>>
> >>>>>>> On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net>
> >>> wrote:
> >>>>>>>
> >>>>>>>> My vote (which everyone is free to ignore) is still for
> >>> HelpWriter.
> >>>>>> It's
> >>>>>>>> simple and intuitive, and it's consistent with the names of the
> >>>> methods
> >>>>>>> the
> >>>>>>>> interface declares (e.g. writePara, writeTable). I
> >>>>>>>> find SemanticAppendableDecorator too verbose and I have no
> >>>> intuition
> >>>>>> for
> >>>>>>>> what it means.
> >>>>>>>>
> >>>>>>>> Peter
> >>>>>>>>
> >>>>>>>> On Mon, Sep 30, 2024, 12:31 PM Claude Warren <claude@xenei.com
> >>>
> >>>> wrote:
> >>>>>>>>
> >>>>>>>>> If we can settle on a name for the
> >>>>>>>>> serializer/scribe/writer/printDecorator/amenuensis thing the
> >>>> rest of
> >>>>>>> the
> >>>>>>>>> code is ready. It passes all the tests, it has 100% test
> >>>> coverage,
> >>>>>>> and
> >>>>>>>> it
> >>>>>>>>> works for what Rat is trying to do.
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>> On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <
> >>> claude@xenei.com>
> >>>>>>> wrote:
> >>>>>>>>>
> >>>>>>>>>> I have opened
> >> https://github.com/apache/commons-cli/pull/314
> >>>> to
> >>>>>>> track
> >>>>>>>>> the
> >>>>>>>>>> proposed changes
> >>>>>>>>>>
> >>>>>>>>>> On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <
> >>>> claude@xenei.com>
> >>>>>>>> wrote:
> >>>>>>>>>>
> >>>>>>>>>>> I know some graphics programs use the term "engraver" for
> >>> code
> >>>>>> that
> >>>>>>>>>>> creates the output of graphical representations of things
> >>>> (like
> >>>>>>> notes,
> >>>>>>>>>>> staves, and resets in musical notation). Scribe seems
> >> like
> >>>> the
> >>>>>>>> textual
> >>>>>>>>>>> equivalent.
> >>>>>>>>>>>
> >>>>>>>>>>> If we go with the decorator approach then I think the
> >>>> underlying
> >>>>>>>>>>> interface should be SemanticAppendableDecorator.
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>> - Semantic because it describes what to do with the
> >>>> semantic
> >>>>>>> terms
> >>>>>>>>>>> like "paragraph", "header", and "list".
> >>>>>>>>>>> - Appendable because that is what is wraps.
> >>>>>>>>>>> - Decorator because that is what it does.
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
> >>>>>>> gilleseran@gmail.com
> >>>>>>>>>
> >>>>>>>>>>> wrote:
> >>>>>>>>>>>
> >>>>>>>>>>>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
> >>>>>>> garydgregory@gmail.com>
> >>>>>>>> a
> >>>>>>>>>>>> écrit :
> >>>>>>>>>>>>>
> >>>>>>>>>>>>> It's pretty unusual IMO, not like anything in the JDK
> >> for
> >>>>>>> example.
> >>>>>>>>>>>>
> >>>>>>>>>>>> Agreed.
> >>>>>>>>>>>>
> >>>>>>>>>>>>> I'll see
> >>>>>>>>>>>>> if I can come up with something tomorrow...
> >>>>>>>>>>>>
> >>>>>>>>>>>> How about "PrintDecorator" ?
> >>>>>>>>>>>>
> >>>>>>>>>>>> Gilles
> >>>>>>>>>>>>
> >>>>>>>>>>>>>>> [...]
> >>>>>>>>>>>>
> >>>>>>>>>>>>
> >>>>>>>
> >>> ---------------------------------------------------------------------
> >>>>>>>>>>>> To unsubscribe, e-mail:
> >> dev-unsubscribe@commons.apache.org
> >>>>>>>>>>>> For additional commands, e-mail:
> >>> dev-help@commons.apache.org
> >>>>>>>>>>>>
> >>>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>> --
> >>>>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>> --
> >>>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>> --
> >>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>>>>>
> >>>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> --
> >>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>>>
> >>>>>>
> >>>>>
> >>>>
> >>>> ---------------------------------------------------------------------
> >>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >>>> For additional commands, e-mail: dev-help@commons.apache.org
> >>>>
> >>>>
> >>>
> >>
>
> _______________________
> 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.
>
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
Width is set in the TextStyle and (potentially) in the Appendable.
The TextStyle specifies for the specific chunk of code what the requested
size is. The Appendable can ignore that or make adjustments to it. This
is seen in the TextHelpAppendable.appendTable() method where the specified
columns for the table may be adjusted to fit the page width. If
AsciiDocAppendable has the concept of width then look to the
TextHelpAppendable for examples.
Some Appendables may choose not to specify a width (e.g. XHTML for example,
though it may also create CSS inline or something similar with the width
information).
AlmostPlainText doesn't have any with controls that I could find, nor does
markdown so they would ignore the width settings.
I hope this makes sense,
Claude
On Tue, Nov 12, 2024 at 12:43 PM Eric Pugh <ep...@opensourceconnections.com>
wrote:
> Working through it… I am hoping to be able to contribute a
> AsciiDocAppendable.
>
> So, here is a question.. How do I set the Width?
> HelpFormatter.setWidth() has gone away, and I can’t quite track where it
> went!
>
>
> > On Nov 10, 2024, at 10:36 AM, Gary Gregory <ga...@gmail.com>
> wrote:
> >
> > Let me know and feel free to create a PR.
> >
> > I can cut a release candidate whenever you are ready.
> >
> > Gary
> >
> > On Sun, Nov 10, 2024, 7:23 AM Eric Pugh <epugh@opensourceconnections.com
> >
> > wrote:
> >
> >> I am starting to poke at the CLI-339 feature.. Looking at the PR,
> >>
> >>
> https://github.com/apache/commons-cli/pull/314/files#diff-c5837d81e3e4f87d5222b1d8caa45c9c9cd2c6edff6ad31e3a0b603f0b64d389
> >> ,
> >> I see the code... I am not quite seeing the big picture however...
> I
> >> am hoping to see some docs on "How to use the new Help Formatter
> >> extensions"...
> >>
> >> It does seem like JavaDocs are our primary documentation format over the
> >> website usage.html page...
> >>
> >> I'm hoping to confirm that what Claude wrote (thank you!!) works the
> way we
> >> want it to before 1.10 goes out!
> >>
> >> On Fri, Oct 4, 2024 at 12:56 PM Claude Warren <cl...@xenei.com> wrote:
> >>
> >>> Thx Gary. I will review this weekend.
> >>>
> >>> On Fri 4 Oct 2024, 15:41 Gary D. Gregory, <gg...@apache.org> wrote:
> >>>
> >>>> Hi all,
> >>>>
> >>>> I wrote a bunch of comments in the PR.
> >>>>
> >>>> Gary
> >>>>
> >>>> On 2024/10/02 10:57:53 Tushar Kapila wrote:
> >>>>> I don't contribute code. But looking at the dictionary meaning Scribe
> >>>> fits.
> >>>>> So my vote is Scribe.
> >>>>>
> >>>>> a word that fits and not confused with existing class/
> >> responsibility?
> >>>>>
> >>>>> verb
> >>>>> 1.
> >>>>> literary
> >>>>> write.
> >>>>> "he scribed a note that he passed to Dan"
> >>>>>
> >>>>> On Wed, 2 Oct 2024, 14:35 Gary Gregory, <ga...@gmail.com>
> >>> wrote:
> >>>>>
> >>>>>> Sorry about that, I'll have a look today or tomorrow.
> >>>>>>
> >>>>>> Gary
> >>>>>>
> >>>>>> On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com>
> >> wrote:
> >>>>>>
> >>>>>>> Not hearing any other ideas and even though I prefer "Scribe" I
> >>> will
> >>>>>> rename
> >>>>>>> the class to "HelpWriter".
> >>>>>>>
> >>>>>>> Thanks everyone for your input.
> >>>>>>>
> >>>>>>> On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net>
> >>> wrote:
> >>>>>>>
> >>>>>>>> My vote (which everyone is free to ignore) is still for
> >>> HelpWriter.
> >>>>>> It's
> >>>>>>>> simple and intuitive, and it's consistent with the names of the
> >>>> methods
> >>>>>>> the
> >>>>>>>> interface declares (e.g. writePara, writeTable). I
> >>>>>>>> find SemanticAppendableDecorator too verbose and I have no
> >>>> intuition
> >>>>>> for
> >>>>>>>> what it means.
> >>>>>>>>
> >>>>>>>> Peter
> >>>>>>>>
> >>>>>>>> On Mon, Sep 30, 2024, 12:31 PM Claude Warren <claude@xenei.com
> >>>
> >>>> wrote:
> >>>>>>>>
> >>>>>>>>> If we can settle on a name for the
> >>>>>>>>> serializer/scribe/writer/printDecorator/amenuensis thing the
> >>>> rest of
> >>>>>>> the
> >>>>>>>>> code is ready. It passes all the tests, it has 100% test
> >>>> coverage,
> >>>>>>> and
> >>>>>>>> it
> >>>>>>>>> works for what Rat is trying to do.
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>> On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <
> >>> claude@xenei.com>
> >>>>>>> wrote:
> >>>>>>>>>
> >>>>>>>>>> I have opened
> >> https://github.com/apache/commons-cli/pull/314
> >>>> to
> >>>>>>> track
> >>>>>>>>> the
> >>>>>>>>>> proposed changes
> >>>>>>>>>>
> >>>>>>>>>> On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <
> >>>> claude@xenei.com>
> >>>>>>>> wrote:
> >>>>>>>>>>
> >>>>>>>>>>> I know some graphics programs use the term "engraver" for
> >>> code
> >>>>>> that
> >>>>>>>>>>> creates the output of graphical representations of things
> >>>> (like
> >>>>>>> notes,
> >>>>>>>>>>> staves, and resets in musical notation). Scribe seems
> >> like
> >>>> the
> >>>>>>>> textual
> >>>>>>>>>>> equivalent.
> >>>>>>>>>>>
> >>>>>>>>>>> If we go with the decorator approach then I think the
> >>>> underlying
> >>>>>>>>>>> interface should be SemanticAppendableDecorator.
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>> - Semantic because it describes what to do with the
> >>>> semantic
> >>>>>>> terms
> >>>>>>>>>>> like "paragraph", "header", and "list".
> >>>>>>>>>>> - Appendable because that is what is wraps.
> >>>>>>>>>>> - Decorator because that is what it does.
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
> >>>>>>> gilleseran@gmail.com
> >>>>>>>>>
> >>>>>>>>>>> wrote:
> >>>>>>>>>>>
> >>>>>>>>>>>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
> >>>>>>> garydgregory@gmail.com>
> >>>>>>>> a
> >>>>>>>>>>>> écrit :
> >>>>>>>>>>>>>
> >>>>>>>>>>>>> It's pretty unusual IMO, not like anything in the JDK
> >> for
> >>>>>>> example.
> >>>>>>>>>>>>
> >>>>>>>>>>>> Agreed.
> >>>>>>>>>>>>
> >>>>>>>>>>>>> I'll see
> >>>>>>>>>>>>> if I can come up with something tomorrow...
> >>>>>>>>>>>>
> >>>>>>>>>>>> How about "PrintDecorator" ?
> >>>>>>>>>>>>
> >>>>>>>>>>>> Gilles
> >>>>>>>>>>>>
> >>>>>>>>>>>>>>> [...]
> >>>>>>>>>>>>
> >>>>>>>>>>>>
> >>>>>>>
> >>> ---------------------------------------------------------------------
> >>>>>>>>>>>> To unsubscribe, e-mail:
> >> dev-unsubscribe@commons.apache.org
> >>>>>>>>>>>> For additional commands, e-mail:
> >>> dev-help@commons.apache.org
> >>>>>>>>>>>>
> >>>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>> --
> >>>>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>> --
> >>>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>> --
> >>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>>>>>
> >>>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> --
> >>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>>>
> >>>>>>
> >>>>>
> >>>>
> >>>> ---------------------------------------------------------------------
> >>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >>>> For additional commands, e-mail: dev-help@commons.apache.org
> >>>>
> >>>>
> >>>
> >>
>
> _______________________
> 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
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Eric Pugh <ep...@opensourceconnections.com>.
Working through it… I am hoping to be able to contribute a AsciiDocAppendable.
So, here is a question.. How do I set the Width? HelpFormatter.setWidth() has gone away, and I can’t quite track where it went!
> On Nov 10, 2024, at 10:36 AM, Gary Gregory <ga...@gmail.com> wrote:
>
> Let me know and feel free to create a PR.
>
> I can cut a release candidate whenever you are ready.
>
> Gary
>
> On Sun, Nov 10, 2024, 7:23 AM Eric Pugh <ep...@opensourceconnections.com>
> wrote:
>
>> I am starting to poke at the CLI-339 feature.. Looking at the PR,
>>
>> https://github.com/apache/commons-cli/pull/314/files#diff-c5837d81e3e4f87d5222b1d8caa45c9c9cd2c6edff6ad31e3a0b603f0b64d389
>> ,
>> I see the code... I am not quite seeing the big picture however... I
>> am hoping to see some docs on "How to use the new Help Formatter
>> extensions"...
>>
>> It does seem like JavaDocs are our primary documentation format over the
>> website usage.html page...
>>
>> I'm hoping to confirm that what Claude wrote (thank you!!) works the way we
>> want it to before 1.10 goes out!
>>
>> On Fri, Oct 4, 2024 at 12:56 PM Claude Warren <cl...@xenei.com> wrote:
>>
>>> Thx Gary. I will review this weekend.
>>>
>>> On Fri 4 Oct 2024, 15:41 Gary D. Gregory, <gg...@apache.org> wrote:
>>>
>>>> Hi all,
>>>>
>>>> I wrote a bunch of comments in the PR.
>>>>
>>>> Gary
>>>>
>>>> On 2024/10/02 10:57:53 Tushar Kapila wrote:
>>>>> I don't contribute code. But looking at the dictionary meaning Scribe
>>>> fits.
>>>>> So my vote is Scribe.
>>>>>
>>>>> a word that fits and not confused with existing class/
>> responsibility?
>>>>>
>>>>> verb
>>>>> 1.
>>>>> literary
>>>>> write.
>>>>> "he scribed a note that he passed to Dan"
>>>>>
>>>>> On Wed, 2 Oct 2024, 14:35 Gary Gregory, <ga...@gmail.com>
>>> wrote:
>>>>>
>>>>>> Sorry about that, I'll have a look today or tomorrow.
>>>>>>
>>>>>> Gary
>>>>>>
>>>>>> On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com>
>> wrote:
>>>>>>
>>>>>>> Not hearing any other ideas and even though I prefer "Scribe" I
>>> will
>>>>>> rename
>>>>>>> the class to "HelpWriter".
>>>>>>>
>>>>>>> Thanks everyone for your input.
>>>>>>>
>>>>>>> On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net>
>>> wrote:
>>>>>>>
>>>>>>>> My vote (which everyone is free to ignore) is still for
>>> HelpWriter.
>>>>>> It's
>>>>>>>> simple and intuitive, and it's consistent with the names of the
>>>> methods
>>>>>>> the
>>>>>>>> interface declares (e.g. writePara, writeTable). I
>>>>>>>> find SemanticAppendableDecorator too verbose and I have no
>>>> intuition
>>>>>> for
>>>>>>>> what it means.
>>>>>>>>
>>>>>>>> Peter
>>>>>>>>
>>>>>>>> On Mon, Sep 30, 2024, 12:31 PM Claude Warren <claude@xenei.com
>>>
>>>> wrote:
>>>>>>>>
>>>>>>>>> If we can settle on a name for the
>>>>>>>>> serializer/scribe/writer/printDecorator/amenuensis thing the
>>>> rest of
>>>>>>> the
>>>>>>>>> code is ready. It passes all the tests, it has 100% test
>>>> coverage,
>>>>>>> and
>>>>>>>> it
>>>>>>>>> works for what Rat is trying to do.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <
>>> claude@xenei.com>
>>>>>>> wrote:
>>>>>>>>>
>>>>>>>>>> I have opened
>> https://github.com/apache/commons-cli/pull/314
>>>> to
>>>>>>> track
>>>>>>>>> the
>>>>>>>>>> proposed changes
>>>>>>>>>>
>>>>>>>>>> On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <
>>>> claude@xenei.com>
>>>>>>>> wrote:
>>>>>>>>>>
>>>>>>>>>>> I know some graphics programs use the term "engraver" for
>>> code
>>>>>> that
>>>>>>>>>>> creates the output of graphical representations of things
>>>> (like
>>>>>>> notes,
>>>>>>>>>>> staves, and resets in musical notation). Scribe seems
>> like
>>>> the
>>>>>>>> textual
>>>>>>>>>>> equivalent.
>>>>>>>>>>>
>>>>>>>>>>> If we go with the decorator approach then I think the
>>>> underlying
>>>>>>>>>>> interface should be SemanticAppendableDecorator.
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> - Semantic because it describes what to do with the
>>>> semantic
>>>>>>> terms
>>>>>>>>>>> like "paragraph", "header", and "list".
>>>>>>>>>>> - Appendable because that is what is wraps.
>>>>>>>>>>> - Decorator because that is what it does.
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
>>>>>>> gilleseran@gmail.com
>>>>>>>>>
>>>>>>>>>>> wrote:
>>>>>>>>>>>
>>>>>>>>>>>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
>>>>>>> garydgregory@gmail.com>
>>>>>>>> a
>>>>>>>>>>>> écrit :
>>>>>>>>>>>>>
>>>>>>>>>>>>> It's pretty unusual IMO, not like anything in the JDK
>> for
>>>>>>> example.
>>>>>>>>>>>>
>>>>>>>>>>>> Agreed.
>>>>>>>>>>>>
>>>>>>>>>>>>> I'll see
>>>>>>>>>>>>> if I can come up with something tomorrow...
>>>>>>>>>>>>
>>>>>>>>>>>> How about "PrintDecorator" ?
>>>>>>>>>>>>
>>>>>>>>>>>> Gilles
>>>>>>>>>>>>
>>>>>>>>>>>>>>> [...]
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>
>>> ---------------------------------------------------------------------
>>>>>>>>>>>> To unsubscribe, e-mail:
>> dev-unsubscribe@commons.apache.org
>>>>>>>>>>>> For additional commands, e-mail:
>>> dev-help@commons.apache.org
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> --
>>>>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> --
>>>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> --
>>>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>
>>>>
>>>
>>
_______________________
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.
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
Let me know and feel free to create a PR.
I can cut a release candidate whenever you are ready.
Gary
On Sun, Nov 10, 2024, 7:23 AM Eric Pugh <ep...@opensourceconnections.com>
wrote:
> I am starting to poke at the CLI-339 feature.. Looking at the PR,
>
> https://github.com/apache/commons-cli/pull/314/files#diff-c5837d81e3e4f87d5222b1d8caa45c9c9cd2c6edff6ad31e3a0b603f0b64d389
> ,
> I see the code... I am not quite seeing the big picture however... I
> am hoping to see some docs on "How to use the new Help Formatter
> extensions"...
>
> It does seem like JavaDocs are our primary documentation format over the
> website usage.html page...
>
> I'm hoping to confirm that what Claude wrote (thank you!!) works the way we
> want it to before 1.10 goes out!
>
> On Fri, Oct 4, 2024 at 12:56 PM Claude Warren <cl...@xenei.com> wrote:
>
> > Thx Gary. I will review this weekend.
> >
> > On Fri 4 Oct 2024, 15:41 Gary D. Gregory, <gg...@apache.org> wrote:
> >
> > > Hi all,
> > >
> > > I wrote a bunch of comments in the PR.
> > >
> > > Gary
> > >
> > > On 2024/10/02 10:57:53 Tushar Kapila wrote:
> > > > I don't contribute code. But looking at the dictionary meaning Scribe
> > > fits.
> > > > So my vote is Scribe.
> > > >
> > > > a word that fits and not confused with existing class/
> responsibility?
> > > >
> > > > verb
> > > > 1.
> > > > literary
> > > > write.
> > > > "he scribed a note that he passed to Dan"
> > > >
> > > > On Wed, 2 Oct 2024, 14:35 Gary Gregory, <ga...@gmail.com>
> > wrote:
> > > >
> > > > > Sorry about that, I'll have a look today or tomorrow.
> > > > >
> > > > > Gary
> > > > >
> > > > > On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com>
> wrote:
> > > > >
> > > > > > Not hearing any other ideas and even though I prefer "Scribe" I
> > will
> > > > > rename
> > > > > > the class to "HelpWriter".
> > > > > >
> > > > > > Thanks everyone for your input.
> > > > > >
> > > > > > On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net>
> > wrote:
> > > > > >
> > > > > > > My vote (which everyone is free to ignore) is still for
> > HelpWriter.
> > > > > It's
> > > > > > > simple and intuitive, and it's consistent with the names of the
> > > methods
> > > > > > the
> > > > > > > interface declares (e.g. writePara, writeTable). I
> > > > > > > find SemanticAppendableDecorator too verbose and I have no
> > > intuition
> > > > > for
> > > > > > > what it means.
> > > > > > >
> > > > > > > Peter
> > > > > > >
> > > > > > > On Mon, Sep 30, 2024, 12:31 PM Claude Warren <claude@xenei.com
> >
> > > wrote:
> > > > > > >
> > > > > > > > If we can settle on a name for the
> > > > > > > > serializer/scribe/writer/printDecorator/amenuensis thing the
> > > rest of
> > > > > > the
> > > > > > > > code is ready. It passes all the tests, it has 100% test
> > > coverage,
> > > > > > and
> > > > > > > it
> > > > > > > > works for what Rat is trying to do.
> > > > > > > >
> > > > > > > >
> > > > > > > > On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <
> > claude@xenei.com>
> > > > > > wrote:
> > > > > > > >
> > > > > > > > > I have opened
> https://github.com/apache/commons-cli/pull/314
> > > to
> > > > > > track
> > > > > > > > the
> > > > > > > > > proposed changes
> > > > > > > > >
> > > > > > > > > On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <
> > > claude@xenei.com>
> > > > > > > wrote:
> > > > > > > > >
> > > > > > > > >> I know some graphics programs use the term "engraver" for
> > code
> > > > > that
> > > > > > > > >> creates the output of graphical representations of things
> > > (like
> > > > > > notes,
> > > > > > > > >> staves, and resets in musical notation). Scribe seems
> like
> > > the
> > > > > > > textual
> > > > > > > > >> equivalent.
> > > > > > > > >>
> > > > > > > > >> If we go with the decorator approach then I think the
> > > underlying
> > > > > > > > >> interface should be SemanticAppendableDecorator.
> > > > > > > > >>
> > > > > > > > >>
> > > > > > > > >> - Semantic because it describes what to do with the
> > > semantic
> > > > > > terms
> > > > > > > > >> like "paragraph", "header", and "list".
> > > > > > > > >> - Appendable because that is what is wraps.
> > > > > > > > >> - Decorator because that is what it does.
> > > > > > > > >>
> > > > > > > > >>
> > > > > > > > >>
> > > > > > > > >> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
> > > > > > gilleseran@gmail.com
> > > > > > > >
> > > > > > > > >> wrote:
> > > > > > > > >>
> > > > > > > > >>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
> > > > > > garydgregory@gmail.com>
> > > > > > > a
> > > > > > > > >>> écrit :
> > > > > > > > >>> >
> > > > > > > > >>> > It's pretty unusual IMO, not like anything in the JDK
> for
> > > > > > example.
> > > > > > > > >>>
> > > > > > > > >>> Agreed.
> > > > > > > > >>>
> > > > > > > > >>> > I'll see
> > > > > > > > >>> > if I can come up with something tomorrow...
> > > > > > > > >>>
> > > > > > > > >>> How about "PrintDecorator" ?
> > > > > > > > >>>
> > > > > > > > >>> Gilles
> > > > > > > > >>>
> > > > > > > > >>> >>> [...]
> > > > > > > > >>>
> > > > > > > > >>>
> > > > > >
> > ---------------------------------------------------------------------
> > > > > > > > >>> To unsubscribe, e-mail:
> dev-unsubscribe@commons.apache.org
> > > > > > > > >>> For additional commands, e-mail:
> > dev-help@commons.apache.org
> > > > > > > > >>>
> > > > > > > > >>>
> > > > > > > > >>
> > > > > > > > >> --
> > > > > > > > >> LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > > > > >>
> > > > > > > > >
> > > > > > > > >
> > > > > > > > > --
> > > > > > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > --
> > > > > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > > > >
> > > > > > >
> > > > > >
> > > > > >
> > > > > > --
> > > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > >
> > > > >
> > > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > >
> >
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Eric Pugh <ep...@opensourceconnections.com>.
I am starting to poke at the CLI-339 feature.. Looking at the PR,
https://github.com/apache/commons-cli/pull/314/files#diff-c5837d81e3e4f87d5222b1d8caa45c9c9cd2c6edff6ad31e3a0b603f0b64d389,
I see the code... I am not quite seeing the big picture however... I
am hoping to see some docs on "How to use the new Help Formatter
extensions"...
It does seem like JavaDocs are our primary documentation format over the
website usage.html page...
I'm hoping to confirm that what Claude wrote (thank you!!) works the way we
want it to before 1.10 goes out!
On Fri, Oct 4, 2024 at 12:56 PM Claude Warren <cl...@xenei.com> wrote:
> Thx Gary. I will review this weekend.
>
> On Fri 4 Oct 2024, 15:41 Gary D. Gregory, <gg...@apache.org> wrote:
>
> > Hi all,
> >
> > I wrote a bunch of comments in the PR.
> >
> > Gary
> >
> > On 2024/10/02 10:57:53 Tushar Kapila wrote:
> > > I don't contribute code. But looking at the dictionary meaning Scribe
> > fits.
> > > So my vote is Scribe.
> > >
> > > a word that fits and not confused with existing class/ responsibility?
> > >
> > > verb
> > > 1.
> > > literary
> > > write.
> > > "he scribed a note that he passed to Dan"
> > >
> > > On Wed, 2 Oct 2024, 14:35 Gary Gregory, <ga...@gmail.com>
> wrote:
> > >
> > > > Sorry about that, I'll have a look today or tomorrow.
> > > >
> > > > Gary
> > > >
> > > > On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com> wrote:
> > > >
> > > > > Not hearing any other ideas and even though I prefer "Scribe" I
> will
> > > > rename
> > > > > the class to "HelpWriter".
> > > > >
> > > > > Thanks everyone for your input.
> > > > >
> > > > > On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net>
> wrote:
> > > > >
> > > > > > My vote (which everyone is free to ignore) is still for
> HelpWriter.
> > > > It's
> > > > > > simple and intuitive, and it's consistent with the names of the
> > methods
> > > > > the
> > > > > > interface declares (e.g. writePara, writeTable). I
> > > > > > find SemanticAppendableDecorator too verbose and I have no
> > intuition
> > > > for
> > > > > > what it means.
> > > > > >
> > > > > > Peter
> > > > > >
> > > > > > On Mon, Sep 30, 2024, 12:31 PM Claude Warren <cl...@xenei.com>
> > wrote:
> > > > > >
> > > > > > > If we can settle on a name for the
> > > > > > > serializer/scribe/writer/printDecorator/amenuensis thing the
> > rest of
> > > > > the
> > > > > > > code is ready. It passes all the tests, it has 100% test
> > coverage,
> > > > > and
> > > > > > it
> > > > > > > works for what Rat is trying to do.
> > > > > > >
> > > > > > >
> > > > > > > On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <
> claude@xenei.com>
> > > > > wrote:
> > > > > > >
> > > > > > > > I have opened https://github.com/apache/commons-cli/pull/314
> > to
> > > > > track
> > > > > > > the
> > > > > > > > proposed changes
> > > > > > > >
> > > > > > > > On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <
> > claude@xenei.com>
> > > > > > wrote:
> > > > > > > >
> > > > > > > >> I know some graphics programs use the term "engraver" for
> code
> > > > that
> > > > > > > >> creates the output of graphical representations of things
> > (like
> > > > > notes,
> > > > > > > >> staves, and resets in musical notation). Scribe seems like
> > the
> > > > > > textual
> > > > > > > >> equivalent.
> > > > > > > >>
> > > > > > > >> If we go with the decorator approach then I think the
> > underlying
> > > > > > > >> interface should be SemanticAppendableDecorator.
> > > > > > > >>
> > > > > > > >>
> > > > > > > >> - Semantic because it describes what to do with the
> > semantic
> > > > > terms
> > > > > > > >> like "paragraph", "header", and "list".
> > > > > > > >> - Appendable because that is what is wraps.
> > > > > > > >> - Decorator because that is what it does.
> > > > > > > >>
> > > > > > > >>
> > > > > > > >>
> > > > > > > >> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
> > > > > gilleseran@gmail.com
> > > > > > >
> > > > > > > >> wrote:
> > > > > > > >>
> > > > > > > >>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
> > > > > garydgregory@gmail.com>
> > > > > > a
> > > > > > > >>> écrit :
> > > > > > > >>> >
> > > > > > > >>> > It's pretty unusual IMO, not like anything in the JDK for
> > > > > example.
> > > > > > > >>>
> > > > > > > >>> Agreed.
> > > > > > > >>>
> > > > > > > >>> > I'll see
> > > > > > > >>> > if I can come up with something tomorrow...
> > > > > > > >>>
> > > > > > > >>> How about "PrintDecorator" ?
> > > > > > > >>>
> > > > > > > >>> Gilles
> > > > > > > >>>
> > > > > > > >>> >>> [...]
> > > > > > > >>>
> > > > > > > >>>
> > > > >
> ---------------------------------------------------------------------
> > > > > > > >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > > > > > >>> For additional commands, e-mail:
> dev-help@commons.apache.org
> > > > > > > >>>
> > > > > > > >>>
> > > > > > > >>
> > > > > > > >> --
> > > > > > > >> LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > > > >>
> > > > > > > >
> > > > > > > >
> > > > > > > > --
> > > > > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > --
> > > > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > > >
> > > > > >
> > > > >
> > > > >
> > > > > --
> > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > >
> > > >
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
Thx Gary. I will review this weekend.
On Fri 4 Oct 2024, 15:41 Gary D. Gregory, <gg...@apache.org> wrote:
> Hi all,
>
> I wrote a bunch of comments in the PR.
>
> Gary
>
> On 2024/10/02 10:57:53 Tushar Kapila wrote:
> > I don't contribute code. But looking at the dictionary meaning Scribe
> fits.
> > So my vote is Scribe.
> >
> > a word that fits and not confused with existing class/ responsibility?
> >
> > verb
> > 1.
> > literary
> > write.
> > "he scribed a note that he passed to Dan"
> >
> > On Wed, 2 Oct 2024, 14:35 Gary Gregory, <ga...@gmail.com> wrote:
> >
> > > Sorry about that, I'll have a look today or tomorrow.
> > >
> > > Gary
> > >
> > > On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com> wrote:
> > >
> > > > Not hearing any other ideas and even though I prefer "Scribe" I will
> > > rename
> > > > the class to "HelpWriter".
> > > >
> > > > Thanks everyone for your input.
> > > >
> > > > On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net> wrote:
> > > >
> > > > > My vote (which everyone is free to ignore) is still for HelpWriter.
> > > It's
> > > > > simple and intuitive, and it's consistent with the names of the
> methods
> > > > the
> > > > > interface declares (e.g. writePara, writeTable). I
> > > > > find SemanticAppendableDecorator too verbose and I have no
> intuition
> > > for
> > > > > what it means.
> > > > >
> > > > > Peter
> > > > >
> > > > > On Mon, Sep 30, 2024, 12:31 PM Claude Warren <cl...@xenei.com>
> wrote:
> > > > >
> > > > > > If we can settle on a name for the
> > > > > > serializer/scribe/writer/printDecorator/amenuensis thing the
> rest of
> > > > the
> > > > > > code is ready. It passes all the tests, it has 100% test
> coverage,
> > > > and
> > > > > it
> > > > > > works for what Rat is trying to do.
> > > > > >
> > > > > >
> > > > > > On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <cl...@xenei.com>
> > > > wrote:
> > > > > >
> > > > > > > I have opened https://github.com/apache/commons-cli/pull/314
> to
> > > > track
> > > > > > the
> > > > > > > proposed changes
> > > > > > >
> > > > > > > On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <
> claude@xenei.com>
> > > > > wrote:
> > > > > > >
> > > > > > >> I know some graphics programs use the term "engraver" for code
> > > that
> > > > > > >> creates the output of graphical representations of things
> (like
> > > > notes,
> > > > > > >> staves, and resets in musical notation). Scribe seems like
> the
> > > > > textual
> > > > > > >> equivalent.
> > > > > > >>
> > > > > > >> If we go with the decorator approach then I think the
> underlying
> > > > > > >> interface should be SemanticAppendableDecorator.
> > > > > > >>
> > > > > > >>
> > > > > > >> - Semantic because it describes what to do with the
> semantic
> > > > terms
> > > > > > >> like "paragraph", "header", and "list".
> > > > > > >> - Appendable because that is what is wraps.
> > > > > > >> - Decorator because that is what it does.
> > > > > > >>
> > > > > > >>
> > > > > > >>
> > > > > > >> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
> > > > gilleseran@gmail.com
> > > > > >
> > > > > > >> wrote:
> > > > > > >>
> > > > > > >>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
> > > > garydgregory@gmail.com>
> > > > > a
> > > > > > >>> écrit :
> > > > > > >>> >
> > > > > > >>> > It's pretty unusual IMO, not like anything in the JDK for
> > > > example.
> > > > > > >>>
> > > > > > >>> Agreed.
> > > > > > >>>
> > > > > > >>> > I'll see
> > > > > > >>> > if I can come up with something tomorrow...
> > > > > > >>>
> > > > > > >>> How about "PrintDecorator" ?
> > > > > > >>>
> > > > > > >>> Gilles
> > > > > > >>>
> > > > > > >>> >>> [...]
> > > > > > >>>
> > > > > > >>>
> > > > ---------------------------------------------------------------------
> > > > > > >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > > > > >>> For additional commands, e-mail: dev-help@commons.apache.org
> > > > > > >>>
> > > > > > >>>
> > > > > > >>
> > > > > > >> --
> > > > > > >> LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > > >>
> > > > > > >
> > > > > > >
> > > > > > > --
> > > > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > > >
> > > > > >
> > > > > >
> > > > > > --
> > > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > >
> > > > >
> > > >
> > > >
> > > > --
> > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > >
> > >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by "Gary D. Gregory" <gg...@apache.org>.
Hi all,
I wrote a bunch of comments in the PR.
Gary
On 2024/10/02 10:57:53 Tushar Kapila wrote:
> I don't contribute code. But looking at the dictionary meaning Scribe fits.
> So my vote is Scribe.
>
> a word that fits and not confused with existing class/ responsibility?
>
> verb
> 1.
> literary
> write.
> "he scribed a note that he passed to Dan"
>
> On Wed, 2 Oct 2024, 14:35 Gary Gregory, <ga...@gmail.com> wrote:
>
> > Sorry about that, I'll have a look today or tomorrow.
> >
> > Gary
> >
> > On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com> wrote:
> >
> > > Not hearing any other ideas and even though I prefer "Scribe" I will
> > rename
> > > the class to "HelpWriter".
> > >
> > > Thanks everyone for your input.
> > >
> > > On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net> wrote:
> > >
> > > > My vote (which everyone is free to ignore) is still for HelpWriter.
> > It's
> > > > simple and intuitive, and it's consistent with the names of the methods
> > > the
> > > > interface declares (e.g. writePara, writeTable). I
> > > > find SemanticAppendableDecorator too verbose and I have no intuition
> > for
> > > > what it means.
> > > >
> > > > Peter
> > > >
> > > > On Mon, Sep 30, 2024, 12:31 PM Claude Warren <cl...@xenei.com> wrote:
> > > >
> > > > > If we can settle on a name for the
> > > > > serializer/scribe/writer/printDecorator/amenuensis thing the rest of
> > > the
> > > > > code is ready. It passes all the tests, it has 100% test coverage,
> > > and
> > > > it
> > > > > works for what Rat is trying to do.
> > > > >
> > > > >
> > > > > On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <cl...@xenei.com>
> > > wrote:
> > > > >
> > > > > > I have opened https://github.com/apache/commons-cli/pull/314 to
> > > track
> > > > > the
> > > > > > proposed changes
> > > > > >
> > > > > > On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <cl...@xenei.com>
> > > > wrote:
> > > > > >
> > > > > >> I know some graphics programs use the term "engraver" for code
> > that
> > > > > >> creates the output of graphical representations of things (like
> > > notes,
> > > > > >> staves, and resets in musical notation). Scribe seems like the
> > > > textual
> > > > > >> equivalent.
> > > > > >>
> > > > > >> If we go with the decorator approach then I think the underlying
> > > > > >> interface should be SemanticAppendableDecorator.
> > > > > >>
> > > > > >>
> > > > > >> - Semantic because it describes what to do with the semantic
> > > terms
> > > > > >> like "paragraph", "header", and "list".
> > > > > >> - Appendable because that is what is wraps.
> > > > > >> - Decorator because that is what it does.
> > > > > >>
> > > > > >>
> > > > > >>
> > > > > >> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
> > > gilleseran@gmail.com
> > > > >
> > > > > >> wrote:
> > > > > >>
> > > > > >>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
> > > garydgregory@gmail.com>
> > > > a
> > > > > >>> écrit :
> > > > > >>> >
> > > > > >>> > It's pretty unusual IMO, not like anything in the JDK for
> > > example.
> > > > > >>>
> > > > > >>> Agreed.
> > > > > >>>
> > > > > >>> > I'll see
> > > > > >>> > if I can come up with something tomorrow...
> > > > > >>>
> > > > > >>> How about "PrintDecorator" ?
> > > > > >>>
> > > > > >>> Gilles
> > > > > >>>
> > > > > >>> >>> [...]
> > > > > >>>
> > > > > >>>
> > > ---------------------------------------------------------------------
> > > > > >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > > > >>> For additional commands, e-mail: dev-help@commons.apache.org
> > > > > >>>
> > > > > >>>
> > > > > >>
> > > > > >> --
> > > > > >> LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > >>
> > > > > >
> > > > > >
> > > > > > --
> > > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > > >
> > > > >
> > > > >
> > > > > --
> > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > >
> > > >
> > >
> > >
> > > --
> > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > >
> >
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Tushar Kapila <tg...@gmail.com>.
I don't contribute code. But looking at the dictionary meaning Scribe fits.
So my vote is Scribe.
a word that fits and not confused with existing class/ responsibility?
verb
1.
literary
write.
"he scribed a note that he passed to Dan"
On Wed, 2 Oct 2024, 14:35 Gary Gregory, <ga...@gmail.com> wrote:
> Sorry about that, I'll have a look today or tomorrow.
>
> Gary
>
> On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com> wrote:
>
> > Not hearing any other ideas and even though I prefer "Scribe" I will
> rename
> > the class to "HelpWriter".
> >
> > Thanks everyone for your input.
> >
> > On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net> wrote:
> >
> > > My vote (which everyone is free to ignore) is still for HelpWriter.
> It's
> > > simple and intuitive, and it's consistent with the names of the methods
> > the
> > > interface declares (e.g. writePara, writeTable). I
> > > find SemanticAppendableDecorator too verbose and I have no intuition
> for
> > > what it means.
> > >
> > > Peter
> > >
> > > On Mon, Sep 30, 2024, 12:31 PM Claude Warren <cl...@xenei.com> wrote:
> > >
> > > > If we can settle on a name for the
> > > > serializer/scribe/writer/printDecorator/amenuensis thing the rest of
> > the
> > > > code is ready. It passes all the tests, it has 100% test coverage,
> > and
> > > it
> > > > works for what Rat is trying to do.
> > > >
> > > >
> > > > On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <cl...@xenei.com>
> > wrote:
> > > >
> > > > > I have opened https://github.com/apache/commons-cli/pull/314 to
> > track
> > > > the
> > > > > proposed changes
> > > > >
> > > > > On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <cl...@xenei.com>
> > > wrote:
> > > > >
> > > > >> I know some graphics programs use the term "engraver" for code
> that
> > > > >> creates the output of graphical representations of things (like
> > notes,
> > > > >> staves, and resets in musical notation). Scribe seems like the
> > > textual
> > > > >> equivalent.
> > > > >>
> > > > >> If we go with the decorator approach then I think the underlying
> > > > >> interface should be SemanticAppendableDecorator.
> > > > >>
> > > > >>
> > > > >> - Semantic because it describes what to do with the semantic
> > terms
> > > > >> like "paragraph", "header", and "list".
> > > > >> - Appendable because that is what is wraps.
> > > > >> - Decorator because that is what it does.
> > > > >>
> > > > >>
> > > > >>
> > > > >> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
> > gilleseran@gmail.com
> > > >
> > > > >> wrote:
> > > > >>
> > > > >>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
> > garydgregory@gmail.com>
> > > a
> > > > >>> écrit :
> > > > >>> >
> > > > >>> > It's pretty unusual IMO, not like anything in the JDK for
> > example.
> > > > >>>
> > > > >>> Agreed.
> > > > >>>
> > > > >>> > I'll see
> > > > >>> > if I can come up with something tomorrow...
> > > > >>>
> > > > >>> How about "PrintDecorator" ?
> > > > >>>
> > > > >>> Gilles
> > > > >>>
> > > > >>> >>> [...]
> > > > >>>
> > > > >>>
> > ---------------------------------------------------------------------
> > > > >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > > >>> For additional commands, e-mail: dev-help@commons.apache.org
> > > > >>>
> > > > >>>
> > > > >>
> > > > >> --
> > > > >> LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > >>
> > > > >
> > > > >
> > > > > --
> > > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > > >
> > > >
> > > >
> > > > --
> > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > >
> > >
> >
> >
> > --
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
Sorry about that, I'll have a look today or tomorrow.
Gary
On Wed, Oct 2, 2024, 3:39 AM Claude Warren <cl...@xenei.com> wrote:
> Not hearing any other ideas and even though I prefer "Scribe" I will rename
> the class to "HelpWriter".
>
> Thanks everyone for your input.
>
> On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net> wrote:
>
> > My vote (which everyone is free to ignore) is still for HelpWriter. It's
> > simple and intuitive, and it's consistent with the names of the methods
> the
> > interface declares (e.g. writePara, writeTable). I
> > find SemanticAppendableDecorator too verbose and I have no intuition for
> > what it means.
> >
> > Peter
> >
> > On Mon, Sep 30, 2024, 12:31 PM Claude Warren <cl...@xenei.com> wrote:
> >
> > > If we can settle on a name for the
> > > serializer/scribe/writer/printDecorator/amenuensis thing the rest of
> the
> > > code is ready. It passes all the tests, it has 100% test coverage,
> and
> > it
> > > works for what Rat is trying to do.
> > >
> > >
> > > On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <cl...@xenei.com>
> wrote:
> > >
> > > > I have opened https://github.com/apache/commons-cli/pull/314 to
> track
> > > the
> > > > proposed changes
> > > >
> > > > On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <cl...@xenei.com>
> > wrote:
> > > >
> > > >> I know some graphics programs use the term "engraver" for code that
> > > >> creates the output of graphical representations of things (like
> notes,
> > > >> staves, and resets in musical notation). Scribe seems like the
> > textual
> > > >> equivalent.
> > > >>
> > > >> If we go with the decorator approach then I think the underlying
> > > >> interface should be SemanticAppendableDecorator.
> > > >>
> > > >>
> > > >> - Semantic because it describes what to do with the semantic
> terms
> > > >> like "paragraph", "header", and "list".
> > > >> - Appendable because that is what is wraps.
> > > >> - Decorator because that is what it does.
> > > >>
> > > >>
> > > >>
> > > >> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <
> gilleseran@gmail.com
> > >
> > > >> wrote:
> > > >>
> > > >>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <
> garydgregory@gmail.com>
> > a
> > > >>> écrit :
> > > >>> >
> > > >>> > It's pretty unusual IMO, not like anything in the JDK for
> example.
> > > >>>
> > > >>> Agreed.
> > > >>>
> > > >>> > I'll see
> > > >>> > if I can come up with something tomorrow...
> > > >>>
> > > >>> How about "PrintDecorator" ?
> > > >>>
> > > >>> Gilles
> > > >>>
> > > >>> >>> [...]
> > > >>>
> > > >>>
> ---------------------------------------------------------------------
> > > >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > >>> For additional commands, e-mail: dev-help@commons.apache.org
> > > >>>
> > > >>>
> > > >>
> > > >> --
> > > >> LinkedIn: http://www.linkedin.com/in/claudewarren
> > > >>
> > > >
> > > >
> > > > --
> > > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > > >
> > >
> > >
> > > --
> > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > >
> >
>
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
Not hearing any other ideas and even though I prefer "Scribe" I will rename
the class to "HelpWriter".
Thanks everyone for your input.
On Mon, Sep 30, 2024 at 9:26 PM Peter Burka <pe...@quux.net> wrote:
> My vote (which everyone is free to ignore) is still for HelpWriter. It's
> simple and intuitive, and it's consistent with the names of the methods the
> interface declares (e.g. writePara, writeTable). I
> find SemanticAppendableDecorator too verbose and I have no intuition for
> what it means.
>
> Peter
>
> On Mon, Sep 30, 2024, 12:31 PM Claude Warren <cl...@xenei.com> wrote:
>
> > If we can settle on a name for the
> > serializer/scribe/writer/printDecorator/amenuensis thing the rest of the
> > code is ready. It passes all the tests, it has 100% test coverage, and
> it
> > works for what Rat is trying to do.
> >
> >
> > On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <cl...@xenei.com> wrote:
> >
> > > I have opened https://github.com/apache/commons-cli/pull/314 to track
> > the
> > > proposed changes
> > >
> > > On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <cl...@xenei.com>
> wrote:
> > >
> > >> I know some graphics programs use the term "engraver" for code that
> > >> creates the output of graphical representations of things (like notes,
> > >> staves, and resets in musical notation). Scribe seems like the
> textual
> > >> equivalent.
> > >>
> > >> If we go with the decorator approach then I think the underlying
> > >> interface should be SemanticAppendableDecorator.
> > >>
> > >>
> > >> - Semantic because it describes what to do with the semantic terms
> > >> like "paragraph", "header", and "list".
> > >> - Appendable because that is what is wraps.
> > >> - Decorator because that is what it does.
> > >>
> > >>
> > >>
> > >> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <gilleseran@gmail.com
> >
> > >> wrote:
> > >>
> > >>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <ga...@gmail.com>
> a
> > >>> écrit :
> > >>> >
> > >>> > It's pretty unusual IMO, not like anything in the JDK for example.
> > >>>
> > >>> Agreed.
> > >>>
> > >>> > I'll see
> > >>> > if I can come up with something tomorrow...
> > >>>
> > >>> How about "PrintDecorator" ?
> > >>>
> > >>> Gilles
> > >>>
> > >>> >>> [...]
> > >>>
> > >>> ---------------------------------------------------------------------
> > >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > >>> For additional commands, e-mail: dev-help@commons.apache.org
> > >>>
> > >>>
> > >>
> > >> --
> > >> LinkedIn: http://www.linkedin.com/in/claudewarren
> > >>
> > >
> > >
> > > --
> > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > >
> >
> >
> > --
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Peter Burka <pe...@quux.net>.
My vote (which everyone is free to ignore) is still for HelpWriter. It's
simple and intuitive, and it's consistent with the names of the methods the
interface declares (e.g. writePara, writeTable). I
find SemanticAppendableDecorator too verbose and I have no intuition for
what it means.
Peter
On Mon, Sep 30, 2024, 12:31 PM Claude Warren <cl...@xenei.com> wrote:
> If we can settle on a name for the
> serializer/scribe/writer/printDecorator/amenuensis thing the rest of the
> code is ready. It passes all the tests, it has 100% test coverage, and it
> works for what Rat is trying to do.
>
>
> On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <cl...@xenei.com> wrote:
>
> > I have opened https://github.com/apache/commons-cli/pull/314 to track
> the
> > proposed changes
> >
> > On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <cl...@xenei.com> wrote:
> >
> >> I know some graphics programs use the term "engraver" for code that
> >> creates the output of graphical representations of things (like notes,
> >> staves, and resets in musical notation). Scribe seems like the textual
> >> equivalent.
> >>
> >> If we go with the decorator approach then I think the underlying
> >> interface should be SemanticAppendableDecorator.
> >>
> >>
> >> - Semantic because it describes what to do with the semantic terms
> >> like "paragraph", "header", and "list".
> >> - Appendable because that is what is wraps.
> >> - Decorator because that is what it does.
> >>
> >>
> >>
> >> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <gi...@gmail.com>
> >> wrote:
> >>
> >>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <ga...@gmail.com> a
> >>> écrit :
> >>> >
> >>> > It's pretty unusual IMO, not like anything in the JDK for example.
> >>>
> >>> Agreed.
> >>>
> >>> > I'll see
> >>> > if I can come up with something tomorrow...
> >>>
> >>> How about "PrintDecorator" ?
> >>>
> >>> Gilles
> >>>
> >>> >>> [...]
> >>>
> >>> ---------------------------------------------------------------------
> >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >>> For additional commands, e-mail: dev-help@commons.apache.org
> >>>
> >>>
> >>
> >> --
> >> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>
> >
> >
> > --
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
>
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
If we can settle on a name for the
serializer/scribe/writer/printDecorator/amenuensis thing the rest of the
code is ready. It passes all the tests, it has 100% test coverage, and it
works for what Rat is trying to do.
On Sat, Sep 28, 2024 at 2:08 PM Claude Warren <cl...@xenei.com> wrote:
> I have opened https://github.com/apache/commons-cli/pull/314 to track the
> proposed changes
>
> On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <cl...@xenei.com> wrote:
>
>> I know some graphics programs use the term "engraver" for code that
>> creates the output of graphical representations of things (like notes,
>> staves, and resets in musical notation). Scribe seems like the textual
>> equivalent.
>>
>> If we go with the decorator approach then I think the underlying
>> interface should be SemanticAppendableDecorator.
>>
>>
>> - Semantic because it describes what to do with the semantic terms
>> like "paragraph", "header", and "list".
>> - Appendable because that is what is wraps.
>> - Decorator because that is what it does.
>>
>>
>>
>> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <gi...@gmail.com>
>> wrote:
>>
>>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <ga...@gmail.com> a
>>> écrit :
>>> >
>>> > It's pretty unusual IMO, not like anything in the JDK for example.
>>>
>>> Agreed.
>>>
>>> > I'll see
>>> > if I can come up with something tomorrow...
>>>
>>> How about "PrintDecorator" ?
>>>
>>> Gilles
>>>
>>> >>> [...]
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>
>>>
>>
>> --
>> LinkedIn: http://www.linkedin.com/in/claudewarren
>>
>
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
I have opened https://github.com/apache/commons-cli/pull/314 to track the
proposed changes
On Sat, Sep 28, 2024 at 11:42 AM Claude Warren <cl...@xenei.com> wrote:
> I know some graphics programs use the term "engraver" for code that
> creates the output of graphical representations of things (like notes,
> staves, and resets in musical notation). Scribe seems like the textual
> equivalent.
>
> If we go with the decorator approach then I think the underlying interface
> should be SemanticAppendableDecorator.
>
>
> - Semantic because it describes what to do with the semantic terms
> like "paragraph", "header", and "list".
> - Appendable because that is what is wraps.
> - Decorator because that is what it does.
>
>
>
> On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <gi...@gmail.com>
> wrote:
>
>> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <ga...@gmail.com> a
>> écrit :
>> >
>> > It's pretty unusual IMO, not like anything in the JDK for example.
>>
>> Agreed.
>>
>> > I'll see
>> > if I can come up with something tomorrow...
>>
>> How about "PrintDecorator" ?
>>
>> Gilles
>>
>> >>> [...]
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
I know some graphics programs use the term "engraver" for code that creates
the output of graphical representations of things (like notes, staves, and
resets in musical notation). Scribe seems like the textual equivalent.
If we go with the decorator approach then I think the underlying interface
should be SemanticAppendableDecorator.
- Semantic because it describes what to do with the semantic terms like
"paragraph", "header", and "list".
- Appendable because that is what is wraps.
- Decorator because that is what it does.
On Sat, Sep 28, 2024 at 9:26 AM Gilles Sadowski <gi...@gmail.com>
wrote:
> Le sam. 28 sept. 2024 à 00:17, Gary Gregory <ga...@gmail.com> a
> écrit :
> >
> > It's pretty unusual IMO, not like anything in the JDK for example.
>
> Agreed.
>
> > I'll see
> > if I can come up with something tomorrow...
>
> How about "PrintDecorator" ?
>
> Gilles
>
> >>> [...]
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gilles Sadowski <gi...@gmail.com>.
Le sam. 28 sept. 2024 à 00:17, Gary Gregory <ga...@gmail.com> a écrit :
>
> It's pretty unusual IMO, not like anything in the JDK for example.
Agreed.
> I'll see
> if I can come up with something tomorrow...
How about "PrintDecorator" ?
Gilles
>>> [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
It's pretty unusual IMO, not like anything in the JDK for example. I'll see
if I can come up with something tomorrow...
Gary
On Fri, Sep 27, 2024, 6:11 PM Claude Warren <cl...@xenei.com> wrote:
> Anybody have an objection to using Scribe as the class name?
>
> On Thu, Sep 26, 2024 at 11:25 AM Claude Warren <cl...@xenei.com> wrote:
>
> > I am now thinking "Scribe". Writer tend to indicate that you can do low
> > level writing and would expect the Writer to implement the Writer
> interface.
> >
> > "Amanuensis" comes to mind but that is too hard to spell/type. ;)
> >
> > Claude
> >
> >
> >
> > On Thu, Sep 26, 2024 at 4:26 AM Peter Burka <pe...@quux.net> wrote:
> >
> >> That sounds similar to java.io.Writer. Maybe this should be a
> HelpWriter?
> >>
> >> On Wed, Sep 25, 2024, 7:11 PM Claude Warren <cl...@xenei.com> wrote:
> >>
> >> > Actually the Producer constructor takes an "Appendable" as an argument
> >> and
> >> > then provides methods like
> >> >
> >> > printPara("Some text here")
> >> >
> >> > Which would output a paragraph of "Some text here"
> >> >
> >> > TestProducer appends "Some text here\n\n" (where \n is
> >> > System.lineSeparator) to the appendable
> >> > XmlProducer would append something like "<p>Some text here</p>" to the
> >> > appendable.
> >> >
> >> > (they really are serializing the data to an output format)
> >> >
> >> > Claude
> >> >
> >> > --
> >> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >> >
> >>
> >
> >
> > --
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
>
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
Anybody have an objection to using Scribe as the class name?
On Thu, Sep 26, 2024 at 11:25 AM Claude Warren <cl...@xenei.com> wrote:
> I am now thinking "Scribe". Writer tend to indicate that you can do low
> level writing and would expect the Writer to implement the Writer interface.
>
> "Amanuensis" comes to mind but that is too hard to spell/type. ;)
>
> Claude
>
>
>
> On Thu, Sep 26, 2024 at 4:26 AM Peter Burka <pe...@quux.net> wrote:
>
>> That sounds similar to java.io.Writer. Maybe this should be a HelpWriter?
>>
>> On Wed, Sep 25, 2024, 7:11 PM Claude Warren <cl...@xenei.com> wrote:
>>
>> > Actually the Producer constructor takes an "Appendable" as an argument
>> and
>> > then provides methods like
>> >
>> > printPara("Some text here")
>> >
>> > Which would output a paragraph of "Some text here"
>> >
>> > TestProducer appends "Some text here\n\n" (where \n is
>> > System.lineSeparator) to the appendable
>> > XmlProducer would append something like "<p>Some text here</p>" to the
>> > appendable.
>> >
>> > (they really are serializing the data to an output format)
>> >
>> > Claude
>> >
>> > --
>> > LinkedIn: http://www.linkedin.com/in/claudewarren
>> >
>>
>
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
I am now thinking "Scribe". Writer tend to indicate that you can do low
level writing and would expect the Writer to implement the Writer interface.
"Amanuensis" comes to mind but that is too hard to spell/type. ;)
Claude
On Thu, Sep 26, 2024 at 4:26 AM Peter Burka <pe...@quux.net> wrote:
> That sounds similar to java.io.Writer. Maybe this should be a HelpWriter?
>
> On Wed, Sep 25, 2024, 7:11 PM Claude Warren <cl...@xenei.com> wrote:
>
> > Actually the Producer constructor takes an "Appendable" as an argument
> and
> > then provides methods like
> >
> > printPara("Some text here")
> >
> > Which would output a paragraph of "Some text here"
> >
> > TestProducer appends "Some text here\n\n" (where \n is
> > System.lineSeparator) to the appendable
> > XmlProducer would append something like "<p>Some text here</p>" to the
> > appendable.
> >
> > (they really are serializing the data to an output format)
> >
> > Claude
> >
> > --
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Peter Burka <pe...@quux.net>.
That sounds similar to java.io.Writer. Maybe this should be a HelpWriter?
On Wed, Sep 25, 2024, 7:11 PM Claude Warren <cl...@xenei.com> wrote:
> Actually the Producer constructor takes an "Appendable" as an argument and
> then provides methods like
>
> printPara("Some text here")
>
> Which would output a paragraph of "Some text here"
>
> TestProducer appends "Some text here\n\n" (where \n is
> System.lineSeparator) to the appendable
> XmlProducer would append something like "<p>Some text here</p>" to the
> appendable.
>
> (they really are serializing the data to an output format)
>
> Claude
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
Actually the Producer constructor takes an "Appendable" as an argument and
then provides methods like
printPara("Some text here")
Which would output a paragraph of "Some text here"
TestProducer appends "Some text here\n\n" (where \n is
System.lineSeparator) to the appendable
XmlProducer would append something like "<p>Some text here</p>" to the
appendable.
(they really are serializing the data to an output format)
Claude
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
On Wed, Sep 25, 2024 at 6:09 PM Claude Warren <cl...@xenei.com> wrote:
>
> I have to agree that Serializer is an overloaded term and should be
> avoided, and I knew when I named it that the name would have to change.
> But I don't like "Render" because it is a verb and the noun for something
> that renders would be a renderer. And to my ears (and fingers) that seems
> clunky.
>
> How about "Producer" for the interface, and TextProducer, XmlProducer,
> MarkdownProcucer, as the concrete class names?
Hi Claude,
Better :-)
Java has the general-use Supplier, so... assuming a producer creates
something, could this be an actual Supplier, like a TextSupplier that
implements a get()?
Or, does the class draw/render/print _onto_ something in which case it
could be a Java Consumer<Writer>.
Some of this depends on details I've not looked at in your branch
yet... (working on something else ATM ;-)
HTH,
Gary
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
I have to agree that Serializer is an overloaded term and should be
avoided, and I knew when I named it that the name would have to change.
But I don't like "Render" because it is a verb and the noun for something
that renders would be a renderer. And to my ears (and fingers) that seems
clunky.
How about "Producer" for the interface, and TextProducer, XmlProducer,
MarkdownProcucer, as the concrete class names?
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
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 <cl...@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 <cl...@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 <ga...@gmail.com>
> > > wrote:
> > >
> > >> Looking forward to it 😀
> > >>
> > >> Gary
> > >>
> > >> On Fri, Sep 20, 2024, 3:56 AM Claude Warren <cl...@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 <
> > >> epugh@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 <ga...@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 <cl...@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 <
> > >> garydgregory@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 <cl...@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 <
> > >>>>>>>> epugh@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 <
> > >> garydgregory@gmail.com>
> > >>>>>>>>> wrote:
> > >>>>>>>>>
> > >>>>>>>>> Or a new better formatting class?
> > >>>>>>>>>
> > >>>>>>>>> Gary
> > >>>>>>>>>
> > >>>>>>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
> > >>>>>>>> For additional commands, e-mail: dev-help@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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@apache.org>.
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 <cl...@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 <ga...@gmail.com>
> > wrote:
> >
> >> Looking forward to it 😀
> >>
> >> Gary
> >>
> >> On Fri, Sep 20, 2024, 3:56 AM Claude Warren <cl...@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 <
> >> epugh@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 <ga...@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 <cl...@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 <
> >> garydgregory@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 <cl...@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 <
> >>>>>>>> epugh@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 <
> >> garydgregory@gmail.com>
> >>>>>>>>> wrote:
> >>>>>>>>>
> >>>>>>>>> Or a new better formatting class?
> >>>>>>>>>
> >>>>>>>>> Gary
> >>>>>>>>>
> >>>>>>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
> >>>>>>>> For additional commands, e-mail: dev-help@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.
>
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Eric Pugh <ep...@opensourceconnections.com>.
Keep us posted! I would love to contribute a Markdown format.
> On Sep 23, 2024, at 7:20 AM, Claude Warren <cl...@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 <ga...@gmail.com>
> wrote:
>
>> Looking forward to it 😀
>>
>> Gary
>>
>> On Fri, Sep 20, 2024, 3:56 AM Claude Warren <cl...@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 <
>> epugh@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 <ga...@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 <cl...@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 <
>> garydgregory@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 <cl...@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 <
>>>>>>>> epugh@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 <
>> garydgregory@gmail.com>
>>>>>>>>> wrote:
>>>>>>>>>
>>>>>>>>> Or a new better formatting class?
>>>>>>>>>
>>>>>>>>> Gary
>>>>>>>>>
>>>>>>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
>>>>>>>> For additional commands, e-mail: dev-help@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.
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
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 <ga...@gmail.com>
wrote:
> Looking forward to it 😀
>
> Gary
>
> On Fri, Sep 20, 2024, 3:56 AM Claude Warren <cl...@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 <
> epugh@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 <ga...@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 <cl...@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 <
> garydgregory@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 <cl...@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 <
> > > >>>> epugh@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 <
> garydgregory@gmail.com>
> > > >>>>> wrote:
> > > >>>>>
> > > >>>>> Or a new better formatting class?
> > > >>>>>
> > > >>>>> Gary
> > > >>>>>
> > > >>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
> > > >>>> For additional commands, e-mail: dev-help@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
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
Looking forward to it 😀
Gary
On Fri, Sep 20, 2024, 3:56 AM Claude Warren <cl...@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 <epugh@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 <ga...@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 <cl...@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 <ga...@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 <cl...@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 <
> > >>>> epugh@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 <ga...@gmail.com>
> > >>>>> wrote:
> > >>>>>
> > >>>>> Or a new better formatting class?
> > >>>>>
> > >>>>> Gary
> > >>>>>
> > >>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
> > >>>> For additional commands, e-mail: dev-help@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
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
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 <ga...@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 <cl...@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 <ga...@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 <cl...@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 <
> >>>> epugh@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 <ga...@gmail.com>
> >>>>> wrote:
> >>>>>
> >>>>> Or a new better formatting class?
> >>>>>
> >>>>> Gary
> >>>>>
> >>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
> >>>> For additional commands, e-mail: dev-help@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
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Eric Pugh <ep...@opensourceconnections.com>.
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 <ga...@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 <cl...@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 <ga...@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 <cl...@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 <
>>>> epugh@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 <ga...@gmail.com>
>>>>> wrote:
>>>>>
>>>>> Or a new better formatting class?
>>>>>
>>>>> Gary
>>>>>
>>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
>>>> For additional commands, e-mail: dev-help@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.
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
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 <cl...@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 <ga...@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 <cl...@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 <
> >> epugh@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 <ga...@gmail.com>
> >>> wrote:
> >>>
> >>> Or a new better formatting class?
> >>>
> >>> Gary
> >>>
> >>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
> >> For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
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 <ga...@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 <cl...@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 <
>> epugh@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 <ga...@gmail.com>
>>> wrote:
>>>
>>> Or a new better formatting class?
>>>
>>> Gary
>>>
>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
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 <cl...@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 <ga...@gmail.com> wrote:
>>
>> Or a new better formatting class?
>>
>> Gary
>>
>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
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 <ga...@gmail.com> wrote:
>
> Or a new better formatting class?
>
> Gary
>
> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Eric Pugh <ep...@opensourceconnections.com>.
In Solr we added some additional formatting methods to our Tool.java interface to help with formatting the various tools that use commons-cli:
https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34
solr/solr/core/src/java/org/apache/solr/cli/Tool.java at main · apache/solr
github.com
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:
https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251
solr/solr/core/src/java/org/apache/solr/cli/PackageTool.java at main · apache/solr
github.com
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 <ga...@gmail.com> wrote:
>
> Or a new better formatting class?
>
> Gary
>
> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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 <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.
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Gary Gregory <ga...@gmail.com>.
Or a new better formatting class?
Gary
On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cl...@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 <cl...@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
>
Re: [CLI] [DISCUSS] Help formatter extension proposal
Posted by Claude Warren <cl...@xenei.com>.
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 <cl...@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