github.com/bingoohuang/gg@v0.0.0-20240325092523-45da7dee9335/pkg/fla9/README.md (about)

     1  # Flag
     2  
     3  fork from github.com/namsral/flag
     4  
     5  Flag is a drop in replacement for Go's flag package with the addition to parse files and environment variables. 
     6  
     7  If you support the [twelve-factor app methodology][], Flag complies with the third factor; "Store config in the environment".
     8  
     9  [twelve-factor app methodology]: http://12factor.net
    10  
    11  An example:
    12  
    13  ```go
    14  package main
    15  
    16  import (
    17  	"fmt"
    18  	flag "github.com/bingoohuang/gg/pkg/fla9"
    19  )
    20  
    21  func main() {
    22  	var age int
    23  	flag.IntVar(&age, "age", 0, "age of gopher")
    24  	flag.Parse()
    25  	fmt.Print("age:", age)
    26  }
    27  ```
    28  
    29  ```sh
    30  $ go run gopher.go -age 1
    31  age: 1
    32  ```
    33  
    34  Same code but using an environment variable:
    35  
    36  ```go
    37  $ export AGE=2
    38  $ go run gopher.go
    39  age: 2
    40  ```
    41  
    42  Same code but using a configuration file:
    43  
    44  ```go
    45  $ cat > gopher.conf
    46  age 3
    47  
    48  $ go run gopher.go -config gopher.conf
    49  age: 3
    50  ```
    51  
    52  The following table shows how flags are translated to environment variables and configuration files:
    53  
    54  | Type   | Flag          | Environment  | File         |
    55  | ------ | :------------ |:------------ |:------------ |
    56  | int    | -age 2        | AGE=2        | age 2        |
    57  | bool   | -female       | FEMALE=true  | female true  |
    58  | float  | -length 175.5 | LENGTH=175.5 | length 175.5 |
    59  | string | -name Gloria  | NAME=Gloria  | name Gloria  |
    60  
    61  This package is a port of Go's [flag][] package from the standard library with the addition of two functions `ParseEnv` and `ParseFile`.
    62  
    63  [flag]: http://golang.org/src/pkg/flag
    64  
    65  
    66  Goals
    67  -----
    68  
    69  - Compatability with the original `flag` package
    70  - Support the [twelve-factor app methodology][]
    71  - Uniform user experience between the three input methods
    72  
    73  
    74  Why?
    75  ---
    76  
    77  Why not use one of the many INI, JSON or YAML parsers?
    78  
    79  I find it best practice to have simple configuration options to control the behaviour of an applications when it starts up. Use basic types like ints, floats and strings for configuration options and store more complex data structures in the "datastore" layer.
    80  
    81  
    82  Usage
    83  ---
    84  
    85  It's intended for projects which require a simple configuration made available through command-line flags, configuration files and shell environments. It's similar to the original `flag` package.
    86  
    87  Example:
    88  
    89  ```go
    90  import "github.com/namsral/flag"
    91  
    92  flag.String(flag.DefaultConfigFlagname, "", "path to config file")
    93  flag.Int("age", 24, "help message for age")
    94  
    95  flag.Parse()
    96  ```
    97  
    98  Order of precedence:
    99  
   100  1. Command line options
   101  2. Environment variables
   102  3. Configuration file
   103  4. Default values
   104  
   105  #### Parsing Configuration Files
   106  
   107  Create a configuration file:
   108  
   109  ```go
   110  $ cat > ./gopher.conf
   111  # empty newlines and lines beginning with a "#" character are ignored.
   112  name bob
   113  
   114  # keys and values can also be separated by the "=" character
   115  age=20
   116  
   117  # booleans can be empty, set with 0, 1, true, false, etc
   118  hacker
   119  ```
   120  
   121  Add a "config" flag:
   122  
   123  ```go
   124  flag.String(flag.DefaultConfigFlagname, "", "path to config file")
   125  ```
   126  
   127  Run the command:
   128  
   129  ```go
   130  $ go run ./gopher.go -config ./gopher.conf
   131  ```
   132  
   133  The default flag name for the configuration file is "config" and can be changed
   134  by setting `flag.DefaultConfigFlagname`:
   135  
   136  ```go
   137  flag.DefaultConfigFlagname = "conf"
   138  flag.Parse()
   139  ```
   140  
   141  #### Parsing Environment Variables
   142  
   143  Environment variables are parsed 1-on-1 with defined flags:
   144  
   145  ```go
   146  $ export AGE=44
   147  $ go run ./gopher.go
   148  age=44
   149  ```
   150  
   151  
   152  You can also parse prefixed environment variables by setting a prefix name when creating a new empty flag set:
   153  
   154  ```go
   155  fs := flag.NewFlagSetWithEnvPrefix(os.Args[0], "GO", 0)
   156  fs.Int("age", 24, "help message for age")
   157  fs.Parse(os.Args[1:])
   158  ...
   159  $ go export GO_AGE=33
   160  $ go run ./gopher.go
   161  age=33
   162  ```
   163  
   164  
   165  For more examples see the [examples][] directory in the project repository.
   166  
   167  [examples]: https://github.com/namsral/flag/tree/master/examples
   168  
   169  That's it.