search

bmjames / scala-optparse-applicative

Scala port of Paolo Capriotti's optparse-applicative library. This repository is no longer maintained; newer versions exist in this fork: https://github.com/xuwei-k/optparse-applicative
BSD 3-Clause "New" or "Revised" License
72 stars 9 forks source link

Add more examples/doc #1

Closed erikkaplun closed 8 years ago

erikkaplun commented 9 years ago

It's quite hard to get on track without knowing how exactly to use the library in non-trivial cases, for example how to parse the same option multiple times (the equivalent of many and some in optparse-applicative), or how to use subparsers/commands.

bmjames commented 9 years ago

Of course, I agree :smile:

By the way, did you see the examples in src/test/example? There are usages of subparser, command, some and many, which I hope are not difficult to follow.

erikkaplun commented 9 years ago

Oh... I didn't realise to look under src/test — would it make sense to make this explicit in the README? I ended up reading the source and figuring out how to use things like optional and some etc but I'm also relatively comfortable with reading Scalaz based idiomatic non-trivial code... and it took me a while. Some people might steer away because of lack of accessibility to all the available features. And that'd be a shame — it's a lovely library!

Also, it's not obvious what can and can not be done using the library, like for example I ended up using 4 optional subcommands but I'm not sure if there's possibly a way to require at least one (because it makes no sense to invoke my utility without specifying a single subcommand, except with -h/--help or -V/--version).

bmjames commented 9 years ago

Those examples are mentioned briefly in the README, but it's probably easy to miss. I've made it a bit more prominent in 7a9a14c6.

If you gist the code for your parser with subcommands, I'd be happy to look and see if I can help.

And thanks for the feedback!

erikkaplun commented 9 years ago

Actually I already figured it out: I have to combine all my subcommand subparsers using <+> (or <|>) and then wrap the resulting parser with some(), but having no deeper familiarity with parser combinators, it took some time to realise. All I was saying basically is that the README could point to examples that cover the typical use cases.

My code looks roughly as follows: https://gist.github.com/eallik/26d2699b41c40ff6e775; feel free to include this as part of the examples (modified in however way you like).

bmjames commented 9 years ago

Usually I compose commands inside one subparser by using the monoid for Mod[CommandFields, A] (the return type of command). But I guess your way works just as well, and it also makes the type annotations nicer; Mod[CommandFields, A] never looked to me like something that was supposed to appear in user code.

By the way, this is another thing I should document: To aid inference when composing things monoidally (for example, commands inside a subparser), I've used varargs in the signatures of methods like subparser. That is, subparser(a, b) can get better inference than subparser(a |+| b).