github.com/loggregator/cli@v6.33.1-0.20180224010324-82334f081791+incompatible/cf/flags/README.md (about)

     1  # flags - Golang command-line flag parser
     2  [![GoDoc](https://godoc.org/github.com/cloudfoundry/cli/cf/flags?status.svg)](https://godoc.org/github.com/cloudfoundry/cli/cf/flags)
     3  
     4  - Fully tested, reliable
     5  - Support flag ShortName (Alias)
     6  - Catches any non-defined flags, and any invalid flag values
     7  - Flags can come before or after the arguments. The followings are all valid inputs:
     8  ```bash
     9  testapp -i 100 -m 500 arg1 arg2   # flags go first
    10  testapp arg1 arg2 --i 100 -m 500  # flags go last
    11  testapp arg1 -i 100 arg2 -m=500   # flags go in between arguments
    12  ```
    13  The parsed results for all 3 statements are identical: `i=100`, `Args=[arg1, arg2]`, `m=500`
    14  
    15  # Installation
    16  ```bash
    17  go get github.com/cloudfoundry/cli/cf/flags  # installs the flags library
    18  ```
    19  
    20  # Usage
    21  ```Go
    22  package main
    23  
    24  import "github.com/cloudfoundry/cli/cf/flags"
    25  
    26  func main(){
    27    fc := flags.New()
    28    fc.NewStringFlag("password", "p", "flag for password")  //name, short_name and usage of the string flag
    29    fc.Parse(os.Args...)  //parse the OS arguments
    30    println("Flag 'password' is set: ", fc.IsSet("s"))
    31    println("Flag 'password' value: ", fc.String("s"))
    32  }
    33  ```
    34  Running the above code
    35  ```
    36  $ main -password abc
    37  Flag 'password' is set: true
    38  Flag 'password' value: abc
    39  ```
    40  
    41  # Available Flag Constructor
    42  Flags: String, Int, float64, Bool, String Slice
    43  ```Go
    44  NewStringFlag(name string, short_name string, usage string)
    45  NewStringFlagWithDefault(name string, short_name string, usage string, value string)
    46  NewIntFlag(name string, short_name string, usage string)
    47  NewIntFlagWithDefault(name string, short_name string, usage string, value int)
    48  NewFloat64Flag(name string, short_name string, usage string)
    49  NewFloat64FlagWithDefault(name string, short_name string, usage string, value float64)
    50  NewStringSliceFlag(name string, short_name string, usage string) //this flag can be supplied more than 1 time
    51  NewStringSliceFlagWithDefault(name string, short_name string, usage string, value []string)
    52  NewBoolFlag(name string, short_name string, usage string)
    53  ```
    54  
    55  # Functions for flags/args reading
    56  ```Go
    57  IsSet(flag_name string)bool
    58  String(flag_name string)string
    59  Int(flag_name string)int
    60  Float64(flag_name string)float64
    61  Bool(flag_name string)bool
    62  StringSlice(flag_name string)[]string  
    63  Args()[]string
    64  ```
    65  
    66  # Parsing flags and arguments
    67  ```Go
    68  Parse(args ...string)error  //returns error for any non-defined flags & invalid value for Int, Float64 and Bool flag.
    69  ```
    70  Sample Code
    71  ```Go
    72  fc := flags.New()
    73  fc.NewIntFlag("i", "", "Int flag name i")  //set up a Int flag '-i'
    74  fc.NewBoolFlag("verbose", "v", "Bool flag name verbose")  //set up a bool flag '-verbose'
    75  err := fc.Parse(os.Args...) //Parse() returns any error it finds during parsing
    76  If err != nil {
    77    fmt.Println("Parsing error:", err)
    78  }
    79  fmt.Println("Args:", fc.Args())  //Args() returns an array of all the arguments
    80  fmt.Println("Verbose:", fc.Bool("verbose"))
    81  fmt.Println("i:", fc.Int("i"))
    82  ```
    83  Running above
    84  ```bash
    85  $ app arg_1 -i 100 arg_2 -verbose  # run the code
    86  Args: [arg_1 arg_2]
    87  Verbose: true
    88  i: 100
    89  ```
    90  
    91  # Special function
    92  ```Go
    93  SkipFlagParsing(bool)  //if set to true, all flags become arguments
    94  ShowUsage(leadingSpace int)string  //string containing all the flags and their usage text
    95  ```