# Recherche de texte

Greph recherche par défaut les octets ligne par ligne dans une arborescence de fichiers parcourue. C'est le mode par défaut de `greph` CLI et de la façade `Greph::searchText()`. La sortie suit le format canonique `file:line:content`, analysé par grep, ripgrep et la plupart des intégrations d'éditeurs.

## Exemples rapides

```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
```

## Modèles de blocs

Par défaut, le motif est interprété comme une expression régulière PCRE2. Les fonctions `preg_*` de PHP pilotent le moteur ; la syntaxe correspond donc à la [référence PCRE de PHP](https://www.php.net/manual/en/pcre.pattern.php).

Désactivez le moteur d'expressions régulières avec `-F` pour traiter le motif comme une séquence littérale d'octets. Le mode chaîne fixe est la voie rapide : il utilise `strpos()` pour la recherche et ignore entièrement l'étape de compilation PCRE2.

`-i` rend les deux modes insensibles à la casse. `-w` ajoute des limites de mot de part et d'autre de la correspondance.

## Filtrer les fichiers

Greph parcourt l'arborescence de fichiers avant la recherche. Le parcours est partagé avec les modes AST et indexé ; les mêmes options de filtrage s'appliquent donc partout.

| Option | Effet |
|---|---|
| `--type NAME` | Inclut uniquement les fichiers correspondant à l'alias de type indiqué (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Exclut les fichiers correspondant à l'alias de type indiqué |
| `--glob GLOB` | Inclut uniquement les fichiers dont le chemin correspond à GLOB. Peut être répété. |
| `--no-ignore` | Ne tient pas compte de `.gitignore` ni de `.grephignore` |
| `--hidden` | Inclut les fichiers cachés |

Par défaut, le parcours respecte `.gitignore` et `.grephignore`, ignore les fichiers binaires (détectés par la présence d'octets nuls dans les 512 premiers octets) et limite la taille des fichiers à 10 MiB. Ces deux limites sont configurables via `WalkOptions`.

Consultez [API / FileTypeFilter](https://greph.inline0.dev/fr/docs/api#grephwalkerfiletypefilter) pour obtenir la liste complète des alias de type intégrés.

## Contexte, compteurs et modes limités aux fichiers

```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` et `-L` court-circuitent le formateur pour éviter de matérialiser chaque ligne. Ce sont les modes adaptés aux requêtes du type « combien » et « où ».

## Analyses parallèles

Passez `-j N` pour répartir l'analyse entre N workers. Greph utilise `pcntl_fork()` pour le pool de workers et revient à une exécution à processus unique si `ext-pcntl` n'est pas disponible.

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

La façade détermine si l'exécution parallèle vaut le surcoût en fonction du nombre de fichiers, du mode et de la forme du motif. Sous le seuil, l'exécution reste à processus unique. Consultez [Avancé / Workers parallèles](https://greph.inline0.dev/fr/docs/advanced/parallel) pour connaître les heuristiques.

## Sortie JSON

`--json` émet une charge utile structurée que les outils en aval peuvent analyser sans extraire les données de la sortie grep :

```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": []
      }
    ]
  }
]
```

L'enveloppe `rg` émet plutôt du JSON au format événement ripgrep. Utilisez-la lorsqu'un consommateur existant attend le schéma ripgrep.

## Utilisation par programmation

```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";
    }
}
```

La documentation des objets de résultat se trouve dans [API / Objets de résultat](https://greph.inline0.dev/fr/docs/api#result-objects).

## Fonctionnement

Le moteur de recherche de texte comporte deux chemins :

- **Chemin littéral** : lorsque `-F` est défini, la recherche s'effectue `strpos()` au moyen d'un lecteur tamponné de 64 KiB qui suit les retours à la ligne pour numéroter les lignes. Aucune compilation d'expression régulière n'est nécessaire.
- **Chemin regex** : lorsque `-F` n'est pas défini, Greph extrait des sous-chaînes littérales du motif à l'aide d'un petit analyseur de forme PCRE (`Greph\Text\LiteralExtractor`) et les utilise comme préfiltre `strpos()`. Les lignes qui passent ce préfiltre sont ensuite comparées au motif PCRE2 compilé avec JIT activé.

Les deux chemins utilisent le même `BufferedReader` pour les E/S. Le lecteur lit des blocs de 64 KiB au lieu de procéder `fgets()` par ligne, ce qui réduit considérablement le nombre d'appels système dans les gros fichiers.

Pour les charges de travail répétées, le [mode texte indexé](https://greph.inline0.dev/fr/docs/indexed/text) remplace le lecteur tamponné par un index trigramme et un stockage d'index de termes préchauffés, et ignore la plupart des fichiers.