Group commands in CLI #1692
Merged
Group commands in CLI #1692
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There are currently 15 subcommands for the `dhall` binary. This is great
because it means the `dhall` binary is full of features. It's not so
great because trying to figure out what to do is non-trivial. We start
grouping commands so we can provide a bit of guidance on what people
might want to do.
The previous `--help` output looked like:
```console
$ dhall --help
Usage: dhall ([version] | [resolve] | [type] | [normalize] | [repl] | [diff] |
[hash] | [lint] | [tags] | [format] | [freeze] | [encode] |
[decode] | [text] | [to-directory-tree] | [--file FILE]
[--output FILE] [--annotate] [--alpha] [--no-cache] [--version])
[--explain] [--plain] [--ascii] [--censor]
Interpreter for the Dhall language
Available options:
-h,--help Show this help text
--file FILE Read expression from a file instead of standard input
--output FILE Write result to a file instead of standard output
--annotate Add a type annotation to the output
--alpha α-normalize expression
--no-cache Handle protected imports as if the cache was empty
--version Display version
--explain Explain error messages in more detail
--plain Disable syntax highlighting
--ascii Format code using only ASCII syntax
--censor Hide source code in error messages
Available commands:
version Display version
resolve Resolve an expression's imports
type Infer an expression's type
normalize Normalize an expression
repl Interpret expressions in a REPL
diff Render the difference between the normal form of two
expressions
hash Compute semantic hashes for Dhall expressions
lint Improve Dhall code by using newer language features
and removing dead code
tags Generate etags file
format Standard code formatter for the Dhall language
freeze Add integrity checks to remote import statements of
an expression
encode Encode a Dhall expression to binary
decode Decode a Dhall expression from binary
text Render a Dhall expression that evaluates to a Text
literal
to-directory-tree Convert nested records of Text literals into a
directory tree
```
This new output looks like:
```console
$ dhall --help
Usage: dhall ([version] | [resolve] | [type] | [normalize] | [repl] | [diff] |
[hash] | [lint] | [tags] | [format] | [freeze] | [encode] |
[decode] | [text] | [to-directory-tree] | [--file FILE]
[--output FILE] [--annotate] [--alpha] [--no-cache] [--version])
[--explain] [--plain] [--ascii] [--censor]
Interpreter for the Dhall language
Available options:
-h,--help Show this help text
--file FILE Read expression from a file instead of standard input
--output FILE Write result to a file instead of standard output
--annotate Add a type annotation to the output
--alpha α-normalize expression
--no-cache Handle protected imports as if the cache was empty
--version Display version
--explain Explain error messages in more detail
--plain Disable syntax highlighting
--ascii Format code using only ASCII syntax
--censor Hide source code in error messages
Miscellaneous
version Display version
Interpret Dhall
resolve Resolve an expression's imports
type Infer an expression's type
normalize Normalize an expression
Miscellaneous
repl Interpret expressions in a REPL
diff Render the difference between the normal form of two
expressions
hash Compute semantic hashes for Dhall expressions
Manipulate Dhall code
lint Improve Dhall code by using newer language features
and removing dead code
Miscellaneous
tags Generate etags file
Manipulate Dhall code
format Standard code formatter for the Dhall language
freeze Add integrity checks to remote import statements of
an expression
Convert Dhall to and from its binary representation
encode Encode a Dhall expression to binary
decode Decode a Dhall expression from binary
Generate other formats from Dhall
text Render a Dhall expression that evaluates to a Text
literal
to-directory-tree Convert nested records of Text literals into a
directory tree
```
There's still work to do: actually grouping the subcommands, and
displaying the debugging subcommand. But, this gets us on the path.
The way `optparse-applicative` works with command groups is by grouping
adjacent commands together. It doesn't traverse the entire graph and
build groups. We have to move the commands where we want them so it'll
produce the groups.
This is better for us because it means we can display our groups in the
order we want.
The help output changes from:
```console
$ dhall --help
Usage: dhall ([version] | [resolve] | [type] | [normalize] | [repl] | [diff] |
[hash] | [lint] | [tags] | [format] | [freeze] | [encode] |
[decode] | [text] | [to-directory-tree] | [--file FILE]
[--output FILE] [--annotate] [--alpha] [--no-cache] [--version])
[--explain] [--plain] [--ascii] [--censor]
Interpreter for the Dhall language
Available options:
-h,--help Show this help text
--file FILE Read expression from a file instead of standard input
--output FILE Write result to a file instead of standard output
--annotate Add a type annotation to the output
--alpha α-normalize expression
--no-cache Handle protected imports as if the cache was empty
--version Display version
--explain Explain error messages in more detail
--plain Disable syntax highlighting
--ascii Format code using only ASCII syntax
--censor Hide source code in error messages
Miscellaneous
version Display version
Interpret Dhall
resolve Resolve an expression's imports
type Infer an expression's type
normalize Normalize an expression
Miscellaneous
repl Interpret expressions in a REPL
diff Render the difference between the normal form of two
expressions
hash Compute semantic hashes for Dhall expressions
Manipulate Dhall code
lint Improve Dhall code by using newer language features
and removing dead code
Miscellaneous
tags Generate etags file
Manipulate Dhall code
format Standard code formatter for the Dhall language
freeze Add integrity checks to remote import statements of
an expression
Convert Dhall to and from its binary representation
encode Encode a Dhall expression to binary
decode Decode a Dhall expression from binary
Generate other formats from Dhall
text Render a Dhall expression that evaluates to a Text
literal
to-directory-tree Convert nested records of Text literals into a
directory tree
```
to:
```console
$ dhall --help
Usage: dhall ([format] | [freeze] | [lint] | [text] | [to-directory-tree] |
[resolve] | [type] | [normalize] | [encode] | [decode] | [repl] |
[diff] | [hash] | [tags] | [version] | [--file FILE]
[--output FILE] [--annotate] [--alpha] [--no-cache] [--version])
[--explain] [--plain] [--ascii] [--censor]
Interpreter for the Dhall language
Available options:
-h,--help Show this help text
--file FILE Read expression from a file instead of standard input
--output FILE Write result to a file instead of standard output
--annotate Add a type annotation to the output
--alpha α-normalize expression
--no-cache Handle protected imports as if the cache was empty
--version Display version
--explain Explain error messages in more detail
--plain Disable syntax highlighting
--ascii Format code using only ASCII syntax
--censor Hide source code in error messages
Manipulate Dhall code
format Standard code formatter for the Dhall language
freeze Add integrity checks to remote import statements of
an expression
lint Improve Dhall code by using newer language features
and removing dead code
Generate other formats from Dhall
text Render a Dhall expression that evaluates to a Text
literal
to-directory-tree Convert nested records of Text literals into a
directory tree
Interpret Dhall
resolve Resolve an expression's imports
type Infer an expression's type
normalize Normalize an expression
Convert Dhall to and from its binary representation
encode Encode a Dhall expression to binary
decode Decode a Dhall expression from binary
Miscellaneous
repl Interpret expressions in a REPL
diff Render the difference between the normal form of two
expressions
hash Compute semantic hashes for Dhall expressions
tags Generate etags file
version Display version
```
This is much easier to understand, and should help direct people to the
right place. If we find that the groups should change, we can always do
that.
Now that we can describe groups of subcommands, we can describe the
subcommands that are for internal use only. These commands should not be
depended upon, and may change without warning. We might want to provide
more of a description around there.
The help output goes from:
```console
$ dhall --help
Usage: dhall ([format] | [freeze] | [lint] | [text] | [to-directory-tree] |
[resolve] | [type] | [normalize] | [encode] | [decode] | [repl] |
[diff] | [hash] | [tags] | [version] | [--file FILE]
[--output FILE] [--annotate] [--alpha] [--no-cache] [--version])
[--explain] [--plain] [--ascii] [--censor]
Interpreter for the Dhall language
Available options:
-h,--help Show this help text
--file FILE Read expression from a file instead of standard input
--output FILE Write result to a file instead of standard output
--annotate Add a type annotation to the output
--alpha α-normalize expression
--no-cache Handle protected imports as if the cache was empty
--version Display version
--explain Explain error messages in more detail
--plain Disable syntax highlighting
--ascii Format code using only ASCII syntax
--censor Hide source code in error messages
Manipulate Dhall code
format Standard code formatter for the Dhall language
freeze Add integrity checks to remote import statements of
an expression
lint Improve Dhall code by using newer language features
and removing dead code
Generate other formats from Dhall
text Render a Dhall expression that evaluates to a Text
literal
to-directory-tree Convert nested records of Text literals into a
directory tree
Interpret Dhall
resolve Resolve an expression's imports
type Infer an expression's type
normalize Normalize an expression
Convert Dhall to and from its binary representation
encode Encode a Dhall expression to binary
decode Decode a Dhall expression from binary
Miscellaneous
repl Interpret expressions in a REPL
diff Render the difference between the normal form of two
expressions
hash Compute semantic hashes for Dhall expressions
tags Generate etags file
version Display version
```
to:
```console
$ dhall --help
Usage: dhall ([format] | [freeze] | [lint] | [text] | [to-directory-tree] |
[resolve] | [type] | [normalize] | [encode] | [decode] | [repl] |
[diff] | [hash] | [tags] | [version] | [haskell-syntax-tree] |
[--file FILE] [--output FILE] [--annotate] [--alpha] [--no-cache]
[--version]) [--explain] [--plain] [--ascii] [--censor]
Interpreter for the Dhall language
Available options:
-h,--help Show this help text
--file FILE Read expression from a file instead of standard input
--output FILE Write result to a file instead of standard output
--annotate Add a type annotation to the output
--alpha α-normalize expression
--no-cache Handle protected imports as if the cache was empty
--version Display version
--explain Explain error messages in more detail
--plain Disable syntax highlighting
--ascii Format code using only ASCII syntax
--censor Hide source code in error messages
Manipulate Dhall code
format Standard code formatter for the Dhall language
freeze Add integrity checks to remote import statements of
an expression
lint Improve Dhall code by using newer language features
and removing dead code
Generate other formats from Dhall
text Render a Dhall expression that evaluates to a Text
literal
to-directory-tree Convert nested records of Text literals into a
directory tree
Interpret Dhall
resolve Resolve an expression's imports
type Infer an expression's type
normalize Normalize an expression
Convert Dhall to and from its binary representation
encode Encode a Dhall expression to binary
decode Decode a Dhall expression from binary
Miscellaneous
repl Interpret expressions in a REPL
diff Render the difference between the normal form of two
expressions
hash Compute semantic hashes for Dhall expressions
tags Generate etags file
version Display version
Debugging this interpreter
haskell-syntax-tree Output the parsed syntax tree (for debugging)
```
N.B. There's a new section at the end for debugging.
Gabriella439
approved these changes
Mar 2, 2020
|
My pleasure! It's been a while since I've made a PR here (have I ever?). What's the merge policy again? Do we wait three days or something before merging? |
|
@joneshf: You can merge once you have an approval |
joneshf
commented
Mar 2, 2020
As noticed in review, we want to keep indentation consistent, so we reformat this to be four spaces instead of two.
sjakobi
approved these changes
Mar 2, 2020
|
Thanks for the speedy reviews! |
Closed
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As mentioned in #1686, grouping commands should make using the CLI a bit easier. This PR changes the output from:
Old output of
dhall --helpto:
New output of
dhall --helpcc @sjakobi