Capy EBNF Grammar

This repository contains an EBNF grammar for Capy.

NOTE: The code in this repo is NOT used in the Capy compiler. Capy uses a custom handwritten parser. The EBNF file given in this repo is given as an aid for those who want something that formally defines Capy's grammar. To see Capy's actual parser, see the parser code

The EBNF given here is specifically written in TatSu's EBNF format, but is standard EBNF for the most part and should be compatable with most EBNF tools.

You can find it in grammar.ebnf.

Testing

A testing script has been made to test this EBNF against Capy's custom parser to ensure correctness.

The test script will go over every .test file in capy/crates/parser/src/tests, parse the test code with the EBNF, convert both the EBNF AST and the expected Capy AST into a simplified AST format, and then ensure that these simplified AST's match.

The test script will also go over every file in examples and core, ensuring that they are at the very least parseable.

You can run the test script with

python3 test.py

This will produce .result files under test_results/, which will show you all the simplified and unsimplified ASTs.

To test only against the .test files in capy/crates/parser/src/tests, run

python3 -m tests.compare_tests

Use python3 -m tests.compare_tests --help to see the available options.

To test only that the given files and folders are paresable, run

python3 -m tests.passing_tests file1.capy file2.capy dir1/ dir2/

Use python3 -m tests.passing_tests --help to see the available options.

You can also use tests.passing_tests to actually check the EBNF AST of a particular .capy file,

python3 -m tests.passing_tests --show-ast=full file1.capy file2.capy

Syncing Capy Tests

This repository only mirrors the Capy files that the tests need. The commit hash of the latest supported Capy version is stored in latest_supported_capy.txt.

When you run python3 -m tests.compare_tests or python3 test.py the required directories (crates/parser/src/tests, examples, and core/src) are fetched from GitHub and cached inside .capy_upstream/. The cache is reused until you change latest_supported_capy.txt, at which point the new commit is downloaded.

You can refresh/inspect the cache manually with:

python3 -m tests.capy_support --print-paths

Final Notes

Because this EBNF file is tested extensively against the same exact tests that the regular parser is tested against you can be assured that:

1. Anything parsed by the Rust parser (which doesn't contain errors) will result in an equivalent AST by the EBNF.
2. Any input which would result in an error in the Rust parser will also result in an error in the EBNF (although since the EBNF doesn't have as extensive error recovery as the Rust parser, no promises can be made that the ASTs will be equivalent, just that both ASTs will contain errors).

I'll be forthcoming with the fact that since the code in this directory repository doesn't really affect or touch the main compiler at all, this EBNF was a fun personal experiment of mine into how well "vibe coding" actually works. I wanted to get the most out of the free trial of Plus that OpenAI decided to give me so I used ChatGPT Codex for the majority of the code written here.

Although, since I tend to be very distrusting of AI I did put together the very extensive testing as already mentioned.

I'm not sure how much I'll use AI to write code in the future but at the very least this was a fun experiment and I acheived my goal of making a working EBNF. I feel like you can't have an opinion on things like this until you've actually tried it yourself.

The results were kind of a mixed bag, sometimes it was really smart and able to figure things out itself and other times it was dumber than a rock.

Practically none of the code outside of this repo is written by AI, which I'm very proud of.

License

The Capy Programming Language EBNF is licensed under the Apache License (Version 2.0) or the MIT license, at your option.

See LICENSE-APACHE and LICENSE-MIT for details.

It is Copyright (c) The Capy Programming Language EBNF Contributors.