tree-sitter: document grammar scope overrides

Document overrideScope as the supported extension point and the scoped grammar-only views (derivations, allGrammars, withPlugins) that consumers should iterate.
2026-06-30 22:07:45 -05:00
parent a8fad7e641
commit 0a53614dbb
1 changed files with 53 additions and 0 deletions
@@ -109,6 +109,59 @@ This includes build-related flags and metadata.
 }
 ```

+## Overriding the Grammar Set
+
+Use `pkgs.tree-sitter-grammars.overrideScope` when adding a grammar or replacing a grammar that another package should consume.
+`pkgs.tree-sitter-grammars` is the scoped package set used for grammar overrides and scoped helpers such as `derivations`, `allGrammars`, and `withPlugins`.
+
+```nix
+let
+  grammars = pkgs.tree-sitter-grammars.overrideScope (
+    final: prev: {
+      tree-sitter-foolang = pkgs.tree-sitter.buildGrammar {
+        language = "foolang";
+        version = "0.42.0";
+        src = pkgs.fetchFromGitHub {
+          owner = "example";
+          repo = "tree-sitter-foolang";
+          rev = "v0.42.0";
+          hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+        };
+      };
+
+      tree-sitter-rust = prev.tree-sitter-rust.overrideAttrs (_: {
+        version = "custom";
+        src = pkgs.fetchFromGitHub {
+          owner = "example";
+          repo = "tree-sitter-rust";
+          rev = "custom";
+          hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+        };
+      });
+    }
+  );
+in
+grammars.withPlugins (p: [
+  p.tree-sitter-foolang
+  p.tree-sitter-rust
+])
+```
+
+The scoped `withPlugins` helper receives derivations from the same overridden scope, so added or replaced grammars are visible.
+
+The set also carries package-set helpers (`callPackage`, `newScope`, `overrideScope`, …) alongside the grammars, so do not iterate it directly.
+Use one of its grammar-only views instead; each reflects any `overrideScope`:
+
+- `pkgs.tree-sitter-grammars.derivations` — attrset of every grammar derivation, including grammars marked broken.
+- `pkgs.tree-sitter-grammars.allGrammars` — list of the non-broken grammar derivations.
+- `pkgs.tree-sitter-grammars.withPlugins` — build a grammar link farm.
+
+```nix
+builtins.attrValues pkgs.tree-sitter-grammars.derivations
+```
+
+`pkgs.tree-sitter.builtGrammars` remains the plain attribute set generated directly from [grammar-sources.nix](grammar-sources.nix); use it when you specifically want the stock grammars without any scope overrides.
+
 ## Building WebAssembly Parsers

 `buildGrammar` builds a native `$out/parser`.