Add suggestions support

The new option `app.Suggest` enables command and flag suggestions via
the jaro-winkler distance algorithm. Flags are scoped to their
appropriate commands whereas command suggestions are scoped to the
current command level.

Signed-off-by: Sascha Grunert <sgrunert@suse.com>
This commit is contained in:
Sascha Grunert 2019-11-29 14:09:46 +01:00
parent 1b7e4e00c7
commit 002bde2233
No known key found for this signature in database
GPG Key ID: 8CE029DD1A866E52
9 changed files with 257 additions and 8 deletions

12
app.go
View File

@ -88,6 +88,8 @@ type App struct {
// single-character bool arguments into one
// i.e. foobar -o -v -> foobar -ov
UseShortOptionHandling bool
// Enable suggestions for commands and flags
Suggest bool
didSetup bool
}
@ -250,6 +252,11 @@ func (a *App) RunContext(ctx context.Context, arguments []string) (err error) {
return err
}
_, _ = fmt.Fprintf(a.Writer, "%s %s\n\n", "Incorrect Usage.", err.Error())
if a.Suggest {
if suggestion, err := a.suggestFlagFromError(err, ""); err == nil {
fmt.Fprintf(a.Writer, suggestion)
}
}
_ = ShowAppHelp(context)
return err
}
@ -381,6 +388,11 @@ func (a *App) RunAsSubcommand(ctx *Context) (err error) {
return err
}
_, _ = fmt.Fprintf(a.Writer, "%s %s\n\n", "Incorrect Usage.", err.Error())
if a.Suggest {
if suggestion, err := a.suggestFlagFromError(err, context.Command.Name); err == nil {
fmt.Fprintf(a.Writer, suggestion)
}
}
_ = ShowSubcommandHelp(context)
return err
}

View File

@ -116,6 +116,11 @@ func (c *Command) Run(ctx *Context) (err error) {
}
_, _ = fmt.Fprintln(context.App.Writer, "Incorrect Usage:", err.Error())
_, _ = fmt.Fprintln(context.App.Writer)
if ctx.App.Suggest {
if suggestion, err := ctx.App.suggestFlagFromError(err, c.Name); err == nil {
fmt.Fprintf(context.App.Writer, suggestion)
}
}
_ = ShowCommandHelp(context, c.Name)
return err
}
@ -244,6 +249,7 @@ func (c *Command) startApp(ctx *Context) error {
app.ErrWriter = ctx.App.ErrWriter
app.ExitErrHandler = ctx.App.ExitErrHandler
app.UseShortOptionHandling = ctx.App.UseShortOptionHandling
app.Suggest = ctx.App.Suggest
app.categories = newCommandCategories()
for _, command := range c.Subcommands {

View File

@ -34,6 +34,7 @@ cli v2 manual
* [Version Flag](#version-flag)
+ [Customization](#customization-2)
* [Timestamp Flag](#timestamp-flag)
* [Suggestions](#suggestions)
* [Full API Example](#full-api-example)
<!-- tocstop -->
@ -1426,6 +1427,13 @@ In this example the flag could be used like this :
Side note: quotes may be necessary around the date depending on your layout (if you have spaces for instance)
### Suggestions
To enable flag and command suggestions, set `app.Suggest = true`. If the suggest
feature is enabled, then the help output of the corresponding command will
provide an appropriate suggestion for the provided flag or subcommand if
available.
### Full API Example
**Notice**: This is a contrived (functioning) example meant strictly for API

1
go.mod
View File

@ -4,6 +4,7 @@ go 1.11
require (
github.com/BurntSushi/toml v0.3.1
github.com/antzucaro/matchr v0.0.0-20180616170659-cbc221335f3c
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d
gopkg.in/yaml.v2 v2.2.2
)

2
go.sum
View File

@ -1,5 +1,7 @@
github.com/BurntSushi/toml v0.3.1 h1:WXkYYl6Yr3qBf1K79EBnL4mak0OimBfB0XUf9Vl28OQ=
github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
github.com/antzucaro/matchr v0.0.0-20180616170659-cbc221335f3c h1:CucViv7orgFBMkehuFFdkCVF5ERovbkRRyhvaYaHu/k=
github.com/antzucaro/matchr v0.0.0-20180616170659-cbc221335f3c/go.mod h1:bV/CkX4+ANGDaBwbHkt9kK287al/i9BsB18PRBvyqYo=
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d h1:U+s90UTSYgptZMwQh2aRr3LuazLJIa+Pg3Kc1ylSYVY=
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=

21
help.go
View File

@ -10,9 +10,14 @@ import (
"unicode/utf8"
)
const (
helpName = "help"
helpAlias = "h"
)
var helpCommand = &Command{
Name: "help",
Aliases: []string{"h"},
Name: helpName,
Aliases: []string{helpAlias},
Usage: "Shows a list of commands or help for one command",
ArgsUsage: "[command]",
Action: func(c *Context) error {
@ -27,8 +32,8 @@ var helpCommand = &Command{
}
var helpSubcommand = &Command{
Name: "help",
Aliases: []string{"h"},
Name: helpName,
Aliases: []string{helpAlias},
Usage: "Shows a list of commands or help for one command",
ArgsUsage: "[command]",
Action: func(c *Context) error {
@ -207,7 +212,13 @@ func ShowCommandHelp(ctx *Context, command string) error {
}
if ctx.App.CommandNotFound == nil {
return Exit(fmt.Sprintf("No help topic for '%v'", command), 3)
errMsg := fmt.Sprintf("No help topic for '%v'", command)
if ctx.App.Suggest {
if suggestion := suggestCommand(ctx.App.Commands, command); suggestion != "" {
errMsg += ". " + suggestion
}
}
return Exit(errMsg, 3)
}
ctx.App.CommandNotFound(ctx, command)

View File

@ -26,9 +26,8 @@ func parseIter(set *flag.FlagSet, ip iterativeParser, args []string, shellComple
return err
}
errStr := err.Error()
trimmed := strings.TrimPrefix(errStr, "flag provided but not defined: -")
if errStr == trimmed {
trimmed, trimErr := flagFromError(err)
if trimErr != nil {
return err
}
@ -67,6 +66,19 @@ func parseIter(set *flag.FlagSet, ip iterativeParser, args []string, shellComple
}
}
const providedButNotDefinedErrMsg = "flag provided but not defined: -"
// flagFromError tries to parse a provided flag from an error message. If the
// parsing fials, it returns the input error and an empty string
func flagFromError(err error) (string, error) {
errStr := err.Error()
trimmed := strings.TrimPrefix(errStr, providedButNotDefinedErrMsg)
if errStr == trimmed {
return "", err
}
return trimmed, nil
}
func splitShortOptions(set *flag.FlagSet, arg string) []string {
shortFlagsExist := func(s string) bool {
for _, c := range s[1:] {

75
suggestions.go Normal file
View File

@ -0,0 +1,75 @@
package cli
import (
"fmt"
"github.com/antzucaro/matchr"
)
const didYouMeanTemplate = "Did you mean '%s'?"
func (a *App) suggestFlagFromError(err error, command string) (string, error) {
flag, parseErr := flagFromError(err)
if parseErr != nil {
return "", err
}
flags := a.Flags
if command != "" {
cmd := a.Command(command)
if cmd == nil {
return "", err
}
flags = cmd.Flags
}
suggestion := a.suggestFlag(flags, flag)
if len(suggestion) == 0 {
return "", err
}
return fmt.Sprintf(didYouMeanTemplate+"\n\n", suggestion), nil
}
func (a *App) suggestFlag(flags []Flag, provided string) (suggestion string) {
distance := 0.0
for _, flag := range flags {
flagNames := flag.Names()
if !a.HideHelp {
flagNames = append(flagNames, HelpFlag.Names()...)
}
for _, name := range flagNames {
newDistance := matchr.JaroWinkler(name, provided, true)
if newDistance > distance {
distance = newDistance
suggestion = name
}
}
}
if len(suggestion) == 1 {
suggestion = "-" + suggestion
} else if len(suggestion) > 1 {
suggestion = "--" + suggestion
}
return suggestion
}
// suggestCommand takes a list of commands and a provided string to suggest a
// command name
func suggestCommand(commands []*Command, provided string) (suggestion string) {
distance := 0.0
for _, command := range commands {
for _, name := range append(command.Names(), helpName, helpAlias) {
newDistance := matchr.JaroWinkler(name, provided, true)
if newDistance > distance {
distance = newDistance
suggestion = name
}
}
}
return fmt.Sprintf(didYouMeanTemplate, suggestion)
}

122
suggestions_test.go Normal file
View File

@ -0,0 +1,122 @@
package cli
import (
"errors"
"fmt"
"testing"
)
func TestSuggestFlag(t *testing.T) {
// Given
app := testApp()
for _, testCase := range []struct {
provided, expected string
}{
{"", ""},
{"a", "--another-flag"},
{"hlp", "--help"},
{"k", ""},
{"s", "-s"},
} {
// When
res := app.suggestFlag(app.Flags, testCase.provided)
// Then
expect(t, res, testCase.expected)
}
}
func TestSuggestFlagHideHelp(t *testing.T) {
// Given
app := testApp()
app.HideHelp = true
// When
res := app.suggestFlag(app.Flags, "hlp")
// Then
expect(t, res, "--fl")
}
func TestSuggestFlagFromError(t *testing.T) {
// Given
app := testApp()
for _, testCase := range []struct {
command, provided, expected string
}{
{"", "hel", "--help"},
{"", "soccer", "--socket"},
{"config", "anot", "--another-flag"},
} {
// When
res, _ := app.suggestFlagFromError(
errors.New(providedButNotDefinedErrMsg+testCase.provided),
testCase.command,
)
// Then
expect(t, res, fmt.Sprintf(didYouMeanTemplate+"\n\n", testCase.expected))
}
}
func TestSuggestFlagFromErrorWrongError(t *testing.T) {
// Given
app := testApp()
// When
_, err := app.suggestFlagFromError(errors.New("invalid"), "")
// Then
expect(t, true, err != nil)
}
func TestSuggestFlagFromErrorWrongCommand(t *testing.T) {
// Given
app := testApp()
// When
_, err := app.suggestFlagFromError(
errors.New(providedButNotDefinedErrMsg+"flag"),
"invalid",
)
// Then
expect(t, true, err != nil)
}
func TestSuggestFlagFromErrorNoSuggestion(t *testing.T) {
// Given
app := testApp()
// When
_, err := app.suggestFlagFromError(
errors.New(providedButNotDefinedErrMsg+""),
"",
)
// Then
expect(t, true, err != nil)
}
func TestSuggestCommand(t *testing.T) {
// Given
app := testApp()
for _, testCase := range []struct {
provided, expected string
}{
{"", ""},
{"conf", "config"},
{"i", "i"},
{"information", "info"},
{"not-existing", "info"},
} {
// When
res := suggestCommand(app.Commands, testCase.provided)
// Then
expect(t, res, fmt.Sprintf(didYouMeanTemplate, testCase.expected))
}
}