..

Author: asgerf

lib/parsejs.dart

@@ -12,9 +12,13 @@ export 'src/lexer.dart' show ParseError;
 /// Parse [text] as a JavaScript program and return its AST.
 /// 
 /// Options:
-/// - [filename]: an string indicating where the source came from (this string has no special syntax or meaning).
+/// 
+/// - [filename]: a string indicating where the source came from (this string has no special syntax or meaning).
+/// 
 /// - [firstLine]: line number to associate with the first line of code.
+/// 
 /// - [handleNoise]: tolerate noise, such as hash bangs (#!) and HTML comment markers (<!--,-->) (default: true).
+/// 
 /// - [annotations]: if true, [Node.parent], [Scope.environment], and [Name.scope] will be initialized (default: true).
 Program parsejs(String text, {String filename, int firstLine : 1, bool handleNoise : true, bool annotations : true}) {
   Offsets offset = new Offsets(0, text.length, firstLine);

lib/src/ast.dart

@@ -5,10 +5,14 @@ part 'ast_visitor.dart';
 // AST structure mostly designed after the Mozilla Parser API:
 //  https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Parser_API
 
+/// A node in the abstract syntax tree of a JavaScript program.
 abstract class Node {
+  /// The parent of this node, or null if this is the [Program] node.
+  /// 
+  /// If you transform the AST in any way, it is your own responsibility to update pointer pointers accordingly.
   Node parent;
 
-  /// Source-code offsets.
+  /// Source-code offset.
   int start, end;
 
   /// 1-based line number. 
@@ -51,11 +55,17 @@ abstract class Node {
   dynamic visitBy(Visitor visitor);
 }
 
+/// Superclass for [Program], [FunctionNode], and [CatchClause], which are the three types of node that
+/// can host local variables.
 abstract class Scope extends Node {
   /// Variables declared in this scope, including the implicitly declared "arguments" variable.
   Set<String> environment;
 }
 
+/// A collection of [Program] nodes.
+/// 
+/// This node is not generated by the parser, but is a convenient way to cluster multiple ASTs into a single AST,
+/// should you wish to do so.
 class Programs extends Node {
   List<Program> programs = <Program>[];
 
@@ -68,6 +78,7 @@ class Programs extends Node {
   visitBy(Visitor v) => v.visitPrograms(this);
 }
 
+/// The root node of a JavaScript AST, representing the top-level scope.
 class Program extends Scope {
   /// Indicates where the program was parsed from.
   /// In principle, this can be anything, it is just a string passed to the parser for convenience.
@@ -84,6 +95,7 @@ class Program extends Scope {
   visitBy(Visitor v) => v.visitProgram(this);
 }
 
+/// A function, which may occur as a function expression, function declaration, or property accessor in an object literal.
 class FunctionNode extends Scope {
   Name name;
   List<Name> params;
@@ -93,6 +105,7 @@ class FunctionNode extends Scope {
 
   bool get isExpression => parent is FunctionExpression;
   bool get isDeclaration => parent is FunctionDeclaration;
+  bool get isAccessor => parent is Property && (parent as Property).isAccessor;
 
   forEach(callback) {
     if (name != null) callback(name);
@@ -138,8 +151,10 @@ class Name extends Node {
 
 ///// STATEMENTS /////
 
+/// Superclass for all nodes that are statements.
 abstract class Statement extends Node {}
 
+/// Statement of form: `;`
 class EmptyStatement extends Statement {
   void forEach(callback) {}
 
@@ -148,6 +163,7 @@ class EmptyStatement extends Statement {
   visitBy(Visitor v) => v.visitEmptyStatement(this);
 }
 
+/// Statement of form: `{ [body] }`
 class BlockStatement extends Statement {
   List<Statement> body;
 
@@ -160,6 +176,7 @@ class BlockStatement extends Statement {
   visitBy(Visitor v) => v.visitBlock(this);
 }
 
+/// Statement of form: `[expression];`
 class ExpressionStatement extends Statement {
   Expression expression;
 
@@ -172,6 +189,7 @@ class ExpressionStatement extends Statement {
   visitBy(Visitor v) => v.visitExpressionStatement(this);
 }
 
+/// Statement of form: `if ([condition]) then [then] else [otherwise]`.
 class IfStatement extends Statement {
   Expression condition;
   Statement then;
@@ -190,6 +208,7 @@ class IfStatement extends Statement {
   visitBy(Visitor v) => v.visitIf(this);
 }
 
+/// Statement of form: `[label]: [body]`
 class LabeledStatement extends Statement {
   Name label;
   Statement body;
@@ -206,6 +225,7 @@ class LabeledStatement extends Statement {
   visitBy(Visitor v) => v.visitLabeledStatement(this);
 }
 
+/// Statement of form: `break;` or `break [label];`
 class BreakStatement extends Statement {
   Name label; // May be null.
 
@@ -220,6 +240,7 @@ class BreakStatement extends Statement {
   visitBy(Visitor v) => v.visitBreak(this);
 }
 
+/// Statement of form: `continue;` or `continue [label];`
 class ContinueStatement extends Statement {
   Name label; // May be null.
 
@@ -234,6 +255,7 @@ class ContinueStatement extends Statement {
   visitBy(Visitor v) => v.visitContinue(this);
 }
 
+/// Statement of form: `with ([object]) { [body] }`
 class WithStatement extends Statement {
   Expression object;
   Statement body;
@@ -250,6 +272,7 @@ class WithStatement extends Statement {
   visitBy(Visitor v) => v.visitWith(this);
 }
 
+/// Statement of form: `switch ([argument]) { [cases] }`
 class SwitchStatement extends Statement {
   Expression argument;
   List<SwitchCase> cases;
@@ -266,13 +289,15 @@ class SwitchStatement extends Statement {
   visitBy(Visitor v) => v.visitSwitch(this);
 }
 
+/// Clause in a switch: `case [expression]: [body]` or `default: [body]` if [expression] is null.
 class SwitchCase extends Node {
   Expression expression; // May be null (for default clause)
   List<Statement> body;
 
   SwitchCase(this.expression, this.body);
   SwitchCase.defaultCase(this.body);
 
+  /// True if this is a default clause, and not a case clause.
   bool get isDefault => expression == null;
 
   forEach(callback) {
@@ -285,6 +310,7 @@ class SwitchCase extends Node {
   visitBy(Visitor v) => v.visitSwitchCase(this);
 }
 
+/// Statement of form: `return [argument];` or `return;`
 class ReturnStatement extends Statement {
   Expression argument;
 
@@ -297,6 +323,7 @@ class ReturnStatement extends Statement {
   visitBy(Visitor v) => v.visitReturn(this);
 }
 
+/// Statement of form: `throw [argument];`
 class ThrowStatement extends Statement {
   Expression argument;
 
@@ -309,6 +336,7 @@ class ThrowStatement extends Statement {
   visitBy(Visitor v) => v.visitThrow(this);
 }
 
+/// Statement of form: `try [block] catch [handler] finally [finalizer]`.
 class TryStatement extends Statement {
   BlockStatement block;
   CatchClause handler; // May be null
@@ -327,6 +355,7 @@ class TryStatement extends Statement {
   visitBy(Visitor v) => v.visitTry(this);
 }
 
+/// A catch clause: `catch ([param]) [body]`
 class CatchClause extends Scope {
   Name param;
   BlockStatement body;
@@ -343,6 +372,7 @@ class CatchClause extends Scope {
   visitBy(Visitor v) => v.visitCatchClause(this);
 }
 
+/// Statement of form: `while ([condition]) [body]`
 class WhileStatement extends Statement {
   Expression condition;
   Statement body;
@@ -359,6 +389,7 @@ class WhileStatement extends Statement {
   visitBy(Visitor v) => v.visitWhile(this);
 }
 
+/// Statement of form: `do [body] while ([condition]);`
 class DoWhileStatement extends Statement {
   Statement body;
   Expression condition;
@@ -375,8 +406,10 @@ class DoWhileStatement extends Statement {
   visitBy(Visitor v) => v.visitDoWhile(this);
 }
 
+/// Statement of form: `for ([init]; [condition]; [update]) [body]`
 class ForStatement extends Statement {
-  Node init; // May be VariableDeclaration, Expression, or null.
+  /// May be VariableDeclaration, Expression, or null.
+  Node init;
   Expression condition; // May be null.
   Expression update; // May be null.
   Statement body;
@@ -395,8 +428,10 @@ class ForStatement extends Statement {
   visitBy(Visitor v) => v.visitFor(this);
 }
 
+/// Statement of form: `for ([left] in [right]) [body]`
 class ForInStatement extends Statement {
-  Node left; // May be VariableDeclaration or Expression.
+  /// May be VariableDeclaration or Expression.
+  Node left; 
   Expression right;
   Statement body;
 
@@ -413,6 +448,7 @@ class ForInStatement extends Statement {
   visitBy(Visitor v) => v.visitForIn(this);
 }
 
+/// Statement of form: `function [function.name])([function.params]) { [function.body] }`.
 class FunctionDeclaration extends Statement {
   FunctionNode function;
 
@@ -425,6 +461,7 @@ class FunctionDeclaration extends Statement {
   visitBy(Visitor v) => v.visitFunctionDeclaration(this);
 }
 
+/// Statement of form: `var [declarations];`
 class VariableDeclaration extends Statement {
   List<VariableDeclarator> declarations;
 
@@ -437,6 +474,7 @@ class VariableDeclaration extends Statement {
   visitBy(Visitor v) => v.visitVariableDeclaration(this);
 }
 
+/// Variable declaration: `[name]` or `[name] = [init]`.
 class VariableDeclarator extends Node {
   Name name;
   Expression init; // May be null.
@@ -453,6 +491,7 @@ class VariableDeclarator extends Node {
   visitBy(Visitor v) => v.visitVariableDeclarator(this);
 }
 
+/// Statement of form: `debugger;`
 class DebuggerStatement extends Statement {
   forEach(callback) {}
 
@@ -463,8 +502,10 @@ class DebuggerStatement extends Statement {
 
 ///////
 
+/// Superclass of all nodes that are expressions.
 abstract class Expression extends Node {}
 
+/// Expression of form: `this`
 class ThisExpression extends Expression {
   forEach(callback) {}
 
@@ -473,6 +514,7 @@ class ThisExpression extends Expression {
   visitBy(Visitor v) => v.visitThis(this);
 }
 
+/// Expression of form: `[ [expressions] ]`
 class ArrayExpression extends Expression {
   List<Expression> expressions; // May CONTAIN nulls for omitted elements: e.g. [1,2,,,]
 
@@ -491,6 +533,7 @@ class ArrayExpression extends Expression {
   visitBy(Visitor v) => v.visitArray(this);
 }
 
+/// Expression of form: `{ [properties] }`
 class ObjectExpression extends Expression {
   List<Property> properties;
 
@@ -503,6 +546,7 @@ class ObjectExpression extends Expression {
   visitBy(Visitor v) => v.visitObject(this);
 }
 
+/// Property initializer `[key]: [value]`, or getter `get [key] [value]`, or setter `set [key] [value]`.
 class Property extends Node {
   Node key;           // Literal or Name
   Node value;         // Will be FunctionNode with no name for getters and setters
@@ -515,6 +559,7 @@ class Property extends Node {
   bool get isInit => kind == 'init';
   bool get isGetter => kind == 'get';
   bool get isSetter => kind == 'set';
+  bool get isAccessor => isGetter || isSetter;
 
   String get nameString => key is Name ? (key as Name).value : (key as LiteralExpression).value.toString();
 
@@ -534,6 +579,7 @@ class Property extends Node {
   visitBy(Visitor v) => v.visitProperty(this);
 }
 
+/// Expression of form: `function [function.name]([function.params]) { [function.body] }`.
 class FunctionExpression extends Expression {
   FunctionNode function;
 
@@ -546,6 +592,7 @@ class FunctionExpression extends Expression {
   visitBy(Visitor v) => v.visitFunctionExpression(this);
 }
 
+/// Comma-seperated expressions.
 class SequenceExpression extends Expression {
   List<Expression> expressions;
 
@@ -558,6 +605,8 @@ class SequenceExpression extends Expression {
   visitBy(Visitor v) => v.visitSequence(this);
 }
 
+/// Expression of form: `+[argument]`, or using any of the unary operators: 
+/// `+, -, !, ~, typeof, void, delete`
 class UnaryExpression extends Expression {
   String operator; // May be: +, -, !, ~, typeof, void, delete
   Expression argument;
@@ -571,6 +620,8 @@ class UnaryExpression extends Expression {
   visitBy(Visitor v) => v.visitUnary(this);
 }
 
+/// Expression of form: `[left] + [right]`, or using any of the binary operators: 
+/// `==, !=, ===, !==, <, <=, >, >=, <<, >>, >>>, +, -, *, /, %, |, ^, &, &&, ||, in, instanceof`
 class BinaryExpression extends Expression {
   Expression left;
   String operator; // May be: ==, !=, ===, !==, <, <=, >, >=, <<, >>, >>>, +, -, *, /, %, |, ^, &, &&, ||, in, instanceof
@@ -588,6 +639,8 @@ class BinaryExpression extends Expression {
   visitBy(Visitor v) => v.visitBinary(this);
 }
 
+/// Expression of form: `[left] = [right]` or `[left] += [right]` or using any of the assignment operators:
+/// `=, +=, -=, *=, /=, %=, <<=, >>=, >>>=, |=, ^=, &=`
 class AssignmentExpression extends Expression {
   Expression left;
   String operator; // May be: =, +=, -=, *=, /=, %=, <<=, >>=, >>>=, |=, ^=, &=
@@ -607,6 +660,7 @@ class AssignmentExpression extends Expression {
   visitBy(Visitor v) => v.visitAssignment(this);
 }
 
+/// Expression of form: `++[argument]`, `--[argument]`, `[argument]++`, `[argument]--`.
 class UpdateExpression extends Expression {
   String operator; // May be: ++, --
   Expression argument;