github/semantic
1
1
Fork 0
mirror of https://github.com/github/semantic.git synced 2024-11-27 12:57:49 +03:00
Code Issues Projects Releases Wiki Activity

semantic-[lang] ingredients

Browse Source
This commit is contained in:
Ayman Nadeem 2020-04-17 18:36:57 -04:00
parent 5c64b56e52
commit be91d5aa8c
1 changed files with 5 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/adding-new-languages.md
View File

@ -10,8 +10,11 @@ Please note that this list of steps reflects the state of Semantic as is, not wh
2. **Create a Haskell library providing an interface to that C source.** The [`haskell-tree-sitter`](https://github.com/tree-sitter/haskell-tree-sitter) repository provides a Cabal package for each supported language. You can find an example of a pull request to add such a package [here](https://github.com/tree-sitter/haskell-tree-sitter/pull/276/files), and a file providing:
- A bridged (via the FFI) reference to the toplevel parser in the generated file must be provided ([example](https://github.com/tree-sitter/haskell-tree-sitter/blob/master/tree-sitter-json/TreeSitter/JSON.hs#L11)).
- A way to retrieve [`tree-sitter` data](https://github.com/tree-sitter/haskell-tree-sitter/blob/master/tree-sitter-json/TreeSitter/JSON.hs#L13-L14) used to auto-generate syntax datatypes using the following steps.
3. **Create a Haskell library in Semantic to auto-generate precise ASTs.**
3. **Create a Haskell library in Semantic to auto-generate precise ASTs.** Create a `semantic-[LANGUAGE]` package ([Example](https://github.com/github/semantic/tree/master/semantic-python)). Each package needs to provide the following API surfaces:
- `Language.[LANGUAGE].AST` - Derives Haskell datatypes from a language and its `node-types.json` file ([Example](https://github.com/github/semantic/blob/master/semantic-python/src/Language/Python/AST.hs)).
- `Language.[LANGUAGE].Grammar` - Provides statically-known rules corresponding to symbols in the grammar for each syntax node, generated with the `mkStaticallyKnownRuleGrammarData` Template Haskell splice. ([Example](https://github.com/github/semantic/blob/master/semantic-python/src/Language/Python/Grammar.hs)).
- `Language.[LANGUAGE]` - Semantic functionality for programs in a language ([Example](https://github.com/github/semantic/blob/master/semantic-python/src/Language/Python.hs)).
- `Language.[LANGUAGE].Tags` - Computes tags for code nav definitions and references found in source ([Example](https://github.com/github/semantic/blob/master/semantic-python/src/Language/Python/Tags.hs)).
5. **Add tests for diffing, tagging, graphing, and evaluating code written in that language.** Because tree-sitter grammars often change, we require extensive testing so as to avoid the unhappy situation of bitrotted languages that break as soon as a new grammar comes down the line.
To summarize, each interaction made possible by the Semantic CLI corresponds to one (or more) of the above steps: