ecma-scopes

Listing of block and lexical scope names for ECMAScript AST

We are using the tokens output by esprima-fb, a fork of esprima with ES6 support.

This was created to make detecting scope boundaries easier and well tested. It is a part of the esformatter-phonetic project, an esformatter plugin that helps with renaming obfuscated variabes to more recognizable ones.

Getting Started

Install the module with: npm install ecma-scopes

var ecmaScopes = require('ecma-scopes');
ecmaScopes.lexical;
// ["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]
ecmaScopes.block;
// ["BlockStatement", "ForStatement", "ForInStatement", "ForOfStatement", "CatchClause", "ComprehensionExpression"]

Explanations of lexical and block scopes/tokens are available in the Documentation section.

Documentation

This library is very lightweight. The annoying part is going through the spec, picking out what works, and testing rigorously. We have done all of that for you.

We provide exports.lexical and exports.block, lexical and block scopes respectively.

We do not include Program in either because depending on your usage, you may want or not want it. Since it is easier to add onto an array, we have chosen to leave it out.

var lexicalWithProgram = ecmaScopes.lexical.slice();
lexicalWithProgram.push('Program');

exports.lexical

Lexical scoping is JavaScript's default way for handling variable scope. This comes into effect when var is used, function arguments, function name's, catch arguments, and probably some more (sorry for an incomplete list).

Functions reference: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Parser_API#Functions

With our research, we found the following tokens to manage lexical scope:

• FunctionDeclaration, function declared as a statement
  • Example: function main() { var item; }
    • main is the function and hello is a lexically scoped variable inside of main
• FunctionExpression, function set to a variable
  • Example: var main = function () { var item; }
    • main is the function and hello is a lexically scoped variable inside of main
• ArrowFunctionExpression
  • Warning: Inside of the SpiderMonkey API documenttion, this is ArrowExpression. However esprima-fb implements it as ArrowFunctionExpression
  • Example: (item) => item;
    • item is defined as an input parameter and remains scoped within the function

exports.block

Block scoping is a new form of scoping performed with a let keyword. Instead of variables being scoped to functions, they are now scoped to block statements (e.g. any time we are between braces { ... }. For example, an if statement using let does not expose the variable to the rest of the program.

if (true) {
  let item;
}
// item is not declared nor defined

In its simplest form, the following is valid and block scoped:

{ let item; }

In addition to braces, loops that allow variable declarations scope let to their corresponding BlockStatement (section between braces):

for (let item = 'hello', i = 0; i < 10; i++) {
  item; // 'hello'
}
// item is not declared nor defined

Statement reference: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Parser_API#Statements

With our research, we found the following tokens to manage block scope:

• BlockStatement, section of braces
  • Example: { let item; }
    • item is scoped to the braces and not exposed outside of them
• ForStatement, for loop
  • Example: for (let item; false; false) { /* Code goes here */ }
    • item is accessible within the loop and between the parentheses but not outside of the loop
• ForInStatement, for in loop (iterates over each of the keys of an object)
  • Example: var obj = {hello: 'world'}; for (let key in obj) { /* Code goes here */ }
    • key is accessible within the loop and between the parentheses but not outside of the loop
• ForOfStatement, for of loop (iterates over each of the values of an array)
  • Example: var arr = ['hello', 'world']; for (let val of arr) { /* Code goes here */ }
    • val is accessible within the loop and between the parentheses but not outside of the loop
• CatchClause, catch handler of a try/catch/finally
  • Example: try { /* ... */ } catch (err) { /* ... */ }
    • err is accessible within the catch's BlockStatement but not outside of it
• ComprehensionExpression, array comprehension (generate an array from another array)
  • Example: var arr1 = [1], arr2 = [val + 1 for (val of arr1)];
    • val is accessible within the comprehension (between the brackets [ ... ]) but not outside of it

Filesystem

If you would like to discover more by reading the source code, here are their corresponding purposes/information:

• lib/ecma-scopes.comments.js - Commented form of scopes we export with links to references
• test/block-scopes.js - Tests against block scope tokens
  • Has additional tests to verify that BlockStatement covers IfStatement, SwitchStatement, and anything that can be braceless
• test/lexical-scopes.js - Tests against lexical scope tokens (e.g. FunctionDeclaration)
• test/test-files/block-*.js - Example usage of a block token (e.g. block-BlockStatement.js for BlockStatement)
• test/test-files/lexical-*.js - Example usage of a lexical token (e.g. lexical-ForStatement.js for ForStatement)

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via grunt and test via npm test.

Donating

Support this project and others by twolfson via gratipay.

Unlicense

As of Nov 04 2014, Todd Wolfson has released this repository and its contents to the public domain.

It has been released under the UNLICENSE.