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