qasm-ts 2.1.3 → 2.1.4

package/dist/qasm2/lexer.js

@@ -0,0 +1,483 @@
+/**
+ * OpenQASM 2.0 Lexical Analyzer
+ *
+ * This module implements the lexer for OpenQASM 2.0, which provides a simpler
+ * token set compared to OpenQASM 3.0. The lexer focuses on basic quantum circuit
+ * constructs without the advanced classical programming features of version 3.0.
+ *
+ * Key characteristics of OpenQASM 2.0 lexing:
+ * - **Limited token set**: Basic quantum and classical registers only
+ * - **Simple operators**: Basic arithmetic and comparison operators
+ * - **No control flow**: No tokens for loops, conditionals, or functions
+ * - **Gate-focused**: Emphasis on gate definitions and applications
+ * - **Mathematical functions**: Built-in math functions (sin, cos, etc.)
+ *
+ * Supported constructs:
+ * - Quantum registers (`qreg`) and classical registers (`creg`)
+ * - Gate definitions and applications
+ * - Measurements with arrow notation (`->`)
+ * - Basic arithmetic expressions for gate parameters
+ * - Include statements for library files
+ *
+ * @module
+ *
+ * @example OpenQASM 2.0 lexing
+ * ```typescript
+ * const lexer = new Lexer('qreg q[2]; h q[0]; measure q -> c;');
+ * const tokens = lexer.lex();
+ * // Produces tokens for register declaration, gate, and measurement
+ * ```
+ */
+import { Token, lookup } from "./token";
+import { BadEqualsError, MissingSemicolonError, UnsupportedOpenQASMVersionError, } from "../errors";
+/**
+ * Handles throwing lexer errors with basic stack trace.
+ * @param error - The error to throw.
+ * @param number - The line number in the source code.
+ * @param code - The source code that the error is about.
+ */
+function throwLexerError(error, line, code) {
+    throw new error(`Line ${line}: ${code}`);
+}
+/**
+ * Returns whether a given character could be an element of a numeric value.
+ * @param c - The character.
+ * @return Whether the character is numeric.
+ */
+function isNumeric(c) {
+    return c == "." || !isNaN(parseInt(c));
+}
+/**
+ * Returns whether a given character is a letter.
+ * @param c - The character.
+ * @param matchCase - Whether to check for a letter that is upper case, lower case, or either. (optional)
+ * @return Whether the character is a letter.
+ */
+function isLetter(c, matchCase) {
+    switch (matchCase) {
+        case "upper":
+            return /^[A-Z]$/.test(c);
+        case "lower":
+            return /^[a-z]$/.test(c);
+        default:
+            return /^[A-Za-z]$/.test(c);
+    }
+}
+/**
+ * Returns whether a given character is unicode.
+ * @param c - The character.
+ * @param excludePi - Whether to exclude the Pi symbol from consideration.
+ * @return - Whether the given character is valid unicode.
+ */
+function isUnicode(c, excludePi) {
+    const isBasicUnicode = /^\u0000-\u00ff/.test(c);
+    switch (excludePi) {
+        case true:
+            return isBasicUnicode && c !== "\u03C0";
+        case false:
+            return isBasicUnicode;
+        default:
+            return isBasicUnicode;
+    }
+}
+/**
+ * Returns whether a given character is alphanumeric.
+ * @param c - The character.
+ * @return Whether the character is alphanumeric.
+ */
+function isAlpha(c) {
+    return /^[0-9a-zA-Z]+$/.test(c);
+}
+/**
+ * Returns whether a given character is a newline character.
+ * @param c - The character.
+ * @return Whether the character is a newline.
+ */
+function isNewline(c) {
+    return /\n|\r(?!\n)|\u2028|\u2029|\r\n/.test(c);
+}
+/**
+ * OpenQASM 2.0 Lexical Analyzer
+ *
+ * A simpler lexer implementation focused on the core quantum circuit description
+ * features of OpenQASM 2.0. This lexer handles the essential constructs needed
+ * for basic quantum programming without the complexity of classical programming
+ * language features.
+ *
+ * @example Basic OpenQASM 2.0 tokenization
+ * ```typescript
+ * const source = `
+ *   OPENQASM 2.0;
+ *   include "qelib1.inc";
+ *   qreg q[2];
+ *   creg c[2];
+ *   h q[0];
+ *   cx q[0],q[1];
+ *   measure q -> c;
+ * `;
+ *
+ * const lexer = new Lexer(source);
+ * const tokens = lexer.lex();
+ * ```
+ */
+class Lexer {
+    /**
+     * Creates a lexer.
+     * @param input - The string to lex.
+     * @param cursor - The starting cursor position.
+     */
+    constructor(input, cursor = 0) {
+        /**
+         * Verifies that all appropriate lines end with a semicolon.
+         * @return A tuple of the status and if False, returns the problematic line.
+         */
+        this.verifyInput = () => {
+            const lines = this.input.split(/\n|\r(?!\n)|\u2028|\u2029|\r\n/g);
+            for (let 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, i + 1, lines[i]];
+                }
+            }
+            return [true, null, null];
+        };
+        /**
+         * Calling this method lexes the code represented by the provided string.
+         * @return An array of tokens and their corresponding values.
+         */
+        this.lex = () => {
+            const tokens = [];
+            let token;
+            const verifyInputResult = this.verifyInput();
+            if (!verifyInputResult[0]) {
+                throwLexerError(MissingSemicolonError, verifyInputResult[1], verifyInputResult[2]);
+            }
+            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 = (num = 1) => {
+            this.cursor += num;
+            return this.input[this.cursor - num];
+        };
+        /**
+         * Advances the cusor past the next comment.
+         */
+        this.skipComment = () => {
+            let 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 = (c) => this.peek() == c;
+        /**
+         * Reads a character without advancing the cursor.
+         * @param index - Optional peek position offset.
+         */
+        this.peek = () => this.input[this.cursor];
+        /**
+         * Reads a numeric value.
+         * @return The numeric value as a string.
+         */
+        this.readNumeric = () => {
+            let num = "";
+            while (isNumeric(this.peek())) {
+                num += this.readChar();
+            }
+            return num;
+        };
+        /**
+         * Reads an identifier.
+         * @return The identifier as a string.
+         */
+        this.readIdentifier = () => {
+            let id = "";
+            let next = this.peek();
+            while (isAlpha(next) || next == "_" || isUnicode(next)) {
+                id += this.readChar();
+                next = this.peek();
+            }
+            return id;
+        };
+        /**
+         * Reads a string literal.
+         * @param terminator - The literal's termination character.
+         * @return The literal as a string.
+         */
+        this.readStringLiteral = (terminator) => {
+            let lit = "";
+            let char = "";
+            while (!(terminator == char)) {
+                char = this.readChar();
+                lit += char;
+            }
+            return lit;
+        };
+        /**
+         * Advances the cusor past the next block of whitespace.
+         */
+        this.skipWhitespace = () => {
+            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 = () => {
+            this.skipWhitespace();
+            if (this.cursor == this.input.length) {
+                return [Token.EndOfFile];
+            }
+            const char = this.peek();
+            this.readChar();
+            switch (char) {
+                case "=":
+                    if (this.peekEq("=")) {
+                        this.readChar();
+                        return [Token.Equals];
+                    }
+                    else {
+                        throwLexerError(BadEqualsError, this.getLineNumber(this.cursor), this.getCurrentLine(this.cursor));
+                        break;
+                    }
+                case "-":
+                    if (this.peekEq(">")) {
+                        this.readChar();
+                        return [Token.Arrow];
+                    }
+                    else {
+                        return [Token.Minus];
+                    }
+                case "+":
+                    return [Token.Plus];
+                case "*":
+                    return [Token.Times];
+                case "^":
+                    return [Token.Power];
+                case ";":
+                    return [Token.Semicolon];
+                case ",":
+                    return [Token.Comma];
+                case "(":
+                    return [Token.LParen];
+                case "[":
+                    return [Token.LSParen];
+                case "{":
+                    return [Token.LCParen];
+                case ")":
+                    return [Token.RParen];
+                case "]":
+                    return [Token.RSParen];
+                case "}":
+                    return [Token.RCParen];
+                case "/":
+                    if (this.peekEq("/")) {
+                        this.skipComment();
+                        return;
+                    }
+                    else {
+                        return [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.Gate];
+                    }
+                    {
+                        const literal = char + this.readIdentifier();
+                        return [lookup(literal), 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.QReg];
+                    }
+                    {
+                        const qregLit = char + this.readIdentifier();
+                        return [lookup(qregLit), 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.CReg];
+                    }
+                    {
+                        const cregLit = char + this.readIdentifier();
+                        return [lookup(cregLit), 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.Barrier];
+                    }
+                    {
+                        const barLit = char + this.readIdentifier();
+                        return [lookup(barLit), 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.Measure];
+                    }
+                    {
+                        const measureLit = char + this.readIdentifier();
+                        return [lookup(measureLit), measureLit];
+                    }
+                case "O":
+                    if (this.input[this.cursor].toLowerCase() == "p" &&
+                        this.input[this.cursor + 1].toLowerCase() == "e" &&
+                        this.input[this.cursor + 2].toLowerCase() == "n" &&
+                        this.input[this.cursor + 3] == "Q" &&
+                        this.input[this.cursor + 4] == "A" &&
+                        this.input[this.cursor + 5] == "S" &&
+                        this.input[this.cursor + 6] == "M") {
+                        this.readChar(7);
+                        let offset = 0;
+                        while (this.cursor + offset < this.input.length &&
+                            " \t".indexOf(this.input[this.cursor + offset]) > -1) {
+                            offset++;
+                        }
+                        // Read the major version
+                        let majorVersion = "";
+                        while (this.cursor + offset < this.input.length &&
+                            !isNaN(parseInt(this.input[this.cursor + offset], 10))) {
+                            majorVersion += this.input[this.cursor + offset];
+                            offset++;
+                        }
+                        // Attempt to read the minor version
+                        let minorVersion = undefined;
+                        if (this.input[this.cursor + offset] == ".") {
+                            offset++;
+                            minorVersion = "";
+                            while (this.cursor + offset < this.input.length &&
+                                !isNaN(parseInt(this.input[this.cursor + offset], 10))) {
+                                minorVersion += this.input[this.cursor + offset];
+                                offset++;
+                            }
+                        }
+                        // Parse major and minor versions
+                        const major = parseInt(majorVersion, 10);
+                        const minor = minorVersion ? parseInt(minorVersion, 10) : undefined;
+                        if (major !== 2) {
+                            throw new UnsupportedOpenQASMVersionError(`Unsupported OpenQASM version detected: ${majorVersion}.${minor !== null && minor !== void 0 ? minor : 0}`);
+                        }
+                        return [Token.OpenQASM];
+                    }
+                    {
+                        const openQasmLit = char + this.readIdentifier();
+                        return [lookup[openQasmLit], openQasmLit];
+                    }
+                case "i":
+                    if (this.input[this.cursor] == "n" &&
+                        this.input[this.cursor + 1] == "c" &&
+                        this.input[this.cursor + 2] == "l" &&
+                        this.input[this.cursor + 3] == "u" &&
+                        this.input[this.cursor + 4] == "d" &&
+                        this.input[this.cursor + 5] == "e") {
+                        this.readChar(6);
+                        return [Token.Include];
+                    }
+                    {
+                        const includeLit = char + this.readIdentifier();
+                        return [lookup(includeLit), includeLit];
+                    }
+                case "o":
+                    if (this.input[this.cursor] == "p" &&
+                        this.input[this.cursor + 1] == "a" &&
+                        this.input[this.cursor + 2] == "q" &&
+                        this.input[this.cursor + 3] == "u" &&
+                        this.input[this.cursor + 4] == "e") {
+                        this.readChar(5);
+                        return [Token.Opaque];
+                    }
+                    {
+                        const opaqueLit = char + this.readIdentifier();
+                        return [lookup(opaqueLit), opaqueLit];
+                    }
+                case '"': {
+                    const stringLiteral = char + this.readStringLiteral('"');
+                    return [Token.String, stringLiteral];
+                }
+                case "’": {
+                    const singleStringLiteral = char + this.readStringLiteral("’");
+                    return [Token.String, singleStringLiteral];
+                }
+                default:
+                    if (isLetter(char)) {
+                        const literal = char + this.readIdentifier();
+                        return [lookup(literal), literal];
+                    }
+                    else if (isNumeric(char)) {
+                        const num = char + this.readNumeric();
+                        if (num.indexOf(".") != -1) {
+                            return [Token.Real, parseFloat(num)];
+                        }
+                        else {
+                            return [Token.NNInteger, parseFloat(num)];
+                        }
+                    }
+                    else {
+                        return [Token.Illegal];
+                    }
+            }
+        };
+        /**
+         * Returns the line number where the current cursor is located.
+         * @param cursor - The current cursor position in the input string.
+         * @return The line number.
+         */
+        this.getLineNumber = (cursor) => {
+            return this.input
+                .substring(0, cursor)
+                .split(/\n|\r(?!\n)|\u2028|\u2029|\r\n/).length;
+        };
+        /**
+         * Returns the current line of code where the cursor is located.
+         * @param cursor - The current cursor position in the input string.
+         * @return The specific line where the cursor is located.
+         */
+        this.getCurrentLine = (cursor) => {
+            const lines = this.input.split(/\n|\r(?!\n)|\u2028|\u2029|\r\n/);
+            const lineNumber = this.getLineNumber(cursor);
+            return lines[lineNumber - 1];
+        };
+        this.input = input;
+        this.cursor = cursor;
+    }
+}
+export default Lexer;

package/dist/qasm2/parser.d.ts

@@ -0,0 +1,187 @@
+/**
+ * OpenQASM 2.0 Parser Implementation
+ *
+ * This module implements a parser for OpenQASM 2.0 that focuses on the core
+ * quantum circuit description language without the advanced features of version 3.0.
+ * The parser handles quantum and classical register declarations, gate definitions
+ * and applications, measurements, and basic control structures.
+ *
+ * OpenQASM 2.0 parsing capabilities:
+ * - **Register declarations**: qreg and creg with size specifications
+ * - **Gate definitions**: Custom gate definitions with parameters and bodies
+ * - **Gate applications**: Built-in and custom gate applications
+ * - **Measurements**: Quantum measurements with classical result storage
+ * - **Basic conditionals**: Simple if statements based on classical register values
+ * - **Arithmetic expressions**: Parameter expressions for gate operations
+ * - **Opaque gates**: External gate declarations
+ *
+ * The parser maintains a list of known gates and validates gate applications
+ * against declared gates and built-in operations.
+ *
+ * @module
+ *
+ * @example Parsing OpenQASM 2.0 code
+ * ```typescript
+ * const tokens = lexer.lex();
+ * const parser = new Parser(tokens);
+ * const ast = parser.parse();
+ *
+ * // AST contains simplified node structure for OpenQASM 2.0
+ * ```
+ */
+import { Token } from "./token";
+import { AstNode, Version, Include } from "./ast";
+/**
+ * OpenQASM 2.0 Parser
+ *
+ * A straightforward recursive descent parser for OpenQASM 2.0 that produces
+ * a simplified AST structure appropriate for the more limited feature set
+ * of the 2.0 language specification.
+ *
+ * @example Basic parsing workflow
+ * ```typescript
+ * const parser = new Parser(tokens);
+ * const ast = parser.parse();
+ *
+ * // Process the resulting AST nodes
+ * ast.forEach(node => {
+ *   if (node instanceof QReg) {
+ *     console.log(`Quantum register: ${node.id}[${node.size}]`);
+ *   }
+ * });
+ * ```
+ */
+declare class Parser {
+    /** The tokens to parse. */
+    tokens: Array<[Token, (number | string)?]>;
+    /** The allowed gates. */
+    gates: Array<string>;
+    /**
+     * Creates a parser.
+     * @param tokens - Tokens to parse.
+     */
+    constructor(tokens: Array<[Token, (number | string)?]>);
+    /**
+     * Calling this method parses the code represented by the provided tokens.
+     * @return The abstract syntax tree.
+     */
+    parse(): Array<AstNode>;
+    /**
+    * Delegates the parsing of the next set of tokens to the appropriate method.
+    * @param tokens - Remaining tokens to parse.
+    * @param allowVariables - Whether encountered identifiers should be consider
+        variable initializations or references.
+    * @return A set of AST nodes.
+    */
+    parseNode(tokens: Array<[Token, (number | string)?]>, allowVariables?: boolean): Array<AstNode>;
+    /**
+     * Checks if the next tokens match those expected.
+     * @param tokens - Remaining tokens to parse.
+     * @param expectedTokens - Expected tokens.
+     * @return Whether these is a match.
+     */
+    matchNext(tokens: Array<[Token, (number | string)?]>, expectedTokens: Array<Token>): boolean;
+    /**
+     * Parses a quantum register.
+     * @param tokens - Remaining tokens to parse.
+     * @return An AST node representing the quantum register.
+     */
+    qreg(tokens: Array<[Token, (number | string)?]>): AstNode;
+    /**
+     * Parses a classical register.
+     * @param tokens - Remaining tokens to parse.
+     * @return An AST node representing the classical register.
+     */
+    creg(tokens: Array<[Token, (number | string)?]>): AstNode;
+    /**
+     * Parses a conditional.
+     * @param tokens - Remaining tokens to parse.
+     * @return An AST node representing the conditional.
+     */
+    conditional(tokens: Array<[Token, (number | string)?]>): AstNode;
+    /**
+     * Parses a barrier.
+     * @param tokens - Remaining tokens to parse.
+     * @return An AST node representing the barrier.
+     */
+    barrier(tokens: Array<[Token, (number | string)?]>): AstNode;
+    /**
+     * Parses a measurement.
+     * @param tokens - Remaining tokens to parse.
+     * @return An AST node representing the measurement.
+     */
+    measure(tokens: Array<[Token, (number | string)?]>): AstNode;
+    /**
+     * Parses an application of one of the allowed gates.
+     * @param tokens - Remaining tokens to parse.
+     * @return An AST node representing the gate application.
+     */
+    application(tokens: Array<[Token, (number | string)?]>, op: string): Array<AstNode>;
+    /**
+     * Parses a subroutine used in a custom gate definition.
+     * @param tokens - Expression tokens to parse.
+     * @return A parsed subroutine.
+     */
+    sub(tokens: Array<[Token, (number | string)?]>): Array<AstNode>;
+    /**
+     * Parses a parameter value.
+     * @param tokens - Tokens to parse.
+     * @return An AST node representing the parameter value.
+     */
+    matchParam(tokens: Array<[Token, (number | string)?]>): AstNode;
+    /**
+     * Parses a list of parameter values.
+     * @param tokens - Tokens to parse.
+     * @return An array of AST nodes representing the parameter values.
+     */
+    matchParamList(tokens: Array<[Token, (number | string)?]>): Array<Array<AstNode>>;
+    /**
+     * Parses an argument value.
+     * @param tokens - Tokens to parse.
+     * @return An AST node representing the argument value.
+     */
+    matchArg(tokens: Array<[Token, (number | string)?]>): number;
+    /**
+     * Parses a list of argument values.
+     * @param tokens - Tokens to parse.
+     * @return An array of AST nodes representing the argument values.
+     */
+    matchArgList(tokens: Array<[Token, (number | string)?]>): Array<[string, number?]>;
+    /**
+     * Parses an include statement.
+     * @param tokens - Tokens to parse.
+     * @return An Include node representing the include statement.
+     */
+    include(tokens: Array<[Token, (number | string)?]>): Include;
+    /**
+     * Parses the version header and sets the parser version.
+     * @param tokens - Tokens to parse.
+     * @return A Version node representing the version statement.
+     */
+    versionHeader(tokens: Array<[Token, (number | string)?]>): Version;
+    /**
+     * Parses a list of identifiers.
+     * @param tokens - Tokens to parse.
+     * @return An array of AST nodes representing the identifiers.
+     */
+    matchIdList(tokens: Array<[Token, (number | string)?]>): Array<string>;
+    /**
+     * Parses a gate.
+     * @param tokens - Remaining tokens to parse.
+     * @return An AST node representing the gate.
+     */
+    gate(tokens: Array<[Token, (number | string)?]>): AstNode;
+    /**
+     * Parses an opaque declaration if using OpenQASM 2. If using OpenQASM 3 it skips the line.
+     * @param tokens - Remaining tokens to parse.
+     * @return An AST node representing the opaque declaration.
+     */
+    opaque(tokens: Array<[Token, (number | string)?]>): AstNode;
+    /**
+     * Validates whether a register or gate identifier.
+     * @param identifier - The identifier to validate.
+     * @return Boolean indicating successful validation or not.
+     */
+    private validateIdentifier;
+}
+export default Parser;