1 // Copyright 2013-2022 Frank Schroeder. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 // Package properties provides functions for reading and writing
6 // ISO-8859-1 and UTF-8 encoded .properties files and has
7 // support for recursive property expansion.
8 //
9 // Java properties files are ISO-8859-1 encoded and use Unicode
10 // literals for characters outside the ISO character set. Unicode
11 // literals can be used in UTF-8 encoded properties files but
12 // aren't necessary.
13 //
14 // To load a single properties file use MustLoadFile():
15 //
16 // p := properties.MustLoadFile(filename, properties.UTF8)
17 //
18 // To load multiple properties files use MustLoadFiles()
19 // which loads the files in the given order and merges the
20 // result. Missing properties files can be ignored if the
21 // 'ignoreMissing' flag is set to true.
22 //
23 // Filenames can contain environment variables which are expanded
24 // before loading.
25 //
26 // f1 := "/etc/myapp/myapp.conf"
27 // f2 := "/home/${USER}/myapp.conf"
28 // p := MustLoadFiles([]string{f1, f2}, properties.UTF8, true)
29 //
30 // All of the different key/value delimiters ' ', ':' and '=' are
31 // supported as well as the comment characters '!' and '#' and
32 // multi-line values.
33 //
34 // ! this is a comment
35 // # and so is this
36 //
37 // # the following expressions are equal
38 // key value
39 // key=value
40 // key:value
41 // key = value
42 // key : value
43 // key = val\
44 // ue
45 //
46 // Properties stores all comments preceding a key and provides
47 // GetComments() and SetComments() methods to retrieve and
48 // update them. The convenience functions GetComment() and
49 // SetComment() allow access to the last comment. The
50 // WriteComment() method writes properties files including
51 // the comments and with the keys in the original order.
52 // This can be used for sanitizing properties files.
53 //
54 // Property expansion is recursive and circular references
55 // and malformed expressions are not allowed and cause an
56 // error. Expansion of environment variables is supported.
57 //
58 // # standard property
59 // key = value
60 //
61 // # property expansion: key2 = value
62 // key2 = ${key}
63 //
64 // # recursive expansion: key3 = value
65 // key3 = ${key2}
66 //
67 // # circular reference (error)
68 // key = ${key}
69 //
70 // # malformed expression (error)
71 // key = ${ke
72 //
73 // # refers to the users' home dir
74 // home = ${HOME}
75 //
76 // # local key takes precedence over env var: u = foo
77 // USER = foo
78 // u = ${USER}
79 //
80 // The default property expansion format is ${key} but can be
81 // changed by setting different pre- and postfix values on the
82 // Properties object.
83 //
84 // p := properties.NewProperties()
85 // p.Prefix = "#["
86 // p.Postfix = "]#"
87 //
88 // Properties provides convenience functions for getting typed
89 // values with default values if the key does not exist or the
90 // type conversion failed.
91 //
92 // # Returns true if the value is either "1", "on", "yes" or "true"
93 // # Returns false for every other value and the default value if
94 // # the key does not exist.
95 // v = p.GetBool("key", false)
96 //
97 // # Returns the value if the key exists and the format conversion
98 // # was successful. Otherwise, the default value is returned.
99 // v = p.GetInt64("key", 999)
100 // v = p.GetUint64("key", 999)
101 // v = p.GetFloat64("key", 123.0)
102 // v = p.GetString("key", "def")
103 // v = p.GetDuration("key", 999)
104 //
105 // As an alternative properties may be applied with the standard
106 // library's flag implementation at any time.
107 //
108 // # Standard configuration
109 // v = flag.Int("key", 999, "help message")
110 // flag.Parse()
111 //
112 // # Merge p into the flag set
113 // p.MustFlag(flag.CommandLine)
114 //
115 // Properties provides several MustXXX() convenience functions
116 // which will terminate the app if an error occurs. The behavior
117 // of the failure is configurable and the default is to call
118 // log.Fatal(err). To have the MustXXX() functions panic instead
119 // of logging the error set a different ErrorHandler before
120 // you use the Properties package.
121 //
122 // properties.ErrorHandler = properties.PanicHandler
123 //
124 // # Will panic instead of logging an error
125 // p := properties.MustLoadFile("config.properties")
126 //
127 // You can also provide your own ErrorHandler function. The only requirement
128 // is that the error handler function must exit after handling the error.
129 //
130 // properties.ErrorHandler = func(err error) {
131 // fmt.Println(err)
132 // os.Exit(1)
133 // }
134 //
135 // # Will write to stdout and then exit
136 // p := properties.MustLoadFile("config.properties")
137 //
138 // Properties can also be loaded into a struct via the `Decode`
139 // method, e.g.
140 //
141 // type S struct {
142 // A string `properties:"a,default=foo"`
143 // D time.Duration `properties:"timeout,default=5s"`
144 // E time.Time `properties:"expires,layout=2006-01-02,default=2015-01-01"`
145 // }
146 //
147 // See `Decode()` method for the full documentation.
148 //
149 // The following documents provide a description of the properties
150 // file format.
151 //
152 // http://en.wikipedia.org/wiki/.properties
153 //
154 // http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#load%28java.io.Reader%29
155 package properties
156