Adding FromArgs::help_json_from_args() to get JSON encoded help message #115

claywilkinson · 2021-12-13T20:11:07Z

(revised summary to match code changes)

Adding FromArgs::help_json_from_args() to get JSON encoded help message
This enables template engines to render
the help information in other formats such as markdown.

* Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown. * Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown.

richkadel

I didn't do a thorough review yet, but wanted to make sure you have a chance to respond to my initial comment.

Thanks!

argh/tests/lib.rs

argh_derive/src/help_json.rs

* Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown. * Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown. * Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown.

This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown.

richkadel

Much more complete tests! Thanks.

I don't know if you have flexibility in the schema definition, but I have some recommendations. I think an argh JSON schema should capture all of the configurability supported by the API as first class JSON values, IMO.

README.md

argh/tests/help_json_tests.rs

richkadel · 2021-12-15T17:28:37Z

argh/tests/help_json_tests.rs

+ r###"{
+"usage": "test_arg_0 [--power] --required <required> [-s <speed>] [--link <url...>]",
+"description": "Basic command args demonstrating multiple types and cardinality. \"With quotes\"",
+"options": [{"short": "", "long": "--power", "description": "should the power be on. \"Quoted value\" should work too."},


nit: I know argh uses the term option but to me it's a little ambiguous to say "required option". Option sounds too much like "optional". You may feel differently, and this is really in the weeds, but if your schema is not too rigid, maybe consider calling the JSON array "args" or "flags"?

@erickt feel free to weigh in if you think I'm off base.

erickt

I don't think we can land it as. This would be a breaking change, since we can't tell if the community could be using --help-json or a help-json subcommand. We'd need to either bump to 0.2.x, or we need a backwards compatible way to implement this.

I got an idea I want to explore for backwards compatibility, but I won't have time for a few days to try it out. In short, we might be able to do something along the lines of https://github.com/google/argh/blob/master/argh/src/lib.rs#L447. Maybe we could do something like this:

trait Help {
     const FIELDS: &'static [&'static FieldInfo];
}

struct FieldInfo<'a> {
     switch: bool,
     option: &['a str],
     ...
}

We'd then just auto-generate impls for this Help type.

Anyway, I'll experiment with this and let you know (or if you want you could explore this route as well, or other routes too you might come up with).

argh/src/lib.rs

* Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown. * Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown.

* Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown. * Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown. * Adding --help-json to get JSON encoded help message This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown.

This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown.

This adds 2 methods to arghm, help_json_from_args() and help_json(), which is parallel to ::from_env(). The return value is a JSON encoded string suitable for parsing and using as input to generate reference docs.

These were made inadvertently when merging changes.

This makes several changes that make it easier to use the JSON help data and also makes it more complete. * The subcommands are recursively called to collect the help information for each command. This means one call to help_json_from_args on the "TopLevel" struct will generate complete help for all subcommands. * `options` has been renamed to `flags`. * optionality has been added to the flags. This is "required", "optional", "repeated", or a Rust fragment containing for the default value. * "arg_name" as been added to flags.

richkadel

A couple of minor things I noticed, but generally this looks good to me. I'd like @erickt to do the final review though.

Thanks!

argh/src/lib.rs

argh/tests/lib.rs

This also adds a default implementation of help_json_from_args for FromArgs in order to be backwards compatible with non `derived` implmentations of the FromArgs trait.

claywilkinson · 2022-01-10T17:46:35Z

@erickt friendly post-holiday ping :)

richkadel reviewed Dec 13, 2021

View reviewed changes

argh/tests/lib.rs Outdated Show resolved Hide resolved

richkadel reviewed Dec 13, 2021

View reviewed changes

argh_derive/src/help_json.rs Outdated Show resolved Hide resolved

claywilkinson and others added 2 commits December 14, 2021 13:55

Adding --help-json to get JSON encoded help message

287703b

This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown.

richkadel reviewed Dec 15, 2021

View reviewed changes

erickt requested changes Dec 15, 2021

View reviewed changes

argh/src/lib.rs Outdated Show resolved Hide resolved

claywilkinson and others added 9 commits December 28, 2021 16:23

Adding --help-json to get JSON encoded help message

66e80be

This adds the `--help-json` flag which prints the help information encoded in a JSON object. This enables template engines to render the help information in other formats such as markdown.

Merge branch 'google-master'

b7d61a3

Adding argh::help_json_from_args()

8131de1

This adds 2 methods to arghm, help_json_from_args() and help_json(), which is parallel to ::from_env(). The return value is a JSON encoded string suitable for parsing and using as input to generate reference docs.

Adding argh::help_json_from_args()

f00f762

This adds 2 methods to arghm, help_json_from_args() and help_json(), which is parallel to ::from_env(). The return value is a JSON encoded string suitable for parsing and using as input to generate reference docs.

reverting unnessary changes.

03f0229

These were made inadvertently when merging changes.

Addressing clippy warnings

cca7412

claywilkinson changed the title ~~Adding --help-json to get JSON encoded help message~~ Adding FromArgs::help_json_from_args() to get JSON encoded help message Dec 29, 2021

richkadel suggested changes Dec 30, 2021

View reviewed changes

argh/src/lib.rs Outdated Show resolved Hide resolved

argh/tests/lib.rs Show resolved Hide resolved

claywilkinson added 2 commits December 30, 2021 15:32

Adding README documentation and clippy warnings

8df0bf2

This also adds a default implementation of help_json_from_args for FromArgs in order to be backwards compatible with non `derived` implmentations of the FromArgs trait.

fixing typo extra blank line.

6027f97

erickt mentioned this pull request Feb 8, 2022

Prototype out a help trait #119

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding FromArgs::help_json_from_args() to get JSON encoded help message #115

Adding FromArgs::help_json_from_args() to get JSON encoded help message #115

claywilkinson commented Dec 13, 2021 •

edited

richkadel left a comment

richkadel left a comment

richkadel Dec 15, 2021

erickt left a comment

richkadel left a comment

claywilkinson commented Jan 10, 2022

Adding FromArgs::help_json_from_args() to get JSON encoded help message #115

Are you sure you want to change the base?

Adding FromArgs::help_json_from_args() to get JSON encoded help message #115

Conversation

claywilkinson commented Dec 13, 2021 • edited

richkadel left a comment

Choose a reason for hiding this comment

richkadel left a comment

Choose a reason for hiding this comment

richkadel Dec 15, 2021

Choose a reason for hiding this comment

erickt left a comment

Choose a reason for hiding this comment

richkadel left a comment

Choose a reason for hiding this comment

claywilkinson commented Jan 10, 2022

claywilkinson commented Dec 13, 2021 •

edited