Extension refactoring.

README.md

@@ -31,7 +31,7 @@ For questions and suggestions regarding The Art of C++ / Config, success or fail
  * use environment variables and the output of arbitrary shell commands.
  * The function [`tao::config::from_file()`](doc/Parsing-Config-Files.md) is all you need to get going.
 
-Every JSON file with a top-level object can be used as config file.
+Every JSON file with a top-level object can be used as [config file](doc/Writing-Config-Files.md).
 
 ```
 {
@@ -41,7 +41,7 @@ Every JSON file with a top-level object can be used as config file.
 }
 ```
 
-This small example can be rendered differently using some of the additional syntactic possibilities of the config file format.
+This small example can be rendered differently using some of the additional syntactic possibilities of the [config file](doc/Writing-Config-Files.md) format.
 
 ```
 #!/usr/local/bin/q3s
@@ -51,20 +51,20 @@ port = 27960
 maps = [ "ztn" "dm13" "t9" ]  // Add dm6 or t4?
 ```
 
-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.
+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.
 
 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.
 
-Parsing a config file generally entails nothing more than calling the appropriate `from_file()` function with the filename.
+[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.
 
 ```
 #include <tao/config.hpp>
 
 const tao::config::value config = tao::config::from_file( "foo.cfg" );
 ```
 
-The resulting value is nothing other but a [JSON Value] from The Art of C++ / JSON with a custom traits class.
-It can be inspected using all the facilities of that JSON library.
+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.
+It can be inspected -- and manipulated -- using all the facilities of that JSON library.
 
 ## License
 
@@ -87,5 +87,5 @@ It is distributed under the terms of the [MIT license] reproduced here.
 [JSON Value]: https://github.com/taocpp/json/
 [MIT license]: http://www.opensource.org/licenses/mit-license.html
 [Open Source]: http://www.opensource.org/docs/definition.html
-[taocpp/json]: https://github.com/taocpp/json/
+[taoJSON]: https://github.com/taocpp/json/
 [The Art of C++]: https://taocpp.github.io/

doc/Value-Extensions.md → doc/All-Config-Functions.md

@@ -1,7 +1,4 @@
-# Value Extensions
-
-Value extensions produce a [JAXN] value and can be used wherever a value is expected.
-Note that whitespace is significant within value extensions, i.e. whitespace MUST be used as shown and comments are forbidden.
+# All Config Functions
 
  * [binary](#binary)
  * [cbor](#cbor)
@@ -17,12 +14,15 @@ Note that whitespace is significant within value extensions, i.e. whitespace MUS
  * [string](#string)
  * [ubjson](#ubjson)
 
+This page is the reference documentation for all included config functions.
+
+The [general information on functions and how to use them can be found here.](Writing-Config-Files.md#functions)
 
 
 ## binary
 
-The `binary` value extension explicitly transforms a string value into a binary value.
-Only the type is changed, the represented sequence of bytes is not changed.
+The `binary` function explicitly transforms a string value into a binary value.
+Only the type is changed, the sequence of bytes stays the same.
 
 #### Example taoCONFIG Input File
 
@@ -39,10 +39,9 @@ foo = (binary "Hello, world!")
 ```
 
 
-
 ## cbor
 
-The `cbor` value extension parses binary data as [CBOR] and returns the resulting value.
+The `cbor` function parses binary data as [CBOR] and returns the resulting value.
 
 #### Example taoCONFIG Input File
 
@@ -66,14 +65,31 @@ Note that, in line with the JSON data model, only UTF-8 strings are supported as
 Note that `cbor` is frequently combined with `read` as in `foo = (cbor (read "filename.cbor"))`.
 
 
-
 ## default
 
+The `default` function takes one or more arguments and returns the first one that is not a JSON `null`.
+It is an error if all arguments are `null`.
+
+#### Example taoCONFIG Input File
+
+```
+foo = (default 1 2)
+bar = (default null false true)
+```
+
+#### Resulting JAXN Config Data
+
+```javascript
+{
+   bar: false,
+   foo: 1
+}
+```
 
 
 ## env
 
-The `env` value extensions obtain the value of an environment variable as string.
+The `env` functions obtain the value of an environment variable as string.
 For plain `env` it is an error when the environment variable does not exist, the `env?` alternative form returns a default value.
 
 #### Example taoCONFIG Input File
@@ -93,10 +109,9 @@ bar = (env? "GRMBLFX" "default")
 ```
 
 
-
 ## jaxn
 
-The `jaxn` value extension parses string (or binary) data as [JAXN] and returns the resulting value.
+The `jaxn` function parses string (or binary) data as [JAXN] and returns the resulting value.
 In the case of binary data the input is automatically converted to a string, including a check for valid UTF-8.
 
 #### Example taoCONFIG Input File
@@ -116,13 +131,12 @@ foo = (jaxn '[Infinity, $ff]')
 }
 ```
 
-Note that `jaxn` is frequently combined with `string` and `read` as in `foo = (jaxn (read "filename.jaxn"))`.
-
+Note that `jaxn` is frequently combined with `read` as in `foo = (jaxn (read "filename.jaxn"))`.
 
 
 ## json
 
-The `json` value extension parses string (or binary) data as [JSON] and returns the resulting value.
+The `json` function parses string (or binary) data as [JSON] and returns the resulting value.
 In the case of binary data the input is automatically converted to a string, including a check for valid UTF-8.
 
 #### Example taoCONFIG Input File
@@ -145,7 +159,6 @@ foo = (json '["a","b"]')
 Note that `json` is frequently combined with `read` as in `foo = (json (read "filename.json"))`.
 
 
-
 ## msgpack
 
 The `msgpack` value extension parses binary data as [MsgPack] and returns the resulting value.
@@ -170,7 +183,6 @@ foo = (msgpack $82a161c3a162c2)
 Note that `msgpack` is frequently combined with `read` as in `foo = (msgpack (read "filename.msgpack"))`.
 
 
-
 ## parse
 
 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")
 }
 ```
 
-Note that the value described in the string is *not* allowed to use addition/concatenation, however references and/or other value extensions *are* allowed.
+This can be useful when combined with [`env`](#env) for environment variables that contain numeric values as in `foo = (parse (env "MYVAR"))`.
 
+Note that the value described in the string is *not* allowed to use addition/concatenation, however references and/or other value extensions *are* allowed.
 
 
 ## read
 
-The `read` file extension reads the contents of a file and returns them as binary data.
+The `read` function returns the contents of a file as binary data.
 
 #### Example taoCONFIG Input File
 
@@ -215,13 +228,13 @@ bar = (string (read "tests/doc_value_read.config"))
 
 Note that `read` can be combined with `string` to validate the data as UTF-8 and transform it into a string.
 
-Note that the conversion from `binary` to `string` is automatic when the binary data is passed to an extension that expects a string.
-
+Note that the conversion from `binary` to `string` is automatic when the binary data is passed to a function that expects a string.
+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.
 
 
 ## shell
 
-The `shell` value extension execute the given string as shell script and returns its output.
+The `shell` function executes the given string as shell script and returns its output.
 
 #### Example taoCONFIG Input File
 
@@ -238,13 +251,13 @@ foo = (shell "uname -s")
 ```
 
 Note that availability and behaviour of the `shell` value extension are inherently system dependent.
-Currently it is only supported on Unix-style operating system like Linux and macOS.
-
+Currently it is only supported on Unix-style operating systems that are sufficiently POSIX compliant, most prominently Linux and macOS.
 
 
 ## split
 
-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.
+The `split` function splits a string into its space-separated components and returns an array of them.
+Here "space" is a non-empty sequence of `' ', '\n', '\r', '\t', '\v' and/or '\f'` characters.
 
 #### Example taoCONFIG Input File
 
@@ -265,10 +278,9 @@ foo = (split "a b c ")
 ```
 
 
-
 ## string
 
-The `string` value extension transforms a binary value into a string value.
+The `string` function transforms a binary value into a string value.
 It validates that the binary data is valid UTF-8 and produces an error if that is not the case.
 
 #### Example taoCONFIG Input File
@@ -286,12 +298,12 @@ foo = (string $48656C6C6F2C20776F726C6421)
 ```
 
 Note that the conversion from `binary` to `string` is automatic when the binary data is passed to an extension that expects a string.
-
+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.
 
 
 ## ubjson
 
-The `ubjson` value extension parses binary data as [UBJSON] and returns the resulting value.
+The `ubjson` value function parses binary data as [UBJSON] and returns the resulting value.
 
 #### Example taoCONFIG Input File
 

doc/Changelog.md

@@ -8,6 +8,8 @@
 
 Pre-1.0.0 milestones in rough reverse chronological order.
 
+* Integrate value extensions with phase 2.
+* Reduce member extensions to the essentials.
 * Remove the minus token from config keys.
 * Change the semantics of star and move evaluation to phase two.
 * Refactor everything in order to simplify the implementation.
@@ -20,6 +22,8 @@ Pre-1.0.0 milestones in rough reverse chronological order.
 
 Development of taoCONFIG started in September 2018 to provide a more expressive config file syntax for [JSON] (or [JAXN]) config files.
 
+
+
 Copyright (c) 2018-2024 Dr. Colin Hirsch and Daniel Frey
 
 [JAXN]: https://github.com/stand-art/jaxn