# Căutare text

Modul text al Greph caută octeți, linie cu linie, într-un arbore de fișiere parcurs. Este modul implicit pentru `greph` CLI și fațada `Greph::searchText()`. Rezultatele folosesc formatul canonic `file:line:content`, interpretat de grep, ripgrep și de majoritatea integrărilor pentru editor.

## Exemple rapide

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

## Modele

În mod implicit, tiparul este tratat ca o expresie regulată PCRE2. Funcțiile `preg_*` ale PHP stau la baza motorului, astfel că sintaxa corespunde referinței PCRE [PHP](https://www.php.net/manual/en/pcre.pattern.php).

Dezactivați motorul de expresii regulate cu `-F` pentru a trata tiparul ca pe o secvență literală de octeți. Modul cu șir fix este calea rapidă: folosește `strpos()` pentru potrivire și omite complet etapa de compilare PCRE2.

`-i` face ambele moduri insensibile la majuscule și minuscule. `-w` adaugă limite de cuvânt întreg de ambele părți ale potrivirii.

## Filtrarea fișierelor

Greph parcurge arborele de fișiere înainte de căutare. Walker-ul este comun cu modul AST și modul indexat, așa că aceleași opțiuni de filtrare se aplică peste tot.

| Opțiune | Efect |
|---|---|
| `--type NAME` | Include numai fișierele care corespund aliasului de tip specificat (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Exclude fișierele care corespund aliasului de tip specificat |
| `--glob GLOB` | Include numai fișierele ale căror căi corespund cu GLOB. Poate fi repetată. |
| `--no-ignore` | Nu respectă `.gitignore` sau `.grephignore` |
| `--hidden` | Include fișierele ascunse |

În mod implicit, walker-ul respectă `.gitignore` și `.grephignore`, omite fișierele binare (detectate prin octeți nuli în primii 512 octeți) și limitează dimensiunea fișierelor la 10 MiB. Ambele limite pot fi configurate prin `WalkOptions`.

Consultați [API / Filtru pentru tipuri de fișiere](https://greph.inline0.dev/ro/docs/api#grephwalkerfiletypefilter) pentru lista completă a aliasurilor de tip incluse.

## Context, numărători și moduri doar pentru fișiere

```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` și `-L` opresc formatarea înainte de a crea toate liniile. Acestea sunt modurile potrivite pentru întrebări de tipul „câte?” și „unde?”.

## Scanări paralele

Transmiteți `-j N` pentru a distribui scanarea între N lucrători. Greph folosește `pcntl_fork()` pentru grupul de lucrători și revine la execuția într-un singur proces când `ext-pcntl` nu este disponibil.

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

Fațada calculează dacă execuția paralelă merită costul suplimentar, în funcție de numărul de fișiere, mod și forma tiparului. Sub prag, rămâne la un singur proces. Consultați [Avansat / Lucrători paraleli](https://greph.inline0.dev/ro/docs/advanced/parallel) pentru euristici.

## Ieșire JSON

`--json` emite un conținut structurat pe care instrumentele din aval îl pot interpreta fără să extragă informații din formatul 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": []
      }
    ]
  }
]
```

Wrapper-ul `rg` emite în schimb ripgrep în formatul JSON cu evenimente. Folosiți-l când un consumator existent așteaptă schema ripgrep.

## Utilizare programatică

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

Obiectele rezultat sunt documentate în [API / Obiecte rezultat](https://greph.inline0.dev/ro/docs/api#result-objects).

## Cum funcționează

Motorul text are două căi:

- **Calea literală**: când este setat `-F`, căutarea rulează `strpos()` folosind un cititor cu buffer de 64 KiB și urmărește caracterele de linie nouă pentru numerotarea liniilor. Nu există etapă de compilare a expresiei regulate.
- **Calea cu expresii regulate**: când `-F` nu este setat, Greph extrage subșiruri literale din tipar folosind un analizor mic în stil PCRE (`Greph\Text\LiteralExtractor`) și le folosește ca prefiltru `strpos()`. Liniile care trec de prefiltru sunt apoi comparate cu tiparul PCRE2 compilat, cu JIT activat.

Ambele căi folosesc același `BufferedReader` pentru I/O. Cititorul citește în blocuri de 64 KiB, nu `fgets()` pentru fiecare linie, ceea ce reduce considerabil numărul apelurilor de sistem pentru fișiere mari.

Pentru sarcini repetate, [modul text indexat](https://greph.inline0.dev/ro/docs/indexed/text) înlocuiește cititorul cu buffer cu un depozit de postări trigramă și identificator încălzit și omite complet majoritatea fișierelor.