Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gleam-lang/tree-sitter-gleam

🌳 A tree-sitter grammar for the Gleam programming language
https://github.com/gleam-lang/tree-sitter-gleam

gleam parser tree-sitter

Last synced: 4 days ago
JSON representation

🌳 A tree-sitter grammar for the Gleam programming language

Awesome Lists containing this project

README 

        
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`.