Code blocks

Supercharge your editor with syntactically aware code navigation and manipulation, in any language supported by tree-sitter.

Features

Block mode

Syntactically aware code selection (e.g. select scope), navigation (e.g. goto next function) and manipulation (e.g. re-order function parameters), right inside your editor.

Code Blocks Editor

Birds eye view over all your code blocks, with point and click refactoring.

Tree viewer

View your code's syntax tree directly

Requirements

• node / npm: Used to download tree-sitter language parsers. Can be installed from here.

• tree-sitter: Used to build tree-sitter language parsers. After installing npm, can be installed by running:

  $ npm i -g tree-sitter-cli
  

• emcc: Emscripten compiler, used by tree-sitter to compile parsers to WASM. Can be provided either through:

  • Emscripten (preferred): Provides emcc directly.

  • Docker: Provides emcc via the emscripten/emsdk image. Note that the first parser installation can take some time (depending on internet speed), since the image is 1.68GB. Next installs will re-use the image and should take a few seconds at most.

Commands

Keybindings

These are the default key bindings, they are only active when "block mode" is active, and when the cursor is inside a text editor tab:

Configuration

Global

• codeBlocks.treeSitterCliPath: Path to the tree-sitter cli command. Defaults to tree-sitter (assumes command is in PATH).
• codeBlocks.colors.enabled: Whether Block Mode should color selections or not. Defaults to false.
• codeBlocks.colors.sibling: CSS string for sibling selection background color. Defaults to var(--vscode-editor-selectionHighlightBackground).
• codeBlocks.colors.parent: CSS string for parent selection background color. Defaults to var(--vscode-editor-linkedEditingBackground).
• codeBlocks.ignoredLanguageIds: Array of VScode languageIds not to install/load parsers for.

Language specific (advanced)

These configurations are set at the languageId level.

Most languages should just work™, if you find a language that requires manual configuration please create an issue. Or create a pull request with your configuration added to the configurationDefaults section of the package.json file.

• codeBlocks.npmPackageName: NPM package name of the tree-sitter parser to use for the language. Defaults to tree-sitter-<languageId>, change if the package name doesn't match the languageId.

• codeBlocks.parserName: Filename of the WASM parser built by the tree-sitter build-wasm command, without the .wasm extension. Defaults to tree-sitter-<languageId>, change if the parser filename doesn't match the languageId.

• codeBlocks.subdirectory: Directory inside the NPM package containing the tree-sitter grammar. Defaults to the root directory of the package, change if the grammar isn't there.

• codeBlocks.queries: Tree-sitter queries to generate blocks, must contain at least one @capture. The name of the capture doesn't matter, the entire match will be a block.

  Required by Code Blocks Editor.

  Optional for Block Mode - will auto-expand a selection if it is contained by a block.

Example configuration for tsx

Language ID: typescriptreact

NPM package name: tree-sitter-typescript

WASM parser name: tree-sitter-ts.wasm

Desired blocks: JSX blocks, and documentation comments should be merged with documentees.

{
    // language ID of .tsx files is 'typescriptreact'
    "[typescriptreact]": {
        // languageID != package name
        "codeBlocks.npmPackageName": "tree-sitter-typescript",
        // languageID != parser name
        "codeBlocks.parserName": "tree-sitter-tsx",
        // tree-sitter-typescript package contains a 'typescript' dir and a 'tsx' dir, so we need to specify 'tsx
        "codeBlocks.subdirectory": "tsx",
        "codeBlocks.queries": [
            // group documentation comments with their documentees
            "( (comment)* @header . (class_declaration) @item)",
            "( (comment)* @header . (method_definition) @item)",
            "( (comment)* @header . (function_declaration) @item)",
            "( (comment)* @header . (export_statement) @item)",
            // build blocks from jsx elements
            "(jsx_element) @item",
            "(jsx_self_closing_element) @item"
        ]
    }
}

Custom editors

• Code Blocks Editor (viewType codeBlocks.editor): UI for moving code blocks inside a file. Useful when refactoring large blocks over long distances.

Known Issues

• Out of bounds memory access (#154): For now, reloading the editor fixes this.

License

MIT License © 2023 Tom Selfin

Gallery

Block Mode - Move - Rust - Functions

Block Mode - Move - Rust - Match arms

Block Mode - Move - Rust - Parameters

Block Mode - Select - Rust

Block Mode - Select - TypeScript

Block Mode - Select - TypeScript - Selection expands to block

Tree Viewer