idyll-ast

Utilities for manipulating Idyll's AST

Usage no npm install needed!

<script type="module">
  import idyllAst from 'https://cdn.skypack.dev/idyll-ast';
</script>

README

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

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 modify 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~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~toMarkup ⇒ string

Function to convert an AST back into idyll markup

Kind: inner property of idyll-ast Returns: string - markup string

Param Type
node 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