# Textové vyhľadávanie

Textový režim nástroja Greph vyhľadáva po riadkoch bajty v prechádzanom strome súborov. Je to predvolený režim nástroja `greph` CLI a fasády `Greph::searchText()`. Výstup používa kanonický formát `file:line:content`, ktorý dokážu spracovať grep, ripgrep a väčšina integrácií editorov.

## Rýchle príklady

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

## Vzory

Predvolene sa vzor považuje za regulárny výraz PCRE2. Funkcie `preg_*` nástroja PHP zabezpečujú jeho vykonávanie, takže syntax zodpovedá [referencii PCRE](https://www.php.net/manual/en/pcre.pattern.php)PHP.

Vypnutím enginu regulárnych výrazov pomocou `-F` sa vzor bude považovať za doslovnú sekvenciu bajtov. Režim pevných reťazcov je rýchlejšia cesta: na porovnávanie používa `strpos()` a úplne vynecháva kompiláciu PCRE2.

`-i` zabezpečí, že oba režimy nerozlišujú veľké a malé písmená. `-w` pridá na obe strany zhody hranice celého slova.

## Filtrovanie súborov

Greph pred vyhľadávaním prechádza strom súborov. Tento prehliadač je zdieľaný s režimami AST a indexovaným režimom, takže rovnaké príznaky filtrovania platia všade.

| Príznak | Účinok |
|---|---|
| `--type NAME` | Zahrnie iba súbory zodpovedajúce pomenovanému aliasu typu (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Vylúči súbory zodpovedajúce pomenovanému aliasu typu |
| `--glob GLOB` | Zahrnie iba súbory, ktorých cesty zodpovedajú vzoru GLOB. Možno opakovať. |
| `--no-ignore` | Nerešpektuje `.gitignore` ani `.grephignore` |
| `--hidden` | Zahrnie skryté súbory |

Prehliadač štandardne rešpektuje `.gitignore` a `.grephignore`, preskakuje binárne súbory (rozpoznané podľa nulových bajtov v prvých 512 bajtoch) a obmedzuje veľkosť súboru na 10 MiB. Oba limity možno nastaviť pomocou `WalkOptions`.

Úplný zoznam vstavaných aliasov typov nájdete v [API / FileTypeFilter](https://greph.inline0.dev/sk/docs/api#grephwalkerfiletypefilter).

## Kontext, počty a režimy iba so súbormi

```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` a `-L` obchádzajú formátovač, takže nemusia načítať každý riadok do pamäte. Sú vhodnými režimami pre otázky „koľko“ a „kde“.

## Paralelné prehľadávanie

Pomocou `-j N` rozdeľte prehľadávanie medzi N pracovných procesov. Greph používa na ich správu `pcntl_fork()` a pri nedostupnosti `ext-pcntl` sa prepne na vykonávanie v jednom procese.

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

Fasáda podľa počtu súborov, režimu a tvaru vzoru vypočíta, či sa oplatí paralelné vykonávanie. Ak je počet nižší než stanovená hranica, zostane pri jednom procese. Heuristiky nájdete v [Pokročilé / Paralelné pracovné procesy](https://greph.inline0.dev/sk/docs/advanced/parallel).

## Výstup JSON

`--json` vytvára štruktúrovaný obsah, ktorý môžu nadväzujúce nástroje spracovať bez parsovania výstupu 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": []
      }
    ]
  }
]
```

Obal `rg` namiesto toho vytvára JSON v tvare udalostí ripgrep. Použite ho, ak existujúci konzument očakáva schému ripgrep.

## Programové použitie

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

Objekty výsledkov sú zdokumentované v [API / Objekty výsledkov](https://greph.inline0.dev/sk/docs/api#result-objects).

## Ako to funguje

Textový engine má dve cesty:

- **Doslovná cesta**: keď je nastavené `-F`, vyhľadávanie prebieha pomocou `strpos()` nad 64 KiB čítacou vyrovnávacou pamäťou a na číslovanie riadkov sleduje nové riadky. Kompilácia regulárneho výrazu sa nevykonáva.
- **Cesta regulárnych výrazov**: keď `-F` nie je nastavené, Greph pomocou jednoduchého analyzátora v štýle PCRE (`Greph\Text\LiteralExtractor`) získa zo vzoru doslovné podreťazce a použije ich ako predbežný filter `strpos()`. Riadky, ktoré prejdú predbežným filtrom, sa potom porovnajú so skompilovaným vzorom PCRE2 so zapnutým JIT.

Obe cesty používajú na I/O rovnaký `BufferedReader`. Čítač číta po 64 KiB blokoch namiesto `fgets()` na riadok, čo pri veľkých súboroch výrazne znižuje počet systémových volaní.

Pri opakovaných úlohách nahrádza [indexovaný textový režim](https://greph.inline0.dev/sk/docs/indexed/text) čítač s vyrovnávacou pamäťou zahriatym úložiskom trigramov a príspevkov identifikátorov a úplne preskočí väčšinu súborov.