node package manager

trowel

ECMAScript parsing utility

Trowel is an under-construction Ecmascript5 interpreter written in TypeScript

Current Keywords: lexer, parser, lex, syntax, ecmascript, javascript, ast

Bibliography: EcmaScript5, Mozilla SpiderMonkey Parser API


Trowel is splitted in three architectural components. The components compose a chain by giving the output to the next component. Each component can be used separately from the others, providing a variety of language utility applications.

  1. The lexical phase recognise the tokens of the Ecmascript5 definition, and marks the type of the token.

  2. The syntax phase recognise the syntax of the language. The result of this phase is an Abstract Syntax Tree (AST) that embodies the nodes of the structure.

  3. The last phase is the interpreter. The interpreter will evaluate the the frontend's structure and will execute it in its context.

The lexer and the parser are known as the frontend part of the Javascript Engine and the intepreter is the backend.

Usually there is an intermediate structure between the frontend and the backend, but to simplify the procedure we are planning to execute directly the AST by traversing it.

  1. lexical phase (finished)
  2. syntax phase (finished)
  3. run-time (working on it)

Documentation

In order to build the application the following tools are required: node.js, npm, bower, gulp, and tsd

For bower, gulp and tsd you'll need to execute:

npm install -g gulp
npm install -g bower
npm install -g tsd

Run the following commands in the project root:

  1. npm install
  2. bower install
  3. tsd install
  4. gulp

the gulp command will automatically build the JavaScript and run the tests.

gulp build-js

gulp test

Trowel is full compatible on all the web browsers, Rhino, Node.js and most of the wellknown javascript runtime enviroments (jscc).

Trowel has dependency on underscore

<script src="trowel.js"></script>
<!-- exported variable: trowel, trl -->
require(['trowel'], function (trowel) {
 
});
var trowel = require('trowel');
load('/path/to/trowel.js');
// exported variable: trowel, trl

trowel.frontend.api.parse

trowel.frontend.api.parse(sourceCode, ?options);

Takes as argument an Ecmascript5 source code string and yields an Object that contains:

  1. program: The ast of the source code as defined in MDN
  2. exceptions: array of exceptions, in case of parse errors

More Information

var programNode = trowel.frontend.api.parse("HelloWorld = true", { loc: true });
console.log(JSON.stringify(programNode, undefined, 4));
 
{
    "program": {
        "type": "Program",
        "body": [
            {
                "type": "ExpressionStatement",
                "expression": {
                    "type": "AssignmentExpression",
                    "operator": "=",
                    "left": {
                        "type": "Identifier",
                        "name": "HelloWorld",
                        "loc": {
                            "start": {
                                "line": 1,
                                "column": 0
                            },
                            "end": {
                                "line": 1,
                                "column": 10
                            }
                        }
                    },
                    "right": {
                        "type": "Literal",
                        "value": true,
                        "loc": {
                            "start": {
                                "line": 1,
                                "column": 13
                            },
                            "end": {
                                "line": 1,
                                "column": 17
                            }
                        }
                    },
                    "loc": {
                        "start": {
                            "line": 1,
                            "column": 0
                        },
                        "end": {
                            "line": 1,
                            "column": 17
                        }
                    }
                },
                "loc": {
                    "start": {
                        "line": 1,
                        "column": 0
                    },
                    "end": {
                        "line": 1,
                        "column": 17
                    }
                }
            }
        ],
        "loc": {
            "start": {
                "line": 1,
                "column": 0
            },
            "end": {
                "line": 1,
                "column": 17
            }
        }
    }
}

trowel.frontend.api.tokenize

trowel.frontend.api.tokenize(sourceCode, ?options);

Takes as argument an Ecmascript5 source code string and yields an Object that contains:

  1. tokens: array of tokens
  2. exceptions: array of exceptions, in case of parse error

More Information

var tokens = trowel.frontend.api.tokenize("HelloWorld = true", { loc: true });
console.log(JSON.stringify(tokens, undefined, 4));
// result of console log: 
{
    "tokens": [
        {
            "type": "identifier",
            "value": "HelloWorld",
            "loc": {
                "start": {
                    "line": 1,
                    "column": 0
                },
                "end": {
                    "line": 1,
                    "column": 10
                }
            }
        },
        {
            "type": "punctuation",
            "value": "=",
            "loc": {
                "start": {
                    "line": 1,
                    "column": 11
                },
                "end": {
                    "line": 1,
                    "column": 12
                }
            }
        },
        {
            "type": "literal",
            "value": true,
            "subType": "boolean",
            "loc": {
                "start": {
                    "line": 1,
                    "column": 13
                },
                "end": {
                    "line": 1,
                    "column": 17
                }
            }
        }
    ]
}