Cobra, in its default configuration, will execute a template to generate
help, usage and version outputs. Text/template execution calls MethodByName
and MethodByName disables dead code elimination in the Go linker, therefore
all programs that make use of cobra will be linked with dead code
elimination disabled, even if they end up replacing the default usage, help
and version formatters with a custom function and no actual text/template
evaluations are ever made at runtime.
Dead code elimination in the linker helps reduce disk space and memory
utilization of programs. For example, for the simple example program used by
TestDeadcodeElimination 40% of the final executable size is dead code. For a
more realistic example, 12% of the size of Delve's executable is deadcode.
This PR changes Cobra so that, in its default configuration, it does not
automatically inhibit deadcode elimination by:
1. changing Cobra's default behavior to emit output for usage and help using
simple Go functions instead of template execution
2. quarantining all calls to template execution into SetUsageTemplate,
SetHelpTemplate and SetVersionTemplate so that the linker can statically
determine if they are reachable
Fix some typos in README and comments.
Move arg validation to after flag validation so that the help flag is run first.
Pass the same args to ValidateArgs as the Run methods receive.
Update README.
Signed-off-by: Daniel Nephin <dnephin@gmail.com>
* Fix tests so they give correct args
Shell already deletes all quotes and unite args under quotes, so we
don't need to test it.
* Simplify stripFlags
* Fix 'unused' and 'gosimple' complaints
As persistent flags of parents can only be added, we don't need to always
check them every time, so make updateParentsPflags return only added flags.
Performance improvement:
benchmark old ns/op new ns/op delta
BenchmarkInheritedFlags-4 5595 4412 -21.14%
BenchmarkLocalFlags-4 3235 2667 -17.56%
benchmark old allocs new allocs delta
BenchmarkInheritedFlags-4 39 24 -38.46%
BenchmarkLocalFlags-4 21 15 -28.57%
benchmark old bytes new bytes delta
BenchmarkInheritedFlags-4 1000 600 -40.00%
BenchmarkLocalFlags-4 544 408 -25.00%
I think It's more obvious now to understand the inheritance of flags.
Fix#403Fix#404
Performance improvements:
benchmark old ns/op new ns/op delta
BenchmarkInheritedFlags-4 6536 5595 -14.40%
BenchmarkLocalFlags-4 3193 3235 +1.32%
benchmark old allocs new allocs delta
BenchmarkInheritedFlags-4 49 39 -20.41%
BenchmarkLocalFlags-4 23 21 -8.70%
benchmark old bytes new bytes delta
BenchmarkInheritedFlags-4 2040 1000 -50.98%
BenchmarkLocalFlags-4 1008 544 -46.03%
* Moving final return outside of if-else
* Removing type declarations that Go can infer from values
* Cleaning up some existing comments
* Changing snake_case variables to camelCase
Added the ability to have hidden commands that cobra will still run as intended, however they won't show up in any usage/help text
adding internal field to command
private is a better name
hiding private commands in default help/usage
opting for 'hidden' over 'private'
updating all 'help command' checks to exclude hidden commands
updating how commands are displayed in usage/help text by updating/adding some methods. added tests for hidden/deprecated commands
making command hidden when testing hidden command execution
test now leverage the included suite and are much less custom. also removed deprecation tests, once I discovered them in cobra_test.go
updating hidden command test to be more reliable
removing unnecessary () when checking len(c.Deprecated)
updating command comments to be godoc friendly
This patch enables developers to add one to many template functions that
can be used by custom Usage and Help templates. Here is an example that
is included in the file cobra_test.go as the test function named
TestAddTemplateFunctions:
AddTemplateFunc("t", func() bool { return true })
AddTemplateFuncs(template.FuncMap{
"f": func() bool { return false },
"h": func() string { return "Hello," },
"w": func() string { return "world." }})
const usage = "Hello, world."
c := &Command{}
c.SetUsageTemplate(`{{if t}}{{h}}{{end}}{{if f}}{{h}}{{end}} {{w}}`)
if us := c.UsageString(); us != usage {
t.Errorf("c.UsageString() != \"%s\", is \"%s\"", usage, us)
}
In the above example four functions are added to the template function
map used when the Usage and Help text is generated from the templates
that enable custom logic as well as data injection during template
execution.
```go
package main
import (
"github.com/spf13/cobra"
"github.com/spf13/pflag"
)
func main() {
cmd := &cobra.Command{
Use: "min",
Short: "minimal command",
Run: func(_ *cobra.Command, _ []string) {},
}
pflag.String("oncmdline", "oncmdline", "oncmdline")
cmd.Execute()
}
```
Is a minimal cobra program. When --help is displayed without this patch
you only get:
But with the patch --oncmdline is shows under flags.
Calling `cobra-test echo times one two turkey` where `one` and `two` are
valid arguments but `turkey` is not now results in.
Error: invalid argument "turkey" for "cobra-test echo times"
Run 'cobra-test echo times --help' for usage.
This fixes a problem where if you had a root command and a grand child
with the same name, the parser would break and would not run the
grandchild. The code was special casing if the immediate child had the
same name, but didn't handle grand-children
by now, if someone calls: `program --validflag unknowncommand` the
output will be:
```
Error: unknown command "--validflag"
Run 'program help' for usage.
```
This patch strips out flags so the unknown command is printed:
```
Error: unknown command "unknowncommand"
Run 'program help' for usage.
```
