tree-sitter-magnolia

A tree-sitter grammar for the Magnolia programming language. It can be used to provide syntax highlighting for Magnolia code in many code editors and IDEs, as well as in LaTeX documents.

⚠️ This project (grammar and highlighting queries) is generated by a Large Language Model (Claude Opus 4.6), based on existing Magnolia grammars. Redundancies, inconsistencies, and hallucinated concepts might ensue. Please do not use this grammar as a reference for how to parse Magnolia code, its intended use-case is putting pretty colors on your source code.

Details and instructions in this README is mostly written and fully tested by a human. See the git commit history for specifics.

Syntax highlighting in Neovim

Syntax-highlighted listing typeset in LaTeX

Details regarding LLM-generation process

This was originally built based on the magnoliav3 project. The grammar is based on:

• magnoliav3/src/lib/Magnolia/Parser/Parser.y — Happy/LALR parser (current, authoritative)
• magnoliav3/src/lib/Magnolia/Parser/Lexer.x — Alex lexer (current, authoritative)
• magnoliav3/src/lib/Magnolia/Parser/Magnolia.rsc — Rascal/GLL grammar (older, used as reference)

The LLM then analyzed a library of example Magnolia code from the magnoliav3 repo, trying the generated parser on them, and tweaking it until parser errors were fixed. Most errors were a result of conflicts arising from ambiguities in the parser.

Known limitations

• Nested block comments — Magnolia's lexer supports /* /* */ */ nesting. The grammar handles /* */ but not nested variants. An external C scanner would be needed to fix this properly.
• Flat concept syntax — one old example uses concept Foo { } (without =); the grammar follows the current Happy parser which requires concept Foo = { }.

Using

tree-sitter is supported for syntax highlighting in most modern code editors. The following are instructions on how to use this grammar in neovim, Zed, and VSCode.

Another use-case is for coloring code typeset as part of a LaTeX document. Instructions for this are provided too.

Neovim

I use the nvim-treesitter/nvim-treesitter plugin. I think this is the most popular one, you likely have it too. You can extend it with custom config like this:

local parser_config = require('nvim-treesitter.parsers').get_parser_configs()
parser_config.magnolia = {
  install_info = {
    url = vim.fn.expand('~/git/uib/tree-sitter-magnolia'),
    files = { 'src/parser.c' },
    generate_requires_npm = false,
    requires_generate_from_grammar = false,
  },
  filetype = 'magnolia',
}

-- Associate .mg files
vim.filetype.add({ extension = { mg = 'magnolia' } })

Correct ~/git/uib/tree-sitter-magnolia to the appropriate path of where you cloned this repo. Ensure you've built the project, as instructed in the buliding-section of this README.

You also need neovim to know about the queries (specifying what parts of the AST to highlight). In my config, I did this, which may or may not work depending on your nvim config:

mkdir -p ~/.config/nvim/queries/magnolia
cp queries/highlights.scm ~/.config/nvim/queries/magnolia/highlights.scm

Open neovim, and run :TSInstall magnolia. Syntax highlighting should now be working. You can use :InspectTree to open a buffer showing the parse tree of an opened Magnolia file.

TODO: add official grammar to nvim-treesitter, maybe also to official tree-sitter sources.

• https://github.com/nvim-treesitter/nvim-treesitter/blob/main/.github/PULL_REQUEST_TEMPLATE/new_language.md
• https://github.com/tree-sitter/tree-sitter/wiki/List-of-parsers

Zed

Instructions TODO. Official extension also TODO.

VSCode

Instructions TODO. Official extension also TODO.

LaTeX

chromacode is a tool that produces syntax-highlighted LaTeX listings from a piece of source code and a tree-sitter grammar. There's an example LaTeX document in the latex-directory of this project, refer to its Makefile for an example of how to use chromacode.

You need to first install tree-sitter as a binary available on your computer, then add configuration for it. This config includes the location to the tree-sitter parser and chosen colors for highlighting. Refer to the chromacode README configuration section for this.

NOTE: in the tree-sitter configuration, you need to specify the parent directory of this repository as a parser-directory. For example, if you have this project cloned to ~/git/thirdparty/tree-sitter-magnolia, you need to specify ~/git/thirdparty.

If you want to use tree-sitter through npx instead of installing a binary (like the other parts of this README), you can apply my patch latex/chromacode-npx.patch to chroma_code and rebuild it.

Make sure your chromacode binary is in a location that's included in your $PATH to ensure the example Makefile works.

Development instructions for this parser

Building

The entire grammar is defined in grammar.js. Queries for syntax highlighting is in queries/highlights.scm.

To build the project, install tree-sitter as a dependency, and generate source code based on the grammar:

npm install
npx tree-sitter generate

This gives you bindings for Node.js and Rust in a directory bindings/, as well as C11 code for a functional parser, and the grammar expressed as JSON in src/.

Testing

test/corpus/packages.txt contains many pieces of example Magnolia code, with their expected parse trees, taken from real code in the magnoliav3 repo.

You can use the following commands to test your grammar:

npx tree-sitter test                          # run all corpus tests
npx tree-sitter test -f "Function signature"  # run one test by name
npx tree-sitter test --update                 # update expected output to match parser

npx tree-sitter parse path/to/file.mg         # inspect the CST for a file