refactor noms to use kingpin instead of hand-rolled flags parser

jesseditson commented 7 years ago

Initial work on #2157:

Summary

This PR switches the CLI to use kingpin, which has a number of advantages, namely:

arbitrary depth contextual commands and help. This will remove weird hacks like noms ds --delete <ds>, which should be noms ds delete <ds>, and allow for creating "suites" of CLI tools, like noms blob [command].
don't hide basic usage docs under thing help commands, show it at the root and provide details when thing --help'd
no need to check args.length anymore, can just mark args required
everything is named, so stuff is a bit easier to parse
non-defined args are nil when not provided by the user now that they are pointers. Could simplify things like using -1 as a proxy for nil
easier CLI doc customization
free shell completion and manpage generation

in general, it's also nice to have a lib handle deciding how to represent things like optional params and short flags, so it'll be consistent.

I opened this PR for initial eyes, but I'll at minimum break out the dataset command on this PR, and possibly start adding commands from #2157 (e.g. blob) on here depending on the temperature of the room.

TODO

[ ] @<file> stuff for file paths?
[ ] Restore or intentionally remove profiling
[ ] Fix any broken tests
[ ] Simplify verbosity and remove old flags libs

examples

output from noms:

usage: noms [<flags>] <command> [<args> ...]

Noms is a tool for showing off Noms data.

Flags:
  --help  Show context-sensitive help (also try --help-long and --help-man).

Commands:
  help [<command>...]
    Show help.

  commit [<flags>] <database> [<absolute-path>]
    Commits a specified value as head of the dataset

    If absolute-path is not provided, then it is read from stdin. See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the dataset and absolute-path arguments.

  config
    Prints the active configuration if a .nomsconfig file is present

  diff [<flags>] <object1> <object2>
    Shows the difference between two objects

    See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the object arguments.

  ds [<flags>] [<database>]
    Noms dataset management

    See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the database argument.

  log [<flags>] <path-spec>
    Displays the history of a path

    See Spelling Values at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the <path-spec> parameter.

  merge [<flags>] <database> <left-dataset-name> <right-dataset-name> <output-dataset-name>
    Merges and commits the head values of two named datasets

    See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the database argument.

    You must provide a working database and the names of two Datasets you want to merge. The values at the heads of these Datasets will be merged, put into a new Commit object, and set as the Head of the third provided Dataset name.

  root [<flags>] <database>
    Get or set the current root hash of the entire database

    See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the database argument.

  serve [<flags>] <database>
    Serves a Noms database over HTTP

    See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the database argument.

  show [<flags>] <object>
    Shows a serialization of a Noms object

    See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the object argument.

  sync [<flags>] <source-object> <dest-dataset>
    Moves datasets between or within databases

    See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the object and dataset arguments.

  version
    Print the noms version

output of noms merge --help

usage: noms merge [<flags>] <database> <left-dataset-name> <right-dataset-name> <output-dataset-name>

Merges and commits the head values of two named datasets

See Spelling Objects at https://github.com/attic-labs/noms/blob/master/doc/spelling.md for details on the database argument.

You must provide a working database and the names of two Datasets you want to merge. The values at the heads of these Datasets will be merged, put into a new Commit object, and set as the Head of the third provided Dataset name.

Flags:
      --help      Show context-sensitive help (also try --help-long and --help-man).
      --policy=n  conflict resolution policy for merging. Defaults to 'n', which means no resolution strategy will be applied. Supported values are 'l' (left), 'r' (right) and 'p' (prompt). 'prompt' will bring up a simple command-line prompt allowing you to resolve conflicts
                  by choosing between 'l' or 'r' on a case-by-case basis.
  -v, --verbose   show more
  -q, --quiet     show less

Args:
  <database>             a noms database path
  <left-dataset-name>    a dataset
  <right-dataset-name>   a dataset
  <output-dataset-name>  a dataset

aboodman commented 7 years ago

Wow, fast work. One comment on the example output -- can it wrap the lines?

jesseditson commented 7 years ago

I think it might wrap based on terminal width? These are all literals so can easily manually wrap them. I think a lot of these longer messages could be made shorter by documenting more rather than linking, or by moving links to a more global place, there's quite a lot of redundancy.

arv commented 7 years ago

This looks great. I didn't look closely at the code but based on the PR summary this is clearly an improvement.

jesseditson commented 7 years ago

Closing in favor of #3621

attic-labs / noms