tree-sitter-stack-graphs-python 0.0.1

Stack graphs definition for Python using tree-sitter-python
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# tree-sitter-stack-graphs definition for Python

This project defines tree-sitter-stack-graphs rules for Python using the [tree-sitter-python][] grammar.

[tree-sitter-python]: https://crates.io/crates/tree-sitter-python

## Usage

To use this library, add the following to your `Cargo.toml`:

``` toml
[dependencies]
tree-sitter-stack-graphs-python = "0.1.0"
```

Check out our [documentation](https://docs.rs/tree-sitter-stack-graphs-python/*/) for more details on how to use this library.

## Command-line Program

The command-line program for `tree-sitter-stack-graphs-python` lets you do stack graph based analysis and lookup from the command line.

Install the program using `cargo install` as follows:

``` sh
$ cargo install --features cli tree-sitter-stack-graphs-python
$ tree-sitter-stack-graphs-python --help
```

## Development

The project is written in Rust, and requires a recent version installed.  Rust can be installed and updated using [rustup][].

[rustup]: https://rustup.rs/

The project is organized as follows:

- The stack graph rules are defined in `src/stack-graphs.tsg`.
- Builtins sources and configuration are defined in `src/builtins.py` and `builtins.cfg` respectively.
- Tests are put into the `test` directory.

### Building and Running Tests

Build the project by running:

``` sh
$ cargo build
```

Run the tests as follows:

``` sh
$ cargo test
```

The project consists of a library and a CLI. By default, running `cargo` only applies to the library. To run `cargo` commands on the CLI as well, add `--features cli` or `--all-features`.

Run the CLI from source as follows:

``` sh
$ cargo run --features cli -- ARGS
```

Sources are formatted using the standard Rust formatted, which is applied by running:

``` sh
$ cargo fmt
```

### Writing TSG

The stack graph rules are written in [tree-sitter-graph][]. Checkout the [examples][],
which contain self-contained TSG rules for specific language features. A VSCode
[extension][] is available that provides syntax highlighting for TSG files.

[tree-sitter-graph]: https://github.com/tree-sitter/tree-sitter-graph
[examples]: https://github.com/github/stack-graphs/blob/main/tree-sitter-stack-graphs/examples/
[extension]: https://marketplace.visualstudio.com/items?itemName=tree-sitter.tree-sitter-graph

Parse and test a single file by executing the following commands:

``` sh
$ cargo run --features cli -- parse FILES...
$ cargo run --features cli -- test TESTFILES...
```

Generate a visualization to debug failing tests by passing the `-V` flag:

``` sh
$ cargo run --features cli -- test -V TESTFILES...
```

To generate the visualization regardless of test outcome, execute:

``` sh
$ cargo run --features cli -- test -V --output-mode=always TESTFILES...
```

Go to https://crates.io/crates/tree-sitter-stack-graphs for links to examples and documentation.