srgn

The -i, --invert flag attempts to undo the effects of the passed actions. This requires a 1:1 mapping between the original and the transformed content.

Supported for inversion:

• --symbols: e.g., '!=' $\leftrightarrow$ '≠'.

Not supported for inversion (will be applied normally instead):

• --german: Ambiguity in umlaut expansion (e.g., Ä could be Ae or AE).
• --upper, --lower, --delete, --squeeze: Information loss makes inversion impossible.

When writing custom Tree-sitter queries, you can prevent certain captured nodes from being included in the transformation by prefixing their capture name with _SRGN_IGNORE. This is helpful when you want to match a large structure (like a macro invocation) but only want to modify a specific sub-part of it.

cat wrong.rs | srgn --rust-query '((macro_invocation macro: (identifier) @_SRGN_IGNORE_name) @macro)' 'error' -- 'wrong'

While srgn is inspired by tr, it uses regular expressions for most operations, providing more flexibility.

You can create custom, tailor-made scopes using Tree-sitter query syntax. This is useful for building ad-hoc linters or finding complex patterns that standard scopes (like strings or comments) cannot capture.

Use the --<language>-query flag to pass a query string, or --<language>-query-file to read a query from a .scm file.

cat cond.py | srgn --python-query '(if_statement consequence: (block (return_statement (identifier))) alternative: (else_clause body: (block (return_statement (identifier))))) @cond' --fail-any

The srgn tool operates using two fundamental concepts: scopes and actions.

• Scopes: These narrow down which parts of the input should be processed. If no scope is specified, the entire input is considered in scope.
• Actions: These define the processing to be performed on the scoped input.

Both scopes and actions are composable. You can pass multiple scopes or multiple actions to a single command. Replacements are always applied first in the execution order. The tool is designed to be a more powerful, regex-based alternative to the standard tr utility.

echo 'input' | srgn <scope> <action>

Unlike default regex scopes, language grammar-aware scopes use tree-sitter to perform pattern matching against a tree data structure. This allows srgn to understand the syntax of a language (e.g., distinguishing between a keyword, a comment, or a function call).

Key behaviors:

• Priority: Language scopes are applied first. Any subsequent regular expression scope you provide operates only on the text within the matched language constructs.
• Custom Queries: You can run custom ad-hoc queries using the --lang-query <S EXPRESSION> flag, where lang is the target language (e.g., python).
• Dynamic Variants: Some prepared queries support a dynamic variant using the ~ separator. The syntax is node_type~pattern. The pattern is a regular expression that applies to the name of the language item (like a struct or class name).

To use srgn in a CI pipeline, use the cargo-bins/cargo-binstall action to download the binary quickly without compilation. This method works across all major operating systems.

jobs:
  srgn:
    name: Install srgn in CI
    runs-on: ubuntu-latest
    steps:
      - uses: cargo-bins/cargo-binstall@main
      - name: Install binary
        run: >
          cargo binstall
          --no-confirm
          srgn
      - name: Use binary
        run: srgn --version

To compile srgn from source, ensure you have the Rust toolchain and a C compiler installed:

• Linux: gcc
• macOS: clang
• Windows: MSVC (select "Desktop development with C++")

Then run:

cargo install srgn

The fastest way to install srgn on systems with the Rust toolchain is using cargo-binstall, which downloads prebuilt binaries instead of compiling from source. If no prebuilt binary is available for your platform, it will automatically fall back to compiling from source.

# 1. Install the Rust toolchain
# 2. Install cargo-binstall
cargo install cargo-binstall

# 3. Install srgn
cargo binstall srgn

srgn supports shell completion scripts for various shells. To enable completions in ZSH, add the following line to your ~/.zshrc file:

eval "$(srgn --completions zsh)"