difftastic/vendored_parsers/tree-sitter-clojure/doc/what-and-why.md

What the Repository Provides and Why

This document describes what files and directories the repository provides and associated reasoning. First it covers things which are likely to remain in place for some time (except perhaps the src directory). This is followed by a description of things that are more likely to change or be removed.

One might be interested in this content out of academic curiosity but more likely it might be because one is thinking of depending on the repository in some way.

What and Why

The order of the following files and directories is alphabetical and not meant to reflect relative importance.

• CHANGELOG.md - this file contains a changelog.

• COPYING.txt - this file contains license information for the repository.

• grammar.js - this file contains a grammar description and is used in the process of generating parser source code that lives in src. It's likely that this (or something comparable) will continue to be provided assuming tree-sitter doesn't change the way it works.

• package.json - this file is needed by a component of Cursorless. It uses our grammar via yarn and package.json seems to be essential.

• queries - this directory and the simple file it contains are provided on request from difftastic folks. The file it contains doesn't contain much and is not likely to be the sort of thing one expects to be used in an editor.

• README.md - this file contains the repository's README content.

• src - this directory contains source files that are generated [1] from grammar.js. The files are typically used to generate a dynamic library / shared object that can be used by the tree-sitter library to handle Clojure / ClojureScript source code. Although the content of this directory is generated, the files are provided because in practice, multiple parties have already become dependant on them. There have been opinions voiced that this should not remain so, but change in that direction has not been widespread. We would prefer not to be hosting this directory and its content, but are leaving it in place for the time being. See here for more on the topic if interested.

• test/corpus - this directory contains tree-sitter's corpus test-related files.

Other Content

The rest of the content of the repository is currently documentation that lives in the doc directory.

About Bindings

The repository does not host any bindings (e.g. for Rust, Node, or other programming language).

They should be straight-forward to generate as long as one has a suitable tree-sitter cli and the grammar.js file mentioned above.

Binding code used to be created by the generate subcommand, but this appears to have changed from version 0.24.0 of the tree-sitter cli:

Move generation of grammar files to an init command (#3694)

Note that "grammar files" here seems to refer to "bindings" files.

Further evidence in support of this change is this documentation:

When you run tree-sitter init, the CLI will also generate a number of files in your repository that allow for your parser to be used from different language.

Which languages bindings files are generated for is affected by the bindings field in tree-sitter.json. (It appears that omitting the field means "don't generate any bindings".)

Probably it's better to consult the official documentation and/or ask around about what the latest procedure is rather than rely on these brief notes though.

Footnotes

[1] If the grammar uses an external scanner, src may contain non-generated files such as scanner.c, scanner.cc, etc. In the current case, no external scanner is used and the src directory content is entirely generated.