traxys/tree-sitter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve implementation page of docs

Browse source
This commit is contained in:
Max Brunsfeld 2018-06-20 09:49:23 -07:00
parent 34de822738
commit be81989de2
3 changed files with 42 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

24
docs/section-2-architecture.md
View file

@ -1,24 +0,0 @@
---
title: Architecture
permalink: architecture
---
# Architecture
Tree-sitter consists of two separate libraries, both of which expose C APIs.
The first library, `libcompiler`, is
used to generate a parser for a language by supplying a [context-free grammar](https://en.wikipedia.org/wiki/Context-free_grammar) describing the
language. `libcompiler` is a build tool; it is no longer needed once a parser has been generated. Its public interface is specified in the header file [`compiler.h`](https://github.com/tree-sitter/tree-sitter/blob/master/include/tree_sitter/compiler.h).
The second library, `libruntime`, is used in combination with the parsers
generated by `libcompiler`, to produce syntax trees from source code and keep the
syntax trees up-to-date as the source code changes. `libruntime` is designed to be embedded in applications. Its interface is specified in the header file [`runtime.h`](https://github.com/tree-sitter/tree-sitter/blob/master/include/tree_sitter/runtime.h).
## The Compiler
WIP
## The Runtime
WIP

0
docs/section-4-using-parsers.md → docs/section-2-using-parsers.md
View file

42
docs/section-4-implementation.md Normal file
View file

@ -0,0 +1,42 @@
---
title: Implementation
permalink: implementation
---
# Implementation
Tree-sitter consists of two separate libraries, both of which expose C APIs.
The first library, `libcompiler`, is
used to generate a parser for a language by supplying a [context-free grammar](https://en.wikipedia.org/wiki/Context-free_grammar) describing the
language. `libcompiler` is a build tool; it is no longer needed once a parser has been generated. It is written in C++, but exposes a C interface, which is declared in the header file [`compiler.h`](https://github.com/tree-sitter/tree-sitter/blob/master/include/tree_sitter/compiler.h).
The second library, `libruntime`, is used in combination with the parsers
generated by `libcompiler`, to produce syntax trees from source code and keep the
syntax trees up-to-date as the source code changes. `libruntime` is designed to be embedded in applications. It is written in plain C. Its interface is specified in the header file [`runtime.h`](https://github.com/tree-sitter/tree-sitter/blob/master/include/tree_sitter/runtime.h).
## The Compiler
The `libcompiler` library exports only one function: `ts_compile_grammar`. This function takes a context-free grammar as a JSON string and returns a parser as a string of C code. The source files in the [`src/compiler`](https://github.com/tree-sitter/tree-sitter/tree/master/src/compiler) directory all play a role in producing this C code. This section will describe some key parts of this process.
### Parsing a Grammar
First, `libcompiler` must parse the JSON grammar. The format of the grammars is formally specified by the JSON schema in [grammar-schema.json](https://github.com/tree-sitter/tree-sitter/blob/master/src/compiler/grammar-schema.json). The parsing is implemented in [parser_grammar.cc](https://github.com/tree-sitter/tree-sitter/blob/master/src/compiler/parse_grammar.cc). It uses [udp/json-parser](https://github.com/udp/json-parser), one of Tree-sitter's few library dependencies.
### Grammar Rules
A Tree-sitter grammar is composed of a set of *rules* - objects that describe how syntax nodes can be composed from other syntax nodes. There are several types of rules: symbols, strings, regexes, sequences, choices, repetitions, and a few others. Internally, these are all represented using a [tagged union](https://en.wikipedia.org/wiki/Tagged_union) class called [`Rule`](https://github.com/tree-sitter/tree-sitter/blob/master/src/compiler/rule.h). This class has a method called `match`, which makes it easy to [pattern-match](https://en.wikipedia.org/wiki/Pattern_matching) a rule, processing each type of rule with separate code.
### Preparing a Grammar
Once a grammar has been parsed, it must be transformed in several ways before it can be used to generate a parser. Each transformation is implemented by a separate file in the [`src/compiler/prepare_grammar`](https://github.com/tree-sitter/tree-sitter/tree/master/src/compiler/prepare_grammar) directory, and the transformations are ultimately composed together in `prepare_grammar.cc`.
At the end of these transformations, the initial grammar is split into two grammars: a *syntax grammar* and a *lexical grammar*. The syntax grammar describes how the language's [*non-terminal symbols*](https://en.wikipedia.org/wiki/Terminal_and_nonterminal_symbols) are constructed from other grammar symbols, and the lexical grammar describes how the grammar's *terminal symbols* (strings and regexes) can be composed from individual characters.
### Building Parse Tables
## The Runtime
WIP