mirror of https://github.com/Wilfred/difftastic/
104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
tree-sitter-gleam
|
|
=================
|
|
|
|
A [tree-sitter] grammar for the [Gleam programming language]
|
|
|
|
[tree-sitter]: https://tree-sitter.github.io
|
|
[Gleam programming language]: https://gleam.run
|
|
|
|
This grammar is able to parse the entire Gleam language. It is largely based
|
|
on the Gleam parser itself, and deviations from that are noted throughout the
|
|
codebase.
|
|
|
|
Usage
|
|
-----
|
|
|
|
tree-sitter-gleam, as with all tree-sitter grammars, is of limited utility on
|
|
its own. Instead, tree-sitter-gleam is best used as a Gleam parser that can be
|
|
embedded in other projects. An example of such a project is
|
|
[tree-sitter-gleam-rust-example].
|
|
|
|
However, [tree-sitter-cli] can be used with this grammar to show generated parse
|
|
trees and syntax highlighting for a given Gleam file.
|
|
|
|
1. [Install tree-sitter-cli]
|
|
2. Create a `tree-sitters` directory in your home directory.
|
|
3. Clone this repository (or symlink it) into the new `~/tree-sitters/` directory.
|
|
4. Run `tree-sitter parse path/to/file.gleam` to be shown the parse tree for the
|
|
file.
|
|
5. Run `tree-sitter highlight path/to/file.gleam` to be shown the file with
|
|
syntax highlighting applied.
|
|
|
|
[tree-sitter-gleam-rust-example]: https://github.com/J3RN/tree-sitter-gleam-rust-example
|
|
[tree-sitter-cli]: https://github.com/tree-sitter/tree-sitter/blob/master/cli/README.md
|
|
[Install tree-sitter-cli]: https://github.com/tree-sitter/tree-sitter/blob/master/cli/README.md#installation
|
|
|
|
Various Gotchas
|
|
---------------
|
|
|
|
There are a few nodes in the generated AST that may be confusing at first:
|
|
|
|
- `type` :: A very ambiguous name, but this refers to a concrete type such as
|
|
`List(#(String, Int))`
|
|
- `type_name` :: Refers to essentially the left side of a type declaration and
|
|
includes parameters, e.g. `MyType(foo, bar)`.
|
|
- `type_identifier` :: Known in the parser as "UpName", this is what you would
|
|
intuitively think of as a type's name, such as `List` or `Result`.
|
|
- `function_call` :: The name is not confusing, but its structure may be. Since
|
|
Gleam supports first-class functions, the function being invoked could be a
|
|
variable, a field of a record, an element of a tuple, etc. Some of these are
|
|
ambiguous without context that tree-sitter does not have. e.g.
|
|
In `string.replace(x, y, z)`, `string` could be a record with a field
|
|
`replace` that is a function or it could be a module with a function `replace`
|
|
—there's no way for the parser to know. In this case, it will be parsed to
|
|
`(function_call function: (field_access ...) ...)` , as I arbitrarily decided
|
|
to always assume the code is accessing a field on a record.
|
|
- `constant_field_access` :: Recognizes when a reference to a remote function is used as a constant's value. Generally field accesses are indistinguishable from remote function invocations by the parser so `field_access` is the node name used for both (hence this misnomer).
|
|
|
|
This is not a comprehensive list. If you find a node confusing, search for it
|
|
in `grammar.js`, as it might have an explanatory comment. Either way, feel free
|
|
to add it to this list and send a PR! ✨
|
|
|
|
To-do List
|
|
----------
|
|
|
|
- [x] Add ability to parse all language constructs
|
|
- [x] Syntax highlighting queries
|
|
- [ ] Have an issue? Let me know! Please [open an issue] 💁
|
|
|
|
[open an issue]: https://github.com/J3RN/tree-sitter-gleam/issues/new
|
|
|
|
Contributing
|
|
------------
|
|
|
|
1. Change files such as `grammar.js` and `queries/highlight.scm`.
|
|
2. The grammar needs to be generated from the `grammar.js` file by running `npm run generate`.
|
|
3. Add parser feature tests to the relevant file(s) in `test/corpus/`, or make a new one.
|
|
4. Run `npm run test` and fix any failing tests.
|
|
|
|
Policies
|
|
--------
|
|
|
|
### Backwards-Compatibility Policy
|
|
|
|
Per the conversation in [#55](https://github.com/gleam-lang/tree-sitter-gleam/pull/55), we have decided that from v0.28.0 forward, tree-sitter-gleam will maintain backwards compatibility with the previous two minor versions; meaning that each release will support three versions:
|
|
- 0.x.0
|
|
- 0.x-1.*
|
|
- 0.x-2.*
|
|
|
|
e.g. The v0.30.0 release of tree-sitter gleam will support the following version of the Gleam language:
|
|
- v0.30.0
|
|
- v0.29.*
|
|
- v0.28.*
|
|
|
|
Style
|
|
-----
|
|
|
|
To prevent headaches from stylistic differences, I request that you please
|
|
follow these style suggestions. 🙏
|
|
|
|
- Remove all non-mandatory trailing whitespace.
|
|
- Ensure a final newline is present at the end of all files (this is the default
|
|
in Vim, Emacs).
|
|
- Format JavaScript by running `npm run format`.
|