This library parses USD ASCII files using tree-sitter to produce a light-weight grammar of the file.
For those who don't know what tree-sitter is and why you'd care to use it, see Why Tree-sitter?. For install / usage instructions, see below.
This repository's parsing rules are subject to change.
Make sure you include the following somewhere in your init.lua file.
require("nvim-treesitter.configs").setup {
ensure_installed = {"usd"},
parser_install_dir = installation_directory,
highlight = { enable = true },
-- More stuff
}In the beginning, Tree-sitter was made to give text editors better syntax highlighting.
Most text editors today create syntax highlighting with regex patterns. On large files with long line counts, this approach is slow and error-prone.
In contrast to regex, Tree-sitter actually knows about your file. It can convert a USD file like:
#usda 1.0
def "root"
{
custom uniform int value = 10
}
Into a tokenized tree like this:
(prim_definition) ; [3:1 - 2:5]
(prim_type) ; [3:1 - 4:2]
(string) ; [3:5 - 11:2]
(block) ; [4:1 - 2:5]
(attribute_assignment) ; [5:5 - 34:4]
(custom) ; [5:5 - 11:4]
(uniform) ; [5:12 - 19:4]
(attribute_type) ; [5:20 - 23:4]
(identifier) ; [5:24 - 29:4]
(integer) ; [5:32 - 34:4]That tree is built sparsely, interactively, and even works with WIP files where
you may be missing a } or two. Tree-sitter is accurate, fast, and getting
better all the time.
Having this tree is really powerful. It became clear very quickly to others that Tree-sitter can be used for a lot more than just syntax highlighting. Here's some of the fun plug-ins showing off what you can do using this USD parser.
Effortlessly move in, out, or around any USD Prim, no matter how large it is.
navigate_within_prim_tree.mp4
Many times I find myself thinking "I'm in a nested Prim but I actually need to go one down, and over". This aerial.nvim view is super good at moving around.
move_up_and_drop_the_prim_hiearchy.mp4
Tree-sitter is an incremental parser. That means
- Parsing is lightning quick
- Making edits to the file doesn't require a full re-parse of the file
- WIP files with syntax errors still parse
And the results are pretty good. My Neovim theme is
hybrid2.nvim. If you desire
even more colors (e.g. coloring uniform as blue, instead of white), there's
already an out-of-box highlight group for that over at
nvim-treesitter-highlights-usd.
In the future, this might get upstreamed to
nvim-treesitter, maybe.
prim_treesitter_context.mp4
Have you ever been viewing a huge USD file and, in the middle of viewing some Prim, forget the name / tree of the Prim that you're viewing? This fun plug-in keeps the Prim name pinned as you scroll so you never lose your place.
treesitter_usd_statusline.mp4
The top bar tracks your location in the file.
prim_auto_folding.mp4
Select, move, delete, comment, edit anything easily, using whatever mappings you desire.
In truth, most people don't have much need to edit USD files directly. But it's a testiment to tree-sitter that the same mappings do as you expect across all languages.
USD of course has parsing capabilities but, at the time of writing, most of the parsing classes and functions are private. On top of that, it's a multi-million like repository written in C++.
In contrast, tree-sitter
- Has no dependencies
- Has over 10 language bindings (C, C++, Rust, Python, Swift, JavaScript, etc)
- Is a fraction of the code
Tree-sitter is easy to embed and extend, making it very attractive for plug-in authors.
There's a bunch of open-source momentum behind tree-sitter. New tools and plug-ins may come out that further expands upon the list of reasons above.
Some other plug-ins that could be useful in the future
- https://github.com/nvim-treesitter/nvim-treesitter-refactor
- https://github.com/t-troebst/perfanno.nvim
- https://github.com/ThePrimeagen/refactoring.nvim
- https://github.com/bennypowers/nvim-regexplainer/
- https://github.com/ray-x/navigator.lua
- https://github.com/Olical/conjure
And others
I spotted a couple Neovim roadmap items that seem to want to make tree-sitter faster and more async. It's already fast but more speed is definitely welcome on larger USD files. Needless to say I'll be keeping an eye on those!
- Install the tree-sitter-cli
cd {root}
tree-sitter testAll tests should pass.
- Clone this repository
- Add this clone's parent directory
"parser-directories"(see Per-user configuration)
If everything worked correctly, you should be able to highlight any USD file from the tree-sitter CLI like so:
tree-sitter highlight /path/to/file.usda
You should see something like this
And the next time you run tree-sitter test, highlighting information will
be in the output.
syntax highlighting:
✓ payload.usda (N assertions)
✓ references.usda (N assertions)
✓ relationship.usda (N assertions)
✓ specializes.usda (N assertions)
✓ string.usda (N assertions)
...
The best way to test tree-sitter-usd is to parse USD files in-action.
- The USD repository has over 800 production USD files
- The Pixar Kitchen set
- Animal Logic's ALab scene
The basic steps are
- Download from any of the links above
- Install the tree-sitter-cli
- Find + parse the files. e.g.
find /path/to/your/root/usd_files/folder -name "*.usda" -type f | xargs tree-sitter parsetree-sitter-usd parses all of the files, everywhere, without errors.
If you find a bug in a USD file, please submit an issue or pull request specifying the expected parse and the actual results.