@@ -53,141 +53,14 @@ They do exactly what they say in their name,
53
53
because they're named exactly the same as the corresponding section of the Syntax spec:
54
54
55
55
* ` parseAStylesheet() `
56
- * ` parseAListOfRules() `
56
+ * ` parseAStylesheetsContents() `
57
+ * ` parseABlocksContents() `
57
58
* ` parseARule() `
58
59
* ` parseADeclaration() `
59
- * ` parseAListOfDeclarations() `
60
60
* ` parseAComponentValue() `
61
61
* ` parseAListOfComponentValues() `
62
62
* ` parseACommaSeparatedListOfComponentValues() `
63
63
64
- Canonicalizing Against A Grammar
65
- --------------------------------
66
-
67
- By default, the parser can only do so much;
68
- it knows how to interpret the top-level rules in a stylesheet,
69
- but not how to interpret the contents of anything below that.
70
- This means that anything nested within a top-level block is left as a bare token stream,
71
- requiring you to call the correct parsing function on it.
72
-
73
- The ` canonicalize() ` function takes a parsing result and a grammar
74
- and transforms the result accordingly,
75
- rendering the result into an easier-to-digest form.
76
-
77
- A grammar is an object with one of the following four forms:
78
-
79
- ``` js
80
- {" stylesheet" : true }
81
- ```
82
-
83
- ``` js
84
- {
85
- " qualified" : < grammar> ,
86
- " @foo" : < grammar> ,
87
- " unknown" : < function >
88
- }
89
- ```
90
-
91
- ```js
92
- {
93
- "declarations": true,
94
- "@foo": <grammar>
95
- "unknown": <function >
96
- }
97
- ```
98
-
99
- ```js
100
- null
101
- ```
102
-
103
- A `stylesheet` block contains nothing else;
104
- it just means that this rule uses the top-level grammar for its contents.
105
- This is true, for example, of the `@media` rule.
106
-
107
- A `qualified` block means that the rule's contents are qualified rules (style rules ) and at-rules.
108
- The "qualified" key must have another grammar as its value (often `{declarations: true }` ).
109
- Any at-rules that are valid in this context must be listed,
110
- also with a grammar for their contents.
111
- Optionally, the "unknown" key can be provided with a function value;
112
- this will be called with any unknown at-rules (ones not listed in the grammar)/
113
- If it returns a truthy value, it's inserted into the structure with everything else;
114
- if falsey, the rule is put into the "errors" entry of the resulting block for later processing or ignoring.
115
-
116
- A ` declarations` block means that the rule's contents are declarations and at-rules.
117
- Currently, the "declarations" key only accepts the value ` true ` ;
118
- eventually it'll allow you to specify what declarations are valid.
119
- Similar to ` qualified` blocks,
120
- you must list what at-rules are allowed,
121
- and can provide an "unknown" function.
122
-
123
- A ` null ` just means that the block has no contents.
124
- This is used for at-rules that are statements,
125
- ended with a semicolon rather than a block,
126
- like ` @import ` .
127
-
128
- A ` CSSGrammar` object is provided with a default grammar for CSS.
129
- If you call ` canonicalize()` without a grammar,
130
- this is used automatically.
131
- This is what it currently looks like:
132
-
133
- ` ` ` js
134
- {
135
- qualified: {declarations: true },
136
- " @media" : {stylesheet: true },
137
- " @keyframes" : {qualified: {declarations: true }},
138
- " @font-face" : {declarations: true },
139
- " @supports" : {stylesheet: true },
140
- " @scope" : {stylesheet: true },
141
- " @counter-style" : {declarations: true },
142
- " @import" : null ,
143
- " @font-feature-values" : {
144
- // No qualified rules actually allowed,
145
- // but have to declare it one way or the other.
146
- qualified: true ,
147
- " @stylistic" : {declarations: true },
148
- " @styleset" : {declarations: true },
149
- " @character-variants" : {declarations: true },
150
- " @swash" : {declarations: true },
151
- " @ornaments" : {declarations: true },
152
- " @annotation" : {declarations: true },
153
- },
154
- " @viewport" : {declarations: true },
155
- " @page" : {
156
- declarations: true ,
157
- " @top-left-corner" : {declarations: true },
158
- " @top-left" : {declarations: true },
159
- " @top-center" : {declarations: true },
160
- " @top-right" : {declarations: true },
161
- " @top-right-corner" : {declarations: true },
162
- " @right-top" : {declarations: true },
163
- " @right-middle" : {declarations: true },
164
- " @right-bottom" : {declarations: true },
165
- " @right-bottom-corner" : {declarations: true },
166
- " @bottom-right" : {declarations: true },
167
- " @bottom-center" : {declarations: true },
168
- " @bottom-left" : {declarations: true },
169
- " @bottom-left-corner" : {declarations: true },
170
- " @left-bottom" : {declarations: true },
171
- " @left-center" : {declarations: true },
172
- " @left-top" : {declarations: true },
173
- },
174
- " @custom-selector" : null ,
175
- " @custom-media" : null
176
- }
177
- ` ` `
178
-
179
- The return value is a nested structure of objects.
180
- Each has a "type" key, set to either "stylesheet", "qualified-rule" or "at-rule".
181
- Unless it's a statement at-rule,
182
- each has a "rules" key set to an array of contained rules/declarations.
183
- At-rules also have a "name" (string) and "prelude" (list of tokens for the part before the block).
184
- Qualified rules have a "declarations",
185
- which is an object mapping declaration name to value (list of tokens),
186
- for ease of use
187
- (all the declarations are in the ` .rules ` property already,
188
- but this gives you easy access to them by name,
189
- and only stores the last of each if they're repeated).
190
-
191
64
Node Integration
192
65
----------------
193
66
0 commit comments