qasm-ts 2.1.2 → 2.1.4

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;