From 24621fc412811ebfaccc2b10b5b4bb99972fe335 Mon Sep 17 00:00:00 2001 From: Anders Hartvoll Ruud Date: Tue, 2 Jul 2019 10:31:14 +0200 Subject: [PATCH] [css-properties-values-api] Avoid the term 'descriptor'. Using 'descriptor' is very confusing since we're going to introduce @property, which has descriptors in the at-rule sense. Especially "syntax descriptor" is confusing when we're adding an at-rule descriptor named 'syntax'. --- css-properties-values-api/Overview.bs | 80 +++++++++++++-------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/css-properties-values-api/Overview.bs b/css-properties-values-api/Overview.bs index dc568075..84d93552 100644 --- a/css-properties-values-api/Overview.bs +++ b/css-properties-values-api/Overview.bs @@ -67,7 +67,7 @@ Registering custom properties {#registering-custom-properties} ============================================================== 
-dictionary PropertyDescriptor {
+dictionary PropertyDefinition {
 	required DOMString name;
 	         DOMString syntax       = "*";
 	required boolean   inherits;
@@ -75,41 +75,41 @@ dictionary PropertyDescriptor {
 };
 
 partial namespace CSS {
-	void registerProperty(PropertyDescriptor descriptor);
+	void registerProperty(PropertyDefinition definition);
 };
Additional, the {{Document}} object gains a new \[[registeredPropertySet]] private slot, which is a set of records that describe registered custom properties. -The {{PropertyDescriptor}} dictionary {#the-propertydescriptor-dictionary} +The {{PropertyDefinition}} dictionary {#the-propertydefinition-dictionary} -------------------------------------------------------------------------- -A PropertyDescriptor dictionary represents author-specified configuration -options for a custom property. {{PropertyDescriptor}} dictionaries contain the +A PropertyDefinition dictionary represents author-specified configuration +options for a custom property. {{PropertyDefinition}} dictionaries contain the following members: -: name +: name :: The name of the custom property being defined. -: syntax +: syntax :: A string representing how this custom property is parsed. -: inherits +: inherits :: True if this custom property should inherit down the DOM tree; False otherwise. -: initialValue +: initialValue :: The initial value of this custom property. The {{registerProperty()}} function {#the-registerproperty-function} -------------------------------------------------------------------- -The registerProperty(PropertyDescriptor descriptor) method +The registerProperty(PropertyDefinition definition) method registers a custom property according to the configuration options provided in -descriptor. +definition. When it is called, it executes the register a custom property algorithm, -passing the options in its descriptor argument +passing the options in its definition argument as arguments of the same names.
@@ -142,11 +142,11 @@ as arguments of the same names. throw an {{InvalidModificationError}} and exit this algorithm. - 3. Attempt to [=consume a syntax descriptor=] from |syntax|. + 3. Attempt to [=consume a syntax definition=] from |syntax|. If it returns failure, throw a {{SyntaxError}}. - Otherwise, let |syntax descriptor| be the returned syntax descriptor. + Otherwise, let |syntax definition| be the returned syntax definition. - 4. If |syntax descriptor| is the universal syntax descriptor, + 4. If |syntax definition| is the universal syntax definition, and |initialValue| is not present, let |parsed initial value| be empty. This must be treated identically to the "default" initial value of custom properties, @@ -154,7 +154,7 @@ as arguments of the same names. Skip to the next step of this algorithm. Otherwise, - if |syntax descriptor| is the universal syntax descriptor, + if |syntax definition| is the universal syntax definition, [=CSS/parse=] |initialValue| as a <>. If this fails, throw a {{SyntaxError}} @@ -168,8 +168,8 @@ as arguments of the same names. and exit this algorithm. Otherwise, - [=CSS/parse=] {{PropertyDescriptor/initialValue}} - according to |syntax descriptor|. + [=CSS/parse=] {{PropertyDefinition/initialValue}} + according to |syntax definition|. If this fails, throw a {{SyntaxError}} and exit this algorithm. @@ -183,7 +183,7 @@ as arguments of the same names. 6. Let |registered property| be a [=struct=] with a property name of |parsed name|, - a syntax of |syntax descriptor|, + a syntax of |syntax definition|, an initial value of |parsed initial value|, and an inherit flag of |inherit flag|. [=set/Append=] |registered property| @@ -404,11 +404,11 @@ custom property. Syntax strings consists of [=syntax component names=], that are optionally [[#multipliers|multiplied]] and [[#combinator|combined]]. -A syntax string can be parsed into a syntax descriptor, which is either: +A syntax string can be parsed into a syntax definition, which is either: 1. A list of syntax components, each of which accept the value types specified in [[#supported-names]], or - 2. The universal syntax descriptor ('*'), which accepts any valid token + 2. The universal syntax definition ('*'), which accepts any valid token stream. Note: Regardless of the syntax specified, all custom properties accept @@ -498,7 +498,7 @@ corresponding types accepted by the resulting syntax component. equivalent to "<transform-function>+" Note: A syntax string of "*" will produce the - universal syntax descriptor, which is not a syntax component. + universal syntax definition, which is not a syntax component. Therefore, "*" may not be [[#multipliers|multiplied]] or [[#combinator|combined]] with anything else. @@ -529,9 +529,9 @@ The '|' combinator {#combinator} Syntax strings may use U+007C VERTICAL LINE (|) to provide multiple syntax component names. Such syntax strings will result in a -syntax descriptor with multiple syntax components. +syntax definition with multiple syntax components. -When a syntax descriptor with multiple syntax components is used +When a syntax definition with multiple syntax components is used to parse a CSS value, the syntax components are matched in the order specified. Note: That is, given the syntax string "red | <color>", @@ -563,18 +563,18 @@ Parsing the syntax string {#parsing-syntax} :: A sequence of code points which is either a data type name, or a sequence that can produce a <>. -: syntax descriptor +: syntax definition :: An object consisting of a list of syntax components. -: universal syntax descriptor -:: A special descriptor which accepts any valid token stream. +: universal syntax definition +:: A special syntax definition which accepts any valid token stream. -### Consume a syntax descriptor ### {#consume-syntax-descriptor} +### Consume a syntax definition ### {#consume-syntax-definition}
- This section describes how to consume a syntax descriptor from a [=string=] |string|. - It either produces a syntax descriptor - with a list of syntax components, or the universal syntax descriptor. + This section describes how to consume a syntax definition from a [=string=] |string|. + It either produces a syntax definition + with a list of syntax components, or the universal syntax definition. 1. [=Strip leading and trailing ASCII whitespace=] from |string|. @@ -583,23 +583,23 @@ Parsing the syntax string {#parsing-syntax} 3. If |string|’s [=string/length=] is 1, and the only [=code point=] in |string| is U+002A ASTERISK (*), - return the [=universal syntax descriptor=]. + return the [=universal syntax definition=]. 4. Let |stream| be an [=input stream=] created from the [=code points=] of |string|, preprocessed as specified in [[css-syntax-3]]. - Let |descriptor| be an initially empty [=list=] of syntax components. + Let |definition| be an initially empty [=list=] of syntax components. 5. Consume a syntax component from |stream|. If failure was returned, return failure; otherwise, - [=list/append=] the returned value to |descriptor|. + [=list/append=] the returned value to |definition|. Consume as much whitespace as possible from |stream|. Consume the next input code point in |stream|: : EOF - :: return |descriptor|. + :: return |definition|. : U+007C VERTICAL LINE (|) :: Repeat step 5. @@ -776,7 +776,7 @@ Fallbacks in ''var()'' references {#fallbacks-in-var-references} References to registered custom properties using the ''var()'' function may provide a fallback. However, the fallback value must match the -syntax descriptor of the custom property being referenced, otherwise the +syntax definition of the custom property being referenced, otherwise the declaration is invalid at computed-value time. Note: This applies regardless of whether or not the fallback is being used. @@ -827,7 +827,7 @@ The set a CSS declaration algorithm gains an additional constraint for registered custom properties: * The target declaration must have a value that matches the registered - [=syntax descriptor|syntax=] of the property. + [=syntax definition|syntax=] of the property. This means that once a property is registered, it is not possible to use {{setProperty()}} with a value that violates the registered syntax of the @@ -878,12 +878,12 @@ and affects how the custom property calculates its [=computed value=].
To reify a registered custom property value given a property - |property| and [=syntax descriptor=] |syntax|, run these steps: + |property| and [=syntax definition=] |syntax|, run these steps: For specified values: 1. If the value is a <>, and |syntax| is not the - [=universal syntax descriptor=], attempt to [=CSS/parse=] + [=universal syntax definition=], attempt to [=CSS/parse=] the value according to |syntax|. If this succeeds, [=reify=] the result as if it were a computed value, and return that result. 2. Otherwise, [=reify a list of component values=] from the value, and @@ -903,7 +903,7 @@ and affects how the custom property calculates its [=computed value=]. return the result. 5. If the value is an [=identifier=], [=reify an identifier=] from the value and return the result. - 6. If |syntax| is the [=universal syntax descriptor=], + 6. If |syntax| is the [=universal syntax definition=], [=reify a list of component values=] from the value, and return the result. 7. Otherwise, [=reify as a CSSStyleValue=] with the