idyll-ast

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