Utilities for manipulating Idyll's AST
npm install idyll-astidyll-ast is a library that defines the Abstract Syntax Tree used for Idyll. It is a JSON based AST,
and the structure is defined by this schema.
You can install idyll-ast by both npm and yarn.
``
//using npm
npm install --save idyll-ast
//using yarn
yarn add idyll-ast
`
We recommend using --save to add all the dependencies required for idyll-ast to your package.json file.
The ast structure used, is defined by JSON schema (Draft-6), and the current schema is at src/ast.schema.json.
Let's take a look at an example:
`This is a header
And this is a normal paragraph. This is # not a header.
`
The above Idyll syntax would look like the following when in ast form:
`js`
{ id: 0,
type: 'component',
name: 'div',
children:
[ { id: 2,
type: 'component',
name: 'TextContainer',
children:
[ { id: 3,
type: 'component',
name: 'h2',
children: [ { id: 4, type: 'textnode', value: 'This is a header' } ] },
{ id: 5,
type: 'component',
name: 'p',
children:
[ { id: 6,
type: 'textnode',
value: 'And this is a normal paragraph. This is # not a header.' } ] } ] } ] }
All the data in the tree is encapsulated by the node called root. All the top-level components in the document are considered the children of the root.
There can be 5 different types of nodes in the AST.
1. component : Represents an Idyll component.
2. textnode: Represents an Idyll textnode.
3. var: Represents a variable declaration in Idyll.
4. derive: Represents a derived variable. In Idyll, it represents a variable whose value is derived from other variables.
5. data: Represents a dataset in Idyll. In Idyll, datasets act like variables, but instead of value, they have a source field.
The properties field for each component represent, its attributes or value. The general structure for a properties field is as following:
`json
"properties" : {
"prop1": {
"type": "type1",
"value": "value1"
},
"prop2": {
"type": "type2",
"value" : "value2"
}
}
`
The type field can take 3 different values.
1. value: This type field will evaluate the value field as the given property's value.type
2. variable: This field will evaluate the value field as the given property's variables declaration.type
3. expression: This field will evaluate the value field as the given property's expression syntax.
Also, the property key should match the pattern: /[^+\-0-9:\s\/\]"'\.][^:\s\/\]"'\.]*/ `
The children field is an array that contains all the child nodes of a node.
Only component nodes can have any children. textnodes, var, derive and data nodes should not have any children.
- idyll-ast
- ~appendNode ⇒ object
- ~appendNodes ⇒ object
- ~createNode ⇒ object
- ~createTextNode ⇒
- ~getChildren ⇒ Array.<object>
- ~setChildren ⇒ object
- ~getNodesByName ⇒ Array.<object>
- ~getNodesByType ⇒ Array.<object>
- ~hasType ⇒ boolean
- ~getType ⇒ string
- ~getText ⇒ string
- ~filterNodes ⇒ Array.<object>
- ~modifyChildren ⇒ object
- ~filterChildren ⇒ object
- ~modifyNodesByName ⇒ object
- ~handleNodeByName ⇒ object
- ~getNodeName ⇒ string
- ~getPropertyKeys ⇒ Array.<string>
- ~getProperty ⇒
- ~getProperties ⇒ object
- ~getPropertiesByType ⇒ Array.<object>
- ~prependNode ⇒ object
- ~prependNodes ⇒ object
- ~removeNodesByName
- ~removeNodesByType
- ~removeProperties ⇒ object
- ~setProperty ⇒ object
- ~setProperties ⇒ object
- ~walkNodes
- ~walkNodeBreadthFirst
- ~toMarkup ⇒ string
Function to append a top-level child to the root element.
Kind: inner property of idyll-ast
Returns: object - Modifed ast node
| Param | Type | Description |
| ----- | ------------------- | ----------- |
| ast | object | JSON-object |
| node | object | JSON-object |
Function to append multiple top-level children to the root element.
Kind: inner property of idyll-ast
Returns: object - modified ast
| Param | Type | Description |
| ----- | --------------------------------- | ------------------------ |
| ast | oject | JSON-object |
| node | Array.<object> | an array of JSON-objects |
Function to create a new AST node following the schema.
Kind: inner property of idyll-ast
Returns: object - New component node.
| Param | Type | Description |
| -------- | --------------------------------- | ---------------------------- |
| id | integer | Id of the node |
| name | string | Name of the node. |
| type | string | Type of the node. |
| value | string | Value evaluation of the node |
| props | Array.<object> | Properties of the node. |
| children | Array.<object> | Children of the node. |
Function to create a new textnode
Kind: inner property of idyll-ast
Returns: New textnode
| Param | Type |
| ----- | --------------- |
| id | \* |
| value | \* |
Function to return the children of the passed node.
Kind: inner property of idyll-ast
Returns: Array.<object> - children of the node
| Param | Type | Description |
| ----- | ------------------- | ----------- |
| node | object | AST node |
Function to set children of the passed node.
Kind: inner property of idyll-ast
Returns: object - modified node
| Param | Type |
| -------- | ------------------- |
| node | object |
| children | object |
Function to get all the nodes with the passed name in the passed AST.
Kind: inner property of idyll-ast
Returns: Array.<object> - Array of nodes matching the name
| Param | Type | Description |
| ----- | ------------------- | ----------------- |
| ast | object | AST object |
| name | string | name of the nodes |
Function to get all the nodes with the passed type in the passed AST.
Kind: inner property of idyll-ast
Returns: Array.<object> - Array of nodes matching the type
| Param | Type | Description |
| ----- | ------------------- | ----------------- |
| ast | object | AST object |
| type | string | type of the nodes |
Function to check if a node has type attribute or not
Kind: inner property of idyll-ast
Returns: boolean - true if type exists, false otherwise
| Param | Type |
| ----- | ------------------- |
| node | object |
Function to get the type information of a node
Kind: inner property of idyll-ast
Returns: string - type of the node
| Param | Type | Description |
| ----- | ------------------- | ----------- |
| ast | object | AST object |
Function to get all the text from textnodes from the passed AST node
Kind: inner property of idyll-ast
| Param | Type | Description |
| ----- | ------------------- | ----------- |
| ast | object | AST node |
Function to find certain nodes based on a filter passed.
Kind: inner property of idyll-ast
Returns: Array.<object> - Array of all the nodes found
| Param | Type | Description |
| ------ | --------------------- | ----------------------------- |
| ast | object | AST node |
| filter | function | Filter function to find nodes |
Function to modify children of a passed AST node using a passed modifier.
Kind: inner property of idyll-ast
Returns: object - node with modified children.
| Param | Type |
| -------- | --------------------- |
| node | object |
| modifier | function |
Function to pass in a filter function to the children.
Kind: inner property of idyll-ast
Returns: object - node with modified children
| Param | Type | Description |
| ------ | --------------------- | --------------- |
| node | object | AST node |
| filter | function | Filter function |
Function to modiy nodes based on the name property.
Kind: inner property of idyll-ast
Returns: object - ast
| Param | Type |
| -------- | --------------------- |
| ast | object |
| name | string |
| modifier | function |
Function to modify a single node using a modifier and name property.
Kind: inner property of idyll-ast
Returns: object - if node.name = name then modifier(node), else node.
| Param | Type |
| -------- | --------------------- |
| node | Object |
| name | string |
| modifier | function |
Function to get the name of a component
Kind: inner property of idyll-ast
Returns: string - name of the passed node
| Param | Type |
| ----- | ------------------- |
| node | object |
Function to return a the list of property keys of a node
Kind: inner property of idyll-ast
Returns: Array.<string> - keys
| Param | Type |
| ----- | ------------------- |
| node | object |
Getter function to a return a specific property of a node based on a key.
Kind: inner property of idyll-ast
Returns: null, if the property does not exist, else property.data.
| Param | Type |
| ----- | ------------------- |
| node | object |
| key | string |
Function to return all the properties of a given node.
Kind: inner property of idyll-ast
Returns: object - properties of the node, or null if none exists,
| Param | Type |
| ----- | --------------- |
| node | \* |
Function to get properties of a particular type of a given node.
Kind: inner property of idyll-ast
Returns: Array.<object> - Array of properties if they exists, or an empty array of no properties of the given type exists.
| Param | Type |
| ----- | ------------------- |
| node | object |
| type | string |
Function to prepend a node in the children array of root.
Kind: inner property of idyll-ast
Returns: object - modfied ast.
| Param | Type |
| ----- | ------------------- |
| ast | object |
| node | object |
Function to prepend multiple nodes in the children array of root.
Kind: inner property of idyll-ast
Returns: object - modfied ast.
| Param | Type |
| ----- | --------------------------------- |
| ast | object |
| nodes | Array.<object> |
Function remove node with a particular name from the ast
Kind: inner property of idyll-ast
| Param | Type |
| ----- | --------------- |
| ast | \* |
| name | \* |
Function remove node with a particular name from the ast
Kind: inner property of idyll-ast
| Param | Type |
| ----- | --------------- |
| ast | \* |
| type | \* |
Function to remove a property from a node
Kind: inner property of idyll-ast
Returns: object - Modified node
| Param | Type |
| ----- | ------------------- |
| node | object |
| key | string |
Function to add a property to a node or change the value if the property already exists.
Kind: inner property of idyll-ast
Returns: object - Modfied Node
| Param | Type |
| ----- | --------------- |
| node | \* |
| name | \* |
| data | \* |
Function to add multiple properties to a node
Kind: inner property of idyll-ast
Returns: object - Modified node
| Param | Type |
| ---------- | ------------------- |
| node | object |
| properties | object |
Function to do a depth-first traversal of the AST.
Kind: inner property of idyll-ast
| Param | Type | Description |
| ----- | --------------------- | -------------------------------- |
| ast | object | AST node |
| f | function | callback function for each node. |
Function to breadth-first traversal on the AST.
Kind: inner property of idyll-ast
| Param | Type |
| ----- | --------------------- |
| ast | object |
| f | function |
Function to convert AST back to idyll markup
Kind: inner property of idyll-ast
Returns: string - Markup string
| Param | Type | Description |
| ----- | ------------------- | ----------- |
| ast | object | AST node |