Code-shape

Code-shape is a tool that uses Tree-sitter to extract a shape of code definitions from a source code file. The tool uses the same language parsers that are installed for Tree-sitter CLI.

Installation

To install the code-shape CLI it's possible to use Rust's Cargo package manager:

cargo install code-shape

Usage

To start using to tool it's needed to do some preparation.

Prerequsites

1. Install Tree-sitter CLI.
2. Run tree-sitter init-config that creates a config file like ~/.config/tree-sitter/config.json in Tree-sitter's config dir.
3. Create a directory where installed parsers would be located and add it in "parser-directories" list in Tree-sitter's config file.
4. Clone Tree-sitter parsers for required languages to the parsers directory.

Define extraction query

To make it possible to extract a shape of definitions from some source code file for some language, it's needed to define a query. To define a new query create a file in a Code-shape's languages config dir ~/.config/code-shape/languages/ with an .scm suffix like ~/.config/code-shape/languages/c.scm and put there a set of Tree-sitter query patterns like:

; C language function definitions & declarations
[
    (declaration
        [
            (function_declarator
                declarator: (identifier) @fn.name
            )
            (init_declarator
                (_
                    (function_declarator
                        (_ (_ declarator: (identifier) @fn.name))
                    )
                )
            )
        ]
    )
    (function_definition
        [
            (function_declarator
                declarator: (identifier) @fn.name
            )
            (_
                (function_declarator
                    declarator: (identifier) @fn.name
                )
            )
        ]
        body: (_
            "{" @fn.begin
            "}" @fn.end
        )
    )
]

It's needed to define captures with special names:

• <type>.name is a capture where the type may be, e.g., fn, class or anything else to match a code entity name.
• <type>.begin and <type>.end are special captures that allow for the tool to capture a context of entities and usually are tokens that defines a body of the the entity, e.g., a function body.

An example of the tool output:

# code-shape --scope source.c tree-sitter/lib/src/alloc.c
fn ts_malloc_default
fn ts_calloc_default
fn ts_realloc_default
fn ts_current_malloc
fn ts_current_calloc
fn ts_current_realloc
fn ts_set_allocator

Embedded shape queries

For now the tool has builtin shape queries for the following language parsers:

• C