aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.cli
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2022-03-23 09:10:50 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2022-03-23 09:10:50 +0200
commite6b40289f227428901e246149c25ffef18dd4491 (patch)
treee4951bb9e5ff40f63ad6f6bee0dd4a94f7dab755 /doc/manual.cli
parentc1c80c10a8d469b2659015429c7695f3dbd51ef2 (diff)
Make project configuration variables non-nullable by default
A project configuration variable with the NULL default value is naturally assumed nullable, for example: config [string] config.libhello.fallback_name ?= [null] Otherwise, to make a project configuration nullable we use the `null` variable attribute, for example: config [string, null] config.libhello.fallback_name ?= "World"
Diffstat (limited to 'doc/manual.cli')
-rw-r--r--doc/manual.cli31
1 files changed, 20 insertions, 11 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index 0ac053e..fcee403 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -4782,13 +4782,31 @@ is user-defined, then the default value is not evaluated.
Note also that if the configuration value is not specified by the user and you
haven't provided the default, the variable will be undefined, not \c{null},
and, as a result, omitted from the persistent configuration
-(\c{build/config.build} file). However, \c{null} is a valid default value. It
-is traditionally used for \i{optional} configuration values. For example:
+(\c{build/config.build} file). In fact, unlike other variables, project
+configuration variables are by default not \i{nullable}. For example:
+
+\
+$ b configure config.libhello.fancy=[null]
+error: null value in non-nullable variable config.libhello.fancy
+\
+
+There are two ways to make \c{null} a valid value of a project configuration
+variable. Firstly, if the default value is \c{null}, then naturally the
+variable is assumed nullable. This is traditionally used for \i{optional}
+configuration values. For example:
\
config [string] config.libhello.fallback_name ?= [null]
\
+If we need a nullable configuration variable but with a non-\c{null} default
+value (or no default value at all), then we have to use the \c{null} variable
+attribute. For example:
+
+\
+config [string, null] config.libhello.fallback_name ?= \"World\"
+\
+
A common approach for representing an C/C++ enum-like value is to use
\c{string} as a type and pattern matching for validation. In fact, validation
and propagation can often be combined. For example, if our library needed to
@@ -4832,15 +4850,6 @@ if! $defined(config.libhello.database)
fail 'config.libhello.database must be specified'
\
-And if you want to also disallow \c{null} values, then the above check should
-be rewritten like this: \N{An undefined variable expands into a \c{null}
-value.}
-
-\
-if ($config.libhello.database == [null])
- fail 'config.libhello.database must be specified'
-\
-
If computing the default value is expensive or requires elaborate logic, then
the handling of a configuration variable can be broken down into two steps
along these lines: