github.com/dooferlad/cmd@v0.0.0-20150716022859-3edef806220b/README.md (about) 1 2 # cmd 3 import "github.com/juju/cmd" 4 5 6 7 8 9 ## Variables 10 ``` go 11 var DefaultFormatters = map[string]Formatter{ 12 "smart": FormatSmart, 13 "yaml": FormatYaml, 14 "json": FormatJson, 15 } 16 ``` 17 DefaultFormatters holds the formatters that can be 18 specified with the --format flag. 19 20 ``` go 21 var ErrNoPath = errors.New("path not set") 22 ``` 23 ``` go 24 var ErrSilent = errors.New("cmd: error out silently") 25 ``` 26 ErrSilent can be returned from Run to signal that Main should exit with 27 code 1 without producing error output. 28 29 ``` go 30 var FormatJson = json.Marshal 31 ``` 32 FormatJson marshals value to a json-formatted []byte. 33 34 35 ## func CheckEmpty 36 ``` go 37 func CheckEmpty(args []string) error 38 ``` 39 CheckEmpty is a utility function that returns an error if args is not empty. 40 41 42 ## func FormatSmart 43 ``` go 44 func FormatSmart(value interface{}) ([]byte, error) 45 ``` 46 FormatSmart marshals value into a []byte according to the following rules: 47 48 49 * string: untouched 50 * bool: converted to `True` or `False` (to match pyjuju) 51 * int or float: converted to sensible strings 52 * []string: joined by `\n`s into a single string 53 * anything else: delegate to FormatYaml 54 55 56 ## func FormatYaml 57 ``` go 58 func FormatYaml(value interface{}) ([]byte, error) 59 ``` 60 FormatYaml marshals value to a yaml-formatted []byte, unless value is nil. 61 62 63 ## func IsRcPassthroughError 64 ``` go 65 func IsRcPassthroughError(err error) bool 66 ``` 67 68 ## func Main 69 ``` go 70 func Main(c Command, ctx *Context, args []string) int 71 ``` 72 Main runs the given Command in the supplied Context with the given 73 arguments, which should not include the command name. It returns a code 74 suitable for passing to os.Exit. 75 76 77 ## func NewCommandLogWriter 78 ``` go 79 func NewCommandLogWriter(name string, out, err io.Writer) loggo.Writer 80 ``` 81 NewCommandLogWriter creates a loggo writer for registration 82 by the callers of a command. This way the logged output can also 83 be displayed otherwise, e.g. on the screen. 84 85 86 ## func NewRcPassthroughError 87 ``` go 88 func NewRcPassthroughError(code int) error 89 ``` 90 NewRcPassthroughError creates an error that will have the code used at the 91 return code from the cmd.Main function rather than the default of 1 if 92 there is an error. 93 94 95 ## func ZeroOrOneArgs 96 ``` go 97 func ZeroOrOneArgs(args []string) (string, error) 98 ``` 99 ZeroOrOneArgs checks to see that there are zero or one args, and returns 100 the value of the arg if provided, or the empty string if not. 101 102 103 104 ## type AppendStringsValue 105 ``` go 106 type AppendStringsValue []string 107 ``` 108 AppendStringsValue implements gnuflag.Value for a value that can be set 109 multiple times, and it appends each value to the slice. 110 111 112 113 114 115 116 117 118 119 ### func NewAppendStringsValue 120 ``` go 121 func NewAppendStringsValue(target *[]string) *AppendStringsValue 122 ``` 123 NewAppendStringsValue is used to create the type passed into the gnuflag.FlagSet Var function. 124 f.Var(cmd.NewAppendStringsValue(&someMember), "name", "help") 125 126 127 128 129 ### func (\*AppendStringsValue) Set 130 ``` go 131 func (v *AppendStringsValue) Set(s string) error 132 ``` 133 Implements gnuflag.Value Set. 134 135 136 137 ### func (\*AppendStringsValue) String 138 ``` go 139 func (v *AppendStringsValue) String() string 140 ``` 141 Implements gnuflag.Value String. 142 143 144 145 ## type Command 146 ``` go 147 type Command interface { 148 // IsSuperCommand returns true if the command is a super command. 149 IsSuperCommand() bool 150 151 // Info returns information about the Command. 152 Info() *Info 153 154 // SetFlags adds command specific flags to the flag set. 155 SetFlags(f *gnuflag.FlagSet) 156 157 // Init initializes the Command before running. 158 Init(args []string) error 159 160 // Run will execute the Command as directed by the options and positional 161 // arguments passed to Init. 162 Run(ctx *Context) error 163 164 // AllowInterspersedFlags returns whether the command allows flag 165 // arguments to be interspersed with non-flag arguments. 166 AllowInterspersedFlags() bool 167 } 168 ``` 169 Command is implemented by types that interpret command-line arguments. 170 171 172 173 174 175 176 177 178 179 180 181 ## type CommandBase 182 ``` go 183 type CommandBase struct{} 184 ``` 185 CommandBase provides the default implementation for SetFlags, Init, and Help. 186 187 188 189 190 191 192 193 194 195 196 197 ### func (\*CommandBase) AllowInterspersedFlags 198 ``` go 199 func (c *CommandBase) AllowInterspersedFlags() bool 200 ``` 201 AllowInterspersedFlags returns true by default. Some subcommands 202 may want to override this. 203 204 205 206 ### func (\*CommandBase) Init 207 ``` go 208 func (c *CommandBase) Init(args []string) error 209 ``` 210 Init in the simplest case makes sure there are no args. 211 212 213 214 ### func (\*CommandBase) IsSuperCommand 215 ``` go 216 func (c *CommandBase) IsSuperCommand() bool 217 ``` 218 IsSuperCommand implements Command.IsSuperCommand 219 220 221 222 ### func (\*CommandBase) SetFlags 223 ``` go 224 func (c *CommandBase) SetFlags(f *gnuflag.FlagSet) 225 ``` 226 SetFlags does nothing in the simplest case. 227 228 229 230 ## type Context 231 ``` go 232 type Context struct { 233 Dir string 234 Stdin io.Reader 235 Stdout io.Writer 236 Stderr io.Writer 237 // contains filtered or unexported fields 238 } 239 ``` 240 Context represents the run context of a Command. Command implementations 241 should interpret file names relative to Dir (see AbsPath below), and print 242 output and errors to Stdout and Stderr respectively. 243 244 245 246 247 248 249 250 251 252 ### func DefaultContext 253 ``` go 254 func DefaultContext() (*Context, error) 255 ``` 256 DefaultContext returns a Context suitable for use in non-hosted situations. 257 258 259 260 261 ### func (\*Context) AbsPath 262 ``` go 263 func (ctx *Context) AbsPath(path string) string 264 ``` 265 AbsPath returns an absolute representation of path, with relative paths 266 interpreted as relative to ctx.Dir. 267 268 269 270 ### func (\*Context) GetStderr 271 ``` go 272 func (ctx *Context) GetStderr() io.Writer 273 ``` 274 GetStderr satisfies environs.BootstrapContext 275 276 277 278 ### func (\*Context) GetStdin 279 ``` go 280 func (ctx *Context) GetStdin() io.Reader 281 ``` 282 GetStdin satisfies environs.BootstrapContext 283 284 285 286 ### func (\*Context) GetStdout 287 ``` go 288 func (ctx *Context) GetStdout() io.Writer 289 ``` 290 GetStdout satisfies environs.BootstrapContext 291 292 293 294 ### func (\*Context) Infof 295 ``` go 296 func (ctx *Context) Infof(format string, params ...interface{}) 297 ``` 298 Infof will write the formatted string to Stderr if quiet is false, but if 299 quiet is true the message is logged. 300 301 302 303 ### func (\*Context) InterruptNotify 304 ``` go 305 func (ctx *Context) InterruptNotify(c chan<- os.Signal) 306 ``` 307 InterruptNotify satisfies environs.BootstrapContext 308 309 310 311 ### func (\*Context) StopInterruptNotify 312 ``` go 313 func (ctx *Context) StopInterruptNotify(c chan<- os.Signal) 314 ``` 315 StopInterruptNotify satisfies environs.BootstrapContext 316 317 318 319 ### func (\*Context) Verbosef 320 ``` go 321 func (ctx *Context) Verbosef(format string, params ...interface{}) 322 ``` 323 Verbosef will write the formatted string to Stderr if the verbose is true, 324 and to the logger if not. 325 326 327 328 ## type DeprecationCheck 329 ``` go 330 type DeprecationCheck interface { 331 332 // Deprecated aliases emit a warning when executed. If the command is 333 // deprecated, the second return value recommends what to use instead. 334 Deprecated() (bool, string) 335 336 // Obsolete aliases are not actually registered. The purpose of this 337 // is to allow code to indicate ahead of time some way to determine 338 // that the command should stop working. 339 Obsolete() bool 340 } 341 ``` 342 DeprecationCheck is used to provide callbacks to determine if 343 a command is deprecated or obsolete. 344 345 346 347 348 349 350 351 352 353 354 355 ## type FileVar 356 ``` go 357 type FileVar struct { 358 Path string 359 } 360 ``` 361 FileVar represents a path to a file. 362 363 364 365 366 367 368 369 370 371 372 373 ### func (\*FileVar) Read 374 ``` go 375 func (f *FileVar) Read(ctx *Context) ([]byte, error) 376 ``` 377 Read returns the contents of the file. 378 379 380 381 ### func (\*FileVar) Set 382 ``` go 383 func (f *FileVar) Set(v string) error 384 ``` 385 Set stores the chosen path name in f.Path. 386 387 388 389 ### func (\*FileVar) String 390 ``` go 391 func (f *FileVar) String() string 392 ``` 393 String returns the path to the file. 394 395 396 397 ## type Formatter 398 ``` go 399 type Formatter func(value interface{}) ([]byte, error) 400 ``` 401 Formatter converts an arbitrary object into a []byte. 402 403 404 405 406 407 408 409 410 411 412 413 ## type Info 414 ``` go 415 type Info struct { 416 // Name is the Command's name. 417 Name string 418 419 // Args describes the command's expected positional arguments. 420 Args string 421 422 // Purpose is a short explanation of the Command's purpose. 423 Purpose string 424 425 // Doc is the long documentation for the Command. 426 Doc string 427 428 // Aliases are other names for the Command. 429 Aliases []string 430 } 431 ``` 432 Info holds some of the usage documentation of a Command. 433 434 435 436 437 438 439 440 441 442 443 444 ### func (\*Info) Help 445 ``` go 446 func (i *Info) Help(f *gnuflag.FlagSet) []byte 447 ``` 448 Help renders i's content, along with documentation for any 449 flags defined in f. It calls f.SetOutput(ioutil.Discard). 450 451 452 453 ## type Log 454 ``` go 455 type Log struct { 456 // If DefaultConfig is set, it will be used for the 457 // default logging configuration. 458 DefaultConfig string 459 Path string 460 Verbose bool 461 Quiet bool 462 Debug bool 463 ShowLog bool 464 Config string 465 Factory WriterFactory 466 } 467 ``` 468 Log supplies the necessary functionality for Commands that wish to set up 469 logging. 470 471 472 473 474 475 476 477 478 479 480 481 ### func (\*Log) AddFlags 482 ``` go 483 func (l *Log) AddFlags(f *gnuflag.FlagSet) 484 ``` 485 AddFlags adds appropriate flags to f. 486 487 488 489 ### func (\*Log) GetLogWriter 490 ``` go 491 func (l *Log) GetLogWriter(target io.Writer) loggo.Writer 492 ``` 493 GetLogWriter returns a logging writer for the specified target. 494 495 496 497 ### func (\*Log) Start 498 ``` go 499 func (log *Log) Start(ctx *Context) error 500 ``` 501 Start starts logging using the given Context. 502 503 504 505 ## type MissingCallback 506 ``` go 507 type MissingCallback func(ctx *Context, subcommand string, args []string) error 508 ``` 509 MissingCallback defines a function that will be used by the SuperCommand if 510 the requested subcommand isn't found. 511 512 513 514 515 516 517 518 519 520 521 522 ## type Output 523 ``` go 524 type Output struct { 525 // contains filtered or unexported fields 526 } 527 ``` 528 Output is responsible for interpreting output-related command line flags 529 and writing a value to a file or to stdout as directed. 530 531 532 533 534 535 536 537 538 539 540 541 ### func (\*Output) AddFlags 542 ``` go 543 func (c *Output) AddFlags(f *gnuflag.FlagSet, defaultFormatter string, formatters map[string]Formatter) 544 ``` 545 AddFlags injects the --format and --output command line flags into f. 546 547 548 549 ### func (\*Output) Name 550 ``` go 551 func (c *Output) Name() string 552 ``` 553 554 555 ### func (\*Output) Write 556 ``` go 557 func (c *Output) Write(ctx *Context, value interface{}) (err error) 558 ``` 559 Write formats and outputs the value as directed by the --format and 560 --output command line flags. 561 562 563 564 ## type RcPassthroughError 565 ``` go 566 type RcPassthroughError struct { 567 Code int 568 } 569 ``` 570 571 572 573 574 575 576 577 578 579 580 ### func (\*RcPassthroughError) Error 581 ``` go 582 func (e *RcPassthroughError) Error() string 583 ``` 584 585 586 ## type StringsValue 587 ``` go 588 type StringsValue []string 589 ``` 590 StringsValue implements gnuflag.Value for a comma separated list of 591 strings. This allows flags to be created where the target is []string, and 592 the caller is after comma separated values. 593 594 595 596 597 598 599 600 601 602 ### func NewStringsValue 603 ``` go 604 func NewStringsValue(defaultValue []string, target *[]string) *StringsValue 605 ``` 606 NewStringsValue is used to create the type passed into the gnuflag.FlagSet Var function. 607 f.Var(cmd.NewStringsValue(defaultValue, &someMember), "name", "help") 608 609 610 611 612 ### func (\*StringsValue) Set 613 ``` go 614 func (v *StringsValue) Set(s string) error 615 ``` 616 Implements gnuflag.Value Set. 617 618 619 620 ### func (\*StringsValue) String 621 ``` go 622 func (v *StringsValue) String() string 623 ``` 624 Implements gnuflag.Value String. 625 626 627 628 ## type SuperCommand 629 ``` go 630 type SuperCommand struct { 631 CommandBase 632 Name string 633 Purpose string 634 Doc string 635 Log *Log 636 Aliases []string 637 // contains filtered or unexported fields 638 } 639 ``` 640 SuperCommand is a Command that selects a subcommand and assumes its 641 properties; any command line arguments that were not used in selecting 642 the subcommand are passed down to it, and to Run a SuperCommand is to run 643 its selected subcommand. 644 645 646 647 648 649 650 651 652 653 ### func NewSuperCommand 654 ``` go 655 func NewSuperCommand(params SuperCommandParams) *SuperCommand 656 ``` 657 NewSuperCommand creates and initializes a new `SuperCommand`, and returns 658 the fully initialized structure. 659 660 661 662 663 ### func (\*SuperCommand) AddHelpTopic 664 ``` go 665 func (c *SuperCommand) AddHelpTopic(name, short, long string, aliases ...string) 666 ``` 667 AddHelpTopic adds a new help topic with the description being the short 668 param, and the full text being the long param. The description is shown in 669 'help topics', and the full text is shown when the command 'help <name>' is 670 called. 671 672 673 674 ### func (\*SuperCommand) AddHelpTopicCallback 675 ``` go 676 func (c *SuperCommand) AddHelpTopicCallback(name, short string, longCallback func() string) 677 ``` 678 AddHelpTopicCallback adds a new help topic with the description being the 679 short param, and the full text being defined by the callback function. 680 681 682 683 ### func (\*SuperCommand) AllowInterspersedFlags 684 ``` go 685 func (c *SuperCommand) AllowInterspersedFlags() bool 686 ``` 687 For a SuperCommand, we want to parse the args with 688 allowIntersperse=false. This will mean that the args may contain other 689 options that haven't been defined yet, and that only options that relate 690 to the SuperCommand itself can come prior to the subcommand name. 691 692 693 694 ### func (\*SuperCommand) Info 695 ``` go 696 func (c *SuperCommand) Info() *Info 697 ``` 698 Info returns a description of the currently selected subcommand, or of the 699 SuperCommand itself if no subcommand has been specified. 700 701 702 703 ### func (\*SuperCommand) Init 704 ``` go 705 func (c *SuperCommand) Init(args []string) error 706 ``` 707 Init initializes the command for running. 708 709 710 711 ### func (\*SuperCommand) IsSuperCommand 712 ``` go 713 func (c *SuperCommand) IsSuperCommand() bool 714 ``` 715 IsSuperCommand implements Command.IsSuperCommand 716 717 718 719 ### func (\*SuperCommand) Register 720 ``` go 721 func (c *SuperCommand) Register(subcmd Command) 722 ``` 723 Register makes a subcommand available for use on the command line. The 724 command will be available via its own name, and via any supplied aliases. 725 726 727 728 ### func (\*SuperCommand) RegisterAlias 729 ``` go 730 func (c *SuperCommand) RegisterAlias(name, forName string, check DeprecationCheck) 731 ``` 732 RegisterAlias makes an existing subcommand available under another name. 733 If `check` is supplied, and the result of the `Obsolete` call is true, 734 then the alias is not registered. 735 736 737 738 ### func (\*SuperCommand) RegisterSuperAlias 739 ``` go 740 func (c *SuperCommand) RegisterSuperAlias(name, super, forName string, check DeprecationCheck) 741 ``` 742 RegisterSuperAlias makes a subcommand of a registered supercommand 743 available under another name. This is useful when the command structure is 744 being refactored. If `check` is supplied, and the result of the `Obsolete` 745 call is true, then the alias is not registered. 746 747 748 749 ### func (\*SuperCommand) Run 750 ``` go 751 func (c *SuperCommand) Run(ctx *Context) error 752 ``` 753 Run executes the subcommand that was selected in Init. 754 755 756 757 ### func (\*SuperCommand) SetCommonFlags 758 ``` go 759 func (c *SuperCommand) SetCommonFlags(f *gnuflag.FlagSet) 760 ``` 761 SetCommonFlags creates a new "commonflags" flagset, whose 762 flags are shared with the argument f; this enables us to 763 add non-global flags to f, which do not carry into subcommands. 764 765 766 767 ### func (\*SuperCommand) SetFlags 768 ``` go 769 func (c *SuperCommand) SetFlags(f *gnuflag.FlagSet) 770 ``` 771 SetFlags adds the options that apply to all commands, particularly those 772 due to logging. 773 774 775 776 ## type SuperCommandParams 777 ``` go 778 type SuperCommandParams struct { 779 // UsagePrefix should be set when the SuperCommand is 780 // actually a subcommand of some other SuperCommand; 781 // if NotifyRun is called, it name will be prefixed accordingly, 782 // unless UsagePrefix is identical to Name. 783 UsagePrefix string 784 785 // Notify, if not nil, is called when the SuperCommand 786 // is about to run a sub-command. 787 NotifyRun func(cmdName string) 788 789 Name string 790 Purpose string 791 Doc string 792 Log *Log 793 MissingCallback MissingCallback 794 Aliases []string 795 Version string 796 } 797 ``` 798 SuperCommandParams provides a way to have default parameter to the 799 `NewSuperCommand` call. 800 801 802 803 804 805 806 807 808 809 810 811 ## type UnrecognizedCommand 812 ``` go 813 type UnrecognizedCommand struct { 814 Name string 815 } 816 ``` 817 818 819 820 821 822 823 824 825 826 827 ### func (\*UnrecognizedCommand) Error 828 ``` go 829 func (e *UnrecognizedCommand) Error() string 830 ``` 831 832 833 ## type WriterFactory 834 ``` go 835 type WriterFactory interface { 836 NewWriter(target io.Writer) loggo.Writer 837 } 838 ``` 839 WriterFactory defines the single method to create a new 840 logging writer for a specified output target. 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 - - - 859 Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md)