Bump actions/checkout from 2 to 4

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/CI.yml

@@ -0,0 +1,78 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+    tags: ['*']
+  pull_request:
+  workflow_dispatch:
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
+      actions: write
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1'
+          - 'lts'
+          - 'pre'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: lcov.info
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write # needed to allow julia-actions/cache to proactively delete old caches that it has created
+      contents: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1 # forces PkgServer refresh
+      - name: Configure doc environment
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Pkg
+          Pkg.Registry.update()
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Run doctests
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Documenter: DocMeta, doctest
+          using Quasar 
+          DocMeta.setdocmeta!(Quasar, :DocTestSetup, :(using Quasar); recursive=true)
+          doctest(Quasar)

.github/workflows/CompatHelper.yml

@@ -0,0 +1,16 @@
+name: CompatHelper
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pkg.add("CompatHelper")
+        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
+      - name: CompatHelper.main()
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia -e 'using CompatHelper; CompatHelper.main()'

.github/workflows/Documentation.yml

@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+
+jobs:
+  build:
+    permissions:
+      contents: write
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: julia --project=docs/ docs/make.jl
+

.github/workflows/TagBot.yml

@@ -0,0 +1,31 @@
+name: TagBot
+on:
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+    inputs:
+      lookback:
+        default: "3"
+permissions:
+  actions: read
+  checks: read
+  contents: write
+  deployments: read
+  issues: read
+  discussions: read
+  packages: read
+  pages: read
+  pull-requests: read
+  repository-projects: read
+  security-events: read
+  statuses: read
+jobs:
+  TagBot:
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -0,0 +1,2 @@
+*Manifest.toml
+lcov.info

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Katharine Hyatt <[email protected]> and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Project.toml

@@ -0,0 +1,29 @@
+name = "Quasar"
+uuid = "86e06105-936e-439e-acf0-7687560b0bd9"
+authors = ["Katharine Hyatt <[email protected]> and contributors"]
+version = "1.0.0-DEV"
+
+[deps]
+AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
+Automa = "67c07d97-cdcb-5c2c-af73-a7f9c32a568b"
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+
+[compat]
+AbstractTrees = "0.4.5"
+Automa = "1.0.4"
+DataStructures = "0.18.20"
+Dates = "1"
+PrecompileTools = "1.2.1"
+julia = "1.6"
+
+[extras]
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test", "Dates", "LinearAlgebra", "Statistics"]

README.md

@@ -0,0 +1,3 @@
+# Quasar
+
+[![Build Status](https://github.com/kshyatt-aws/Quasar.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/kshyatt-aws/Quasar.jl/actions/workflows/CI.yml?query=branch%3Amain)

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Quasar = "86e06105-936e-439e-acf0-7687560b0bd9"

docs/make.jl

@@ -0,0 +1,23 @@
+using Quasar 
+using Documenter
+
+DocMeta.setdocmeta!(Quasar, :DocTestSetup, :(using Quasar; recursive=true))
+
+makedocs(;
+    modules=[Quasar],
+    sitename="Quasar.jl",
+    repo="github.com/kshyatt-aws/Quasar.jl",
+    format=Documenter.HTML(;
+        canonical="github.com/kshyatt-aws/Quasar.jl",
+        edit_link="main",
+        assets=String[],
+    ),
+    pages=[
+        "Home" => "index.md",
+    ],
+)
+
+deploydocs(;
+    repo="github.com/kshyatt-aws/Quasar.jl",
+    devbranch="main",
+)

docs/src/index.md

@@ -0,0 +1,94 @@
+```@meta
+DocTestSetup = quote using Quasar end
+CurrentModule = Quasar
+```
+
+# Quasar
+
+`Quasar.jl`, the Qu(antum) as(sembly) (lex/pars)er, is a package for lexing and parsing the [OpenQASM quantum assembly IR](https://openqasm.com/).
+
+`Quasar` works in a two-step fashion: first, it uses a tokenizer to generate an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) representing the
+quantum program, which is a nested structure of `QasmExpression`s.
+Then, it walks (visits) the AST to evaluate all loops, conditionals, gate calls, and variable declarations.
+
+`Quasar` has support for:
+
+- Basic builtin OpenQASM 3 gates `gphase` and `U`
+- Custom gate definitions
+- `for` and `while` loops
+- `if`, `else`, and `switch` conditional statements
+- Builtin OpenQASM3 functions
+- Function definitions and calls
+- Casting classical types
+- Timing statements `barrier` and `delay`
+- Pragmas (see below)
+
+What is *not* yet supported:
+- `angle` types
+- Annotations
+- OpenPulse
+
+If you need any of these features, feel free to open an issue requesting support for them!
+
+## Quick Start
+
+For more extensive examples, see the tests in `test/`. Here, we can parse and visit a simple OpenQASM 3.0 program to generate a Bell circuit:
+
+```jldoctest
+julia> qasm = """OPENQASM 3.0;\ngate h a { U(π/2, 0, π) a; gphase(-π/4);};\ngate x a { U(π, 0, π) a; gphase(-π/2);};\ngate cx a, b { ctrl @ x a, b; };\ndef bell(qubit q0, qubit q1) {\n    h q0;\n    cx q0, q1;\n}\nqubit[2] q;\nbell(q[0], q[1]);\nbit[2] b = "00";\nb[0] = measure q[0];\nb[1] = measure q[1];\n""";
+
+julia> parsed = Quasar.parse_qasm(qasm);
+
+julia> visitor = Quasar.QasmProgramVisitor();
+
+julia> visitor(parsed);
+```
+
+You can supply [inputs](https://openqasm.com/language/directives.html#input-output) to your program
+by creating the `QasmProgramVisitor` with a `Dict{String, Any}` containing the names of the input variables
+as the keys and their values as the `Dict`'s values. This allows you to re-use the same AST multiple times
+for different inputs.
+
+Once the visitor has walked the AST, its `instructions` field contains `CircuitInstruction` `NamedTuple`s you can
+use to construct your own circuit instruction types. These tuples have fields:
+
+- `type::String` - the name of the instruction, e.g. `"measure"` or `"cx"`
+- `arguments` - any arguments the instruction accepts, such as an angle for an `rx` gate or a `Period` for a `duration` 
+- `targets::Vector{Int}` - the qubits targeted by this instruction. This should include any control qubits. 
+- `controls::Vector{Pair{Int,Int}}` - any controls (including `negctrl`) applied to the instruction. The first item in the pair is the qubit, the second is the value controlled upon, so that `2=>0` represents a `negctrl` on qubit 2.
+- `exponent::Float64` - the `pow` modifier applied to the instruction, if any
+
+You can use a package such as [`StructTypes.jl`](https://github.com/JuliaData/StructTypes.jl) to build your circuits and programs from these named tuples.
+
+In the above example, the `h`, `x`, and `cx` were defined in terms of the built-in gates `U` and `gphase`. In many cases, you may have an implementation of these
+gates that is simpler or more efficient. In that case, you can supply your own gate definition file using the [`include` instruction](https://openqasm.com/language/comments.html#included-files), or provide a *function* to generate a dictionary of builtin gates to `Quasar.jl`:
+
+```julia
+using Quasar
+
+function my_builtin_generator()
+    ...
+end
+
+Quasar.builtin_gates[] = my_builtin_generator 
+```
+
+A generator function is used here in order to allow visitors to overwrite builtin functions in certain scopes without corrupting the reference definition.
+
+## Working with `pragma`s
+
+[OpenQASM `pragma`s](https://openqasm.com/language/directives.html#pragmas) allow specific platforms to provide custom instructions.
+`Quasar.jl` provides a bare `parse_pragma` function you can override and extend to support parsing your pragma constructs. This will
+teach `Quasar.jl` how to incorporate your `pragma` instructions into the AST. You will also need to write a `visit_pragma` function
+for the AST walking step. You may want to use `pragma`s to support custom circuit operations (like noise channels) or results. 
+
+Your `parse_pragma` should take four arguments:
+- `tokens` -- some vector of tokens generated by the tokenizer which represents the `pragma` line, with the leading `#pragma` removed
+- `stack` -- the current stack of `QasmExpressions`, used for error reporting
+- `start` -- the location in the QASM source string of the start of the `#pragma` line, used for error reporting
+- `qasm` -- the QASM source string, used for error reporting
+
+Your `visit_pragma` should take two arguments:
+- `visitor` -- any subtype of `AbstractVisitor`, e.g. a `QasmProgramVisitor`, `QasmForLoopVisitor`, etc.
+- `expr` -- the `QasmExpression` containing your full `pragma` invocation, generated by the above `parse_pragma` function
+