vendor/github.com/magiconair/properties/README.md

   1 Overview [![Build Status](https://travis-ci.org/magiconair/properties.svg?branch=master)](https://travis-ci.org/magiconair/properties)
   2 ========
   3
   4 #### Current version: 1.7.3
   5
   6 properties is a Go library for reading and writing properties files.
   7
   8 It supports reading from multiple files or URLs and Spring style recursive
   9 property expansion of expressions like `${key}` to their corresponding value.
  10 Value expressions can refer to other keys like in `${key}` or to environment
  11 variables like in `${USER}`.  Filenames can also contain environment variables
  12 like in `/home/${USER}/myapp.properties`.
  13
  14 Properties can be decoded into structs, maps, arrays and values through
  15 struct tags.
  16
  17 Comments and the order of keys are preserved. Comments can be modified
  18 and can be written to the output.
  19
  20 The properties library supports both ISO-8859-1 and UTF-8 encoded data.
  21
  22 Starting from version 1.3.0 the behavior of the MustXXX() functions is
  23 configurable by providing a custom `ErrorHandler` function. The default has
  24 changed from `panic` to `log.Fatal` but this is configurable and custom
  25 error handling functions can be provided. See the package documentation for
  26 details.
  27
  28 Read the full documentation on [GoDoc](https://godoc.org/github.com/magiconair/properties)   [![GoDoc](https://godoc.org/github.com/magiconair/properties?status.png)](https://godoc.org/github.com/magiconair/properties)
  29
  30 Getting Started
  31 ---------------
  32
  33 ```go
  34 import (
  35         "flag"
  36         "github.com/magiconair/properties"
  37 )
  38
  39 func main() {
  40         // init from a file
  41         p := properties.MustLoadFile("${HOME}/config.properties", properties.UTF8)
  42
  43         // or multiple files
  44         p = properties.MustLoadFiles([]string{
  45                         "${HOME}/config.properties",
  46                         "${HOME}/config-${USER}.properties",
  47                 }, properties.UTF8, true)
  48
  49         // or from a map
  50         p = properties.LoadMap(map[string]string{"key": "value", "abc": "def"})
  51
  52         // or from a string
  53         p = properties.MustLoadString("key=value\nabc=def")
  54
  55         // or from a URL
  56         p = properties.MustLoadURL("http://host/path")
  57
  58         // or from multiple URLs
  59         p = properties.MustLoadURL([]string{
  60                         "http://host/config",
  61                         "http://host/config-${USER}",
  62                 }, true)
  63
  64         // or from flags
  65         p.MustFlag(flag.CommandLine)
  66
  67         // get values through getters
  68         host := p.MustGetString("host")
  69         port := p.GetInt("port", 8080)
  70
  71         // or through Decode
  72         type Config struct {
  73                 Host    string        `properties:"host"`
  74                 Port    int           `properties:"port,default=9000"`
  75                 Accept  []string      `properties:"accept,default=image/png;image;gif"`
  76                 Timeout time.Duration `properties:"timeout,default=5s"`
  77         }
  78         var cfg Config
  79         if err := p.Decode(&cfg); err != nil {
  80                 log.Fatal(err)
  81         }
  82 }
  83
  84 ```
  85
  86 Installation and Upgrade
  87 ------------------------
  88
  89 ```
  90 $ go get -u github.com/magiconair/properties
  91 ```
  92
  93 License
  94 -------
  95
  96 2 clause BSD license. See [LICENSE](https://github.com/magiconair/properties/blob/master/LICENSE) file for details.
  97
  98 ToDo
  99 ----
 100 * Dump contents with passwords and secrets obscured