qasm-ts 2.0.0 → 2.1.0

package/dist/qasm2/parser.js

@@ -1,10 +1,60 @@
 "use strict";
+/**
+ * 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
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 var token_1 = require("./token");
 var version_1 = require("../version");
 var errors_1 = require("../errors");
 var ast_1 = require("./ast");
-/** Class representing a token parser. */
+/**
+ * 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}]`);
+ *   }
+ * });
+ * ```
+ */
 var Parser = /** @class */ (function () {
     /**
      * Creates a parser.

package/dist/qasm2/token.js

@@ -1,9 +1,39 @@
 "use strict";
+/**
+ * OpenQASM 2.0 Token Definitions and Utilities
+ *
+ * This module defines the token types used in OpenQASM 2.0 syntax. OpenQASM 2.0
+ * has a simpler token set compared to 3.0, focusing on basic quantum operations
+ * and classical registers without advanced control flow or data types.
+ *
+ * Key differences from OpenQASM 3.0:
+ * - Limited to `qreg` and `creg` declarations (no advanced types)
+ * - No control flow tokens (if/else/for/while)
+ * - No subroutine or function definitions
+ * - Simpler expression and operator support
+ *
+ * @module
+ *
+ * @example OpenQASM 2.0 token usage
+ * ```typescript
+ * import { lookup, Token } from './qasm2/token';
+ *
+ * console.log(lookup('qreg'));    // Token.QReg
+ * console.log(lookup('barrier')); // Token.Barrier
+ * console.log(lookup('measure')); // Token.Measure
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Token = void 0;
 exports.notParam = notParam;
 exports.lookup = lookup;
 exports.inverseLookup = inverseLookup;
+/**
+ * Enumeration of OpenQASM 2.0 token types.
+ *
+ * This simplified token set reflects OpenQASM 2.0's focus on basic quantum
+ * circuit description without the advanced features of version 3.0.
+ */
 var Token;
 (function (Token) {
     // 0; invalid or unrecognized token

package/dist/qasm3/lexer.js

@@ -1,6 +1,40 @@
 "use strict";
 /* eslint-disable no-useless-escape */
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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], ...
+ * // ]
+ * ```
+ */
 var token_1 = require("./token");
 var errors_1 = require("../errors");
 /**
@@ -69,7 +103,31 @@ function isAlpha(c) {
 function isNewline(c) {
     return /\n|\r(?!\n)|\u2028|\u2029|\r\n/.test(c);
 }
-/** Class representing a lexer. */
+/**
+ * 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();
+ * ```
+ */
 var Lexer = /** @class */ (function () {
     /**
      * Creates a lexer.

package/dist/qasm3/parser.js

@@ -1,6 +1,37 @@
 "use strict";
 /* eslint-disable  @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * OpenQASM 3.0 Parser Implementation
+ *
+ * This module implements a recursive descent parser for OpenQASM 3.0 that transforms
+ * a stream of tokens into an Abstract Syntax Tree (AST). The parser handles the full
+ * OpenQASM 3.0 language specification including classical programming constructs,
+ * control flow, quantum operations, and advanced features.
+ *
+ * Key parsing capabilities:
+ * - **Classical types**: int, uint, float, bool, bit, complex, angle
+ * - **Control flow**: if/else, for/while loops, switch/case statements
+ * - **Functions**: def, return, extern declarations, subroutine calls
+ * - **Quantum operations**: gate definitions/calls, measurements, barriers, delays
+ * - **Advanced features**: arrays, timing constructs, calibration grammar
+ * - **Expressions**: Arithmetic, logical, function calls with proper precedence
+ *
+ * The parser maintains context about:
+ * - Defined gates (built-in, standard library, custom)
+ * - Declared subroutines and external functions
+ * - Array declarations and aliases
+ * - Type information for validation
+ *
+ * @module
+ *
+ * @example Basic parsing workflow
+ * ```typescript
+ * const tokens = lexer.lex();
+ * const parser = new Parser(tokens);
+ * const ast = parser.parse();
+ * ```
+ */
 var token_1 = require("./token");
 var version_1 = require("../version");
 var errors_1 = require("../errors");
@@ -18,7 +49,29 @@ function throwParserError(error, token, index, message) {
         : "index: ".concat(index, " at token [").concat(token, "]");
     throw new error(errorMessage);
 }
-/** Class representing a token parser. */
+/**
+ * OpenQASM 3.0 Recursive Descent Parser
+ *
+ * Implements a comprehensive parser for the OpenQASM 3.0 language specification.
+ * The parser uses recursive descent parsing with appropriate error recovery and
+ * maintains symbol tables for gates, subroutines, and variables.
+ *
+ * Parser state includes:
+ * - Token stream and current position
+ * - Symbol tables for gates, subroutines, arrays, aliases
+ * - Machine-specific defaults (float width, int size)
+ *
+ * @example Creating and using the parser
+ * ```typescript
+ * const parser = new Parser(tokens);
+ *
+ * // Parse the entire program
+ * const ast = parser.parse();
+ *
+ * // AST contains array of top-level statements and declarations
+ * console.log(ast); // [VersionNode, IncludeNode, DeclarationNode, ...]
+ * ```
+ */
 var Parser = /** @class */ (function () {
     /**
      * Creates a parser.
@@ -1872,7 +1925,7 @@ var Parser = /** @class */ (function () {
     /**
      * Creates a classical type.
      * @param token - The token that represents the type.
-     * @width - The type's width or size, if applicable.
+     * @param width - The type's width or size, if applicable.
      * @return The created ClassicalType.
      */
     Parser.prototype.createClassicalType = function (token, width) {

package/dist/qasm3/token.js

@@ -1,9 +1,46 @@
 "use strict";
+/**
+ * OpenQASM 3.0 Token Definitions and Utilities
+ *
+ * This module defines all the token types used in OpenQASM 3.0 syntax, which
+ * significantly extends OpenQASM 2.0 with modern programming language features.
+ *
+ * Major additions in OpenQASM 3.0:
+ * - **Classical types**: int, uint, float, bool, bit, complex
+ * - **Control flow**: if/else, for/while loops, switch/case
+ * - **Functions**: def, return, extern declarations
+ * - **Advanced features**: arrays, timing (delay, durationof), calibration
+ * - **Quantum extensions**: qubit declarations, gate modifiers, hardware qubits
+ *
+ * @module
+ *
+ * @example OpenQASM 3.0 advanced tokens
+ * ```typescript
+ * import { lookup, Token } from './qasm3/token';
+ *
+ * console.log(lookup('qubit'));    // Token.Qubit
+ * console.log(lookup('if'));       // Token.If
+ * console.log(lookup('def'));      // Token.Def
+ * console.log(lookup('complex'));  // Token.Complex
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Token = void 0;
 exports.notParam = notParam;
 exports.lookup = lookup;
 exports.inverseLookup = inverseLookup;
+/**
+ * Enumeration of all OpenQASM 3.0 token types.
+ *
+ * Each token represents a specific syntactic element in OpenQASM 3.0 code.
+ * The enum values correspond to different categories:
+ * - Literals: NNInteger, Real, String, BoolLiteral
+ * - Identifiers: Id
+ * - Keywords: Qubit, Gate, Measure, If, For, While, etc.
+ * - Operators: ArithmeticOp, BinaryOp, UnaryOp
+ * - Punctuation: Semicolon, Comma, LParen, RParen, etc.
+ * - Special: OpenQASM, Include, EndOfFile, Illegal
+ */
 var Token;
 (function (Token) {
     // 0; invalid or unrecognized token
@@ -209,6 +246,14 @@ var Token;
     // 100; compound binary operators
     Token[Token["CompoundBinaryOp"] = 100] = "CompoundBinaryOp";
 })(Token || (exports.Token = Token = {}));
+/**
+ * Mapping of string keywords to their corresponding token types.
+ *
+ * This lookup table enables the lexer to quickly determine if a string
+ * represents a reserved keyword or should be treated as an identifier.
+ *
+ * @internal
+ */
 var lookupMap = {
     pi: Token.Pi,
     π: Token.Pi,
@@ -300,7 +345,7 @@ var lookupMap = {
     angle: Token.Angle,
     "@": Token.At,
     complex: Token.Complex,
-    "$": Token.Dollar,
+    $: Token.Dollar,
     array: Token.Array,
     durationof: Token.DurationOf,
     stretch: Token.Stretch,
@@ -311,25 +356,63 @@ var lookupMap = {
     extern: Token.Extern,
 };
 /**
- * Returns the token that represents a given string.
- * @param ident - The string.
- * @return The corresponding token.
+ * Returns the token type that corresponds to a given string.
+ *
+ * This function is used by the lexer to classify identifiers and keywords.
+ * If the string is a reserved keyword, it returns the appropriate token type.
+ * Otherwise, it returns Token.Id to indicate a user-defined identifier.
+ *
+ * @param ident - The string to look up
+ * @returns The corresponding token type
+ *
+ * @example Keyword lookup
+ * ```typescript
+ * lookup('qubit');     // Returns Token.Qubit
+ * lookup('measure');   // Returns Token.Measure
+ * lookup('myVar');     // Returns Token.Id
+ * lookup('π');         // Returns Token.Pi
+ * ```
  */
 function lookup(ident) {
     return ident in lookupMap ? lookupMap[ident] : Token.Id;
 }
 /**
- * Returns the string representation of a token.
- * @param tokens - The token.
- * @return The string representation of the token.
+ * Returns the string representation of a token type.
+ *
+ * This is useful for debugging and error reporting, allowing you to
+ * convert token enum values back to their string representations.
+ *
+ * @param token - The token type to convert
+ * @returns The string representation of the token, or undefined if not found
+ *
+ * @example Token to string conversion
+ * ```typescript
+ * inverseLookup(Token.Qubit);   // Returns 'qubit'
+ * inverseLookup(Token.If);      // Returns 'if'
+ * inverseLookup(Token.Pi);      // Returns 'pi'
+ * ```
  */
 function inverseLookup(token) {
     return Object.keys(lookupMap).find(function (ident) { return lookupMap[ident] == token; });
 }
 /**
- * Determines whether a token denotes a parameter.
- * @param tokens - The token.
- * @return Whether the token does NOT denote a parameter.
+ * Determines whether a token can be used as a parameter in expressions.
+ *
+ * This function helps the parser validate parameter lists by checking if
+ * a token type is allowed in parameter contexts. Parameters can include
+ * identifiers, numbers, and other value-bearing tokens, but not structural
+ * tokens like semicolons or braces.
+ *
+ * @param token - The token type to check
+ * @returns true if the token CANNOT be used as a parameter, false otherwise
+ *
+ * @example Parameter validation
+ * ```typescript
+ * notParam(Token.Id);         // false - identifiers can be parameters
+ * notParam(Token.NNInteger);  // false - numbers can be parameters
+ * notParam(Token.Semicolon);  // true - semicolons cannot be parameters
+ * notParam(Token.LParen);     // true - parentheses cannot be parameters
+ * ```
  */
 function notParam(token) {
     if (token == Token.NNInteger ||

package/dist/version.js

@@ -1,4 +1,20 @@
 "use strict";
+/**
+ * OpenQASM version detection and management utilities
+ *
+ * Handles version detection from QASM source code and provides utilities
+ * for working with different OpenQASM versions. Supports automatic version
+ * detection from OPENQASM statements and manual version specification.
+ *
+ * @module Version Management
+ *
+ * @example Version detection
+ * ```typescript
+ * const version = new OpenQASMVersion(3, 0);
+ * console.log(version.toString()); // "3.0"
+ * console.log(version.isVersion3()); // true
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenQASMVersion = exports.OpenQASMMajorVersion = void 0;
 /** Enum representing the major OpenQASM versions. */
@@ -12,7 +28,7 @@ var OpenQASMVersion = /** @class */ (function () {
     /**
      * Creates an OpenQASMVersion instance.
      * @param major - The OpenQASM major version. (optional)
-     * @param minor - The OpenQASM minor version (optional).
+     * @param minor - The OpenQASM minor version (optional)
      */
     function OpenQASMVersion(major, minor) {
         this.major = major ? major : OpenQASMMajorVersion.Version3;

package/docs/assets/hierarchy.js

@@ -0,0 +1 @@
+window.hierarchyData = "eJyrVirKzy8pVrKKjtVRKkpNy0lNLsnMzwMKVNfWAgCbHgqm"

package/docs/custom.css

@@ -0,0 +1,3 @@
+.tsd-navigation.settings {
+  display: none !important;
+}

package/docs/docs-readme.md

@@ -0,0 +1,208 @@
+# QASM TypeScript Documentation
+
+OpenQASM, the low-level programming language for quantum circuit specification, implemented in TypeScript.
+
+QASM-TS 2.0 is an implementation of a compiler frontend for OpenQASM 2.0 and 3.0. It includes a lexer and a parser of the OpenQASM language. The source is parsed into an Intermediate Representation (IR): an Abstract Syntax Tree (AST) that captures program structure including control flow and data flow.
+
+The package is aimed at enabling implementations of verification and validation software (such as semantic and static analyzers), compilers and more. These tools may be instrumental in the formalization of hybrid quantum-classical computing.
+
+Language documentation is provided by IBM [here](https://openqasm.com).
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install qasm-ts
+```
+
+### Basic Usage
+
+Parse from an OpenQASM string snippet:
+
+```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);
+```
+
+Parse from an OpenQASM file:
+
+```typescript
+import { parseFile } from "qasm-ts";
+
+const ast = parseFile("./my-circuit.qasm");
+
+// Specify OpenQASM version explicitly
+const ast2 = parseFile("./legacy-circuit.qasm", 2); // OpenQASM 2.0
+const ast3 = parseFile("./modern-circuit.qasm", 3); // OpenQASM 3.0
+```
+
+### Working with the AST
+
+```typescript
+// Get verbose output with class names
+const verboseAst = parseString(qasmCode, 3, true);
+
+// Get stringified JSON output
+const jsonAst = parseString(qasmCode, 3, false, true);
+
+// Both verbose and stringified
+const verboseJsonAst = parseString(qasmCode, 3, true, true);
+```
+
+## Example I/O
+
+### Input: `alignment.qasm` ([source](https://github.com/openqasm/openqasm/blob/main/examples/alignment.qasm))
+
+```
+include "stdgates.inc";
+
+stretch g;
+
+qubit[3] q;
+barrier q;
+cx q[0], q[1];
+delay[g] q[2];
+U(pi/4, 0, pi/2) q[2];
+delay[2*g] q[2];
+barrier q;
+
+```
+
+### Output: Abstract Syntax Tree
+
+```
+[
+  Include { filename: '"stdgates.inc"' },
+  ClassicalDeclaration {
+    classicalType: StretchType {},
+    identifier: Identifier { name: 'g' },
+    initializer: null,
+    isConst: false
+  },
+  QuantumDeclaration {
+    identifier: Identifier { name: 'q' },
+    size: IntegerLiteral { value: 3 }
+  },
+  QuantumBarrier { qubits: [ [Identifier] ] },
+  QuantumGateCall {
+    quantumGateName: Identifier { name: 'cx' },
+    qubits: [ [SubscriptedIdentifier], [SubscriptedIdentifier] ],
+    parameters: null,
+    modifiers: []
+  },
+  QuantumDelay {
+    duration: Identifier { name: 'g' },
+    qubits: [ [SubscriptedIdentifier] ]
+  },
+  QuantumGateCall {
+    quantumGateName: Identifier { name: 'U' },
+    qubits: [ [SubscriptedIdentifier] ],
+    parameters: Parameters { args: [Array] },
+    modifiers: []
+  },
+  QuantumDelay {
+    duration: Arithmetic { op: '*', left: [IntegerLiteral], right: [Identifier] },
+    qubits: [ [SubscriptedIdentifier] ]
+  },
+  QuantumBarrier { qubits: [ [Identifier] ] }
+]
+```
+
+## API Documentation Navigation
+
+### Core Functions
+
+Start here for the main parsing functions:
+
+- **[parseString](functions/Main_Functions.parseString.html)** - Parse OpenQASM code from a string
+- **[parseFile](functions/Main_Functions.parseFile.html)** - Parse OpenQASM code from a file
+
+### Tokenization
+
+Understand the tokenization process and available token types:
+
+- **[OpenQASM 3.0 Tokens](modules/qasm3_token.html)** - Modern OpenQASM token set
+- **[OpenQASM 2.0 Tokens](modules/qasm2_token.html)** - Legacy OpenQASM token set
+
+### Lexing
+
+Understand the Lexer:
+
+- **[OpenQASM 3.0 Lexer](modules/qasm3_lexer.html)** - Modern OpenQASM lexer
+- **[OpenQASM 2.0 Lexer](modules/qasm2_lexer.html)** - Legacy OpenQASM lexer
+
+### AST Structure
+
+Understand the abstract syntax tree nodes:
+
+- **[OpenQASM 3.0 AST Nodes](modules/qasm3_ast.html)** - Modern OpenQASM syntax tree
+- **[OpenQASM 2.0 AST Nodes](modules/qasm2_ast.html)** - Legacy OpenQASM syntax tree
+
+### Parsing
+
+Understand the Parser:
+
+- **[OpenQASM 3.0 Parser](modules/qasm3_parser.html)** - Modern OpenQASM parser
+- **[OpenQASM 2.0 Parser](modules/qasm2_parser.html)** - Legacy OpenQASM parser
+
+### Utilities and Internals
+
+- **[Error Handling](modules/Error_Handling.html)** - All error types and their usage
+- **[Version Management](modules/Version_Management.html)** - Version detection and handling
+
+Navigate using the sidebar or search functionality to find specific functions and classes.
+
+## New In Version 2.0.0
+
+- Support for the OpenQASM 3.0 spec while retaining OpenQASM 2.0 backwards compatibility.
+
+## Source Code
+
+Feel free to clone, fork, comment or contribute on [GitHub](https://github.com/comp-phys-marc/qasm-ts)!
+
+## References
+
+The original OpenQASM authors:
+
+- Andrew W. Cross, Lev S. Bishop, John A. Smolin, Jay M. Gambetta "Open Quantum Assembly Language" [arXiv:1707.03429](https://web.archive.org/web/20210121114036/https://arxiv.org/abs/1707.03429)
+- Andrew W. Cross, Ali Javadi-Abhari, Thomas Alexander, Niel de Beaudrap, Lev S. Bishop, Steven Heidel, Colm A. Ryan, Prasahnt Sivarajah, John Smolin, Jay M. Gambetta, Blake R. Johnson "OpenQASM 3: A broader and deeper quantum assembly language" [arXiv:2104.14722](https://arxiv.org/abs/2104.14722)
+
+Another strongly typed implementation from which this project took some inspiration:
+
+- [Adam Kelly's Rust QASM Parser](https://github.com/libtangle/qasm-rust)
+
+## License
+
+Copyright 2019 Marcus Edwards
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:
+
+```http://www.apache.org/licenses/LICENSE-2.0```
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+## How to Cite
+
+If you are using QASM-TS for research we appreciate any citations. Please read and cite our pre-print at https://arxiv.org/abs/2412.12578.
+
+```
+@misc{kim2024enablingverificationformalizationhybrid,
+      title={Enabling the Verification and Formalization of Hybrid Quantum-Classical Computing with OpenQASM 3.0 compatible QASM-TS 2.0}, 
+      author={Sean Kim and Marcus Edwards},
+      year={2024},
+      eprint={2412.12578},
+      archivePrefix={arXiv},
+      primaryClass={cs.PL},
+      url={https://arxiv.org/abs/2412.12578}, 
+}
+```