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.