77 lines
3.6 KiB
Plaintext
77 lines
3.6 KiB
Plaintext
|
# Emmet markup abbreviation parser
|
|||
|
|
|
|||
|
|
Parses given Emmet *markup* abbreviation into AST. Parsing is performed in two steps: first it tokenizes given abbreviation (useful for syntax highlighting in editors) and then tokens are analyzed and converted into AST nodes as plain, JSON-serializable objects.
|
|||
|
|
|
|||
|
|
Note that AST tree in most cases cannot be used directly for output: for example, AST node produced from `.foo.bar` element misses element name and contains two `class` attributes with `foo` and `bar` values (not a single `class` with `foo bar` value).
|
|||
|
|
|
|||
|
|
## Usage
|
|||
|
|
|
|||
|
|
You can install it via npm:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npm install @emmetio/abbreviation
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Then add it into your project:
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
import parse from '@emmetio/abbreviation';
|
|||
|
|
|
|||
|
|
const tree = parse('div#foo>span.bar*3');
|
|||
|
|
/* {
|
|||
|
|
type: 'Abbreviation',
|
|||
|
|
children: [{
|
|||
|
|
type: 'AbbreviationNode',
|
|||
|
|
name: 'div',
|
|||
|
|
attributes: [...],
|
|||
|
|
children: [...]
|
|||
|
|
}]
|
|||
|
|
} */
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
The returned tree contains `AbbreviationNode` items: a node with name, attributes and/or text content. E.g. an element that can be represented somehow. Repeated and grouped nodes like `a>(b+c)*3` are automatically converted and duplicated as distinct `AbbreviationNode` with distinct `.repeat` property which identifies node in repeating sequence.
|
|||
|
|
|
|||
|
|
## Abbreviation syntax
|
|||
|
|
|
|||
|
|
Emmet abbreviation element has the following basic parts:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
name.class#id[attributes?, ...]{text value}*repeater/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
* `name` — element name, like `div`, `span` etc. Stored as `node.name` property.
|
|||
|
|
* `[attributes]` — list of attributes. Each attribute is stored as [`AbbreviationAttribute`](/src/types.ts) instance and can be accessed by `node.getAttribute(name)`. Each attribute can be written in different formats:
|
|||
|
|
* `attr` — attribute with empty value.
|
|||
|
|
* `attr=value` — attribute with value. The `value` may contain any character except space or `]`.
|
|||
|
|
* `attr="value"` or `attr='value'` — attribute with value in quotes. Quotes are automatically removed. Expression values like `attr={value}` are supported and can be identified by `valueType: "expression"` property.
|
|||
|
|
* `attr.` — boolean attribute, e.g. attribute without value, like `required` in `<input>`.
|
|||
|
|
* `!attr` – implicit attribute, will be outputted if its value is not empty. Used as a placeholder to preserve attribute order in output.
|
|||
|
|
* `./non/attr/value` — value for default attribute. In other words, anything that doesn’t match a attribute name characters. Can be a single- or double-quotted as well. Default attribute is stored with `null` as name and should be used later, for example, to resolve predefined attributes.
|
|||
|
|
* `.class` — shorthand for `class` attribute. Note that an element can have multiple classes, like `.class1.class2.class3`.
|
|||
|
|
* `#id` — shorthand for `id` attribute.
|
|||
|
|
* `{text}` — node’s text content
|
|||
|
|
* `*N` — element repeater, tells parser to create `N` copies of given node.
|
|||
|
|
* `/` — optional self-closing operator. Marks element with `node.selfClosing = true`.
|
|||
|
|
|
|||
|
|
### Operators
|
|||
|
|
|
|||
|
|
Each element of abbreviation must be separated with any of these operators:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
elem1+elem2>elem3
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
* `+` — sibling operator, adds next element as a next sibling of current element in tree.
|
|||
|
|
* `>` — child operator, adds next element as a child of current element.
|
|||
|
|
* `^` — climb-up operator, adds next element as a child of current element’s parent node. Multiple climb-up operators are allowed, each operator moves one level up by tree.
|
|||
|
|
|
|||
|
|
### Groups
|
|||
|
|
|
|||
|
|
A set of elements could be grouped using `()`, mostly for repeating and for easier elements nesting:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
a>(b>c+d)*4+(e+f)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Groups can be optionally concatenated with `+` operator.
|