Skip to content

Commit c7859c4

Browse files
authored
Various improvements of the code (#53)
1 parent 4b8b861 commit c7859c4

File tree

7 files changed

+3318
-2204
lines changed

7 files changed

+3318
-2204
lines changed

.gitattributes

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.gitattributes text
2+
.gitignore text
3+
*.html text
4+
*.js text
5+
*.json text
6+
*.md text

README.md

Lines changed: 2 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -53,141 +53,14 @@ They do exactly what they say in their name,
5353
because they're named exactly the same as the corresponding section of the Syntax spec:
5454

5555
* `parseAStylesheet()`
56-
* `parseAListOfRules()`
56+
* `parseAStylesheetsContents()`
57+
* `parseABlocksContents()`
5758
* `parseARule()`
5859
* `parseADeclaration()`
59-
* `parseAListOfDeclarations()`
6060
* `parseAComponentValue()`
6161
* `parseAListOfComponentValues()`
6262
* `parseACommaSeparatedListOfComponentValues()`
6363

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-
19164
Node Integration
19265
----------------
19366

0 commit comments

Comments
 (0)