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
And this is a normal paragraph. This is # not a header.

The above Idyll syntax would look like the following when in ast form:

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

"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

idyll-ast~appendNode ⇒ object

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 |

idyll-ast~appendNodes ⇒ 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 |

idyll-ast~createNode ⇒ object

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

idyll-ast~createTextNode ⇒

Function to create a new textnode

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

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

idyll-ast~getChildren ⇒ Array.<object>

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 |

idyll-ast~setChildren ⇒ object

Function to set children of the passed node.

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

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

idyll-ast~getNodesByName ⇒ Array.<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 |

idyll-ast~getNodesByType ⇒ Array.<object>

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 |

idyll-ast~hasType ⇒ boolean

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 |

idyll-ast~getType ⇒ string

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 |

idyll-ast~getText ⇒ string

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 |

idyll-ast~filterNodes ⇒ Array.<object>

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 |

idyll-ast~modifyChildren ⇒ object

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 |

idyll-ast~filterChildren ⇒ object

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 |

idyll-ast~modifyNodesByName ⇒ object

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 |

idyll-ast~handleNodeByName ⇒ object

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 |

idyll-ast~getNodeName ⇒ string

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 |

idyll-ast~getPropertyKeys ⇒ Array.<string>

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 |

idyll-ast~getProperty ⇒

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 |

idyll-ast~getProperties ⇒ object

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

idyll-ast~getPropertiesByType ⇒ Array.<object>

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 |

idyll-ast~prependNode ⇒ object

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 |

idyll-ast~prependNodes ⇒ 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> |

idyll-ast~removeNodesByName

Function remove node with a particular name from the ast

Kind: inner property of idyll-ast

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

idyll-ast~removeNodesByType

Function remove node with a particular name from the ast

Kind: inner property of idyll-ast

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

idyll-ast~removeProperties ⇒ object

Function to remove a property from a node

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

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

idyll-ast~setProperty ⇒ object

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

idyll-ast~setProperties ⇒ object

Function to add multiple properties to a node

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

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

idyll-ast~walkNodes

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

idyll-ast~walkNodeBreadthFirst

Function to breadth-first traversal on the AST.

Kind: inner property of idyll-ast

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

idyll-ast~toMarkup ⇒ string

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 |