qasm-ts 2.1.2 → 2.1.4

package/dist/qasm3/lexer.d.ts

@@ -0,0 +1,156 @@
+/**
+ * OpenQASM 3.0 Lexical Analyzer
+ *
+ * This module implements the lexer for OpenQASM 3.0, which transforms source code
+ * into a stream of tokens. The lexer handles the significantly expanded syntax of
+ * OpenQASM 3.0, including classical programming constructs, control flow, and
+ * advanced quantum features.
+ *
+ * Key features of the OpenQASM 3.0 lexer:
+ * - **Extended token set**: Classical types, control flow, functions
+ * - **Complex operators**: Compound assignment, bitwise operations
+ * - **Advanced literals**: Scientific notation, binary/hex/octal, durations
+ * - **Gate modifiers**: ctrl, negctrl, inv, pow with @ syntax
+ * - **Unicode support**: Mathematical constants (π, ℇ, τ)
+ * - **Robust error handling**: Detailed syntax error reporting
+ *
+ * The lexer performs several validation passes:
+ * - Semicolon verification for statement termination
+ * - Comment handling (single-line // and multi-line /* *\/)
+ * - String literal parsing with multiple quote styles
+ * - Number format validation and conversion
+ *
+ * @module
+ *
+ * @example Basic lexing process
+ * ```typescript
+ * const lexer = new Lexer('qubit[2] q; h q[0];');
+ * const tokens = lexer.lex();
+ * // Returns: [
+ * //   [Token.Id, 'qubit'], [Token.LSParen], [Token.NNInteger, 2],
+ * //   [Token.RSParen], [Token.Id, 'q'], [Token.Semicolon], ...
+ * // ]
+ * ```
+ */
+import { Token } from "./token";
+/**
+ * OpenQASM 3.0 Lexical Analyzer
+ *
+ * The main lexer class that processes OpenQASM 3.0 source code character by
+ * character and produces a stream of tokens for the parser to consume.
+ *
+ * The lexer maintains state including:
+ * - Current cursor position in the input
+ * - Input validation status
+ * - Error reporting context
+ *
+ * @example Creating and using a lexer
+ * ```typescript
+ * const source = `
+ *   OPENQASM 3.0;
+ *   include "stdgates.inc";
+ *   qubit[2] q;
+ *   h q[0];
+ *   cx q[0], q[1];
+ * `;
+ *
+ * const lexer = new Lexer(source);
+ * const tokens = lexer.lex();
+ * ```
+ */
+declare class Lexer {
+    /** The string to lex. */
+    input: string;
+    /** The lexer's current cursor location. */
+    cursor: number;
+    /**
+     * Creates a lexer.
+     * @param input - The string to lex.
+     * @param cursor - The starting cursor position.
+     */
+    constructor(input: string, cursor?: number);
+    /**
+     * Verifies that all appropriate lines end with a semicolon.
+     * @return A tuple of the status and if False, returns the problematic line.
+     */
+    verifyInput: () => [boolean, number | null, string | null];
+    /**
+     * Calling this method lexes the code represented by the provided string.
+     * @return An array of tokens and their corresponding values.
+     */
+    lex: () => Array<[Token, (number | string)?]>;
+    /**
+     * Reads a character and advances the cursor.
+     * @param num - Optional cursor position modifier.
+     */
+    readChar: (num?: number) => string;
+    /**
+     * Advances the cusor past the next comment.
+     */
+    skipComment: () => void;
+    /**
+     * Advances the cursor past a multiline comment.
+     */
+    skipMultiLineComment: () => void;
+    /**
+     * 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.
+     */
+    peekEq: (c: string) => boolean;
+    /**
+     * Reads a character without advancing the cursor.
+     * @param index - Optional peek position offset.
+     */
+    peek: () => string;
+    /**
+     * Reads a numeric value.
+     * @return The numeric value as a string.
+     */
+    readNumeric: () => string;
+    /**
+     * Reads an identifier.
+     * @return The identifier as a string.
+     */
+    readIdentifier: () => string;
+    /**
+     * Reds a keyword or identifier.
+     * If the character sequence matches a keyword, returns the corresponding token.
+     * Otherwise, treats the sequence as an identifier.
+     * @param char - The first character of the keyword or identifier.
+     * @return The corresponding token or identifier.
+     */
+    readKeywordOrIdentifier: (char: string) => [Token, string];
+    /**
+     * Reads a string literal.
+     * @param terminator - The literal's termination character.
+     * @return The literal as a string.
+     */
+    readStringLiteral: (terminator: string) => string;
+    /**
+     * Advances the cusor past the next block of whitespace.
+     */
+    skipWhitespace: () => null;
+    /**
+     * Lexes the next token.
+     * @return The next token and its corresponding value.
+     */
+    nextToken: () => [Token, (number | string)?];
+    /**
+     * Returns the line number where the current cursor is located.
+     * @param cursor - The current cursor position in the input string.
+     * @return The line number.
+     */
+    getLineNumber: (cursor: number) => number;
+    /**
+     * 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.
+     */
+    getCurrentLine: (cursor: number) => string;
+    /**
+     * Retruns an identifier or gate modifier.
+     */
+    lexGateModifier: (keyword: string) => [Token, (number | string)?];
+}
+export default Lexer;