From e6b40289f227428901e246149c25ffef18dd4491 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Wed, 23 Mar 2022 09:10:50 +0200
Subject: 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"
---
 doc/manual.cli | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

(limited to 'doc')

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:
-- 
cgit v1.1