# 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

```bash
# 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](https://www.php.net/manual/en/pcre.pattern.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.

| Indicador | Efecto |
|---|---|
| `--type NAME` | Incluye solo archivos que coincidan con el alias de tipo indicado (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Excluye archivos que coincidan con el alias de tipo indicado |
| `--glob GLOB` | Incluye solo archivos cuyas rutas coincidan con GLOB. Se puede repetir. |
| `--no-ignore` | No respeta `.gitignore` ni `.grephignore` |
| `--hidden` | Incluye archivos ocultos |

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](https://greph.inline0.dev/es/docs/api#grephwalkerfiletypefilter) para ver la lista completa de alias de tipo integrados.

## Contexto, recuentos y modos solo para archivos

```bash
# 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.

```bash
./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](https://greph.inline0.dev/es/docs/advanced/parallel) 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:

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

```json
[
  {
    "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

```php
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](https://greph.inline0.dev/es/docs/api#result-objects).

## 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](https://greph.inline0.dev/es/docs/indexed/text) 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.