mirror of https://github.com/Wilfred/difftastic/
102 lines
4.2 KiB
Markdown
102 lines
4.2 KiB
Markdown
# 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](https://github.com/cursorless-dev/vscode-parse-tree/) of
|
|
[Cursorless](https://www.cursorless.org/). 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`](https://github.com/Wilfred/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](https://github.com/sogaiu/ts-questions/blob/master/questions/should-parser-source-be-committed/README.md)
|
|
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](https://github.com/tree-sitter/tree-sitter/releases/tag/v0.24.0):
|
|
|
|
> Move generation of grammar files to an init command ([#3694](https://github.com/tree-sitter/tree-sitter/pull/3694))
|
|
|
|
Note that "grammar files" here seems to refer to "bindings" files.
|
|
|
|
Further evidence in support of this change is [this
|
|
documentation](https://tree-sitter.github.io/tree-sitter/cli/init.html#binding-files):
|
|
|
|
> 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`](https://tree-sitter.github.io/tree-sitter/cli/init.html#the-bindings-field).
|
|
(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.
|
|
|