diff options
| -rw-r--r-- | jai_neovim_setup.md | 54 | ||||
| -rw-r--r-- | jai_primer.md | 46 |
2 files changed, 100 insertions, 0 deletions
diff --git a/jai_neovim_setup.md b/jai_neovim_setup.md new file mode 100644 index 0000000..1ab0ea6 --- /dev/null +++ b/jai_neovim_setup.md @@ -0,0 +1,54 @@ +# Jai + Neovim: Environment & Tooling Overview + +This document provides a high-level summary of the custom Neovim and `ctags` pipeline engineered for Jai development. Because Jai does not yet have a mature, universally standard Language Server Protocol (LSP) that handles all edge cases perfectly, this setup relies on a heavily customized, robust `ctags` and fuzzy-finding (`fzf-lua`) integration. + +## 1. The Core Philosophy + +Instead of fighting with incomplete LSPs, we built a **data-driven tag indexer** (`ctags`) paired with a **smart fuzzy finder** (`fzf-lua`) and **custom Neovim Lua parsers**. This setup guarantees instant jumps to definitions and references, even when dealing with Jai's unique syntax quirks. + +## 2. Jai Syntax Quirks & The Backslash Problem + +Jai has a unique syntax feature: a backslash (`\`) followed by whitespace inside an identifier is completely ignored by the compiler. This allows developers to split long variable names across lines or format them visually. + +*Example:* `free_site_trace` and `free\ _site_trace` are evaluated identically by the Jai compiler. + +### The Challenge +Standard text editors and indexers fail completely here: +- **Neovim** sees them as separate words because `\` and spaces break standard keyword boundaries. +- **ctags** natively index strings literally, so it would index `free\ _site_trace` with the slash included, making it unsearchable. +- **grep** cannot find references if they are visually split. + +### The Solution: A Custom Pipeline +We engineered a 3-part pipeline to solve this globally: + +1. **Custom `~/.ctags.d/jai.ctags`:** We extended the regular expressions to aggressively capture any identifier containing letters, numbers, underscores, backslashes, and tabs/spaces (`[a-zA-Z0-9_\\\ \t]+`). +2. **Perl Post-Processing:** Every time a `.jai` file is saved, a background job runs `ctags`, followed immediately by a highly optimized Perl script (`perl -i -F'\t' -lane ...`). This script intercepts the newly generated `tags` file and scrubs all backslashes and whitespace out of the tag names. The result? A pristine, normalized tag index. +3. **Custom Lua Parser:** We bypassed Neovim's native `<cword>` (current word) extraction. Instead, `~/.config/nvim/lua/jai_ctags.lua` contains a custom parser that reads the current line, walks left and right from the cursor, skips over `\` and whitespace, and perfectly extracts the underlying normalized identifier. + +## 3. Keybindings & Navigation + +The custom Lua parser feeds directly into the following heavily optimized keybindings: + +### `<leader>b` : Build & Quickfix +- **Action:** Compiles the project using `jai build.jai - src/main.jai`. +- **How it works:** Hooks natively into Neovim's `makeprg`. We wrote a custom `errorformat` (`%f:%l\,%c:\ %m,%f:%l:\ %m`) that teaches Neovim exactly how to parse Jai compiler errors. +- **Result:** If the build fails, a Quickfix window pops up at the bottom of the screen. Pressing `Enter` on any error jumps you exactly to the file, line, and column. + +### `gd` and `<space>D` : Instant Goto Definition +- **Action:** Jumps instantly to the definition of the symbol under your cursor. +- **How it works:** Uses the custom Lua parser to grab the normalized word, then triggers native Vim `:tag` jumping (which behaves exactly like `<C-]>`). + +### `<leader>d` : Interactive Goto Definition +- **Action:** Opens an `fzf-lua` fuzzy-finder menu pre-filled with definitions. +- **When to use:** Use this when a variable name (like `data`) is shadowed or heavily overloaded across multiple files. It lets you visually pick the exact scope you want to jump into. + +### `gr` : Goto References +- **Action:** Finds all occurrences/usages of the symbol under your cursor across the entire codebase. +- **How it works:** Grabs the normalized word and dynamically constructs a PCRE regular expression (e.g., `f[ \t\\]*r[ \t\\]*e...`) that interleaves optional backslash and whitespace matchers between every character. It passes this regex to `fzf-lua grep`. +- **Result:** It flawlessly finds all references to a variable, even if the reference is split with a `\` in the source code! + +## 4. Configuration Locations + +- **`~/.ctags.d/jai.ctags`**: The regex engine rules for universal-ctags to parse Jai syntax. +- **`~/.config/nvim/lua/jai_ctags.lua`**: The brains of the operation. Contains the autocmds, the custom Lua identifier parser, the background tag generation pipeline, and the `fzf-lua` keybindings. +- **Tag Exclusions**: The `ctags` command explicitly excludes `maze-rs/` and `how_to/` directories to prevent tutorial/sandbox files from polluting the global index and causing definition collisions (e.g., `array_add`). diff --git a/jai_primer.md b/jai_primer.md new file mode 100644 index 0000000..b28aba0 --- /dev/null +++ b/jai_primer.md @@ -0,0 +1,46 @@ +# Jai Primer: High-Level Overview & Resources + +Jai is a strongly-typed, data-oriented systems programming language designed primarily by Jonathan Blow. It aims to replace C++ for game development and performance-critical applications by drastically improving compilation times, removing historical C++ baggage, and providing powerful metaprogramming capabilities at compile time. + +## Core Tenets +1. **Frictionless Workflow:** Compilation should be near-instant. The language is designed to get out of your way so you can just write code. +2. **Data-Oriented Design (DOD):** Focuses heavily on memory layouts, cache-friendly data structures (like SoA vs. AoS), and explicit control over memory allocations. +3. **Compile-Time Metaprogramming:** Almost everything you can do at runtime can be done at compile time. You can write scripts that generate code, parse assets, or orchestrate the build process entirely inside Jai itself (e.g., our `build.jai` file). +4. **No Hidden Control Flow:** No implicit copy constructors or magic hidden operations. Code does exactly what it looks like it's doing. + +## Language Quirks +- **Declarations:** `x := 5;` (infer type, mutable), `x : int = 5;` (explicit type), `X :: 5;` (constant). +- **Structs & Polymorphism:** Structs are lightweight. Polymorphism is handled via parameterized structs rather than OOP inheritance. +- **Context:** A hidden `context` struct is implicitly passed to every function. It holds the current allocator, logger, thread index, etc. This means you don't need to pass allocators manually through 10 layers of functions! +- **Line Continuations:** A backslash (`\`) followed by whitespace *inside* an identifier is ignored, allowing you to visually format long variable names across lines (`my_very\ _long_variable`). + +--- + +## Where to Look for Knowledge + +Because Jai is in closed beta, you won't find a centralized, SEO-optimized website with all the documentation. The compiler ships with its own extensive documentation directly in the source files. + +### 1. The `how_to` Directory (The Holy Grail) +Path: `~/jai/how_to/` + +This is the official, authoritative tutorial and language reference. It is a series of numbered `.jai` files designed to be read and executed in order. +- Look here when you want to learn a specific language feature (e.g., macros, polymorphs, custom allocators, print formatting). +- *Tip:* Just open `000_introduction.jai` and start reading! + +### 2. The `modules` Directory (The Standard Library) +Path: `~/jai/modules/` + +This contains the entire standard library and provided modules. Since you have `gd` (Goto Definition) and `gr` (Goto References) configured in Neovim, you can jump directly into these files. +- `Basic`: The core standard library containing `array_add`, `assert`, `print`, etc. +- `Simp`: The simple 2D rendering engine we use for drawing. +- `Window_Creation` and `Input`: For cross-platform window management and event handling. +- Look here when you want to see exactly how a standard function is implemented or what arguments it takes. + +### 3. Community Documentation +While official web documentation is scarce, the community maintains an excellent, searchable wiki. +- **Jai Community Wiki:** [https://jai.community](https://jai.community) +- This is a fantastic resource for quick syntax lookups or high-level explanations when reading the `how_to` files feels too slow. + +### 4. Our Custom Tools +- Use `<leader>d` to fuzzy-search tags across our project and the standard library if you aren't sure where a function lives. +- Use `gr` to see how the standard library (or our own code) uses a specific function in practice. |