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