DOCSEARCHbyAlgolia
Submit Docs

grep-ast

repository·main·Indexed 43 days ago

https://github.com/aider-ai/grep-ast

A source code search tool that leverages Abstract Syntax Trees (AST) via tree-sitter to provide rich context, such as classes, functions, and methods, surrounding matching lines. It includes a CLI (aliased as gast) and a programmatic TreeContext class for AST-based searching.

Tokens
1.5K
Snippets
6
Records
6
Agent score
7%

What's inside grep-ast

  1. Use grep-ast to search source code

    main

    Use grep-ast (or the alias gast) to search for a pattern in source code files. By default, it recurses the current directory and respects .gitignore. It uses tree-sitter to provide context from the abstract syntax tree (AST), showing you the functions, classes, and methods that contain your matches.

    grep-ast [pattern] [filenames...]

  3. Reference grep-ast CLI options

    main

    The following options are available for the grep-ast command:

    • pat: The pattern to search for (positional).
    • filenames: The files to display (positional).
    • -h, --help: Show this help message and exit.
    • -i, --ignore-case: Ignore case distinctions.
    • --color: Force color printing.
    • --no-color: Disable color printing.
    • --encoding ENCODING: Specify the file encoding.
    • --languages: Print the parsers table (supported languages).
    • --verbose: Enable verbose output.
    usage: grep_ast.py [-h] [-i] [--color] [--no-color] [--encoding ENCODING] [--languages] [--verbose]
                   [pat] [filenames ...]

positional arguments:
  pat                  the pattern to search for
  filenames            the files to display

options:
  -h, --help           show this help message and exit
  -i, --ignore-case    ignore case distinctions
  --color              force color printing
  --no-color           disable color printing
  --encoding ENCODING  file encoding
  --languages          print the parsers table
  --verbose            enable verbose output

  4. Use TreeContext for programmatic pattern searching

    main

    The TreeContext class is the core engine for AST-based searching. It takes a filename and the file's source code to build a context that can be queried for lines of interest.

    Initialization: TreeContext(filename, code, color=False, verbose=False, line_number=False)

    Workflow:

    1. Initialize TreeContext with the file path and content.
    2. Call .grep(pattern, ignore_case=False) to find lines of interest.
    3. If matches are found, call .add_lines_of_interest(loi).
    4. Call .add_context() to expand the context around the matches.
    5. Call .format() to get the final string representation of the search results.
    from grep_ast.grep_ast import TreeContext

filename = "example.py"
code = "def hello():\n    print('world')"

tc = TreeContext(filename, code, color=True, line_number=True)
loi = tc.grep("hello", ignore_case=False)

if loi:
    tc.add_lines_of_interest(loi)
    tc.add_context()
    print(tc.format())

  5. Reference: grep-ast CLI arguments

    main

    The following command-line arguments are supported by the grep-ast entrypoint:

    pattern (positional, optional): the pattern to search for
filenames (positional, optional): the files to display (defaults to ".")
--encoding: file encoding (default: "utf8")
--languages: show supported languages
-i, --ignore-case: ignore case distinctions
--color: force color printing
--no-color: disable color printing
--no-gitignore: ignore .gitignore file
--verbose: enable verbose output
-n, --line-number: display line numbers

  6. Use grep-ast CLI to search for patterns

    main

    The grep-ast CLI allows you to search for patterns within files while leveraging AST (Abstract Syntax Tree) parsing for context-aware results. By default, it respects .gitignore files to skip ignored files.

    Basic Usage: grep-ast <pattern> [filenames...]

    Common Options:

    • -i, --ignore-case: Perform case-insensitive searching.
    • -n, --line-number: Display line numbers in the output.
    • --no-gitignore: Ignore .gitignore files when traversing directories.
    • --languages: List all supported file extensions and their associated languages.
    • --color / --no-color: Control colorized output (automatically detects if stdout is a terminal).
    • --verbose: Enable verbose output.
    • --encoding <encoding>: Specify the file encoding (defaults to utf8).
    # Search for 'my_function' in the current directory with line numbers
grep-ast "my_function" -n

# Search for a pattern in a specific file, ignoring case
grep-ast "pattern" path/to/file.py -i

# List supported languages
grep-ast --languages