{"id":16587406,"url":"https://github.com/colinkennedy/tree-sitter-usd","last_synced_at":"2025-03-16T21:30:28.704Z","repository":{"id":162735481,"uuid":"629788763","full_name":"ColinKennedy/tree-sitter-usd","owner":"ColinKennedy","description":"USD file grammar parser","archived":false,"fork":false,"pushed_at":"2024-04-29T06:17:16.000Z","size":265,"stargazers_count":28,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-11T11:55:32.449Z","etag":null,"topics":["grammar-parser","parser","tree-sitter","usd"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ColinKennedy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-19T03:02:40.000Z","updated_at":"2025-03-08T13:41:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"4132aafb-c47a-452b-b809-d9e02d182cf4","html_url":"https://github.com/ColinKennedy/tree-sitter-usd","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinKennedy%2Ftree-sitter-usd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinKennedy%2Ftree-sitter-usd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinKennedy%2Ftree-sitter-usd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinKennedy%2Ftree-sitter-usd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ColinKennedy","download_url":"https://codeload.github.com/ColinKennedy/tree-sitter-usd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830915,"owners_count":20354850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grammar-parser","parser","tree-sitter","usd"],"created_at":"2024-10-11T22:54:08.627Z","updated_at":"2025-03-16T21:30:28.207Z","avatar_url":"https://github.com/ColinKennedy.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tree-sitter-usd\nThis library parses USD ASCII files using\n[tree-sitter](https://tree-sitter.github.io/tree-sitter) to produce\na light-weight grammar of the file.\n\nFor those who don't know what tree-sitter is and why you'd care to use it, see\n[Why Tree-sitter?](#why-tree-sitter). For install / usage instructions, see\nbelow.\n\n\n## Disclaimer\nThis repository's parsing rules are subject to change.\n\n\n## Building + Using\n### Neovim\nMake sure you include the following somewhere in your `init.lua` file.\n\n```lua\nrequire(\"nvim-treesitter.configs\").setup {\n    ensure_installed = {\"usd\"},\n    parser_install_dir = installation_directory,\n    highlight = { enable = true },\n\n    -- More stuff\n}\n```\n\n\n## Why Tree-sitter?\nIn the beginning, Tree-sitter was made to give text editors better syntax highlighting.\n\nMost text editors today create syntax highlighting with regex patterns. On\nlarge files with long line counts, this approach is slow and error-prone.\n\nIn contrast to regex, Tree-sitter actually knows about your file. It can\nconvert a USD file like:\n\n```usd\n#usda 1.0\n\ndef \"root\"\n{\n    custom uniform int value = 10\n}\n```\n\nInto a tokenized tree like this:\n\n```scm\n(prim_definition) ; [3:1 - 2:5]\n (prim_type) ; [3:1 - 4:2]\n (string) ; [3:5 - 11:2]\n (block) ; [4:1 - 2:5]\n  (attribute_assignment) ; [5:5 - 34:4]\n   (custom) ; [5:5 - 11:4]\n   (uniform) ; [5:12 - 19:4]\n   (attribute_type) ; [5:20 - 23:4]\n   (identifier) ; [5:24 - 29:4]\n   (integer) ; [5:32 - 34:4]\n```\n\nThat tree is built sparsely, interactively, and even works with WIP files where\nyou may be missing a `}` or two. Tree-sitter is accurate, fast, and getting\nbetter all the time.\n\nHaving this tree is really powerful. It became clear very quickly to others\nthat Tree-sitter can be used for a lot more than just syntax highlighting.\nHere's some of the fun plug-ins showing off what you can do using this USD\nparser.\n\n\n### Neovim\n#### aerial.nvim - Navigate USD Files Effortlessly\n[aerial.nvim](https://github.com/stevearc/aerial.nvim)\n\n##### Display And Move Through A Prim Tree\nEffortlessly move in, out, or around any USD Prim, no matter how large it is.\n\nhttps://user-images.githubusercontent.com/10103049/235325105-1490fb62-4c95-46bf-a170-50df4c7409ff.mp4\n\n\n##### Prim Tree Based On Your Current Position\nMany times I find myself thinking \"I'm in a nested Prim but I actually need to\ngo one down, and over\". This aerial.nvim view is super good at moving around.\n\nhttps://user-images.githubusercontent.com/10103049/235325115-a74d68c6-8f2d-40dd-a7ff-d58240f9b1cd.mp4\n\n\n#### Syntax Highlighting\nTree-sitter is an incremental parser. That means\n\n- Parsing is lightning quick\n- Making edits to the file doesn't require a full re-parse of the file\n- WIP files with syntax errors still parse\n\n![usd_treesitter_syntax_highlighting](https://user-images.githubusercontent.com/10103049/235325800-0ef86ffc-a557-46a5-af7f-3753850c142a.png)\n\nAnd the results are pretty good. My Neovim theme is\n[hybrid2.nvim](https://github.com/ColinKennedy/hybrid2.nvim). If you desire\neven more colors (e.g. coloring ``uniform`` as blue, instead of white), there's\nalready an out-of-box highlight group for that over at\n[nvim-treesitter-highlights-usd](https://github.com/ColinKennedy/nvim-treesitter-highlights-usd).\nIn the future, this might get upstreamed to\n[nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter), maybe.\n\n\n### Maintain The Current Prim Context\nhttps://user-images.githubusercontent.com/10103049/235326266-93c8e868-ed7f-47a7-bda9-238f02979e82.mp4\n\n[nvim-treesitter-context](https://github.com/nvim-treesitter/nvim-treesitter-context)\n\nHave you ever been viewing a huge USD file and, in the middle of viewing some\nPrim, forget the name / tree of the Prim that you're viewing? This fun plug-in\nkeeps the Prim name pinned as you scroll so you never lose your place.\n\n\n### Prim Statusline\n[nvim-gps](https://github.com/SmiteshP/nvim-gps) + [winbar.nvim](https://github.com/fgheng/winbar.nvim)\n\nhttps://user-images.githubusercontent.com/10103049/235326401-64be269b-5e96-4483-b6ee-995392603ef9.mp4\n\nThe top bar tracks your location in the file.\n\n\n### Auto-Folding\nhttps://user-images.githubusercontent.com/10103049/235326728-076f14d8-63fc-4c0c-b3c8-e29065bb2917.mp4\n\n[nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter#folding)\n\n\n### Text Objects\n[nvim-treesitter-textobjects](https://github.com/nvim-treesitter/nvim-treesitter-textobjects)\n\nSelect, move, delete, comment, edit anything easily, using whatever mappings you desire.\n\nIn truth, most people don't have much need to edit USD files directly. But it's\na testiment to tree-sitter that the same mappings do as you expect across all\nlanguages.\n\n\n### Need A Parser? Look No Further\nUSD of course has parsing capabilities but, at the time of writing, most of the\nparsing classes and functions are private. On top of that, it's a multi-million\nlike repository written in C++.\n\nIn contrast, tree-sitter\n\n- Has no dependencies\n- Has [over 10 language bindings](https://tree-sitter.github.io/tree-sitter/#language-bindings) (C, C++, Rust, Python, Swift, JavaScript, etc)\n- Is a fraction of the code\n\nTree-sitter is easy to embed and extend, making it very attractive for plug-in authors.\n\n\n### Future Improvements\n#### Plug-Ins\nThere's a bunch of open-source momentum behind tree-sitter. New tools and plug-ins\nmay come out that further expands upon the list of reasons above. \n\nSome other plug-ins that could be useful in the future\n\n- https://github.com/nvim-treesitter/nvim-treesitter-refactor\n- https://github.com/t-troebst/perfanno.nvim\n- https://github.com/ThePrimeagen/refactoring.nvim\n- https://github.com/bennypowers/nvim-regexplainer/\n- https://github.com/ray-x/navigator.lua\n- https://github.com/Olical/conjure\n\nAnd others\n\n\n#### Neovim 0.10+\nI spotted a couple Neovim roadmap items that seem to want to make tree-sitter faster\nand more async. It's already fast but more speed is definitely welcome on larger USD\nfiles. Needless to say I'll be keeping an eye on those!\n\n- [feat(treesitter): async parsing](https://github.com/neovim/neovim/pull/22420)\n- [Tree-sitter based highlight may be inefficient](https://github.com/neovim/neovim/issues/18108)\n\n\n## Testing\n### Unittests\n- Install the [tree-sitter-cli](https://www.npmjs.com/package/tree-sitter-cli)\n```sh\ncd {root}\ntree-sitter test\n```\n\nAll tests should pass.\n\n\n### Highlighting\n- Clone this repository\n- Add this clone's parent directory ``\"parser-directories\"`` (see [Per-user\n  configuration](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#per-user-configuration))\n\nIf everything worked correctly, you should be able to highlight any USD file from the ``tree-sitter`` CLI like so:\n```\ntree-sitter highlight /path/to/file.usda\n```\n\nYou should see something like this\n\n![tree-sitter_example_usd_hightlighting](https://user-images.githubusercontent.com/10103049/235369836-1a64a111-7d61-40e2-9eda-f3fee31ff46b.png)\n\nAnd the next time you run ``tree-sitter test``, highlighting information will\nbe in the output.\n\n```\nsyntax highlighting:\n  ✓ payload.usda (N assertions)\n  ✓ references.usda (N assertions)\n  ✓ relationship.usda (N assertions)\n  ✓ specializes.usda (N assertions)\n  ✓ string.usda (N assertions)\n\n  ...\n```\n\n\n### Actual USD Files\nThe best way to test tree-sitter-usd is to parse USD files in-action.\n\n- The [USD repository](https://github.com/PixarAnimationStudios/USD) has over 800 production USD files\n- The Pixar [Kitchen set](https://openusd.org/release/dl_downloads.html#assets)\n- Animal Logic's [ALab scene](https://dpel.aswf.io/alab)\n\nThe basic steps are\n\n- Download from any of the links above\n- Install the [tree-sitter-cli](https://www.npmjs.com/package/tree-sitter-cli)\n- Find + parse the files. e.g.\n\n```sh\nfind /path/to/your/root/usd_files/folder -name \"*.usda\" -type f | xargs tree-sitter parse\n```\n\ntree-sitter-usd parses all of the files, everywhere, without errors.\n\n\n## Contributing\nIf you find a bug in a USD file, please submit an issue or pull request specifying\nthe expected parse and the actual results.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinkennedy%2Ftree-sitter-usd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolinkennedy%2Ftree-sitter-usd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinkennedy%2Ftree-sitter-usd/lists"}