utils.md 3.75 KB
Newer Older
liang ce committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
# Utils to work with AST

<!-- MarkdownTOC -->

- [property\(name\)](#propertyname)
- [keyword\(name\)](#keywordname)
- [clone\(ast\)](#cloneast)
- [fromPlainObject\(object\)](#fromplainobjectobject)
- [toPlainObject\(ast\)](#toplainobjectast)

<!-- /MarkdownTOC -->

## property(name)

Returns details for a property name, such as vendor prefix, used hack etc. Using for safe test of declaration property names, i.e. `Declaration.property`.

```js
var csstree = require('css-tree');

csstree.property('*-vendor-property');
// {
//     basename: 'property',
//     name: '-vendor-property',
//     hack: '*',
//     vendor: '-vendor-',
//     prefix: '*-vendor-',
//     custom: false
// }

csstree.property('--test-var');
// {
//     basename: '--test-var',
//     name: '--test-var',
//     hack: '',
//     vendor: '',
//     prefix: '',
//     custom: true
// };
```

`property()` function normalizes a name to lower case, except custom property names since they are case sensitive. It returns the same immutable (freezed) object for the same input (input after normalization).

```js
csstree.property('name') === csstree.property('NAME')         // true
csstree.property('NAME').name === 'name'                      // true
csstree.property('--custom') === csstree.property('--Custom') // false

var info = csstree.property('NAME');
info.name === 'name'; // 
info.name = 'foo';    // have no effect
info.name === 'name'; // true
```

Supported hacks:

- `_` in the beginning
- `+` in the beginning
- `#` in the beginning
- `*` in the beginning
- `$` in the beginning
- `/` in the beginning
- `//` in the beginning

## keyword(name)

Mostly the same as `property()` function, but without hack detection. Using for any identifier except declaration property name.

```js
var csstree = require('css-tree');

csstree.keyword('-vendor-keyword');
// {
//     basename: 'keyword',
//     name: '-vendor-keyword',
//     vendor: '-vendor-',
//     prefix: '-vendor-',
//     custom: false
// };
```

## clone(ast)

Make AST deep copy.

```js
var orig = csstree.parse('.test { color: red }');
var copy = csstree.clone(orig);

csstree.walk(copy, function(node) {
    if (node.type === 'Class') {
        node.name = 'replaced';
    }
});

console.log(csstree.generate(orig));
// .test{color:red}
console.log(csstree.generate(copy));
// .replaced{color:red}
```

## fromPlainObject(object)

`fromPlainObject()` walks through AST and coverts each `children` value into a `List` instance when value is an array.

```js
var csstree = require('css-tree');
var ast = {
    type: 'SelectorList',
    children: []
};

console.log(Array.isArray(ast.children));          // true
console.log(ast.children instanceof csstree.List); // false

ast = csstree.fromPlainObject(ast);

console.log(Array.isArray(ast.children));          // false
console.log(ast.children instanceof csstree.List); // true
```

Function mutates the passed AST. Use `clone()` function before passing AST to `fromPlainObject()` in case you want to avoid original tree mutation.

```js
astClone = csstree.fromPlainObject(csstree.clone(ast));
```

## toPlainObject(ast)

`fromPlainObject()` walks through AST and coverts each `children` value to regular array when value is a `List` instance.

```js
var csstree = require('css-tree');
var ast = {
    type: 'SelectorList',
    children: new List()
};

console.log(Array.isArray(ast.children));          // false
console.log(ast.children instanceof csstree.List); // true

ast = csstree.toPlainObject(ast);

console.log(Array.isArray(ast.children));          // true
console.log(ast.children instanceof csstree.List); // false
```

Function mutates the passed AST. Use `clone()` function before passing AST to `toPlainObject()` in case you want to avoid original tree mutation.

```js
ast = csstree.toPlainObject(csstree.clone(ast));
```