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.
- component : Represents an Idyll component.
- textnode: Represents an Idyll textnode.
- var: Represents a variable declaration in Idyll.
- derive: Represents a derived variable. In Idyll, it represents a variable whose value is derived from other variables.
-
data: Represents a dataset in Idyll. In Idyll, datasets act like variables, but instead of
value
, they have asource
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.
-
value: This
type
field will evaluate thevalue
field as the given property's value. -
variable: This
type
field will evaluate thevalue
field as the given property's variables declaration. -
expression: This
type
field will evaluate thevalue
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
-
~appendNode ⇒
object
idyll-ast~appendNode ⇒ 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 |
object
idyll-ast~appendNodes ⇒ 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 |
object
idyll-ast~createNode ⇒ 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 | * |
Array.<object>
idyll-ast~getChildren ⇒ 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 |
object
idyll-ast~setChildren ⇒ Function to set children of the passed node.
Kind: inner property of idyll-ast
Returns: object
- modified node
Param | Type |
---|---|
node | object |
children | object |
Array.<object>
idyll-ast~getNodesByName ⇒ 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 |
Array.<object>
idyll-ast~getNodesByType ⇒ 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 |
boolean
idyll-ast~hasType ⇒ 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 |
string
idyll-ast~getType ⇒ 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 |
string
idyll-ast~getText ⇒ 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 |
Array.<object>
idyll-ast~filterNodes ⇒ 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 |
object
idyll-ast~modifyChildren ⇒ 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 |
object
idyll-ast~filterChildren ⇒ 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 |
object
idyll-ast~modifyNodesByName ⇒ 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 |
object
idyll-ast~handleNodeByName ⇒ 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 |
string
idyll-ast~getNodeName ⇒ 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 |
Array.<string>
idyll-ast~getPropertyKeys ⇒ 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 |
object
idyll-ast~getProperties ⇒ 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 | * |
Array.<object>
idyll-ast~getPropertiesByType ⇒ 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 |
object
idyll-ast~prependNode ⇒ 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 |
object
idyll-ast~prependNodes ⇒ 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 | * |
object
idyll-ast~removeProperties ⇒ Function to remove a property from a node
Kind: inner property of idyll-ast
Returns: object
- Modified node
Param | Type |
---|---|
node | object |
key | string |
object
idyll-ast~setProperty ⇒ 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 | * |
object
idyll-ast~setProperties ⇒ 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 |
string
idyll-ast~toMarkup ⇒ 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 |