You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+7-7Lines changed: 7 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ For questions and suggestions regarding The Art of C++ / Config, success or fail
31
31
* use environment variables and the output of arbitrary shell commands.
32
32
* The function [`tao::config::from_file()`](doc/Parsing-Config-Files.md) is all you need to get going.
33
33
34
-
Every JSON file with a top-level object can be used as config file.
34
+
Every JSON file with a top-level object can be used as [config file](doc/Writing-Config-Files.md).
35
35
36
36
```
37
37
{
@@ -41,7 +41,7 @@ Every JSON file with a top-level object can be used as config file.
41
41
}
42
42
```
43
43
44
-
This small example can be rendered differently using some of the additional syntactic possibilities of the config file format.
44
+
This small example can be rendered differently using some of the additional syntactic possibilities of the [config file](doc/Writing-Config-Files.md) format.
45
45
46
46
```
47
47
#!/usr/local/bin/q3s
@@ -51,20 +51,20 @@ port = 27960
51
51
maps = [ "ztn" "dm13" "t9" ] // Add dm6 or t4?
52
52
```
53
53
54
-
Semantic features like deleting and referencing values, or including files and reading environment variables, usually only make sense with larger, non-trivial real-world examples.
54
+
Semantic features like [deleting](doc/Writing-Config-Files.md#delete) and [referencing](doc/Writing-Config-Files.md#references) values, or [including files](doc/Writing-Config-Filesmd#include-files) and [reading environment variables](doc/All-Config-Functions.md#env), usually only make sense with larger, non-trivial real-world examples.
55
55
56
56
These features can be used to manage situations that go beyond single deployments with a single config, for example providing the tools to manage configuration templates that are adapted to different environments.
57
57
58
-
Parsing a config file generally entails nothing more than calling the appropriate `from_file()` function with the filename.
58
+
[Parsing](doc/Parsing-Config-Files.md) a [config file](doc/Writing-Config-Files.md) is as simple as calling the appropriate `from_file()` function with the filename.
The resulting value is nothing other but a [JSON Value] from The Art of C++ / JSON with a custom traits class.
67
-
It can be inspected using all the facilities of that JSON library.
66
+
The resulting value is nothing other but a [JSON Value] from [taoJSON] with a custom traits class that annotates every sub-value with the filename and position it was parsed from.
67
+
It can be inspected -- and manipulated -- using all the facilities of that JSON library.
68
68
69
69
## License
70
70
@@ -87,5 +87,5 @@ It is distributed under the terms of the [MIT license] reproduced here.
Note that `msgpack` is frequently combined with `read` as in `foo = (msgpack (read "filename.msgpack"))`.
171
184
172
185
173
-
174
186
## parse
175
187
176
188
The `parse` value extension parses the given string as a single config value just "as if" the config file contained the string instead of the invocation of `parse`.
@@ -189,13 +201,14 @@ foo = (parse "null")
189
201
}
190
202
```
191
203
192
-
Note that the value described in the string is *not* allowed to use addition/concatenation, however references and/or other value extensions *are* allowed.
204
+
This can be useful when combined with [`env`](#env) for environment variables that contain numeric values as in `foo = (parse (env "MYVAR"))`.
193
205
206
+
Note that the value described in the string is *not* allowed to use addition/concatenation, however references and/or other value extensions *are* allowed.
194
207
195
208
196
209
## read
197
210
198
-
The `read`file extension reads the contents of a file and returns them as binary data.
211
+
The `read`function returns the contents of a file as binary data.
199
212
200
213
#### Example taoCONFIG Input File
201
214
@@ -215,13 +228,13 @@ bar = (string (read "tests/doc_value_read.config"))
215
228
216
229
Note that `read` can be combined with `string` to validate the data as UTF-8 and transform it into a string.
217
230
218
-
Note that the conversion from `binary` to `string` is automatic when the binary data is passed to an extension that expects a string.
219
-
231
+
Note that the conversion from `binary` to `string` is automatic when the binary data is passed to a function that expects a string.
232
+
Like [`string`](#string), the automatic conversion checks whether the binary data is a valid UTF-8 sequence and throws an exception if that is not the case.
220
233
221
234
222
235
## shell
223
236
224
-
The `shell`value extension execute the given string as shell script and returns its output.
237
+
The `shell`function executes the given string as shell script and returns its output.
225
238
226
239
#### Example taoCONFIG Input File
227
240
@@ -238,13 +251,13 @@ foo = (shell "uname -s")
238
251
```
239
252
240
253
Note that availability and behaviour of the `shell` value extension are inherently system dependent.
241
-
Currently it is only supported on Unix-style operating system like Linux and macOS.
242
-
254
+
Currently it is only supported on Unix-style operating systems that are sufficiently POSIX compliant, most prominently Linux and macOS.
243
255
244
256
245
257
## split
246
258
247
-
The `split` value extensions splits a string into its space-separated components and returns an array of them where "space" is a non-empty sequence of `' ', '\n', '\r', '\t', '\v' and/or '\f'` characters.
259
+
The `split` function splits a string into its space-separated components and returns an array of them.
260
+
Here "space" is a non-empty sequence of `' ', '\n', '\r', '\t', '\v' and/or '\f'` characters.
248
261
249
262
#### Example taoCONFIG Input File
250
263
@@ -265,10 +278,9 @@ foo = (split "a b c ")
265
278
```
266
279
267
280
268
-
269
281
## string
270
282
271
-
The `string`value extension transforms a binary value into a string value.
283
+
The `string`function transforms a binary value into a string value.
272
284
It validates that the binary data is valid UTF-8 and produces an error if that is not the case.
0 commit comments