What is idyll-ast?

idyll-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.

Getting Started

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.

Structure

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

`

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.

Type of Nodes

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.

Properties

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.
2. variable: This type field will evaluate the value field as the given property's variables declaration.
3. expression: This type 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\/\]"'\.]*/ `

Children

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.

API

- 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

$3

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 |

$3

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 |

$3

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. |

$3

Function to create a new textnode

Kind: inner property of idyll-ast
Returns: New textnode

| Param | Type |
| ----- | --------------- |
| id | \* |
| value | \* |

$3

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 |

$3

Function to set children of the passed node.

Kind: inner property of idyll-ast
Returns: object - modified node

| Param | Type |
| -------- | ------------------- |
| node | object |
| children | object |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

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 | \* |

$3

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 |

$3

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 |

$3

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> |

$3

Function remove node with a particular name from the ast

Kind: inner property of idyll-ast

| Param | Type |
| ----- | --------------- |
| ast | \* |
| name | \* |

$3

Function remove node with a particular name from the ast

Kind: inner property of idyll-ast

| Param | Type |
| ----- | --------------- |
| ast | \* |
| type | \* |

$3

Function to remove a property from a node

Kind: inner property of idyll-ast
Returns: object - Modified node

| Param | Type |
| ----- | ------------------- |
| node | object |
| key | string |

$3

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 | \* |

$3

Function to add multiple properties to a node

Kind: inner property of idyll-ast
Returns: object - Modified node

| Param | Type |
| ---------- | ------------------- |
| node | object |
| properties | object |

$3

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. |

$3

Function to breadth-first traversal on the AST.

Kind: inner property of idyll-ast

| Param | Type |
| ----- | --------------------- |
| ast | object |
| f | function |

$3

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 |