github.com/zhuohuang-hust/src-cbuild@v0.0.0-20230105071821-c7aab3e7c840/mergeCode/toml/README.md (about)

     1  ## TOML parser and encoder for Go with reflection
     2  
     3  TOML stands for Tom's Obvious, Minimal Language. This Go package provides a
     4  reflection interface similar to Go's standard library `json` and `xml` 
     5  packages. This package also supports the `encoding.TextUnmarshaler` and
     6  `encoding.TextMarshaler` interfaces so that you can define custom data 
     7  representations. (There is an example of this below.)
     8  
     9  Spec: https://github.com/mojombo/toml
    10  
    11  Compatible with TOML version
    12  [v0.2.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.2.0.md)
    13  
    14  Documentation: http://godoc.org/github.com/BurntSushi/toml
    15  
    16  Installation:
    17  
    18  ```bash
    19  go get github.com/BurntSushi/toml
    20  ```
    21  
    22  Try the toml validator:
    23  
    24  ```bash
    25  go get github.com/BurntSushi/toml/cmd/tomlv
    26  tomlv some-toml-file.toml
    27  ```
    28  
    29  [![Build status](https://api.travis-ci.org/BurntSushi/toml.png)](https://travis-ci.org/BurntSushi/toml)
    30  
    31  
    32  ### Testing
    33  
    34  This package passes all tests in
    35  [toml-test](https://github.com/BurntSushi/toml-test) for both the decoder
    36  and the encoder.
    37  
    38  ### Examples
    39  
    40  This package works similarly to how the Go standard library handles `XML`
    41  and `JSON`. Namely, data is loaded into Go values via reflection.
    42  
    43  For the simplest example, consider some TOML file as just a list of keys
    44  and values:
    45  
    46  ```toml
    47  Age = 25
    48  Cats = [ "Cauchy", "Plato" ]
    49  Pi = 3.14
    50  Perfection = [ 6, 28, 496, 8128 ]
    51  DOB = 1987-07-05T05:45:00Z
    52  ```
    53  
    54  Which could be defined in Go as:
    55  
    56  ```go
    57  type Config struct {
    58    Age int
    59    Cats []string
    60    Pi float64
    61    Perfection []int
    62    DOB time.Time // requires `import time`
    63  }
    64  ```
    65  
    66  And then decoded with:
    67  
    68  ```go
    69  var conf Config
    70  if _, err := toml.Decode(tomlData, &conf); err != nil {
    71    // handle error
    72  }
    73  ```
    74  
    75  You can also use struct tags if your struct field name doesn't map to a TOML
    76  key value directly:
    77  
    78  ```toml
    79  some_key_NAME = "wat"
    80  ```
    81  
    82  ```go
    83  type TOML struct {
    84    ObscureKey string `toml:"some_key_NAME"`
    85  }
    86  ```
    87  
    88  ### Using the `encoding.TextUnmarshaler` interface
    89  
    90  Here's an example that automatically parses duration strings into 
    91  `time.Duration` values:
    92  
    93  ```toml
    94  [[song]]
    95  name = "Thunder Road"
    96  duration = "4m49s"
    97  
    98  [[song]]
    99  name = "Stairway to Heaven"
   100  duration = "8m03s"
   101  ```
   102  
   103  Which can be decoded with:
   104  
   105  ```go
   106  type song struct {
   107    Name     string
   108    Duration duration
   109  }
   110  type songs struct {
   111    Song []song
   112  }
   113  var favorites songs
   114  if _, err := toml.Decode(blob, &favorites); err != nil {
   115    log.Fatal(err)
   116  }
   117  
   118  for _, s := range favorites.Song {
   119    fmt.Printf("%s (%s)\n", s.Name, s.Duration)
   120  }
   121  ```
   122  
   123  And you'll also need a `duration` type that satisfies the 
   124  `encoding.TextUnmarshaler` interface:
   125  
   126  ```go
   127  type duration struct {
   128  	time.Duration
   129  }
   130  
   131  func (d *duration) UnmarshalText(text []byte) error {
   132  	var err error
   133  	d.Duration, err = time.ParseDuration(string(text))
   134  	return err
   135  }
   136  ```
   137  
   138  ### More complex usage
   139  
   140  Here's an example of how to load the example from the official spec page:
   141  
   142  ```toml
   143  # This is a TOML document. Boom.
   144  
   145  title = "TOML Example"
   146  
   147  [owner]
   148  name = "Tom Preston-Werner"
   149  organization = "GitHub"
   150  bio = "GitHub Cofounder & CEO\nLikes tater tots and beer."
   151  dob = 1979-05-27T07:32:00Z # First class dates? Why not?
   152  
   153  [database]
   154  server = "192.168.1.1"
   155  ports = [ 8001, 8001, 8002 ]
   156  connection_max = 5000
   157  enabled = true
   158  
   159  [servers]
   160  
   161    # You can indent as you please. Tabs or spaces. TOML don't care.
   162    [servers.alpha]
   163    ip = "10.0.0.1"
   164    dc = "eqdc10"
   165  
   166    [servers.beta]
   167    ip = "10.0.0.2"
   168    dc = "eqdc10"
   169  
   170  [clients]
   171  data = [ ["gamma", "delta"], [1, 2] ] # just an update to make sure parsers support it
   172  
   173  # Line breaks are OK when inside arrays
   174  hosts = [
   175    "alpha",
   176    "omega"
   177  ]
   178  ```
   179  
   180  And the corresponding Go types are:
   181  
   182  ```go
   183  type tomlConfig struct {
   184  	Title string
   185  	Owner ownerInfo
   186  	DB database `toml:"database"`
   187  	Servers map[string]server
   188  	Clients clients
   189  }
   190  
   191  type ownerInfo struct {
   192  	Name string
   193  	Org string `toml:"organization"`
   194  	Bio string
   195  	DOB time.Time
   196  }
   197  
   198  type database struct {
   199  	Server string
   200  	Ports []int
   201  	ConnMax int `toml:"connection_max"`
   202  	Enabled bool
   203  }
   204  
   205  type server struct {
   206  	IP string
   207  	DC string
   208  }
   209  
   210  type clients struct {
   211  	Data [][]interface{}
   212  	Hosts []string
   213  }
   214  ```
   215  
   216  Note that a case insensitive match will be tried if an exact match can't be
   217  found.
   218  
   219  A working example of the above can be found in `_examples/example.{go,toml}`.
   220