DOCSEARCHbyAlgolia
Submit Docs

Shift Parser

repository·es2019·Indexed 42 days ago

https://github.com/shapesecurity/shift-parser-js

An ECMAScript parser that produces a Shift format AST, supporting version 6 (release candidate 2) of the ECMA-262 standard. Version 8.0.0 provides functions like parseScript and parseModule, as well as WithLocation variants to retrieve precise node location data and comments using a WeakMap.

Tokens
1.5K
Snippets
6
Records
7
Agent score
4%

What's inside Shift Parser

  2. Parse ECMAScript using shift-parser

    es2019

    Shift Parser provides several ways to parse ECMAScript text into a Shift format AST. You can use the default parse function for general parsing, or use specific functions for Scripts and Modules to ensure correct parsing context.

    ES6 Imports

    import parse from "shift-parser";
let ast = parse("/* ECMAScript program text */");

import {parseScript, parseModule} from "shift-parser";
let scriptAST = parseScript("/* ECMAScript Script text */");
let moduleAST = parseModule("/* ECMAScript Module text */");

    Node.js (CommonJS)

    var parseScript = require("shift-parser").parseScript;
var scriptAST = parseScript("/* ECMAScript Script text */");
    import {parseScript, parseModule} from "shift-parser";
let scriptAST = parseScript("/* ECMAScript Script text */");
let moduleAST = parseModule("/* ECMAScript Module text */");

  3. Access location information and comments

    es2019

    If your environment supports WeakMap, you can use the parseScriptWithLocation or parseModuleWithLocation functions to retrieve the AST along with precise location data and comments.

    This returns an object containing:

    • tree: The Shift format AST.
    • locations: A WeakMap used to look up location data for specific nodes.
    • comments: An array of comment objects found in the source.

    Location objects contain start and end properties, each with line, column, and offset.

    let {parseScriptWithLocation, parseModuleWithLocation} = require("shift-parser");
let {tree, locations, comments} = parseScriptWithLocation("2 + 3 /* = 5 */");
let threeNode = tree.statements[0].expression.right;
locations.get(threeNode); // { start: { line: 1, column: 4, offset: 4 }, end: { line: 1, column: 5, offset: 5 } }
comments; // [ { text: ' = 5 ', type: 'MultiLine', start: { line: 1, column: 6, offset: 6 }, end: { line: 1, column: 15, offset: 15 } } ]

  4. Parse JavaScript modules with parseModule()

    es2019

    Use parseModule to parse a string of JavaScript code as an ES Module. This is similar to parseScript but uses the module parsing logic.

    Options:

    • earlyErrors (boolean, default: true): If true, the parser will run the EarlyErrorChecker and throw a JsError if semantic errors are found.
    const { parseModule } = require('shift-parser');

try {
  const tree = parseModule('import { x } from "y";');
  console.log(tree);
} catch (e) {
  console.error('Parsing error:', e.message);
}

  5. Parse JavaScript code with parseScript()

    es2019

    Use parseScript to parse a string of JavaScript code into an Abstract Syntax Tree (AST). By default, it performs early error checking to ensure the parsed tree adheres to expected JavaScript semantics.

    Options:

    • earlyErrors (boolean, default: true): If true, the parser will run the EarlyErrorChecker and throw a JsError if semantic errors are found. If false, it will return the tree even if it contains semantic errors.
    const { parseScript } = require('shift-parser');

try {
  const tree = parseScript('const x = 1;');
  console.log(tree);
} catch (e) {
  console.error('Parsing error:', e.message);
}

  6. Parse with location and comment data using parseScriptWithLocation() and parseModuleWithLocation()

    es2019

    If you need to know the exact line, column, and offset of nodes in the AST, or if you need to extract comments, use the WithLocation variants of the parsing functions.

    These functions return an object containing the tree, a locations map, and a comments array.

    Returns:

    • tree: The parsed AST.
    • locations: A WeakMap where keys are AST nodes and values are objects containing { start: { line, column, offset }, end: { line, column, offset } }.
    • comments: An array of comment objects, each containing { text, type, start, end }.
    const { parseScriptWithLocation } = require('shift-parser');

const { tree, locations, comments } = parseScriptWithLocation('// comment\nconst x = 1;');

// Accessing location for a node
const nodeLocation = locations.get(tree.body[0]);
console.log(nodeLocation.start.line, nodeLocation.start.column);

// Accessing comments
console.log(comments);

  7. Reference: Exported modules and classes

    es2019

    The following entities are exported from the main entry point:

    • parseScript: Function for parsing scripts.
    • parseModule: Function for parsing modules.
    • parseScriptWithLocation: Function for parsing scripts with location/comment data.
    • parseModuleWithLocation: Function for parsing modules with location/comment data.
    • EarlyErrorChecker: Utility for checking semantic errors in the AST.
    • GenericParser: The base parser class.
    • ParserWithLocation: A parser subclass that tracks node locations and comments.
    • Tokenizer: The lexical analyzer.
    • TokenClass: Enumeration/Type for token classes.
    • TokenType: Enumeration/Type for token types.