#stack-graphs #tree-sitter #ruby

bin+lib tree-sitter-stack-graphs-ruby

Stack graphs definition for Ruby using tree-sitter-ruby

1 unstable release

0.0.1 May 11, 2023

#5 in #stack-graphs

MIT/Apache

13KB
63 lines

tree-sitter-stack-graphs definition for Ruby

This project defines tree-sitter-stack-graphs rules for Ruby using the tree-sitter-ruby grammar.

Usage

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

[dependencies]
tree-sitter-stack-graphs-ruby = "0.0.1"

Check out our documentation for more details on how to use this library.

Command-line Program

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

Install the program using cargo install as follows:

$ cargo install --features cli tree-sitter-stack-graphs-ruby
$ tree-sitter-stack-graphs-ruby --help

Development

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

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.rb and builtins.cfg respectively.
  • Tests are put into the test directory.

Building and Running Tests

Build the project by running:

$ cargo build

Run the tests as follows:

$ 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:

$ cargo run --features cli -- ARGS

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

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

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

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

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

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

To generate the visualization regardless of test outcome, execute:

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

Dependencies

~24–34MB
~738K SLoC