# Teksto paieška

Greph teksto režimas atlieka eilučių paiešką baitų lygmeniu per peržiūrimą failų medį. Tai numatytasis režimas, naudojamas `greph` CLI ir `Greph::searchText()` fasado. Išvestis pateikiama kanoniniu `file:line:content` formatu, kurį analizuoja grep, ripgrep ir dauguma redaktorių integracijų.

## Greiti pavyzdžiai

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

## Šablonai

Pagal numatytuosius nustatymus šablonas laikomas PCRE2 reguliariąja išraiška. Variklio pagrindą sudaro PHP `preg_*` funkcijos, todėl sintaksė atitinka [PCRE nuorodą](https://www.php.net/manual/en/pcre.pattern.php)PHP.

Išjunkite reguliariųjų išraiškų variklį naudodami `-F`, kad šablonas būtų laikomas pažodine baitų seka. Pažodinių eilučių režimas yra greitasis kelias: atitikmenų paieškai jis naudoja `strpos()` ir visiškai praleidžia PCRE2 kompiliavimo žingsnį.

`-i` įjungia abu režimus, neatsižvelgiančius į raidžių registrą. `-w` prideda viso žodžio ribas abiejose atitikmens pusėse.

## Failų filtravimas

Greph prieš paiešką peržiūri failų medį. Failų peržiūros mechanizmas bendras AST ir indeksuotam režimams, todėl visur taikomos tos pačios filtravimo vėliavėlės.

| Vėliavėlė | Poveikis |
|---|---|
| `--type NAME` | Įtraukti tik failus, atitinkančius nurodytą tipo pseudonimą (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Neįtraukti failų, atitinkančių nurodytą tipo pseudonimą |
| `--glob GLOB` | Įtraukti tik failus, kurių keliai atitinka GLOB. Galima kartoti. |
| `--no-ignore` | Nepaisyti `.gitignore` arba `.grephignore` |
| `--hidden` | Įtraukti paslėptus failus |

Pagal numatytuosius nustatymus failų peržiūros mechanizmas paiso `.gitignore` ir `.grephignore`, praleidžia dvejetainius failus (aptinkamus pagal nulinius baitus pirmuosiuose 512 baituose) ir riboja failo dydį iki 10 MiB. Abi ribas galima konfigūruoti per `WalkOptions`.

Visą įtaisytųjų tipų pseudonimų sąrašą rasite [API / FileTypeFilter](https://greph.inline0.dev/lt/docs/api#grephwalkerfiletypefilter).

## Kontekstas, skaičiai ir tik failų režimai

```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` ir `-L` trumpuoju keliu apeina formatuoklį, todėl nereikia sukurti kiekvienos eilutės. Tai tinkami režimai užklausoms „kiek“ ir „kur“.

## Lygiagretus skenavimas

Perduokite `-j N`, kad skenavimas būtų paskirstytas N darbuotojų. Greph darbuotojų telkiniui naudoja `pcntl_fork()` ir grįžta prie vykdymo viename procese, kai `ext-pcntl` nepasiekiamas.

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

Fasadas apskaičiuoja, ar lygiagretus vykdymas vertas papildomų sąnaudų, atsižvelgdamas į failų skaičių, režimą ir šablono formą. Jei riba nepasiekta, vykdoma viename procese. Heuristiką rasite [Išplėstiniai nustatymai / Lygiagretūs darbuotojai](https://greph.inline0.dev/lt/docs/advanced/parallel).

## JSON išvestis

`--json` pateikia struktūruotą duomenų rinkinį, kurį paskesni įrankiai gali analizuoti, nebandydami nuskaityti grep formato iš ekrano:

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

`rg` apvalkalas vietoj to pateikia ripgrep įvykių formos JSON. Naudokite jį, kai esamas vartotojas tikisi ripgrep schemos.

## Naudojimas programoje

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

Rezultatų objektai aprašyti [API / Rezultatų objektai](https://greph.inline0.dev/lt/docs/api#result-objects).

## Kaip tai veikia

Teksto variklis turi du kelius:

- **Pažodinis kelias**: kai nustatyta `-F`, paieška vykdoma naudojant `strpos()` per 64 KiB buferizuotą skaitytuvą, o eilučių numeravimui sekamos naujos eilutės. Reguliarioji išraiška nekompiliuojama.
- **Reguliariųjų išraiškų kelias**: kai `-F` nenustatyta, Greph iš šablono ištraukia pažodines poeilutes naudodamas nedidelį, į PCRE panašų analizatorių (`Greph\Text\LiteralExtractor`) ir jas taiko kaip `strpos()` išankstinį filtrą. Tada eilutės, praėjusios išankstinį filtrą, tikrinamos pagal sukompiliuotą PCRE2 šabloną su įjungtu JIT.

Abu keliai įvesties ir išvesties operacijoms naudoja tą patį `BufferedReader`. Skaitytuvas skaito 64 KiB dalimis, o ne po `fgets()` kiekvienai eilutei, todėl dideliuose failuose sistemos iškvietimų skaičius gerokai sumažėja.

Pasikartojančioms užduotims [indeksuotas teksto režimas](https://greph.inline0.dev/lt/docs/indexed/text) buferizuotą skaitytuvą pakeičia įkeltu trijų simbolių sekų ir identifikatorių įrašų indeksu ir visiškai praleidžia daugumą failų.