1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
|
Commands and Sub-commands
=========================
The base `Command` interface is found in `cmd/cmd.go`.
Commands need to provide an `Info` method that returns an Info struct.
The info struct contains: name, args, purpose and a detailed description.
This information is used to provide the default help for the command.
In the same package, there is `CommandBase` whose purpose is to be composed
into new commands, and provides a default no-op SetFlags implementation, a
default Init method that checks for no extra args, and a default Help method.
Supercommands
=============
`Supercommand`s are commands that do many things, and have "sub-commands" that
provide this functionality. Git and Bazaar are common examples of
"supercommands". Subcommands must also provide the `Command` interface, and
are registered using the `Register` method. The name and aliases are
registered with the supercommand. If there is a duplicate name registered,
the whole thing panics.
Supercommands need to be created with the `NewSuperCommand` function in order
to provide a fully constructed object.
The 'help' subcommand
---------------------
All supercommand instances get a help command. This provides the basic help
functionality to get all the registered commands, with the addition of also
being able to provide non-command help topics which can be added.
Help topics have a `name` which is what is matched from the command line, a
`short` one line description that is shown when `<cmd> help topics` is called,
and a `long` text that is output when the topic is requested.
Topics are added using the `AddHelpTopic` method.
Execution
=========
The `Main` method in the cmd package handles the execution of a command.
A new `gnuflag.FlagSet` is created and passed to the command in `SetFlags`.
This is for the command to register the flags that it knows how to handle.
The args are then parsed, and passed through to the `Init` method for the
command to decide what to do with the positional arguments.
The command is then `Run` and passed in an execution `Context` that defines
the standard input and output streams, and has the current working directory.
|