• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..--

HISTORY.mdD24-Sep-202366 53

LICENSED24-Sep-20231 KiB1916

README.mdD24-Sep-20234.8 KiB139103

index.jsD24-Sep-20232.9 KiB113103

package.jsonD24-Sep-2023463 2322

README.md

1# pug-walk
2
3Walk and transform a Pug AST
4
5[![Build Status](https://img.shields.io/travis/pugjs/pug-walk/master.svg)](https://travis-ci.org/pugjs/pug-walk)
6[![Dependencies Status](https://david-dm.org/pugjs/pug/status.svg?path=packages/pug-walk)](https://david-dm.org/pugjs/pug?path=packages/pug-walk)
7[![DevDependencies Status](https://david-dm.org/pugjs/pug/dev-status.svg?path=packages/pug-walk)](https://david-dm.org/pugjs/pug?path=packages/pug-walk&type=dev)
8[![npm version](https://img.shields.io/npm/v/pug-walk.svg)](https://www.npmjs.org/package/pug-walk)
9[![Coverage Status](https://img.shields.io/codecov/c/github/pugjs/pug-walk/master.svg)](https://codecov.io/gh/pugjs/pug-walk/branch/master)
10
11## Installation
12
13    npm install pug-walk
14
15## Usage
16
17```js
18var walk = require('pug-walk');
19```
20
21### `walk(ast, before, after, options)`
22
23Traverse and optionally transform a [Pug AST](https://github.com/pugjs/pug-ast-spec).
24
25`ast` is not cloned, so any changes done to it will be done directly on the AST provided.
26
27`before` and `after` are functions with the signature `(node, replace)`. `before` is called when a node is first seen, while `after` is called after the children of the node (if any) have already been traversed.
28
29The `replace` parameter is a function that can be used to replace the node in the AST. It takes either an object or an array as its only parameter. If an object is specified, the current node is replaced by the parameter in the AST. If an array is specified and the ancestor of the current node allows such an operation, the node is replaced by all of the nodes in the specified array. This way, you can remove and add new nodes adjacent to the current node. Whether the parent node allows array operation is indicated by the property `replace.arrayAllowed`, which is set to true when the parent is a Block and when the parent is a Include and the node is an IncludeFilter.
30
31If `before` returns `false`, the children of this node will not be traversed and left unchanged (unless `replace` has been called). Otherwise, the returned value of `before` is ignored. The returned value of `after` is always ignored. If `replace()` is called in `before()` with an array, and `before()` does not return `false`, the nodes in the array are still descended.
32
33`options` can contain the following properties:
34
35* `includeDependencies` (boolean): Walk the AST of a loaded dependent file (i.e., includes and extends). Defaults to `false`.
36* `parents` (array<Node>): Nodes that are ancestors to the current `ast`. This option is used mainly internally, and users usually do not have to specify it. Defaults to `[]`.
37
38```js
39var lex = require('pug-lexer');
40var parse = require('pug-parser');
41
42// Changing content of all Text nodes
43// ==================================
44
45var source = '.my-class foo';
46var dest = '.my-class bar';
47
48var ast = parse(lex(source));
49
50ast = walk(ast, function before(node, replace) {
51  if (node.type === 'Text') {
52    node.val = 'bar';
53
54    // Alternatively, you can replace the entire node
55    // rather than just the text.
56    // replace({ type: 'Text', val: 'bar', line: node.line });
57  }
58}, {
59  includeDependencies: true
60});
61
62assert.deepEqual(parse(lex(dest)), ast);
63
64// Convert all simple <strong> elements to text
65// ============================================
66
67var source = 'p abc #[strong NO]\nstrong on its own line';
68var dest = 'p abc #[| NO]\n| on its own line';
69
70var ast = parse(lex(source));
71
72ast = walk(ast, function before(node, replace) {
73  // Find all <strong> tags
74  if (node.type === 'Tag' && node.name === 'strong') {
75    var children = node.block.nodes;
76
77    // Make sure that the Tag only has one child -- the text
78    if (children.length === 1 && children[0].type === 'Text') {
79      // Replace the Tag with the Text
80      replace({ type: 'Text', val: children[0].val, line: node.line });
81    }
82  }
83}, {
84  includeDependencies: true
85});
86
87assert.deepEqual(parse(lex(dest)), ast);
88
89// Flatten blocks
90// ==============
91
92var ast = {
93  type: 'Block',
94  nodes: [
95    { type: 'Text', val: 'a' },
96    {
97      type: 'Block',
98      nodes: [
99        { type: 'Text', val: 'b' },
100        {
101          type: 'Block',
102          nodes: [ { type: 'Text', val: 'c' } ]
103        },
104        { type: 'Text', val: 'd' }
105      ]
106    },
107    { type: 'Text', val: 'e' }
108  ]
109};
110
111var dest = {
112  type: 'Block',
113  nodes: [
114    { type: 'Text', val: 'a' },
115    { type: 'Text', val: 'b' },
116    { type: 'Text', val: 'c' },
117    { type: 'Text', val: 'd' },
118    { type: 'Text', val: 'e' }
119  ]
120};
121
122// We need to use `after` handler instead of `before`
123// handler because we want to flatten the innermost
124// blocks first before proceeding onto outer blocks.
125
126ast = walk(ast, null, function after(node, replace) {
127  if (node.type === 'Block' && replace.arrayAllowed) {
128    // Replace the block with its contents
129    replace(node.nodes);
130  }
131});
132
133assert.deepEqual(dest, ast);
134```
135
136## License
137
138  MIT
139