tree-sitter-zap

A tree-sitter grammar for the Zap programming language.

Supported Syntax

• Modules — pub module / module, module inheritance with extends, dotted module paths
• Functions — pub fn / fn with typed parameters, pattern matching, guard clauses (if), default values, return types (->)
• Macros — pub macro / macro with quote / unquote / unquote_splicing
• Structs — pub struct with field types, defaults, inheritance (extends), dotted names
• Unions — pub union with named variants and optional typed payloads
• Type system — primitives (i8–i64, u8–u64, f16–f64, Bool, String, Atom, Nil, Never), user-defined types, union types (A | B), tuple/list/map/function types, parameterized types, type and opaque aliases
• Expressions — arithmetic, comparison, logical (and/or/not), string concatenation (<>), pipe (|>), error pipe (~>), unwrap (!), type annotations (::)
• Control flow — if/else, case with pattern matching, cond, for comprehensions, with/<-
• Literals — integers (decimal, hex, binary, octal, underscores), floats, strings with #{} interpolation, heredocs ("""), sigils (~s"...", ~w"""..."""), atoms (:name), booleans, nil, tuples, lists (with cons |), maps (%{}), struct expressions (%Module{}), binaries (<<>>)
• Patterns — wildcard (_), pin (^var), tuple/list/map/struct destructuring
• Attributes — @name :: Type = value and @name = value declarations, @name references, @name() intrinsic calls
• Documentation — @doc / @moduledoc with heredoc content, markdown injection for editor highlighting
• Ownership — shared, unique, borrowed parameter modifiers
• Module system — import (with only: / except:), alias (with as:), use
• Comments — # ...

Neovim

Setup

Add to your nvim-treesitter config:

{
  "nvim-treesitter/nvim-treesitter",
  opts = function(_, opts)
    local parser_configs = require("nvim-treesitter.parsers").get_parser_configs()

    parser_configs.zap = {
      install_info = {
        url = "https://github.com/DockYard/tree-sitter-zap",
        files = { "src/parser.c" },
        branch = "main",
      },
      filetype = "zap",
    }

    opts.ensure_installed = opts.ensure_installed or {}
    vim.list_extend(opts.ensure_installed, { "zap" })
  end,
}

Add filetype detection in ftdetect/zap.lua:

vim.filetype.add({ extension = { zap = "zap" } })

Copy the query files to your neovim config:

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

The injections query enables markdown syntax highlighting inside @doc and @moduledoc heredocs.

Install the parser

:TSInstall zap

Usage

Requirements

• Node.js
• tree-sitter CLI

Install

git clone https://github.com/DockYard/tree-sitter-zap.git
cd tree-sitter-zap
npm install

Generate the parser

npx tree-sitter generate

Parse a file

npx tree-sitter parse path/to/file.zap

Run tests

npx tree-sitter test

Syntax highlighting

npx tree-sitter highlight path/to/file.zap

Example

Given this Zap source:

pub module Greeter {
  @moduledoc = """
    A simple greeter module.
    """

  @doc = """
    Returns a greeting string for the given name.
    """
  pub fn greet(name :: String) -> String {
    "Hello, " <> name <> "!"
  }

  pub fn main(_args :: [String]) -> String {
    greet("World")
    |> IO.puts()
  }
}

The parser produces:

(source_file
  (module_definition
    (visibility_modifier)
    name: (module_path (module_name))
    (attribute_declaration
      name: (identifier)
      value: (heredoc (heredoc_content)))
    (attribute_declaration
      name: (identifier)
      value: (heredoc (heredoc_content)))
    (function_definition
      (visibility_modifier)
      name: (identifier)
      (parameter_list
        (parameter
          pattern: (identifier)
          type: (type_expression (type_name))))
      return_type: (type_expression (type_name))
      body: (body
        (binary_expression
          (binary_expression
            (string (string_content))
            (identifier))
          (string (string_content)))))
    (function_definition
      (visibility_modifier)
      name: (identifier)
      (parameter_list
        (parameter
          pattern: (identifier)
          type: (type_expression
            (list_type (type_expression (type_name))))))
      return_type: (type_expression (type_name))
      body: (body
        (pipe_expression
          (function_call
            name: (identifier)
            (argument_list (string (string_content))))
          (qualified_call
            module: (module_path (module_name))
            name: (identifier)))))))

Project Structure

tree-sitter-zap/
  grammar.js               # Grammar definition
  queries/highlights.scm    # Syntax highlighting queries
  queries/injections.scm    # Language injection queries (markdown in docs)
  test/corpus/              # Test cases
  src/                      # Generated parser (C)
  tree-sitter.json          # Parser metadata