Skip to content

Commit e51813e

Browse files
committed
Extension refactoring.
1 parent e6f0bd9 commit e51813e

File tree

158 files changed

+1291
-3755
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

158 files changed

+1291
-3755
lines changed

README.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ For questions and suggestions regarding The Art of C++ / Config, success or fail
3131
* use environment variables and the output of arbitrary shell commands.
3232
* The function [`tao::config::from_file()`](doc/Parsing-Config-Files.md) is all you need to get going.
3333

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).
3535

3636
```
3737
{
@@ -41,7 +41,7 @@ Every JSON file with a top-level object can be used as config file.
4141
}
4242
```
4343

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.
4545

4646
```
4747
#!/usr/local/bin/q3s
@@ -51,20 +51,20 @@ port = 27960
5151
maps = [ "ztn" "dm13" "t9" ] // Add dm6 or t4?
5252
```
5353

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.
5555

5656
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.
5757

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.
5959

6060
```
6161
#include <tao/config.hpp>
6262
6363
const tao::config::value config = tao::config::from_file( "foo.cfg" );
6464
```
6565

66-
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.
6868

6969
## License
7070

@@ -87,5 +87,5 @@ It is distributed under the terms of the [MIT license] reproduced here.
8787
[JSON Value]: https://github.com/taocpp/json/
8888
[MIT license]: http://www.opensource.org/licenses/mit-license.html
8989
[Open Source]: http://www.opensource.org/docs/definition.html
90-
[taocpp/json]: https://github.com/taocpp/json/
90+
[taoJSON]: https://github.com/taocpp/json/
9191
[The Art of C++]: https://taocpp.github.io/

doc/Value-Extensions.md renamed to doc/All-Config-Functions.md

Lines changed: 41 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
1-
# Value Extensions
2-
3-
Value extensions produce a [JAXN] value and can be used wherever a value is expected.
4-
Note that whitespace is significant within value extensions, i.e. whitespace MUST be used as shown and comments are forbidden.
1+
# All Config Functions
52

63
* [binary](#binary)
74
* [cbor](#cbor)
@@ -17,12 +14,15 @@ Note that whitespace is significant within value extensions, i.e. whitespace MUS
1714
* [string](#string)
1815
* [ubjson](#ubjson)
1916

17+
This page is the reference documentation for all included config functions.
18+
19+
The [general information on functions and how to use them can be found here.](Writing-Config-Files.md#functions)
2020

2121

2222
## binary
2323

24-
The `binary` value extension explicitly transforms a string value into a binary value.
25-
Only the type is changed, the represented sequence of bytes is not changed.
24+
The `binary` function explicitly transforms a string value into a binary value.
25+
Only the type is changed, the sequence of bytes stays the same.
2626

2727
#### Example taoCONFIG Input File
2828

@@ -39,10 +39,9 @@ foo = (binary "Hello, world!")
3939
```
4040

4141

42-
4342
## cbor
4443

45-
The `cbor` value extension parses binary data as [CBOR] and returns the resulting value.
44+
The `cbor` function parses binary data as [CBOR] and returns the resulting value.
4645

4746
#### Example taoCONFIG Input File
4847

@@ -66,14 +65,31 @@ Note that, in line with the JSON data model, only UTF-8 strings are supported as
6665
Note that `cbor` is frequently combined with `read` as in `foo = (cbor (read "filename.cbor"))`.
6766

6867

69-
7068
## default
7169

70+
The `default` function takes one or more arguments and returns the first one that is not a JSON `null`.
71+
It is an error if all arguments are `null`.
72+
73+
#### Example taoCONFIG Input File
74+
75+
```
76+
foo = (default 1 2)
77+
bar = (default null false true)
78+
```
79+
80+
#### Resulting JAXN Config Data
81+
82+
```javascript
83+
{
84+
bar: false,
85+
foo: 1
86+
}
87+
```
7288

7389

7490
## env
7591

76-
The `env` value extensions obtain the value of an environment variable as string.
92+
The `env` functions obtain the value of an environment variable as string.
7793
For plain `env` it is an error when the environment variable does not exist, the `env?` alternative form returns a default value.
7894

7995
#### Example taoCONFIG Input File
@@ -93,10 +109,9 @@ bar = (env? "GRMBLFX" "default")
93109
```
94110

95111

96-
97112
## jaxn
98113

99-
The `jaxn` value extension parses string (or binary) data as [JAXN] and returns the resulting value.
114+
The `jaxn` function parses string (or binary) data as [JAXN] and returns the resulting value.
100115
In the case of binary data the input is automatically converted to a string, including a check for valid UTF-8.
101116

102117
#### Example taoCONFIG Input File
@@ -116,13 +131,12 @@ foo = (jaxn '[Infinity, $ff]')
116131
}
117132
```
118133

119-
Note that `jaxn` is frequently combined with `string` and `read` as in `foo = (jaxn (read "filename.jaxn"))`.
120-
134+
Note that `jaxn` is frequently combined with `read` as in `foo = (jaxn (read "filename.jaxn"))`.
121135

122136

123137
## json
124138

125-
The `json` value extension parses string (or binary) data as [JSON] and returns the resulting value.
139+
The `json` function parses string (or binary) data as [JSON] and returns the resulting value.
126140
In the case of binary data the input is automatically converted to a string, including a check for valid UTF-8.
127141

128142
#### Example taoCONFIG Input File
@@ -145,7 +159,6 @@ foo = (json '["a","b"]')
145159
Note that `json` is frequently combined with `read` as in `foo = (json (read "filename.json"))`.
146160

147161

148-
149162
## msgpack
150163

151164
The `msgpack` value extension parses binary data as [MsgPack] and returns the resulting value.
@@ -170,7 +183,6 @@ foo = (msgpack $82a161c3a162c2)
170183
Note that `msgpack` is frequently combined with `read` as in `foo = (msgpack (read "filename.msgpack"))`.
171184

172185

173-
174186
## parse
175187

176188
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")
189201
}
190202
```
191203

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"))`.
193205

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.
194207

195208

196209
## read
197210

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.
199212

200213
#### Example taoCONFIG Input File
201214

@@ -215,13 +228,13 @@ bar = (string (read "tests/doc_value_read.config"))
215228

216229
Note that `read` can be combined with `string` to validate the data as UTF-8 and transform it into a string.
217230

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.
220233

221234

222235
## shell
223236

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.
225238

226239
#### Example taoCONFIG Input File
227240

@@ -238,13 +251,13 @@ foo = (shell "uname -s")
238251
```
239252

240253
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.
243255

244256

245257
## split
246258

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.
248261

249262
#### Example taoCONFIG Input File
250263

@@ -265,10 +278,9 @@ foo = (split "a b c ")
265278
```
266279

267280

268-
269281
## string
270282

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.
272284
It validates that the binary data is valid UTF-8 and produces an error if that is not the case.
273285

274286
#### Example taoCONFIG Input File
@@ -286,12 +298,12 @@ foo = (string $48656C6C6F2C20776F726C6421)
286298
```
287299

288300
Note that the conversion from `binary` to `string` is automatic when the binary data is passed to an extension that expects a string.
289-
301+
The automatic conversion, too, checks whether the binary data is a valid UTF-8 sequence and throws an exception if that is not the case.
290302

291303

292304
## ubjson
293305

294-
The `ubjson` value extension parses binary data as [UBJSON] and returns the resulting value.
306+
The `ubjson` value function parses binary data as [UBJSON] and returns the resulting value.
295307

296308
#### Example taoCONFIG Input File
297309

doc/Changelog.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88

99
Pre-1.0.0 milestones in rough reverse chronological order.
1010

11+
* Integrate value extensions with phase 2.
12+
* Reduce member extensions to the essentials.
1113
* Remove the minus token from config keys.
1214
* Change the semantics of star and move evaluation to phase two.
1315
* Refactor everything in order to simplify the implementation.
@@ -20,6 +22,8 @@ Pre-1.0.0 milestones in rough reverse chronological order.
2022

2123
Development of taoCONFIG started in September 2018 to provide a more expressive config file syntax for [JSON] (or [JAXN]) config files.
2224

25+
26+
2327
Copyright (c) 2018-2024 Dr. Colin Hirsch and Daniel Frey
2428

2529
[JAXN]: https://github.com/stand-art/jaxn

0 commit comments

Comments
 (0)