git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/toml/README.md (about)

     1  TOML stands for Tom's Obvious, Minimal Language. This Go package provides a
     2  reflection interface similar to Go's standard library `json` and `xml` packages.
     3  
     4  Compatible with TOML version [v1.0.0](https://toml.io/en/v1.0.0).
     5  
     6  Documentation: https://godocs.io/git.sr.ht/~pingoo/stdx/toml
     7  
     8  See the [releases page](https://git.sr.ht/~pingoo/stdx/toml/releases) for a
     9  changelog; this information is also in the git tag annotations (e.g. `git show
    10  v0.4.0`).
    11  
    12  This library requires Go 1.13 or newer; add it to your go.mod with:
    13  
    14      % go get git.sr.ht/~pingoo/stdx/toml@latest
    15  
    16  It also comes with a TOML validator CLI tool:
    17  
    18      % go install git.sr.ht/~pingoo/stdx/toml/cmd/tomlv@latest
    19      % tomlv some-toml-file.toml
    20  
    21  ### Examples
    22  For the simplest example, consider some TOML file as just a list of keys and
    23  values:
    24  
    25  ```toml
    26  Age = 25
    27  Cats = [ "Cauchy", "Plato" ]
    28  Pi = 3.14
    29  Perfection = [ 6, 28, 496, 8128 ]
    30  DOB = 1987-07-05T05:45:00Z
    31  ```
    32  
    33  Which can be decoded with:
    34  
    35  ```go
    36  type Config struct {
    37  	Age        int
    38  	Cats       []string
    39  	Pi         float64
    40  	Perfection []int
    41  	DOB        time.Time
    42  }
    43  
    44  var conf Config
    45  _, err := toml.Decode(tomlData, &conf)
    46  ```
    47  
    48  You can also use struct tags if your struct field name doesn't map to a TOML key
    49  value directly:
    50  
    51  ```toml
    52  some_key_NAME = "wat"
    53  ```
    54  
    55  ```go
    56  type TOML struct {
    57      ObscureKey string `toml:"some_key_NAME"`
    58  }
    59  ```
    60  
    61  Beware that like other decoders **only exported fields** are considered when
    62  encoding and decoding; private fields are silently ignored.
    63  
    64  ### Using the `Marshaler` and `encoding.TextUnmarshaler` interfaces
    65  Here's an example that automatically parses values in a `mail.Address`:
    66  
    67  ```toml
    68  contacts = [
    69      "Donald Duck <donald@duckburg.com>",
    70      "Scrooge McDuck <scrooge@duckburg.com>",
    71  ]
    72  ```
    73  
    74  Can be decoded with:
    75  
    76  ```go
    77  // Create address type which satisfies the encoding.TextUnmarshaler interface.
    78  type address struct {
    79  	*mail.Address
    80  }
    81  
    82  func (a *address) UnmarshalText(text []byte) error {
    83  	var err error
    84  	a.Address, err = mail.ParseAddress(string(text))
    85  	return err
    86  }
    87  
    88  // Decode it.
    89  func decode() {
    90  	blob := `
    91  		contacts = [
    92  			"Donald Duck <donald@duckburg.com>",
    93  			"Scrooge McDuck <scrooge@duckburg.com>",
    94  		]
    95  	`
    96  
    97  	var contacts struct {
    98  		Contacts []address
    99  	}
   100  
   101  	_, err := toml.Decode(blob, &contacts)
   102  	if err != nil {
   103  		log.Fatal(err)
   104  	}
   105  
   106  	for _, c := range contacts.Contacts {
   107  		fmt.Printf("%#v\n", c.Address)
   108  	}
   109  
   110  	// Output:
   111  	// &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"}
   112  	// &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
   113  }
   114  ```
   115  
   116  To target TOML specifically you can implement `UnmarshalTOML` TOML interface in
   117  a similar way.
   118  
   119  ### More complex usage
   120  See the [`_example/`](/_example) directory for a more complex example.