Show HN: Qasmtools CLI tools for formatting, linting, and highlighting OpenQASM

qasmtools is a comprehensive toolkit for OpenQASM 3.0 development, featuring a command-line interface (CLI) tool written in Go and a Visual Studio Code extension. It provides functionalities to parse, format, and highlight QASM files, making them more readable and consistent with enhanced development experience in VSCode.

• QASM 3.0 Parsing: Parses OpenQASM 3.0 files into an Abstract Syntax Tree (AST).
• QASM 3.0 Formatting: Formats QASM 3.0 files to adhere to a consistent style with support for standard input, JSON-style escaped strings, and automatic pipe detection.
• QASM 3.0 Linting: Checks QASM files for style and semantic issues using configurable YAML-based rules with documentation URLs for each violation, colored output, and JSON format support.
• QASM 3.0 Highlighting: Provides syntax highlighting for QASM files in the terminal with color-coded output for keywords, numbers, strings, and operators.
• Pipeline Support: All commands support stdin/stdout piping for seamless integration in command-line workflows.
• Web Playground: Interactive browser-based formatter with WebAssembly backend and unescape support.
• VSCode Extension: Provides language support for OpenQASM 3.0 in Visual Studio Code with syntax highlighting, formatting, and Language Server Protocol (LSP) integration.

The easiest way to install qasmtools is with a single command:

You can also install via Homebrew:

You can use qasmtools via Docker without installing Go:

Use qasmtools in your CI/CD pipeline:

Multi-platform testing:

Alternative using Docker:

To build qasmtools from source, ensure you have Go installed (version 1.16 or higher recommended).

1. Clone the repository:

   git clone https://github.com/orangekame3/qasmtools.git cd qasmtools

2. Build the executable:

   go build -o qasm ./cmd/qasm

   This will create an executable named qasm in the current directory.

The qasm executable provides three main commands: fmt for formatting, lint for linting, and highlight for syntax highlighting of QASM files.

To format a QASM file:

Options:

• -w, --write: Write result to (source) file instead of stdout
• --check: Check if files are formatted without modifying them
• -i, --indent: Set indentation size (default: 2)
• -n, --newline: Ensure files end with a newline (default: true)
• -v, --verbose: Enable verbose output
• --diff: Display diffs instead of rewriting files
• --stdin: Read input from stdin instead of files
• --unescape: Unescape JSON-style escaped strings (\n, \") before formatting

Examples:

To check QASM files for style and semantic issues:

Options:

• --rules: Directory containing custom rule files (default: use embedded rules)
• -d, --disable: Disable specific rules (e.g., QAS001,QAS002)
• -e, --enable-only: Enable only specific rules
• --format: Output format (text, json)
• -q, --quiet: Suppress info and warning messages

Examples:

The linter includes 12 comprehensive built-in rules to ensure code quality and correctness:

Semantic Analysis:

• QAS001 unused-qubit - Detects qubits that are declared but never used in gates or measurements
• QAS002 undefined-identifier - Error when using undeclared variables, functions, or gates
• QAS003 constant-measured-bit - Warning when measuring qubits with no gates applied (result always |0⟩)
• QAS004 out-of-bounds-index - Error when using out-of-bounds indices on arrays or registers
• QAS006 gate-register-size-mismatch - Error when quantum register lengths do not match in gate calls
• QAS007 gate-parameter-indexing - Error when using index access on gate parameters (prohibited)
• QAS008 qubit-declared-in-local-scope - Error when declaring qubits in local scope (functions, gates, blocks)
• QAS009 illegal-break-continue - Error when using break or continue outside of loops
• QAS010 invalid-instruction-in-gate - Error when including non-unitary operations in gate definitions
• QAS011 reserved-prefix-usage - Error when using reserved prefix (__) in identifiers

Style and Conventions:

• QAS005 naming-convention-violation - Warning for violations of OpenQASM naming conventions
• QAS012 snake-case-required - Warning to enforce snake_case naming for identifiers

Each rule violation includes a documentation URL for detailed explanations and examples.

Detailed documentation for each rule is available at docs/rules/ with examples and explanations.

The QASM Tools Playground provides an interactive web-based environment for formatting OpenQASM 3.0 code directly in your browser.

🌐 Try it online: https://www.orangekame3.net/qasmtools/

• Real-time Formatting: Format QASM code instantly with the same engine used by the CLI
• Unescape Support: Handle JSON-style escaped strings (\n, \") with a simple checkbox
• Sample Code: Quick access to example QASM programs for testing and learning
• Syntax Highlighting: Monaco Editor integration with custom QASM language support
• WebAssembly Backend: Powered by the same Go formatter compiled to WASM for consistency

1. Navigate to the playground web interface
2. Enter or paste your QASM code in the input panel
3. Enable "Unescape JSON strings" if your input contains escaped characters
4. Click "Format" to see the formatted output
5. Use "Copy" to copy the formatted result to clipboard

The playground supports the same functionality as the CLI:

To display QASM files with syntax highlighting in the terminal:

Examples:

The highlight command provides colorized output with:

• Keywords in yellow (OPENQASM, include, qubit, etc.)
• Numbers in cyan
• Strings in green
• Operators in white

The vscode-qasm extension provides comprehensive OpenQASM 3.0 language support for Visual Studio Code.

• Syntax Highlighting: Rich syntax highlighting for OpenQASM 3.0 constructs
• Code Formatting: Automatic code formatting with Shift+Alt+F (Windows/Linux) or Shift+Option+F (Mac)
• Semantic Tokens: Advanced token-based highlighting for better code readability
• Language Server Integration: Real-time parsing and analysis through LSP
• Built-in Linting: Powered by the same YAML-based rule engine as the CLI tool

1. Visit the VSCode Marketplace
2. Click "Install" to add the extension to VSCode
3. Alternatively, search for "OpenQASM 3.0" in the VSCode Extensions view (Ctrl+Shift+X)

1. Download the latest .vsix file from the releases
2. Install via VSCode Command Palette:
   Extensions: Install from VSIX...

1. Open any .qasm or .qasm3 file in VSCode
2. The extension will automatically activate and provide:
   • Syntax highlighting
   • Code formatting capabilities
   • Semantic token highlighting

• cmd/qasm/: Contains the main entry point and CLI implementation
• cmd/qasmlsp/: Language Server Protocol (LSP) server for VSCode integration
• cmd/wasm/: WebAssembly build target for the playground
• parser/: Handles the parsing of QASM 3.0 files and AST generation
  • grammar/: Contains the ANTLR grammar files for QASM 3.0
  • gen/: Contains generated parser code
• formatter/: Implements the QASM 3.0 formatting logic
• lint/: QASM 3.0 linting engine with YAML-based rules
  • rules/: Built-in rule definitions (QAS001-QAS012) with documentation URLs, specification URLs, and examples
  • runner.go: Core linter engine and rule execution
  • rule.go: Rule definitions, violation structures, and checker interfaces
  • factory.go: Rule checker factory for creating specific rule implementations
• highlight/: Syntax highlighting implementation for LSP
• playground/: Web-based QASM formatter with WebAssembly backend
  • src/: React/TypeScript frontend components
  • public/: Static assets (WASM files are generated during build)
• vscode-qasm/: VSCode extension for OpenQASM 3.0 language support
  • syntaxes/: TextMate grammar for syntax highlighting
  • bin/: Contains the embedded LSP server binary
• examples/: Contains example QASM files and usage examples
• testdata/: Contains test files for various QASM constructs

The following diagram illustrates the processing flow of qasmtools:

The diagram shows how QASM code flows through the system:

1. Input code enters through the cmd/qasm package
2. The parser package handles parsing and AST generation
3. Comments are extracted and maintained separately
4. The formatter package processes the AST and comments to generate formatted output

1. VSCode extension receives QASM files
2. LSP server (cmd/qasmlsp) provides language services
3. Syntax highlighting and semantic tokens enhance the editing experience
4. Formatting requests flow through the same formatter package
5. Real-time feedback is provided to the VSCode UI

1. Browser UI receives QASM code input from users
2. Code is processed by the WebAssembly build (cmd/wasm.main)
3. WebAssembly Go runtime executes the same formatting logic as CLI/LSP
4. Formatted output is returned to the browser for display
5. Same core parser and formatter packages ensure consistency across all platforms

1. AST and Comments from parser package are fed into the lint.Linter
2. Linter loads YAML-based rule definitions (QAS001-QAS012)
3. Rule checkers analyze AST nodes for style and semantic violations
4. Violations are generated with file positions, severity levels, documentation URLs, and specification URLs
5. Output is formatted as colored text or JSON for CLI consumption
6. In VSCode, violations are converted to LSP diagnostics for real-time display

Check out the examples/ directory for sample QASM files and usage examples:

　- examples/bell_state.qasm: Implementation of a Bell state 　- examples/grover.qasm: Implementation of Grover's algorithm 　- examples/ast_visitor/: Example of using the AST visitor 　- examples/error_handling/: Example of error handling 　- examples/parse_simple/: Simple parsing example

For development guidelines, please refer to DEVELOPMENT.md.

The project includes comprehensive test coverage for all components:

Test coverage includes:

• Unit tests for all core functionality
• Integration tests for CLI commands with real binary execution
• Formatter idempotency tests
• Edge cases for unescape functionality
• Error handling and validation

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate and follow the existing code style.