qasm-ts/dist/parser.js

QASM, the low-level programming language for quantum circuit specification, implemented in TypeScript.

"use strict";
/**
 * Main parser interface for generating AST from tokens
 *
 * The parser is responsible for transforming a stream of tokens into an Abstract
 * Syntax Tree (AST) that represents the structure of the OpenQASM program. It acts
 * as a dispatcher, selecting the appropriate version-specific parser based on the
 * OpenQASM version being used.
 *
 * The parsing process follows these steps:
 * 1. Receive tokenized input from the lexer
 * 2. Determine OpenQASM version (2.0 or 3.0)
 * 3. Select appropriate parser implementation
 * 4. Generate version-specific AST nodes
 *
 * The specific Parser implementations can be found at:
 * - {@link Qasm3Parser}
 * - {@link Qasm2Parser}
 *
 * @module Parsing
 *
 * @example Basic parsing workflow
 * ```typescript
 * import { lex } from './lexer';
 * import { parse } from './parser';
 *
 * const qasmCode = 'OPENQASM 3.0; h q[0];';
 * const tokens = lex(qasmCode, undefined, 3);
 * const ast = parse(tokens, 3);
 * console.log(ast); // Array of AST nodes
 * ```
 *
 * @example Version-specific parsing
 * ```typescript
 * // Parse as OpenQASM 2.0
 * const ast2 = parse(tokens, 2);
 *
 * // Parse as OpenQASM 3.0
 * const ast3 = parse(tokens, 3);
 *
 * // Use OpenQASMVersion object
 * const version = new OpenQASMVersion(3, 0);
 * const ast = parse(tokens, version);
 * ```
 */
Object.defineProperty(exports, "__esModule", { value: true });
exports.parse = parse;
var parser_1 = require("./qasm2/parser");
var parser_2 = require("./qasm3/parser");
var version_1 = require("./version");
var errors_1 = require("./errors");
/**
 * Parses an array of tokens into an Abstract Syntax Tree (AST).
 *
 * This is the main entry point for parsing tokenized OpenQASM code. It automatically
 * selects the appropriate parser implementation based on the specified version and
 * returns an AST that can be used for further analysis, compilation, or execution.
 *
 * @group Parsing
 * @param tokens - Array of tokens generated by the lexer
 * @param version - OpenQASM version to use for parsing (defaults to 3.0)
 * @returns Abstract Syntax Tree representing the parsed program
 * @throws {UnsupportedOpenQASMVersionError} When an unsupported version is specified
 *
 * @example Parse OpenQASM 3.0 tokens
 * ```typescript
 * const tokens = lex('OPENQASM 3.0; qubit q; h q;');
 * const ast = parse(tokens, 3);
 * // Returns array of OpenQASM 3.0 AST nodes
 * ```
 *
 * @example Parse OpenQASM 2.0 tokens
 * ```typescript
 * const tokens = lex('OPENQASM 2.0; qreg q[1]; h q[0];');
 * const ast = parse(tokens, 2);
 * // Returns array of OpenQASM 2.0 AST nodes
 * ```
 */
function parse(tokens, version) {
    var parser;
    var castTokens;
    if (version instanceof version_1.OpenQASMVersion) {
        switch (version.major) {
            case version_1.OpenQASMMajorVersion.Version2:
                castTokens = tokens;
                parser = new parser_1.default(castTokens);
                break;
            case version_1.OpenQASMMajorVersion.Version3:
                castTokens = tokens;
                parser = new parser_1.default(castTokens);
                break;
            default:
                throw new errors_1.UnsupportedOpenQASMVersionError("Unsupported OpenQASM version detected: ".concat(version.major));
        }
    }
    else if (typeof version === "number") {
        switch (version) {
            case 2:
                castTokens = tokens;
                parser = new parser_1.default(castTokens);
                break;
            case 3:
                castTokens = tokens;
                parser = new parser_2.default(castTokens);
                break;
            default:
                throw new errors_1.UnsupportedOpenQASMVersionError("Unsupported OpenQASM version detected: ".concat(version));
        }
    }
    else if (version === version_1.OpenQASMMajorVersion.Version2) {
        castTokens = tokens;
        parser = new parser_1.default(castTokens);
    }
    else if (version === version_1.OpenQASMMajorVersion.Version3) {
        castTokens = tokens;
        parser = new parser_2.default(castTokens);
    }
    else {
        castTokens = tokens;
        parser = new parser_2.default(castTokens);
    }
    var ast = parser.parse();
    return ast;
}