[css-values-5] Define <boolean [test]> multiplier w3c#10457

Author: fantasai

css-values-4/Overview.bs

@@ -147,7 +147,7 @@ Component Value Types</h3>
 		does not include the top-level <a lt=# grammar>comma-separated list multiplier</a>.
 		(E.g. if a property named <code>pairing</code> is defined as <code>[ <<custom-ident>> <<integer>>? ]#</code>,
 		then <code>&lt;\'pairing'></code> is equivalent to <code>[ <<custom-ident>> <<integer>>? ]</code>,
-		not <code>[ <<custom-ident>> <<integer>>? ]#</code>.)\
+		not <code>[ <<custom-ident>> <<integer>>? ]#</code>.)
 
 		<details class=note>
 			<summary>Why remove the multiplier?</summary>
@@ -5371,102 +5371,6 @@ Appendix A: Recommended Minimum Ranges and Precision of Computed Values</h2>
 	</span>
 -->
 
-
-<!-- Big Text: bools -->
-
-<h2 id="bools">
-Boolean Expressions</h2>
-
-In several contexts, CSS allows certain boolean tests
-(things that can evaluate to true or false),
-and allows them to be combined with the logical operators
-AND, OR, and NOT to form more complicated boolean tests.
-(For example, ''@media'' or ''@supports'' rules.)
-
-All of these locations share a common grammatical structure,
-with the only difference being what "base" boolean tests
-are allowed,
-and whether they use simple 2-value (true/false) boolean algebra,
-or 3-value (true/false/unknown) Kleene logic.
-
-For example, in ''@media'' only <<media-condition>>s are allowed,
-with Kleene logic;
-in ''@supports'' only <<supports-condition>>s are allowed,
-with boolean logic.
-
-As the overall structure of these grammars is identical
-across the various usages of it,
-and also complex enough to be non-trivial to reproduce
-(and easy to accidentally do wrong),
-this specification defines <<boolean>>,
-a generic grammar for all such boolean tests.
-
-<pre class=prod>
-	<dfn>&lt;boolean></dfn> = <<bool-not>> | <<bool-in-parens>> [ <<bool-and>>* | <<bool-or>>* ]
-	<dfn>&lt;boolean-without-or></dfn> = <<bool-not>> | <<bool-in-parens>> <<bool-and>>*
-	<dfn>&lt;bool-not></dfn> = not <<bool-in-parens>>
-	<dfn>&lt;bool-and></dfn> = and <<bool-in-parens>>
-	<dfn>&lt;bool-or></dfn> = or <<bool-in-parens>>
-	<dfn>&lt;bool-in-parens></dfn> = ( <<boolean>> ) | <<bool-test>> | <<general-enclosed>>
-
-	<dfn>&lt;general-enclosed></dfn> = [ <<function-token>> <<any-value>>? ) ] | [ ( <<any-value>>? ) ]
-</pre>
-
-Each specification using <<boolean>>
-must define what things are valid as <dfn>&lt;bool-test></dfn> values
-in that context,
-and whether it uses 2-value or 3-value logic.
-As well, <<bool-test>> values
-<em>should</em> either be wrapped in parentheses
-or be functions;
-if a specification needs to express some conditions in a different way,
-please contact the CSSWG for review.
-
-: If using 2-value logic
-::
-	* Every <<bool-test>> must be defined to evaluate to either true or false.
-	* <<general-enclosed>> evaluates to false.
-	* <<bool-in-parens>> evaluates to the value of its contained <<boolean>>, <<bool-test>>, or <<general-enclosed>>
-	* <<bool-not>> evaluates to true if its contained <<bool-in-parens>> is false,
-		and false otherwise.
-	* A <<boolean>> with only a <<bool-not>> or <<bool-in-parens>> evaluates to that.
-	* A <<boolean>> with multiple <<bool-in-parens>> connected with ''and''
-		evaluates to true if all of its <<bool-in-parens>> are true,
-		and false otherwise.
-	* A <<boolean>> with multiple <<bool-in-parens>> connected with ''or''
-		evaluates to true if any of its <<bool-in-parens>> are true,
-		and false otherwise.
-
-: If using 3-value logic
-::
-	* Every <<bool-test>> must be defined to evaluate to either true, false, or unknown.
-	* <<general-enclosed>> evaluates to unknown.
-	* <<bool-in-parens>> evaluates to the value of its contained <<boolean>>, <<bool-test>>, or <<general-enclosed>>
-	* <<bool-not>> evaluates to true if its contained <<bool-in-parens>> is false,
-		false if it's true,
-		and unknown if it's unknown.
-	* A <<boolean>> with only a <<bool-not>> or <<bool-in-parens>> evaluates to that.
-	* A <<boolean>> with multiple <<bool-in-parens>> connected with ''and''
-		evaluates to true if all of its <<bool-in-parens>> are true,
-		false if any of them are false,
-		and unknown otherwise
-		(at least one unknown, but no false).
-	* A <<boolean>> with multiple <<bool-in-parens>> connected with ''or''
-		evaluates to true if any of its <<bool-in-parens>> are true,
-		false if all of them are false,
-		and unknown otherwise
-		(at least one unknown, but no true).
-	* If a "top-level" <<boolean>> is unknown,
-		and the containing context uses 2-value logic
-		(or doesn't specify otherwise),
-		it instead evaluates to false.
-
-		Note: That is, unknown doesn't "escape" a 3-value expression,
-		similar to how NaN doesn't "escape" a [=top-level calculation=]).
-
-
-
-
 <!-- Big Text: lists 
 
 █▌    ████  ███▌  █████▌  ███▌ 

css-values-5/Overview.bs

@@ -77,6 +77,17 @@ Value Definition Syntax</h2>
 
 	See [[css-values-4#value-defs]].
 
+	Additionally,
+
+	<ol>
+		<li value=5>Boolean combinations of a conditional notation.
+			These are written using the <<boolean [ &lt;test&gt; ]>> notation,
+			and represent recursive expressions of boolean logic
+			using keywords and parentheses,
+			applied to the type specified in brackets,
+			e.g. <<boolean [ ( &lt;media-feature&gt; ) ]>> to express [=media queries=].
+	</ol>
+
 <h3 id=component-functions>
 Functional Notation Definitions</h3>
 
@@ -201,6 +212,62 @@ Commas in Function Arguments</h4>
 	Other contexts <em>may</em> define that they use [=non-strict comma-containing productions=],
 	but it <em>should</em> be avoided unless necessary.
 
+<h3 id=boolean>
+Boolean Expression Multiplier <<boolean>></h3>
+
+	Several contexts
+	(such as ''@media'', ''@supports'', ''if()'', ...)
+	specify conditions,
+	and allow combining those conditions with boolean logic (and/or/not/grouping).
+	Because they use the same non-trivial recursive syntax structure,
+	the special <dfn><<boolean>></dfn> production represents this pattern generically.
+
+	The <<boolean>> notation wraps another value type in the square brackets within it,
+	e.g. &lt;boolean [ &lt;test&gt; ]&gt;,
+	and represents that value alone as well as
+	boolean combinations of those values
+	using the ''not'', ''and'', and ''or'' keywords
+	and grouping parenthesis.
+	It is formally equivalent to:
+
+	<xmp class=prod>
+		<boolean [ <test> ]> = not <boolean-group> | <boolean-group>
+		                                             [ [ and <boolean-group> ]*
+		                                             | [ or <boolean-group> ]* ]
+
+		<boolean-group> = <test> | ( <boolean> ) | <general-enclosed>
+	</xmp>
+
+	The <<boolean>> production represents a true, false, or unknown value,
+	with top-level unknown values
+	(those not directly nested inside the grammar of another <<boolean>>)
+	resolving to false unless otherwise specified.
+	Its value is resolved using 3-value Kleene logic;
+	see [[#boolean-logic]] for details.
+
+	<div class=example>
+		For example, the ''@container'' rule allows a wide variety of tests:
+		including size queries, style queries, and scroll-state queries.
+		All of these are arbitrarily combinable with boolean logic.
+		Using <<boolean>>, the grammar for an ''@container'' query is:
+
+		<xmp class=prod>
+			<container-query> = <boolean [ <cq-test> ]>
+			<cq-test> = (<size-query>) | style( <style-query> ) | scroll-state( <scroll-state-query> )
+			<size-query> = <boolean [ ( <size-feature> ) ]> | <size-feature>
+			<style-query> = <boolean [ ( <style-feature> ) ]> | <style-feature>
+			<scroll-state-query> = <boolean [ ( <scroll-state-feature> ) ]> | <scroll-state-feature>
+		</xmp>
+	</div>
+
+	The <<general-enclosed>> branch of the logic allows for future compatibility--
+	unless otherwise specified new expressions in an older UA
+	will be parsed and considered “unknown”,
+	rather than invalidating the production.
+	For consistency with that allowance,
+	the <css>&lt;test></css> term in a <<boolean>>
+	should be defined to match <<general-enclosed>>.
+
 <h3 id=css-syntax>
 Specifying CSS Syntax in CSS: the <<syntax>> type</h3>
 
@@ -3070,6 +3137,48 @@ Safely Handling Overly-Long Substitution</h3>
 	and the fact that it can be done without any of the pieces
 	<em>seeming</em> to be too large on first inspection.
 
+<h2 id="boolean-logic">
+Appendix B: Boolean Logic</h2>
+
+	In order to accommodate future extensions of CSS,
+	<<boolean>> productions generally interpret their <<general-enclosed>> grammar branch as unknown,
+	and their boolean logic is resolved using 3-value Kleene logic.
+	In some cases (such as ''@supports''),
+	<<general-enclosed>> is instead defined as false;
+	in which case the logic devolves to standard boolean algebra.
+
+	3-value boolean logic is applied recursively
+	to a boolean condition |test| as follows:
+
+	* A leaf-level |test| resolves to
+		true, false, or unknown,
+		as defined by the relevant specification.
+
+	* ''not |test|'' evaluates to
+		true if its contained |test| is false,
+		false if it's true,
+		and unknown if it's unknown.
+
+	* Multiple |test|s connected with ''and'' evaluate to
+		true if <em>all</em> of those |test|s are true,
+		false if <em>any</em> of them are false,
+		and unknown otherwise (i.e. if at least one unknown, but no false).
+
+	* Multiple |test|s connected with ''or'' evaluate to
+		true if <em>any</em> of those |test|s are true,
+		false if <em>all</em> of them are false,
+		and unknown otherwise (i.e. at least one unknown, but no true).
+
+	If a “top-level” <<boolean>> is unknown,
+	and the containing context doesn't otherwise define
+	how to handle unknown conditions,
+	it evaluates to false.
+
+	Note: That is, unknown doesn't “escape” a 3-value boolean expression
+	unless explicitly handled,
+	similar to how <code>NaN</code> doesn't “escape” a [=top-level calculation=]).
+
+
 <!-- Big Text: etc
 
 █████▌ █████▌  ███▌