qasm-ts 1.1.3 → 2.1.0

package/dist/lexer.js

@@ -1,300 +1,119 @@
 "use strict";
-exports.__esModule = true;
-var token_1 = require("./token");
-var errors_1 = require("./errors");
 /**
- * Returns whether a given character could be an element of a numeric value.
- * @param c - The character.
- * @return Whether the character is numeric.
+ * 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]
+ * // ]
+ * ```
  */
-function isNumeric(c) {
-    return (c == '.') || !isNaN(parseInt(c));
-}
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lex = lex;
+var lexer_1 = require("./qasm2/lexer");
+var lexer_2 = require("./qasm3/lexer");
+var version_1 = require("./version");
+var errors_1 = require("./errors");
 /**
- * Returns whether a given character is a letter.
- * @param c - The character.
- * @return Whether the character is a letter.
+ * 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"
+ * ```
  */
-function isLetter(c) {
-    if (c.match(/[a-z]/i)) {
-        return true;
+function lex(qasm, cursor, version) {
+    var lexer;
+    if (version instanceof version_1.OpenQASMVersion) {
+        switch (version.major) {
+            case version_1.OpenQASMMajorVersion.Version2:
+                lexer = new lexer_1.default(qasm, cursor);
+                break;
+            case version_1.OpenQASMMajorVersion.Version3:
+                lexer = new lexer_2.default(qasm, cursor);
+                break;
+            default:
+                throw new errors_1.UnsupportedOpenQASMVersionError("Unsupported OpenQASM version detected: ".concat(version.major));
+        }
     }
-    return false;
-}
-/**
- * Returns whether a given character is alphanumeric.
- * @param c - The character.
- * @return Whether the character is alphanumeric.
- */
-function isAlpha(c) {
-    if (c.match(/^[0-9a-zA-Z]+$/)) {
-        return true;
+    else if (typeof version === "number") {
+        switch (version) {
+            case 2:
+                lexer = new lexer_1.default(qasm, cursor);
+                break;
+            case 3:
+                lexer = new lexer_2.default(qasm, cursor);
+                break;
+            default:
+                throw new errors_1.UnsupportedOpenQASMVersionError("Unsupported OpenQASM version detected: ".concat(version));
+        }
     }
-    return false;
-}
-/**
- * Returns whether a given character is a newline character.
- * @param c - The character.
- * @return Whether the character is a newline.
- */
-function isNewline(c) {
-    if (c.match(/\n|\r(?!\n)|\u2028|\u2029|\r\n/g)) {
-        return true;
+    else if (version === version_1.OpenQASMMajorVersion.Version2) {
+        lexer = new lexer_1.default(qasm, cursor);
     }
-    return false;
-}
-/** Class representing a lexer. */
-var Lexer = /** @class */ (function () {
-    /**
-     * Creates a lexer.
-     * @param input - The string to lex.
-     * @param cursor - The starting cursor position.
-     */
-    function Lexer(input, cursor) {
-        var _this = this;
-        if (cursor === void 0) { cursor = 0; }
-        this.verifyInput = function () {
-            var lines = _this.input.split(/\n|\r(?!\n)|\u2028|\u2029|\r\n/g);
-            for (var i = 0; i < lines.length; i++) {
-                if (!lines[i].startsWith('//')
-                    && !(lines[i].length == 0)
-                    && !(lines[i].includes('gate'))
-                    && !(lines[i].trim() == '{' || lines[i].trim() == '}')
-                    && !lines[i].includes(';')) {
-                    return false;
-                }
-            }
-            return true;
-        };
-        /**
-         * Calling this method lexes the code represented by the provided string.
-         * @return An array of tokens and their corresponding values.
-         */
-        this.lex = function () {
-            var tokens = [];
-            var token;
-            if (!_this.verifyInput()) {
-                throw errors_1.MissingSemicolonError;
-            }
-            while (_this.cursor < _this.input.length) {
-                token = _this.nextToken();
-                if (token) {
-                    tokens.push(token);
-                }
-            }
-            return tokens;
-        };
-        /**
-        * Reads a character and advances the cursor.
-        * @param num - Optional cursor position modifier.
-        */
-        this.readChar = function (num) {
-            if (num === void 0) { num = 1; }
-            _this.cursor += num;
-            return _this.input[_this.cursor - num];
-        };
-        /**
-         * Advances the cusor past the next comment.
-         */
-        this.skipComment = function () {
-            var char = '';
-            while (!isNewline(char)) {
-                char = _this.readChar();
-            }
-        };
-        /**
-         * Determines whether the next character to process equals a given character.
-         * @param c - The given character.
-         * @return Whether the next character equals the given character.
-         */
-        this.peekEq = function (c) { return (_this.peek() == c); };
-        /**
-         * Reads a character without advancing the cursor.
-         * @param index - Optional peek position offset.
-         */
-        this.peek = function () { return _this.input[_this.cursor]; };
-        /**
-         * Reads a numeric value.
-         * @return The numeric value as a string.
-         */
-        this.readNumeric = function () {
-            var num = '';
-            while (isNumeric(_this.peek())) {
-                num += _this.readChar();
-            }
-            return num;
-        };
-        /**
-         * Reads an identifier.
-         * @return The identifier as a string.
-         */
-        this.readIdentifier = function () {
-            var id = '';
-            while (isAlpha(_this.peek())) {
-                id += _this.readChar();
-            }
-            return id;
-        };
-        /**
-         * Reads a string literal.
-         * @param terminator - The literal's termination character.
-         * @return The literal as a string.
-         */
-        this.readStringLiteral = function (terminator) {
-            var lit = '';
-            var char = '';
-            while (!(terminator == char)) {
-                char = _this.readChar();
-                lit += char;
-            }
-            return lit;
-        };
-        /**
-         * Advances the cusor past the next block of whitespace.
-         */
-        this.skipWhitespace = function () {
-            while (' \t\n\r\v'.indexOf(_this.peek()) > -1) {
-                _this.cursor += 1;
-            }
-            return null;
-        };
-        /**
-         * Lexes the next token.
-         * @return The next token and its corresponding value.
-         */
-        this.nextToken = function () {
-            _this.skipWhitespace();
-            if (_this.cursor == _this.input.length) {
-                return [token_1.Token.EndOfFile];
-            }
-            var char = _this.peek();
-            _this.readChar();
-            switch (char) {
-                case '=':
-                    if (_this.peekEq('=')) {
-                        _this.readChar();
-                        return [token_1.Token.Equals];
-                    }
-                    else {
-                        throw errors_1.BadEqualsError;
-                    }
-                case '-':
-                    if (_this.peekEq('>')) {
-                        _this.readChar();
-                        return [token_1.Token.Arrow];
-                    }
-                    else {
-                        return [token_1.Token.Minus];
-                    }
-                case '+':
-                    return [token_1.Token.Plus];
-                case '*':
-                    return [token_1.Token.Times];
-                case '^':
-                    return [token_1.Token.Power];
-                case ';':
-                    return [token_1.Token.Semicolon];
-                case ',':
-                    return [token_1.Token.Comma];
-                case '(':
-                    return [token_1.Token.LParen];
-                case '[':
-                    return [token_1.Token.LSParen];
-                case '{':
-                    return [token_1.Token.LCParen];
-                case ')':
-                    return [token_1.Token.RParen];
-                case ']':
-                    return [token_1.Token.RSParen];
-                case '}':
-                    return [token_1.Token.RCParen];
-                case '/':
-                    if (_this.peekEq('/')) {
-                        _this.skipComment();
-                        return;
-                    }
-                    else {
-                        return [token_1.Token.Divide];
-                    }
-                case 'g':
-                    if ((_this.input[_this.cursor] == 'a')
-                        && (_this.input[_this.cursor + 1] == 't')
-                        && (_this.input[_this.cursor + 2] == 'e')) {
-                        _this.readChar(3);
-                        return [token_1.Token.Gate];
-                    }
-                    var literal = char + _this.readIdentifier();
-                    return [token_1.lookup(literal), new String(literal)];
-                case 'q':
-                    if ((_this.input[_this.cursor] == 'r')
-                        && (_this.input[_this.cursor + 1] == 'e')
-                        && (_this.input[_this.cursor + 2] == 'g')) {
-                        _this.readChar(3);
-                        return [token_1.Token.QReg];
-                    }
-                    var qregLit = char + _this.readIdentifier();
-                    return [token_1.lookup(qregLit), new String(qregLit)];
-                case 'c':
-                    if ((_this.input[_this.cursor] == 'r')
-                        && (_this.input[_this.cursor + 1] == 'e')
-                        && (_this.input[_this.cursor + 2] == 'g')) {
-                        _this.readChar(3);
-                        return [token_1.Token.QReg];
-                    }
-                    var cregLit = char + _this.readIdentifier();
-                    return [token_1.lookup(cregLit), new String(cregLit)];
-                case 'b':
-                    if ((_this.input[_this.cursor] == 'a')
-                        && (_this.input[_this.cursor + 1] == 'r')
-                        && (_this.input[_this.cursor + 2] == 'r')
-                        && (_this.input[_this.cursor + 3] == 'i')
-                        && (_this.input[_this.cursor + 4] == 'e')
-                        && (_this.input[_this.cursor + 5] == 'r')) {
-                        _this.readChar(6);
-                        return [token_1.Token.Barrier];
-                    }
-                    var barLit = char + _this.readIdentifier();
-                    return [token_1.lookup(barLit), new String(barLit)];
-                case 'm':
-                    if ((_this.input[_this.cursor] == 'e')
-                        && (_this.input[_this.cursor + 1] == 'a')
-                        && (_this.input[_this.cursor + 2] == 's')
-                        && (_this.input[_this.cursor + 3] == 'u')
-                        && (_this.input[_this.cursor + 4] == 'r')
-                        && (_this.input[_this.cursor + 5] == 'e')) {
-                        _this.readChar(6);
-                        return [token_1.Token.Measure];
-                    }
-                    var measureLit = char + _this.readIdentifier();
-                    return [token_1.lookup(measureLit), new String(measureLit)];
-                case '\"':
-                    var stringLiteral = char + _this.readStringLiteral('\"');
-                    return [token_1.Token.String, new String(stringLiteral)];
-                case '\’':
-                    var singleStringLiteral = char + _this.readStringLiteral('\’');
-                    return [token_1.Token.String, new String(singleStringLiteral)];
-                default:
-                    if (isLetter(char)) {
-                        var literal_1 = char + _this.readIdentifier();
-                        return [token_1.lookup(literal_1), new String(literal_1)];
-                    }
-                    else if (isNumeric(char)) {
-                        var num = char + _this.readNumeric();
-                        if (num.indexOf('.') != -1) {
-                            return [token_1.Token.Real, parseFloat(num)];
-                        }
-                        else {
-                            return [token_1.Token.NNInteger, parseFloat(num)];
-                        }
-                    }
-                    else {
-                        return [token_1.Token.Illegal];
-                    }
-            }
-        };
-        this.input = input;
-        this.cursor = cursor;
+    else if (version === version_1.OpenQASMMajorVersion.Version3) {
+        lexer = new lexer_2.default(qasm, cursor);
+    }
+    else {
+        lexer = new lexer_2.default(qasm, cursor);
     }
-    return Lexer;
-}());
-exports["default"] = Lexer;
+    var tokens = lexer.lex();
+    return tokens;
+}

package/dist/main.js

@@ -1,26 +1,131 @@
 "use strict";
-exports.__esModule = true;
-var parser_1 = require("./parser");
-var lexer_1 = require("./lexer");
+/* 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");
 /**
- * Returns the abstract syntax tree for a given string of QASM code.
- * @param qasm - The code string.
- * @return The corresponding AST.
+ * 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
+ * ```
  */
-function parseString(qasm) {
-    var lexer = new lexer_1["default"](qasm, 0);
-    var tokens = lexer.lex();
-    var parser = new parser_1["default"](tokens);
-    var ast = parser.parse();
+function parseString(qasm, version, verbose, stringify) {
+    var ast;
+    var tokens = (0, lexer_1.lex)(qasm, undefined, version);
+    ast = (0, parser_1.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;
 }
 /**
- * Returns the abstract syntax tree for a given QASM file.
- * @param file - The file location.
- * @return The corresponding 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
+ * ```
  */
-exports.parse = function (file) {
-    return parseString(fs.readFileSync(file, 'utf8'));
-};
-exports.parseString = parseString;
+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") {
+        var 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];
+            result[key] = getDetailedOutput(value);
+        }
+        return result;
+    }
+    else {
+        return object;
+    }
+}