Búsqueda de texto

El modo de texto de Greph busca bytes línea por línea en un árbol de archivos recorrido. Es el modo predeterminado de greph CLI y de la fachada Greph::searchText(). La salida usa el formato canónico file:line:content que interpretan grep, ripgrep y la mayoría de las integraciones de editores.

Ejemplos rápidos

# Regex search across the current directory
./vendor/bin/greph "function\s+\w+"

# Fixed-string search across src/
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word search
./vendor/bin/greph -F -i -w "function" src

# Two lines of context around each match
./vendor/bin/greph -F -C 2 "TODO" src

# Stop after the first three matches per file
./vendor/bin/greph -F -m 3 "TODO" src

# Files that contain the pattern
./vendor/bin/greph -F -l "TODO" src

# Files that do not contain the pattern
./vendor/bin/greph -F -L "TODO" src

# Count matches per file
./vendor/bin/greph -F -c "TODO" src

# Inverted match
./vendor/bin/greph -F -v "TODO" src/notes.txt

Patrones

De forma predeterminada, el patrón se trata como una expresión regular PCRE2. Las funciones preg_* de PHP respaldan el motor, por lo que la sintaxis coincide con la referencia PCRE de PHP.

Desactiva el motor de expresiones regulares con -F para tratar el patrón como una secuencia literal de bytes. El modo de cadenas literales es la ruta rápida: usa strpos() para buscar coincidencias y omite por completo la compilación PCRE2.

-i hace que ambos modos no distingan entre mayúsculas y minúsculas. -w añade límites de palabra completa a ambos lados de la coincidencia.

Filtrado de archivos

Greph recorre el árbol de archivos antes de buscar. El recorrido es compartido con los modos AST e indexado, por lo que los mismos indicadores de filtrado se aplican en todas partes.

De forma predeterminada, el recorrido respeta .gitignore y .grephignore, omite los archivos binarios (detectados por bytes nulos en los primeros 512 bytes) y limita el tamaño de los archivos a 10 MiB. Ambos límites se pueden configurar mediante WalkOptions.

Consulta API / FileTypeFilter para ver la lista completa de alias de tipo integrados.

Contexto, recuentos y modos solo para archivos

# Two lines before and after each match
./vendor/bin/greph -F -C 2 "needle" src

# Two lines after, no lines before
./vendor/bin/greph -F -A 2 "needle" src

# Two lines before, no lines after
./vendor/bin/greph -F -B 2 "needle" src

# Count matches per file
./vendor/bin/greph -F -c "needle" src

# List matching files only
./vendor/bin/greph -F -l "needle" src

# List non-matching files only
./vendor/bin/greph -F -L "needle" src

-c, -l y -L omiten el formateador para evitar procesar todas las líneas. Son los modos adecuados para consultas de «cuántos» y «dónde».

Búsquedas en paralelo

Pasa -j N para distribuir la búsqueda entre N trabajadores. Greph usa pcntl_fork() para el grupo de trabajadores y recurre a la ejecución en un solo proceso cuando ext-pcntl no está disponible.

./vendor/bin/greph -F -j 8 "function" src

La fachada calcula si la ejecución en paralelo compensa el coste adicional según el número de archivos, el modo y la forma del patrón. Por debajo del umbral, sigue usando un solo proceso. Consulta Avanzado / Trabajadores en paralelo para ver los criterios.

Salida de JSON

--json emite una carga estructurada que las herramientas posteriores pueden procesar sin extraer datos del formato de grep mediante capturas de pantalla:

./vendor/bin/greph --json -F "function" src

[
  {
    "file": "src/Greph.php",
    "matches": [
      {
        "line": 31,
        "column": 1,
        "content": "final class Greph",
        "matched_text": "function",
        "captures": []
      }
    ]
  }
]

El envoltorio rg emite en su lugar JSON con eventos de tipo ripgrep. Úsalo cuando un consumidor existente espere el esquema ripgrep.

Uso programático

use Greph\Greph;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(
        fixedString: true,
        caseInsensitive: true,
        beforeContext: 1,
        afterContext: 1,
        jobs: 4,
    ),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

Los objetos de resultado se describen en API / Objetos de resultado.

Cómo funciona

El motor de texto tiene dos rutas:

• Ruta literal: cuando se establece -F, la búsqueda ejecuta strpos() sobre un lector con búfer de 64 KiB y lleva el recuento de saltos de línea para numerar las líneas. No hay paso de compilación de expresiones regulares.
• Ruta de expresiones regulares: cuando no se establece -F, Greph extrae subcadenas literales del patrón mediante un analizador sencillo con forma de PCRE (Greph\Text\LiteralExtractor) y las usa como prefiltrado strpos(). Después, las líneas que superan el prefiltrado se comparan con el patrón PCRE2 compilado con JIT activado.

Ambas rutas usan el mismo BufferedReader para la E/S. El lector lee bloques de 64 KiB en lugar de hacerlo fgets() por línea, lo que reduce drásticamente el número de llamadas al sistema en archivos grandes.

Para cargas de trabajo repetidas, el modo de texto indexado reemplaza el lector con búfer por un almacén precargado de índices trigramas y de identificadores, y omite por completo la mayoría de los archivos.