Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 14 commits into
base: master
Choose a base branch
from

Conversation

claywilkinson
Copy link
Contributor

@claywilkinson claywilkinson commented Dec 13, 2021

(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.
Copy link
Contributor

@richkadel richkadel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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.
Copy link
Contributor

@richkadel richkadel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Show resolved Hide resolved
argh/tests/help_json_tests.rs Outdated Show resolved Hide resolved
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."},
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

@erickt erickt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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.
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.
@claywilkinson 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
Copy link
Contributor

@richkadel richkadel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Outdated Show resolved Hide resolved
argh/tests/lib.rs Show resolved Hide resolved
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
Copy link
Contributor Author

@erickt friendly post-holiday ping :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants