qasm-ts 2.1.2 → 2.1.4

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

@@ -1,15 +1,7 @@
-"use strict";
 /* eslint-disable  @typescript-eslint/no-explicit-any */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseString = parseString;
-exports.parseFile = parseFile;
-/**
- * Main parsing functions for qasm-ts - the primary entry points for parsing OpenQASM code
- * @module Main Functions
- */
-var fs = require("fs");
-var lexer_1 = require("./lexer");
-var parser_1 = require("./parser");
+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.
  *
@@ -61,10 +53,10 @@ var parser_1 = require("./parser");
  * // Output will include __className__ properties for each node
  * ```
  */
-function parseString(qasm, version, verbose, stringify) {
-    var ast;
-    var tokens = (0, lexer_1.lex)(qasm, undefined, version);
-    ast = (0, parser_1.parse)(tokens, version);
+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);
@@ -105,7 +97,7 @@ function parseString(qasm, version, verbose, stringify) {
  * // Includes detailed class information for each AST node
  * ```
  */
-function parseFile(file, version, verbose, stringify) {
+export function parseFile(file, version, verbose, stringify) {
     return parseString(fs.readFileSync(file, "utf8"), version, verbose, stringify);
 }
 /**
@@ -117,10 +109,9 @@ function getDetailedOutput(object) {
         return object.map(getDetailedOutput);
     }
     else if (object !== null && typeof object === "object") {
-        var result = {};
+        const result = {};
         result["__className__"] = object.constructor.name;
-        for (var _i = 0, _a = Object.entries(object); _i < _a.length; _i++) {
-            var _b = _a[_i], key = _b[0], value = _b[1];
+        for (const [key, value] of Object.entries(object)) {
             result[key] = getDetailedOutput(value);
         }
         return result;

package/dist/parser.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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);
+ * ```
+ */
+import { Token as Qasm2Token } from "./qasm2/token";
+import { Token as Qasm3Token } from "./qasm3/token";
+import { OpenQASMVersion, OpenQASMMajorVersion } from "./version";
+/**
+ * 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
+ * ```
+ */
+export declare function parse(tokens: Array<[Qasm2Token | Qasm3Token, (number | string)?]>, version?: OpenQASMVersion | OpenQASMMajorVersion | number): import("./qasm2/ast").AstNode[];

package/dist/parser.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Main parser interface for generating AST from tokens
  *
@@ -43,12 +42,10 @@
  * 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");
+import { default as Qasm2Parser } from "./qasm2/parser";
+import { default as Qasm3Parser } from "./qasm3/parser";
+import { OpenQASMVersion, OpenQASMMajorVersion } from "./version";
+import { UnsupportedOpenQASMVersionError } from "./errors";
 /**
  * Parses an array of tokens into an Abstract Syntax Tree (AST).
  *
@@ -76,49 +73,49 @@ var errors_1 = require("./errors");
  * // Returns array of OpenQASM 2.0 AST nodes
  * ```
  */
-function parse(tokens, version) {
-    var parser;
-    var castTokens;
-    if (version instanceof version_1.OpenQASMVersion) {
+export function parse(tokens, version) {
+    let parser;
+    let castTokens;
+    if (version instanceof OpenQASMVersion) {
         switch (version.major) {
-            case version_1.OpenQASMMajorVersion.Version2:
+            case OpenQASMMajorVersion.Version2:
                 castTokens = tokens;
-                parser = new parser_1.default(castTokens);
+                parser = new Qasm2Parser(castTokens);
                 break;
-            case version_1.OpenQASMMajorVersion.Version3:
+            case OpenQASMMajorVersion.Version3:
                 castTokens = tokens;
-                parser = new parser_1.default(castTokens);
+                parser = new Qasm2Parser(castTokens);
                 break;
             default:
-                throw new errors_1.UnsupportedOpenQASMVersionError("Unsupported OpenQASM version detected: ".concat(version.major));
+                throw new UnsupportedOpenQASMVersionError(`Unsupported OpenQASM version detected: ${version.major}`);
         }
     }
     else if (typeof version === "number") {
         switch (version) {
             case 2:
                 castTokens = tokens;
-                parser = new parser_1.default(castTokens);
+                parser = new Qasm2Parser(castTokens);
                 break;
             case 3:
                 castTokens = tokens;
-                parser = new parser_2.default(castTokens);
+                parser = new Qasm3Parser(castTokens);
                 break;
             default:
-                throw new errors_1.UnsupportedOpenQASMVersionError("Unsupported OpenQASM version detected: ".concat(version));
+                throw new UnsupportedOpenQASMVersionError(`Unsupported OpenQASM version detected: ${version}`);
         }
     }
-    else if (version === version_1.OpenQASMMajorVersion.Version2) {
+    else if (version === OpenQASMMajorVersion.Version2) {
         castTokens = tokens;
-        parser = new parser_1.default(castTokens);
+        parser = new Qasm2Parser(castTokens);
     }
-    else if (version === version_1.OpenQASMMajorVersion.Version3) {
+    else if (version === OpenQASMMajorVersion.Version3) {
         castTokens = tokens;
-        parser = new parser_2.default(castTokens);
+        parser = new Qasm3Parser(castTokens);
     }
     else {
         castTokens = tokens;
-        parser = new parser_2.default(castTokens);
+        parser = new Qasm3Parser(castTokens);
     }
-    var ast = parser.parse();
+    const ast = parser.parse();
     return ast;
 }

package/dist/qasm2/ast.d.ts

@@ -0,0 +1,159 @@
+/**
+ * OpenQASM 2.0 Abstract Syntax Tree Node Definitions
+ *
+ * This module defines the AST node classes for OpenQASM 2.0, which provides
+ * a simpler and more limited set of constructs compared to OpenQASM 3.0.
+ *
+ * OpenQASM 2.0 focuses on:
+ * - Basic quantum register (`qreg`) and classical register (`creg`) declarations
+ * - Gate definitions and applications
+ * - Measurement operations
+ * - Simple conditional statements
+ * - Basic arithmetic expressions
+ *
+ * Key limitations compared to 3.0:
+ * - No advanced classical types (only registers)
+ * - No control flow structures (loops, complex conditionals)
+ * - No function definitions or subroutines
+ * - Limited expression capabilities
+ *
+ * @module
+ *
+ * @example Basic OpenQASM 2.0 constructs
+ * ```typescript
+ * // Quantum register: qreg q[2];
+ * new QReg('q', 2)
+ *
+ * // Gate application: h q[0];
+ * new ApplyGate('h', [['q', 0]], [])
+ *
+ * // Measurement: measure q[0] -> c[0];
+ * new Measure('q', 'c', 0, 0)
+ * ```
+ */
+import { OpenQASMVersion } from "../version";
+/** Base class representing a basic AST node. */
+declare class AstNode {
+}
+/** Class representing the version statement. */
+declare class Version extends AstNode {
+    version: OpenQASMVersion;
+    constructor(version: OpenQASMVersion);
+}
+/** Class representing an include statement. */
+declare class Include extends AstNode {
+    filename: string;
+    constructor(filename: string);
+}
+/** Class representing a qubit register. */
+declare class QReg extends AstNode {
+    size: number;
+    id: string;
+    constructor(id: string, size: number);
+}
+/** Class representing a classical register. */
+declare class CReg extends AstNode {
+    size: number;
+    id: string;
+    constructor(id: string, size: number);
+}
+/** Class representing an identifier. */
+declare class Id extends AstNode {
+    id: string;
+    constructor(id: string);
+}
+/** Class representing a barrier. */
+declare class Barrier extends AstNode {
+    index: number;
+    register: string;
+    constructor(register: string, index?: number);
+}
+/** Class representing a variable. */
+declare class Variable extends AstNode {
+    value: string;
+    constructor(value: string);
+}
+/** Class representing a measurement. */
+declare class Measure extends AstNode {
+    src_index: number;
+    src_register: string;
+    dest_index: number;
+    dest_register: string;
+    constructor(src_register: string, dest_register: string, src_index?: number, dest_index?: number);
+}
+/** Class representing a gate application. */
+declare class ApplyGate extends AstNode {
+    name: string;
+    qubits: Array<[string, number?]>;
+    params: Array<AstNode>;
+    constructor(name: string, qubits: Array<[string, number?]>, params: Array<AstNode>);
+}
+/** Class representing a gate. */
+declare class Gate extends AstNode {
+    name: string;
+    registers: Array<string>;
+    params: Array<string>;
+    nodes: Array<AstNode>;
+    constructor(name: string, registers: Array<string>, params: Array<string>, nodes: Array<AstNode>);
+}
+/** Class representing an opaque gate declaration (only available in OpenQASM 2.x versions) */
+declare class Opaque extends AstNode {
+    name: string;
+    qubits: Array<[string, number?]>;
+    params: Array<string>;
+    constructor(name: string, qubits: Array<[string, number?]>, params?: Array<string>);
+}
+/** Class representing conditional. */
+declare class If extends AstNode {
+    register: string;
+    param: number;
+    gate: AstNode;
+    constructor(register: string, param: number, gate: AstNode);
+}
+/** Class representing minus. */
+declare class Minus extends AstNode {
+}
+/** Class representing plus. */
+declare class Plus extends AstNode {
+}
+/** Class representing times. */
+declare class Times extends AstNode {
+}
+/** Class representing power. */
+declare class Power extends AstNode {
+}
+/** Class representing division. */
+declare class Divide extends AstNode {
+}
+/** Class representing pi. */
+declare class Pi extends AstNode {
+}
+/** Class representing the square root. */
+declare class Sqrt extends AstNode {
+}
+/** Class representing natural logarithm. */
+declare class Ln extends AstNode {
+}
+/** Class representing exponentiation. */
+declare class Exp extends AstNode {
+}
+/** Class representing tagnent. */
+declare class Tan extends AstNode {
+}
+/** Class representing cosine. */
+declare class Cos extends AstNode {
+}
+/** Class representing sine. */
+declare class Sin extends AstNode {
+}
+/** Class representing an integer. */
+declare class NNInteger extends AstNode {
+    value: number;
+    constructor(value: number);
+}
+/** Class representing a real. */
+declare class Real extends AstNode {
+    value: number;
+    constructor(value: number);
+}
+export { AstNode, Version, Include, QReg, CReg, Barrier, Measure, ApplyGate, Gate, Opaque, If, Id, Divide, Plus, Minus, Times, Power, Sin, Cos, Tan, Exp, Ln, Sqrt, Pi, NNInteger, Real, Variable, };