Add support for subcommands by williamyaoh · Pull Request #17 · TeXitoi/structopt

williamyaoh · 2017-07-03T19:43:40Z

See #1 for detailed discussion of this feature.

Adds the ability to use #[derive(StructOpt)] on enums, thereby allowing the creation/easy parsing of clap::SubCommands.

This is not a breaking change.

Things that can still be improved:

Fix subcommand names that are hyphenated
Automatically downcase the names of subcommands for help messages (this could also apply to #[derive(StructOpt)] on structs or to changing argument names from _ to -)
Add the ability to use about attribute/doc comments on subcommand variants for help messages
Allow other enum variant types than curly-bracketed ones (e.g. "blank" subcommands)

Other stuff

There are some commits that don't technically have anything to do with adding subcommands in:

Add documentation for the PR that added doc comments for help messages a few weeks ago
Add a link from the structopt documentation to the structopt-derive documentation
Bump versions of structopt and structopt-derive to 0.1.0
Edit the structopt-derive documentation for clarity

Detailed documentation has been added to the structopt-derive crate specifying how to use the new subcommand functionality. Reproduced here:

Subcomamnds

Some applications, like git, support "subcommands;" an extra command that
is used to differentiate what the application should do. With git, these
would be add, init, fetch, commit, for a few examples.

clap has this functionality, so structopt supports this through enums:

#[derive(StructOpt)]
#[structopt(name = "git", about = "the stupid content tracker")]
enum Git {
    #[structopt(name = "add")]
    Add {
        #[structopt(short = "i")]
        interactive: bool,
        #[structopt(short = "p")]
        patch: bool,
        files: Vec<String>
    },
    #[structopt(name = "fetch")]
    Fetch {
        #[structopt(long = "dry-run")]
        dry_run: bool,
        #[structopt(long = "all")]
        all: bool,
        repository: Option<String>
    },
    #[structopt(name = "commit")]
    Commit {
        #[structopt(short = "m")]
        message: Option<String>,
        #[structopt(short = "a")]
        all: bool
    }
}

Using derive(StructOpt) on an enum instead of a struct will produce
a clap::App that only takes subcommands. So git add, git fetch,
and git commit would be commands allowed for the above example.

structopt also provides support for applications where certain flags
need to apply to all subcommands, as well as nested subcommands:

#[derive(StructOpt)]
#[structopt(name = "make-cookie")]
struct MakeCookie {
    #[structopt(name = "supervisor", default_value = "Puck", required = false, long = "supervisor")]
    supervising_faerie: String,
    #[structopt(name = "tree")]
    /// The faerie tree this cookie is being made in.
    tree: Option<String>,
    #[structopt(subcommand)]  // Note that we mark a field as a subcommand
    cmd: Command
}

#[derive(StructOpt)]
enum Command {
    #[structopt(name = "pound")]
    /// Pound acorns into flour for cookie dough.
    Pound {
        acorns: u32
    },
    #[structopt(name = "sparkle")]
    /// Add magical sparkles -- the secret ingredient!
    Sparkle {
        #[structopt(short = "m")]
        magicality: u64,
        #[structopt(short = "c")]
        color: String
    },
    #[structopt(name = "finish")]
    Finish {
        #[structopt(short = "t")]
        time: u32,
        #[structopt(subcommand)]  // Note that we mark a field as a subcommand
        type: FinishType
    }
}

#[derive(StructOpt)]
enum FinishType {
    #[structopt(name = "glaze")]
    Glaze {
        applications: u32
    },
    #[structopt(name = "powder")]
    Powder {
        flavor: String,
        dips: u32
    }
}

Marking a field with structopt(subcommand) will add the subcommands of the
designated enum to the current clap::App. The designated enum must also
be derived StructOpt. So the above example would take the following
commands:

make-cookie pound 50
make-cookie sparkle -mmm --color "green"
make-cookie finish 130 glaze 3

Optional subcommands

A nested subcommand can be marked optional:

#[derive(StructOpt)]
#[structopt(name = "foo")]
struct Foo {
    file: String,
    #[structopt(subcommand)]
    cmd: Option<Command>
}

#[derive(StructOpt)]
enum Command {
    Bar,
    Baz,
    Quux
}

williamyaoh · 2017-07-03T19:45:21Z

I'd like some feedback on the documentation, as well as any bugs/kinks that still need to ironed out.

williamyaoh · 2017-07-03T20:07:31Z

I'm not really sure why the Travis build is failing; it seems to still be looking for structopt-derive 0.0.5 despite having bumped the version(s) in the manifest. rg '0\.0\.5' gets nothing, either.

TeXitoi · 2017-07-03T20:19:10Z

To fix Travis, you must update the structopt-derive version in the dev-depedencies of the Cargo.toml at the root of the project.

TeXitoi · 2017-07-03T20:20:32Z

And please update everything to 0.1.0, else we can't do non breaking change version.

williamyaoh · 2017-07-03T20:21:34Z

It's updated at 72d9d35, so it seems to be something else.

TeXitoi · 2017-07-03T20:24:07Z

This commit update only the README.md.

williamyaoh · 2017-07-03T20:27:45Z

Nevermind, you're right, I'm an idiot. I think I accidentally clobbered updating the [dev-dependencies] after using git reset to fix an older commit.

ErichDonGubler · 2017-07-03T20:55:33Z

Question about these two lines from the examples:

struct MakeCookie {
    #[structopt(name = "supervisor", default_value = "Puck")]
    supervising_faerie: Option<String>,
// ...

Is it necessary for the supervising_faerie field to be an Option, if a default is always provided? Wouldn't that just make client code unnecessarily need to call unwrap on this field every time?

TeXitoi

Great!

A rapid first read. I'll do a deeper read soon.

TeXitoi · 2017-07-03T20:29:26Z

structopt-derive/src/lib.rs

-//! `Arg::with_name()` call (default to the field name).
+//! Then, each field of the struct not marked as a subcommand corresponds
+//! to a `clap::Arg`. As with the struct attributes, every method of
+//! `clap::Arg`in the form of `fn function_name(self, &str)` can be used


Lack space before in

TeXitoi · 2017-07-03T20:34:55Z

structopt-derive/src/lib.rs

+//! }
+//! ```
+//!
+//! ## Subcomamnds


TeXitoi · 2017-07-03T20:43:53Z

structopt-derive/src/lib.rs

+//! #[structopt(name = "make-cookie")]
+//! struct MakeCookie {
+//!     #[structopt(name = "supervisor", default_value = "Puck")]
+//!     supervising_faerie: Option<String>,


With default value you don't want an option

TeXitoi · 2017-07-03T20:59:54Z

Great doc ! Thanks for the corrections of my frenchy English ;-)

williamyaoh · 2017-07-03T21:00:02Z

@ErichDonGubler You're right, will change that.

ErichDonGubler · 2017-07-03T22:31:15Z

@williamyaoh: Looks like something like this fails right now:

enum Subcommand {
    Something // Fails here
}

Adding curly braces fixes it, but shouldn't be necessary:

enum Subcommand {
    Something {}
}

williamyaoh · 2017-07-03T22:37:25Z

@ErichDonGubler Yup, that's already on the Things to be improved list above already. It's fixable, though it's not trivial to do.

williamyaoh · 2017-07-04T22:16:14Z

@ErichDonGubler Fixed at 4ff50e6. It ended up being simpler than I thought it would be.

williamyaoh · 2017-07-05T07:13:41Z

Regarding downcasing of subcommand names by default: I can see the convenience, but on the other hand, it also means using "magic" from the programmer's perspective, where names that they never typed become part of the interface of their program. I'm not sure whether the convenience outweighs the confusion over the exact mechanism of translation of subcommand names.

What does everyone else think?

I think the actual semantics would be to translate all identifiers into kebab case, if no name attribute is specified. So

#[derive(StructOpt)]
enum DoStuff {
    DoTheThing
}

would automatically produce a command $ do-stuff do-the-thing, without having to specify a name attribute. Attributes would act the same way:

#[derive(StructOpt)]
struct DoOtherStuff {
    useful_information: bool
}

would automatically produce a command $ do-other-stuff --useful-information.

TeXitoi · 2017-07-05T07:26:14Z

I think translation to kebab-case is an important feature. I prefer this feature to be in another PR, it'll let me the time to validate this one soon.
Maybe open an issue about that to see feedbacks?

TeXitoi

Great work! Only small feedbacks.

TeXitoi · 2017-07-05T07:52:03Z

structopt-derive/src/lib.rs

+            quote!( .arg(_structopt::clap::Arg::with_name(stringify!(#name)) #modifier #(#from_attr)*) )
+        });
+
+    assert!(subcmds.len() <= 1, "cannot have more than one nested subcommand");


I prefer this assert be just after the declaration, it explain why we have collect

TeXitoi · 2017-07-05T08:04:34Z

src/lib.rs

    fn clap<'a, 'b>() -> clap::App<'a, 'b>;

+    /// Add this app's arguments/subcommands to another `clap::App`.
+    fn augment_clap<'a, 'b>(clap::App<'a, 'b>) -> clap::App<'a, 'b>;


I'm not a big fan of this, but I don't have any better idea.

I could move that function into a inherent impl block for each type; that would remove it from cluttering up the StructOpt documentation, at least, which I think is the real issue.

Great idea.

williamyaoh · 2017-07-07T17:56:36Z

All right, unless someone else finds a bug in the subcommand-related stuff, that looks to be everything.

williamyaoh · 2017-07-14T02:37:19Z

@TeXitoi Do you need anything else from me before merging?

TeXitoi · 2017-07-14T07:34:16Z

Yes a computer. I'm in vacation. Le 14 juillet 2017 04:37:20 GMT+02:00, William Yao <notifications@github.com> a écrit :

…

@TeXitoi Do you need anything else from me before merging? -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #17 (comment)

-- Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.

TeXitoi · 2017-07-17T09:49:40Z

Published, thanks for your work!

fix a bunch of clippy warnings

williamyaoh added 17 commits June 28, 2017 19:16

separate creating app and adding arguments

67ad41a

split impl_structopt into struct and enum branches

d204657

skeleton of enum impl

4112eab

factor out code generation that's needed for enums

dc2a1fb

prototype enum stuff?

eebf9fa

lifetime fix

79295f8

add test for subcommand parsing (TeXitoi#1)

f321bca

add ability to put in nested subcommands (TeXitoi#1)

fdb1b9c

ignore unused matches for empty subcommands (TeXitoi#1)

21df5bc

allow for optional subcommands (TeXitoi#1)

5ab334a

add test suite for nested subcommands (TeXitoi#1)

d5f029a

fix hyphenated subcommands

ae7048b

add link to structopt-derive documentation from structopt crate

650e3bd

preliminary editing of structopt-derive documentation

54372b7

add documentation in structopt-derive about how to use subcommands

86611bc

note about optional subcommands

f2c0cdb

add note about using doc comments for help messages (TeXitoi#1)

c64cc1e

williamyaoh mentioned this pull request Jul 3, 2017

Support subcommand #1

Closed

williamyaoh added 2 commits July 3, 2017 14:48

bump versions of structopt and structopt-derive

0418cb6

add missing backticks (oops)

7b8066c

williamyaoh force-pushed the subcommands branch from 5a6af3f to 7b8066c Compare July 3, 2017 19:49

bump versions of structopt in README, fix typo

72d9d35

bump versions to 0.1.0

7cbf766

TeXitoi reviewed Jul 3, 2017

View reviewed changes

williamyaoh added 3 commits July 3, 2017 16:01

remove unnecessary Option in documentation [ci skip]

fc9a8ae

fix typoes

9a5ea9c

add extra Arg methods in doc so examples still work

cb3bc99

williamyaoh added 3 commits July 4, 2017 16:59

allow for documentation to be placed on subcommands

d7daced

add support for unit-variant subcommands

4ff50e6

update structopt-derive documentation to reflect unit subcommands change

42529fb

TeXitoi approved these changes Jul 5, 2017

View reviewed changes

williamyaoh added 2 commits July 7, 2017 12:40

move augment_clap into inherent impl

b329f01

move assert

8060f31

williamyaoh mentioned this pull request Jul 8, 2017

Support automatic naming and kebab-casing of fields/subcommands #18

Closed

TeXitoi merged commit a7224b5 into TeXitoi:master Jul 17, 2017

CAD97 mentioned this pull request Feb 17, 2018

Re-license to Apache-2.0/MIT #71

Merged

11 tasks

Eijebong pushed a commit to Eijebong/structopt that referenced this pull request Jan 2, 2019

Merge pull request TeXitoi#17 from matthiaskrgr/clippy

2503325

fix a bunch of clippy warnings

Conversation

williamyaoh commented Jul 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Things that can still be improved:

Other stuff

Subcomamnds

Optional subcommands

Uh oh!

williamyaoh commented Jul 3, 2017

Uh oh!

williamyaoh commented Jul 3, 2017

Uh oh!

TeXitoi commented Jul 3, 2017

Uh oh!

TeXitoi commented Jul 3, 2017

Uh oh!

williamyaoh commented Jul 3, 2017

Uh oh!

TeXitoi commented Jul 3, 2017

Uh oh!

williamyaoh commented Jul 3, 2017

Uh oh!

ErichDonGubler commented Jul 3, 2017

Uh oh!

TeXitoi left a comment

Choose a reason for hiding this comment

Uh oh!

TeXitoi Jul 3, 2017

Choose a reason for hiding this comment

Uh oh!

TeXitoi Jul 3, 2017

Choose a reason for hiding this comment

Uh oh!

TeXitoi Jul 3, 2017

Choose a reason for hiding this comment

Uh oh!

TeXitoi commented Jul 3, 2017

Uh oh!

williamyaoh commented Jul 3, 2017

Uh oh!

ErichDonGubler commented Jul 3, 2017

Uh oh!

williamyaoh commented Jul 3, 2017

Uh oh!

williamyaoh commented Jul 4, 2017

Uh oh!

williamyaoh commented Jul 5, 2017

Uh oh!

TeXitoi commented Jul 5, 2017

Uh oh!

TeXitoi left a comment

Choose a reason for hiding this comment

Uh oh!

TeXitoi Jul 5, 2017

Choose a reason for hiding this comment

Uh oh!

TeXitoi Jul 5, 2017

Choose a reason for hiding this comment

Uh oh!

williamyaoh Jul 5, 2017

Choose a reason for hiding this comment

Uh oh!

TeXitoi Jul 5, 2017

Choose a reason for hiding this comment

Uh oh!

williamyaoh commented Jul 7, 2017

Uh oh!

williamyaoh commented Jul 14, 2017

Uh oh!

TeXitoi commented Jul 14, 2017 via email

Uh oh!

TeXitoi commented Jul 17, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

williamyaoh commented Jul 3, 2017 •

edited

Loading