qasm-ts 2.1.3 → 2.1.4

package/dist/errors.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Error classes for QASM parsing and validation
+ *
+ * This module provides specific error types for different parsing failures,
+ * enabling precise error handling and debugging. Each error includes contextual
+ * information about where the error occurred in the source code.
+ *
+ * @module Error Handling
+ */
+/** Class representing a bad argument exception. */
+declare class BadArgumentError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad include statement */
+declare class BadIncludeError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad quantum register exception. */
+declare class BadQregError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad equality exception. */
+declare class BadEqualsError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad classical register exception. */
+declare class BadCregError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad conditional exception. */
+declare class BadConditionalError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad barrier exception. */
+declare class BadBarrierError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad measurement exception. */
+declare class BadMeasurementError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad gate exception. */
+declare class BadGateError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad parameter exception. */
+declare class BadParameterError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a missing semicolon exception. */
+declare class MissingSemicolonError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a missing opening or closing parenthesis, bracket, or curly brakcet. */
+declare class MissingBraceError extends Error {
+    constructor(message?: string);
+}
+/** Class representing an unsupported OpenQASM version exception. */
+declare class UnsupportedOpenQASMVersionError extends Error {
+    constructor(message?: string);
+}
+/** Class representing an error parsing an expected string literal. */
+declare class BadStringLiteralError extends Error {
+    constructor(message?: string);
+}
+/** Class representing an error parsing scalar types. */
+declare class BadClassicalTypeError extends Error {
+    constructor(message?: string);
+}
+/** Class representing an error parsing an expression. */
+declare class BadExpressionError extends Error {
+    constructor(message?: string);
+}
+/** Class representing an error in defining or calling a custom subroutine. */
+declare class BadSubroutineError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad loop statement declaration. */
+declare class BadLoopError extends Error {
+    constructor(message?: string);
+}
+/** Class representing a bad quantum instruction. */
+declare class BadQuantumInstructionError extends Error {
+    constructor(message?: string);
+}
+/** Type for returning an error constructor. */
+type ReturnErrorConstructor = new (message?: string) => Error;
+export { BadArgumentError, BadIncludeError, BadCregError, BadQregError, BadConditionalError, BadBarrierError, BadMeasurementError, BadGateError, BadEqualsError, BadParameterError, MissingSemicolonError, MissingBraceError, UnsupportedOpenQASMVersionError, BadStringLiteralError, BadClassicalTypeError, BadExpressionError, BadSubroutineError, BadLoopError, BadQuantumInstructionError, ReturnErrorConstructor, };

package/dist/errors.js

@@ -0,0 +1,162 @@
+/**
+ * Error classes for QASM parsing and validation
+ *
+ * This module provides specific error types for different parsing failures,
+ * enabling precise error handling and debugging. Each error includes contextual
+ * information about where the error occurred in the source code.
+ *
+ * @module Error Handling
+ */
+/** Class representing a bad argument exception. */
+class BadArgumentError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadArgumentError.name;
+    }
+}
+/** Class representing a bad include statement */
+class BadIncludeError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadIncludeError.name;
+    }
+}
+/** Class representing a bad quantum register exception. */
+class BadQregError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadQregError.name;
+    }
+}
+/** Class representing a bad equality exception. */
+class BadEqualsError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadEqualsError.name;
+    }
+}
+/** Class representing a bad classical register exception. */
+class BadCregError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadCregError.name;
+    }
+}
+/** Class representing a bad conditional exception. */
+class BadConditionalError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadConditionalError.name;
+    }
+}
+/** Class representing a bad barrier exception. */
+class BadBarrierError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadBarrierError.name;
+    }
+}
+/** Class representing a bad measurement exception. */
+class BadMeasurementError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadMeasurementError.name;
+    }
+}
+/** Class representing a bad gate exception. */
+class BadGateError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadGateError.name;
+    }
+}
+/** Class representing a bad parameter exception. */
+class BadParameterError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadParameterError.name;
+    }
+}
+/** Class representing a missing semicolon exception. */
+class MissingSemicolonError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = MissingSemicolonError.name;
+    }
+}
+/** Class representing a missing opening or closing parenthesis, bracket, or curly brakcet. */
+class MissingBraceError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = MissingSemicolonError.name;
+    }
+}
+/** Class representing an unsupported OpenQASM version exception. */
+class UnsupportedOpenQASMVersionError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = UnsupportedOpenQASMVersionError.name;
+    }
+}
+/** Class representing an error parsing an expected string literal. */
+class BadStringLiteralError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadStringLiteralError.name;
+    }
+}
+/** Class representing an error parsing scalar types. */
+class BadClassicalTypeError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadClassicalTypeError.name;
+    }
+}
+/** Class representing an error parsing an expression. */
+class BadExpressionError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadExpressionError.name;
+    }
+}
+/** Class representing an error in defining or calling a custom subroutine. */
+class BadSubroutineError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadSubroutineError.name;
+    }
+}
+/** Class representing a bad loop statement declaration. */
+class BadLoopError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadLoopError.name;
+    }
+}
+/** Class representing a bad quantum instruction. */
+class BadQuantumInstructionError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = BadQuantumInstructionError.name;
+    }
+}
+export { BadArgumentError, BadIncludeError, BadCregError, BadQregError, BadConditionalError, BadBarrierError, BadMeasurementError, BadGateError, BadEqualsError, BadParameterError, MissingSemicolonError, MissingBraceError, UnsupportedOpenQASMVersionError, BadStringLiteralError, BadClassicalTypeError, BadExpressionError, BadSubroutineError, BadLoopError, BadQuantumInstructionError, };

package/dist/lexer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Main lexer interface for tokenizing QASM code
+ *
+ * The lexer is responsible for breaking down QASM source code into tokens
+ * that can be consumed by the parser. It supports both OpenQASM 2.0 and 3.0
+ * syntax, with version-specific lexers handling the differences in token types
+ * and syntax rules.
+ *
+ * The specific Lexer implementations can be found at:
+ * - {@link Qasm3Lexer}
+ * - {@link Qasm2Lexer}
+ *
+ * @module Lexing
+ *
+ * @example Token Flow
+ * ```
+ * Source Code → Lexer → Tokens → Parser → AST
+ * "h q[0];"  →  [Id, Id, LSParen, NNInteger, RSParen, Semicolon]
+ * ```
+ *
+ *  * @example Basic lexing workflow
+ * ```typescript
+ * import { lex } from './lexer';
+ *
+ * const qasmCode = 'OPENQASM 3.0; qubit q; h q;';
+ * const tokens = lex(qasmCode);
+ * console.log(tokens);
+ * // [
+ * //   [Token.OpenQASM, undefined],
+ * //   [Token.Id, 'qubit'],
+ * //   [Token.Id, 'q'],
+ * //   [Token.Semicolon, undefined],
+ * //   [Token.Id, 'h'],
+ * //   [Token.Id, 'q'],
+ * //   [Token.Semicolon, undefined]
+ * // ]
+ * ```
+ */
+import { Token as Qasm2Token } from "./qasm2/token";
+import { Token as Qasm3Token } from "./qasm3/token";
+import { OpenQASMVersion, OpenQASMMajorVersion } from "./version";
+/**
+ * Tokenizes OpenQASM source code into an array of tokens.
+ *
+ * This is the main entry point for lexical analysis. It automatically selects
+ * the appropriate lexer implementation based on the OpenQASM version and returns
+ * an array of tokens that can be consumed by the parser.
+ *
+ * Each token is represented as a tuple containing:
+ * - **Token type**: An enum value indicating the kind of token
+ * - **Token value**: The associated value (for literals, identifiers, operators)
+ *
+ * @group Lexing
+ * @param qasm - The OpenQASM source code to tokenize
+ * @param cursor - Starting position in the input string (defaults to 0)
+ * @param version - OpenQASM version to use for lexing (defaults to 3.0)
+ * @returns Array of token tuples [TokenType, value?]
+ * @throws {UnsupportedOpenQASMVersionError} When an unsupported version is specified
+ *
+ * @example Tokenize OpenQASM 3.0 code
+ * ```typescript
+ * const tokens = lex('qubit[2] q; h q[0];', 0, 3);
+ * // Returns tokens using OpenQASM 3.0 syntax rules
+ * ```
+ *
+ * @example Tokenize OpenQASM 2.0 code
+ * ```typescript
+ * const tokens = lex('qreg q[2]; h q[0];', 0, 2);
+ * // Returns tokens using OpenQASM 2.0 syntax rules
+ * ```
+ *
+ * @example Resume lexing from specific position
+ * ```typescript
+ * const code = 'OPENQASM 3.0; qubit q;';
+ * const tokens = lex(code, 12); // Start after "OPENQASM 3.0"
+ * ```
+ */
+export declare function lex(qasm: string, cursor?: number, version?: OpenQASMVersion | OpenQASMMajorVersion | number): Array<[Qasm2Token | Qasm3Token, (number | string)?]>;

package/dist/lexer.js

@@ -0,0 +1,116 @@
+/**
+ * Main lexer interface for tokenizing QASM code
+ *
+ * The lexer is responsible for breaking down QASM source code into tokens
+ * that can be consumed by the parser. It supports both OpenQASM 2.0 and 3.0
+ * syntax, with version-specific lexers handling the differences in token types
+ * and syntax rules.
+ *
+ * The specific Lexer implementations can be found at:
+ * - {@link Qasm3Lexer}
+ * - {@link Qasm2Lexer}
+ *
+ * @module Lexing
+ *
+ * @example Token Flow
+ * ```
+ * Source Code → Lexer → Tokens → Parser → AST
+ * "h q[0];"  →  [Id, Id, LSParen, NNInteger, RSParen, Semicolon]
+ * ```
+ *
+ *  * @example Basic lexing workflow
+ * ```typescript
+ * import { lex } from './lexer';
+ *
+ * const qasmCode = 'OPENQASM 3.0; qubit q; h q;';
+ * const tokens = lex(qasmCode);
+ * console.log(tokens);
+ * // [
+ * //   [Token.OpenQASM, undefined],
+ * //   [Token.Id, 'qubit'],
+ * //   [Token.Id, 'q'],
+ * //   [Token.Semicolon, undefined],
+ * //   [Token.Id, 'h'],
+ * //   [Token.Id, 'q'],
+ * //   [Token.Semicolon, undefined]
+ * // ]
+ * ```
+ */
+import { default as Qasm2Lexer } from "./qasm2/lexer";
+import { default as Qasm3Lexer } from "./qasm3/lexer";
+import { OpenQASMVersion, OpenQASMMajorVersion } from "./version";
+import { UnsupportedOpenQASMVersionError } from "./errors";
+/**
+ * Tokenizes OpenQASM source code into an array of tokens.
+ *
+ * This is the main entry point for lexical analysis. It automatically selects
+ * the appropriate lexer implementation based on the OpenQASM version and returns
+ * an array of tokens that can be consumed by the parser.
+ *
+ * Each token is represented as a tuple containing:
+ * - **Token type**: An enum value indicating the kind of token
+ * - **Token value**: The associated value (for literals, identifiers, operators)
+ *
+ * @group Lexing
+ * @param qasm - The OpenQASM source code to tokenize
+ * @param cursor - Starting position in the input string (defaults to 0)
+ * @param version - OpenQASM version to use for lexing (defaults to 3.0)
+ * @returns Array of token tuples [TokenType, value?]
+ * @throws {UnsupportedOpenQASMVersionError} When an unsupported version is specified
+ *
+ * @example Tokenize OpenQASM 3.0 code
+ * ```typescript
+ * const tokens = lex('qubit[2] q; h q[0];', 0, 3);
+ * // Returns tokens using OpenQASM 3.0 syntax rules
+ * ```
+ *
+ * @example Tokenize OpenQASM 2.0 code
+ * ```typescript
+ * const tokens = lex('qreg q[2]; h q[0];', 0, 2);
+ * // Returns tokens using OpenQASM 2.0 syntax rules
+ * ```
+ *
+ * @example Resume lexing from specific position
+ * ```typescript
+ * const code = 'OPENQASM 3.0; qubit q;';
+ * const tokens = lex(code, 12); // Start after "OPENQASM 3.0"
+ * ```
+ */
+export function lex(qasm, cursor, version) {
+    let lexer;
+    if (version instanceof OpenQASMVersion) {
+        switch (version.major) {
+            case OpenQASMMajorVersion.Version2:
+                lexer = new Qasm2Lexer(qasm, cursor);
+                break;
+            case OpenQASMMajorVersion.Version3:
+                lexer = new Qasm3Lexer(qasm, cursor);
+                break;
+            default:
+                throw new UnsupportedOpenQASMVersionError(`Unsupported OpenQASM version detected: ${version.major}`);
+        }
+    }
+    else if (typeof version === "number") {
+        switch (version) {
+            case 2:
+                lexer = new Qasm2Lexer(qasm, cursor);
+                break;
+            case 3:
+                lexer = new Qasm3Lexer(qasm, cursor);
+                break;
+            default:
+                throw new UnsupportedOpenQASMVersionError(`Unsupported OpenQASM version detected: ${version}`);
+        }
+    }
+    else if (version === OpenQASMMajorVersion.Version2) {
+        lexer = new Qasm2Lexer(qasm, cursor);
+    }
+    else if (version === OpenQASMMajorVersion.Version3) {
+        lexer = new Qasm3Lexer(qasm, cursor);
+    }
+    else {
+        lexer = new Qasm3Lexer(qasm, cursor);
+    }
+    const tokens = lexer.lex();
+    return tokens;
+}

package/dist/main.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Main parsing functions for qasm-ts - the primary entry points for parsing OpenQASM code
+ * @module Main Functions
+ */
+import type * as qasm2 from "./qasm2/ast";
+import type * as qasm3 from "./qasm3/ast";
+import { OpenQASMVersion, OpenQASMMajorVersion } from "./version";
+/**
+ * Parses OpenQASM code from a string and returns the abstract syntax tree.
+ *
+ * This is the primary entry point for parsing OpenQASM code. It handles both
+ * OpenQASM 2.0 and 3.0 syntax, automatically selecting the appropriate lexer
+ * and parser based on the version parameter.
+ *
+ * @group Main Functions
+ * @param qasm - The OpenQASM code string to parse
+ * @param version - The OpenQASM version to use (defaults to 3.0)
+ * @param verbose - Whether to include class names in the output (defaults to false)
+ * @param stringify - Whether to return stringified JSON (defaults to false)
+ * @returns The corresponding AST as an array of nodes, or stringified JSON if stringify is true
+ *
+ * @example Basic OpenQASM 3.0 parsing
+ * ```typescript
+ * import { parseString } from 'qasm-ts';
+ *
+ * const qasmCode = `
+ * OPENQASM 3.0;
+ * include "stdgates.inc";
+ * qubit[2] q;
+ * h q[0];
+ * cx q[0], q[1];
+ * `;
+ *
+ * const ast = parseString(qasmCode);
+ * console.log(ast);
+ * ```
+ *
+ * @example OpenQASM 2.0 parsing
+ * ```typescript
+ * const qasm2Code = `
+ * OPENQASM 2.0;
+ * include "qelib1.inc";
+ * qreg q[2];
+ * creg c[2];
+ * h q[0];
+ * cx q[0],q[1];
+ * measure q -> c;
+ * `;
+ *
+ * const ast = parseString(qasm2Code, 2);
+ * ```
+ *
+ * @example Verbose output with class names
+ * ```typescript
+ * const ast = parseString(qasmCode, 3, true);
+ * // Output will include __className__ properties for each node
+ * ```
+ */
+export declare function parseString(qasm: string, version?: number | OpenQASMVersion | OpenQASMMajorVersion, verbose?: boolean, stringify?: boolean): string | qasm2.AstNode[] | qasm3.AstNode[];
+/**
+ * Parses OpenQASM code from a file and returns the abstract syntax tree.
+ *
+ * @group Main Functions
+ * @param file - The path to the .qasm file to parse
+ * @param version - The OpenQASM version to use (defaults to 3.0)
+ * @param verbose - Whether to include class names in the output (defaults to false)
+ * @param stringify - Whether to return stringified JSON (defaults to false)
+ * @returns The corresponding AST as an array of nodes, or stringified JSON if stringify is true
+ *
+ * @example Parse a QASM file
+ * ```typescript
+ * import { parseFile } from 'qasm-ts';
+ *
+ * // Parse OpenQASM 3.0 file
+ * const ast = parseFile('./my-circuit.qasm');
+ *
+ * // Parse OpenQASM 2.0 file
+ * const ast2 = parseFile('./legacy-circuit.qasm', 2);
+ * ```
+ *
+ * @example Parse with verbose output
+ * ```typescript
+ * const ast = parseFile('./circuit.qasm', 3, true);
+ * // Includes detailed class information for each AST node
+ * ```
+ */
+export declare function parseFile(file: string, version?: number | OpenQASMVersion | OpenQASMMajorVersion, verbose?: boolean, stringify?: boolean): string | qasm2.AstNode[] | qasm3.AstNode[];

package/dist/main.js

@@ -0,0 +1,122 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import * as fs from "fs";
+import { lex } from "./lexer";
+import { parse } from "./parser";
+/**
+ * Parses OpenQASM code from a string and returns the abstract syntax tree.
+ *
+ * This is the primary entry point for parsing OpenQASM code. It handles both
+ * OpenQASM 2.0 and 3.0 syntax, automatically selecting the appropriate lexer
+ * and parser based on the version parameter.
+ *
+ * @group Main Functions
+ * @param qasm - The OpenQASM code string to parse
+ * @param version - The OpenQASM version to use (defaults to 3.0)
+ * @param verbose - Whether to include class names in the output (defaults to false)
+ * @param stringify - Whether to return stringified JSON (defaults to false)
+ * @returns The corresponding AST as an array of nodes, or stringified JSON if stringify is true
+ *
+ * @example Basic OpenQASM 3.0 parsing
+ * ```typescript
+ * import { parseString } from 'qasm-ts';
+ *
+ * const qasmCode = `
+ * OPENQASM 3.0;
+ * include "stdgates.inc";
+ * qubit[2] q;
+ * h q[0];
+ * cx q[0], q[1];
+ * `;
+ *
+ * const ast = parseString(qasmCode);
+ * console.log(ast);
+ * ```
+ *
+ * @example OpenQASM 2.0 parsing
+ * ```typescript
+ * const qasm2Code = `
+ * OPENQASM 2.0;
+ * include "qelib1.inc";
+ * qreg q[2];
+ * creg c[2];
+ * h q[0];
+ * cx q[0],q[1];
+ * measure q -> c;
+ * `;
+ *
+ * const ast = parseString(qasm2Code, 2);
+ * ```
+ *
+ * @example Verbose output with class names
+ * ```typescript
+ * const ast = parseString(qasmCode, 3, true);
+ * // Output will include __className__ properties for each node
+ * ```
+ */
+export function parseString(qasm, version, verbose, stringify) {
+    let ast;
+    const tokens = lex(qasm, undefined, version);
+    ast = parse(tokens, version);
+    if (verbose === true) {
+        if (stringify === true) {
+            ast = JSON.stringify(getDetailedOutput(ast), null, 2);
+        }
+        ast = getDetailedOutput(ast);
+    }
+    else {
+        if (stringify === true) {
+            ast = JSON.stringify(ast, null, 2);
+        }
+    }
+    return ast;
+}
+/**
+ * Parses OpenQASM code from a file and returns the abstract syntax tree.
+ *
+ * @group Main Functions
+ * @param file - The path to the .qasm file to parse
+ * @param version - The OpenQASM version to use (defaults to 3.0)
+ * @param verbose - Whether to include class names in the output (defaults to false)
+ * @param stringify - Whether to return stringified JSON (defaults to false)
+ * @returns The corresponding AST as an array of nodes, or stringified JSON if stringify is true
+ *
+ * @example Parse a QASM file
+ * ```typescript
+ * import { parseFile } from 'qasm-ts';
+ *
+ * // Parse OpenQASM 3.0 file
+ * const ast = parseFile('./my-circuit.qasm');
+ *
+ * // Parse OpenQASM 2.0 file
+ * const ast2 = parseFile('./legacy-circuit.qasm', 2);
+ * ```
+ *
+ * @example Parse with verbose output
+ * ```typescript
+ * const ast = parseFile('./circuit.qasm', 3, true);
+ * // Includes detailed class information for each AST node
+ * ```
+ */
+export function parseFile(file, version, verbose, stringify) {
+    return parseString(fs.readFileSync(file, "utf8"), version, verbose, stringify);
+}
+/**
+ * Adds class names to AST nodes for detailed inspection.
+ * @internal
+ */
+function getDetailedOutput(object) {
+    if (Array.isArray(object)) {
+        return object.map(getDetailedOutput);
+    }
+    else if (object !== null && typeof object === "object") {
+        const result = {};
+        result["__className__"] = object.constructor.name;
+        for (const [key, value] of Object.entries(object)) {
+            result[key] = getDetailedOutput(value);
+        }
+        return result;
+    }
+    else {
+        return object;
+    }
+}