docs(cli): better description of files generated by init
This commit is contained in:
Christian Clason
Christian Clason
parent
f96d518ebf
commit
ba7350c7ee
3 changed files with 92 additions and 86 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# `tree-sitter generate`
|
||||
|
||||
The most important command for grammar development is `tree-sitter generate`, which reads the grammar in structured form and outputs C files that can be compiled into a shared or static library (e.g., using the [`build`](./build,md) command).
|
||||
The most important command for grammar development is `tree-sitter generate`, which reads the grammar in structured form and outputs C files that can be compiled into a shared or static library (e.g., using the [`build`](./build.md) command).
|
||||
|
||||
```bash
|
||||
tree-sitter generate [OPTIONS] [GRAMMAR_PATH] # Aliases: gen, g
|
||||
|
|
|
|||
|
|
@ -1,4 +1,7 @@
|
|||
# CLI Overview
|
||||
|
||||
Let's go over all of the functionality of the `tree-sitter` command line interface.
|
||||
Once you feel that you have enough of a grasp on the CLI, you can move onto the grammar authoring section to learn more about writing your own parser.
|
||||
The `tree-sitter` command-line interface is used to create, manage, test, and build tree-sitter parsers. It is controlled by
|
||||
|
||||
- a personal `tree-sitter/config.json` config file generated by [`tree-sitter init-config`](./init-config.md)
|
||||
- a parser `tree-sitter.json` config file generated by [`tree-sitter init`](./init.md).
|
||||
|
||||
|
|
|
|||
|
|
@ -8,30 +8,91 @@ we recommend using git for version control of your grammar.
|
|||
tree-sitter init [OPTIONS] # Aliases: i
|
||||
```
|
||||
|
||||
## Options
|
||||
## Generated files
|
||||
|
||||
### `--update`
|
||||
### Required files
|
||||
|
||||
Update outdated generated files, if needed.
|
||||
The following required files are always created if missing:
|
||||
|
||||
### `-p/--grammar-path <PATH>`
|
||||
- `tree-sitter.json` - The main configuration file that determines how `tree-sitter` interacts with the grammar. If missing, the `init` command will prompt the user for the required fields. See [below](./init.md#structure-of-tree-sitterjson) for the full documentation of the structure of this file.
|
||||
- `package.json` - The `npm` manifest for the parser. This file is required for some `tree-sitter` subcommands, and if the grammar has dependencies (e.g., another published base grammar that this grammar extends).
|
||||
- `grammar.js` - An empty template for the main grammar file; see [the section on creating parsers](../2-creating-parser).
|
||||
|
||||
The path to the directory containing the grammar.
|
||||
### Language bindings
|
||||
|
||||
Language bindings are files that allow your parser to be directly used by projects written in the respective language.
|
||||
The following bindings are created if enabled in `tree-sitter.json`:
|
||||
|
||||
#### C/C++
|
||||
|
||||
- `Makefile` — This file tells [`make`][make] how to compile your language.
|
||||
- `CMakeLists.txt` — This file tells [`cmake`][cmake] how to compile your language.
|
||||
- `bindings/c/tree_sitter/tree-sitter-language.h` — This file provides the C interface of your language.
|
||||
- `bindings/c/tree-sitter-language.pc` — This file provides [pkg-config][pkg-config] metadata about your language's C library.
|
||||
|
||||
#### Go
|
||||
|
||||
- `go.mod` — This file is the manifest of the Go module.
|
||||
- `bindings/go/binding.go` — This file wraps your language in a Go module.
|
||||
- `bindings/go/binding_test.go` — This file contains a test for the Go package.
|
||||
|
||||
#### Node
|
||||
|
||||
- `binding.gyp` — This file tells Node.js how to compile your language.
|
||||
- `bindings/node/binding.cc` — This file wraps your language in a JavaScript module for Node.js.
|
||||
- `bindings/node/index.js` — This is the file that Node.js initially loads when using your language.
|
||||
- `bindings/node/index.d.ts` — This file provides type hints for your parser when used in TypeScript.
|
||||
- `bindings/node/binding_test.js` — This file contains a test for the Node.js package.
|
||||
|
||||
#### Java
|
||||
|
||||
- `pom.xml` - This file is the manifest of the Maven package.
|
||||
- `bindings/java/main/namespace/language/TreeSitterLanguage.java` - This file wraps your language in a Java class.
|
||||
- `bindings/java/test/TreeSitterLanguageTest.java` - This file contains a test for the Java package.
|
||||
|
||||
#### Python
|
||||
|
||||
- `pyproject.toml` — This file is the manifest of the Python package.
|
||||
- `setup.py` — This file tells Python how to compile your language.
|
||||
- `bindings/python/tree_sitter_language/binding.c` — This file wraps your language in a Python module.
|
||||
- `bindings/python/tree_sitter_language/__init__.py` — This file tells Python how to load your language.
|
||||
- `bindings/python/tree_sitter_language/__init__.pyi` — This file provides type hints for your parser when used in Python.
|
||||
- `bindings/python/tree_sitter_language/py.typed` — This file provides type hints for your parser when used in Python.
|
||||
- `bindings/python/tests/test_binding.py` — This file contains a test for the Python package.
|
||||
|
||||
#### Rust
|
||||
|
||||
- `Cargo.toml` — This file is the manifest of the Rust package.
|
||||
- `bindings/rust/build.rs` — This file tells Rust how to compile your language.
|
||||
- `bindings/rust/lib.rs` — This file wraps your language in a Rust crate when used in Rust.
|
||||
|
||||
#### Swift
|
||||
|
||||
- `Package.swift` — This file tells Swift how to compile your language.
|
||||
- `bindings/swift/TreeSitterLanguage/language.h` — This file wraps your language in a Swift module when used in Swift.
|
||||
- `bindings/swift/TreeSitterLanguageTests/TreeSitterLanguageTests.swift` — This file contains a test for the Swift package.
|
||||
|
||||
#### Zig
|
||||
|
||||
- `build.zig` - This file tells Zig how to compile your language.
|
||||
- `build.zig.zon` - This file is the manifest of the Zig package.
|
||||
- `bindings/zig/root.zig` - This file wraps your language in a Zig module.
|
||||
- `bindings/zig/test.zig` - This file contains a test for the Zig package.
|
||||
|
||||
### Additional files
|
||||
|
||||
In addition, the following files are created that aim to improve the development experience:
|
||||
|
||||
- `.editorconfig` — This file tells your editor how to format your code. More information about this file can be found [here][editorconfig].
|
||||
- `.gitattributes` — This file tells Git how to handle line endings and tells GitHub which files are generated.
|
||||
- `.gitignore` — This file tells Git which files to ignore when committing changes.
|
||||
|
||||
## Structure of `tree-sitter.json`
|
||||
|
||||
The main file of interest for users to configure is `tree-sitter.json`, which tells the CLI information about your grammar,
|
||||
such as the location of queries.
|
||||
|
||||
### The `grammars` field
|
||||
|
||||
This field is an array of objects, though you typically only need one object in this array unless your repo has
|
||||
multiple grammars (for example, `Typescript` and `TSX`).
|
||||
|
||||
### Example
|
||||
|
||||
Typically, the objects in the `"tree-sitter"` array only needs to specify a few keys:
|
||||
|
||||
multiple grammars (for example, `Typescript` and `TSX`), e.g.,
|
||||
```json
|
||||
{
|
||||
"tree-sitter": [
|
||||
|
|
@ -49,7 +110,7 @@ Typically, the objects in the `"tree-sitter"` array only needs to specify a few
|
|||
}
|
||||
```
|
||||
|
||||
#### Basic Fields
|
||||
#### Basic fields
|
||||
|
||||
These keys specify basic information about the parser:
|
||||
|
||||
|
|
@ -65,11 +126,11 @@ parser to files that should be checked for modifications during recompilation.
|
|||
This is useful during development to have changes to other files besides scanner.c
|
||||
be picked up by the cli.
|
||||
|
||||
#### Language Detection
|
||||
#### Language detection
|
||||
|
||||
These keys help to decide whether the language applies to a given file:
|
||||
|
||||
- `file-types` — An array of filename suffix strings. The grammar will be used for files whose names end with one of
|
||||
- `file-types` — An array of filename suffix strings (not including the dot). The grammar will be used for files whose names end with one of
|
||||
these suffixes. Note that the suffix may match an *entire* filename.
|
||||
|
||||
- `first-line-regex` — A regex pattern that will be tested against the first line of a file
|
||||
|
|
@ -85,14 +146,14 @@ no `content-regex` will be preferred over this one.
|
|||
should be used for a potential *language injection* site.
|
||||
Language injection is described in more detail in [the relevant section](../3-syntax-highlighting.md#language-injection).
|
||||
|
||||
#### Query Paths
|
||||
#### Query paths
|
||||
|
||||
These keys specify relative paths from the directory containing `tree-sitter.json` to the files that control syntax highlighting:
|
||||
|
||||
- `highlights` — Path to a *highlight query*. Default: `queries/highlights.scm`
|
||||
- `locals` — Path to a *local variable query*. Default: `queries/locals.scm`.
|
||||
- `injections` — Path to an *injection query*. Default: `queries/injections.scm`.
|
||||
- `tags` — Path to an *tag query*. Default: `queries/tags.scm`.
|
||||
- `tags` — Path to a *tag query*. Default: `queries/tags.scm`.
|
||||
|
||||
### The `metadata` field
|
||||
|
||||
|
|
@ -121,76 +182,18 @@ Each key is a language name, and the value is a boolean.
|
|||
- `swift` (default: `false`)
|
||||
- `zig` (default: `false`)
|
||||
|
||||
## Binding Files
|
||||
## Options
|
||||
|
||||
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. Here is a list of these bindings files that are generated, and what their purpose is:
|
||||
### `-u/--update`
|
||||
|
||||
### C/C++
|
||||
Update outdated generated files, if possible.
|
||||
|
||||
- `Makefile` — This file tells [`make`][make] how to compile your language.
|
||||
- `CMakeLists.txt` — This file tells [`cmake`][cmake] how to compile your language.
|
||||
- `bindings/c/tree_sitter/tree-sitter-language.h` — This file provides the C interface of your language.
|
||||
- `bindings/c/tree-sitter-language.pc` — This file provides [pkg-config][pkg-config] metadata about your language's C library.
|
||||
**Note:** Existing files that may have been edited manually are _not_ updated in general. To force an update to such files, remove them and call `tree-sitter init -u` again.
|
||||
|
||||
### Go
|
||||
### `-p/--grammar-path <PATH>`
|
||||
|
||||
- `go.mod` — This file is the manifest of the Go module.
|
||||
- `bindings/go/binding.go` — This file wraps your language in a Go module.
|
||||
- `bindings/go/binding_test.go` — This file contains a test for the Go package.
|
||||
The path to the directory containing the grammar.
|
||||
|
||||
### Node
|
||||
|
||||
- `binding.gyp` — This file tells Node.js how to compile your language.
|
||||
- `package.json` — This file is the manifest of the Node.js package.
|
||||
- `bindings/node/binding.cc` — This file wraps your language in a JavaScript module for Node.js.
|
||||
- `bindings/node/index.js` — This is the file that Node.js initially loads when using your language.
|
||||
- `bindings/node/index.d.ts` — This file provides type hints for your parser when used in TypeScript.
|
||||
- `bindings/node/binding_test.js` — This file contains a test for the Node.js package.
|
||||
|
||||
### Java
|
||||
|
||||
- `pom.xml` - This file is the manifest of the Maven package.
|
||||
- `bindings/java/main/namespace/language/TreeSitterLanguage.java` - This file wraps your language in a Java class.
|
||||
- `bindings/java/test/TreeSitterLanguageTest.java` - This file contains a test for the Java package.
|
||||
|
||||
### Python
|
||||
|
||||
- `pyproject.toml` — This file is the manifest of the Python package.
|
||||
- `setup.py` — This file tells Python how to compile your language.
|
||||
- `bindings/python/tree_sitter_language/binding.c` — This file wraps your language in a Python module.
|
||||
- `bindings/python/tree_sitter_language/__init__.py` — This file tells Python how to load your language.
|
||||
`bindings/python/tree_sitter_language/__init__.pyi` — This file provides type hints for your parser when used in Python.
|
||||
- `bindings/python/tree_sitter_language/py.typed` — This file provides type hints for your parser when used in Python.
|
||||
- `bindings/python/tests/test_binding.py` — This file contains a test for the Python package.
|
||||
|
||||
### Rust
|
||||
|
||||
- `Cargo.toml` — This file is the manifest of the Rust package.
|
||||
- `bindings/rust/lib.rs` — This file wraps your language in a Rust crate when used in Rust.
|
||||
- `bindings/rust/build.rs` — This file wraps the building process for the Rust crate.
|
||||
|
||||
### Swift
|
||||
|
||||
- `Package.swift` — This file tells Swift how to compile your language.
|
||||
- `bindings/swift/TreeSitterLanguage/language.h` — This file wraps your language in a Swift module when used in Swift.
|
||||
- `bindings/swift/TreeSitterLanguageTests/TreeSitterLanguageTests.swift` — This file contains a test for the Swift package.
|
||||
|
||||
### Zig
|
||||
|
||||
- `build.zig` - This file tells Zig how to compile your language.
|
||||
- `build.zig.zon` - This file is the manifest of the Zig package.
|
||||
- `bindings/zig/root.zig` - This file wraps your language in a Zig module.
|
||||
- `bindings/zig/test.zig` - This file contains a test for the Zig package.
|
||||
|
||||
### Additional Files
|
||||
|
||||
Additionally, there's a few other files that are generated when you run `tree-sitter init`,
|
||||
that aim to improve the development experience:
|
||||
|
||||
- `.editorconfig` — This file tells your editor how to format your code. More information about this file can be found [here][editorconfig]
|
||||
- `.gitattributes` — This file tells Git how to handle line endings, and tells GitHub what files are generated.
|
||||
- `.gitignore` — This file tells Git what files to ignore when committing changes.
|
||||
|
||||
[cmake]: https://cmake.org/cmake/help/latest
|
||||
[editorconfig]: https://editorconfig.org
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue