# Teksta meklēšana

Greph teksta režīms ir pa rindām veikta baitu meklēšana apstaigātā failu kokā. Tas ir noklusējuma režīms saskarnei `greph` CLI un fasādei `Greph::searchText()`. Izvade izmanto kanonisko `file:line:content` formātu, ko parsē grep, ripgrep un vairums redaktoru integrāciju.

## Īsi piemēri

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

## Raksti

Pēc noklusējuma raksts tiek interpretēts kā PCRE2 regulārā izteiksme. PHP `preg_*` funkcijas nodrošina dzinēja darbību, tāpēc sintakse atbilst [PCREPHP atsaucei](https://www.php.net/manual/en/pcre.pattern.php).

Izslēdziet regulāro izteiksmju dzinēju ar `-F`, lai rakstu uztvertu kā burtisku baitu secību. Precīzas virknes režīms ir ātrākais ceļš: tas salīdzināšanai izmanto `strpos()` un pilnībā izlaiž PCRE2 kompilēšanas soli.

`-i` padara abus režīmus reģistrjutības neņemošus. `-w` pievieno pilna vārda robežas abās atbilstības pusēs.

## Failu filtrēšana

Greph pirms meklēšanas apstaigā failu koku. Apstaigātājs tiek koplietots ar AST režīmu un indeksēto režīmu, tāpēc visur darbojas tie paši filtrēšanas karodziņi.

| Karodziņš | Iedarbība |
|---|---|
| `--type NAME` | Iekļaut tikai failus, kas atbilst nosauktajam tipa aizstājvārdam (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Izslēgt failus, kas atbilst nosauktajam tipa aizstājvārdam |
| `--glob GLOB` | Iekļaut tikai failus, kuru ceļi atbilst GLOB. Var norādīt atkārtoti. |
| `--no-ignore` | Neņemt vērā `.gitignore` vai `.grephignore` |
| `--hidden` | Iekļaut slēptos failus |

Apstaigātājs pēc noklusējuma ievēro `.gitignore` un `.grephignore`, izlaiž bināros failus (tos nosaka pēc nulles baitiem pirmajos 512 baitos) un ierobežo faila lielumu līdz 10 MiB. Abus ierobežojumus var konfigurēt ar `WalkOptions`.

Pilnu iebūvēto tipu aizstājvārdu sarakstu skatiet sadaļā [API / FileTypeFilter](https://greph.inline0.dev/lv/docs/api#grephwalkerfiletypefilter).

## Konteksts, skaits un tikai failu režīmi

```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` un `-L` apiet formatētāju, lai nebūtu jāizveido visas rindas. Šie režīmi ir piemēroti vaicājumiem “cik” un “kur”.

## Paralēla skenēšana

Norādiet `-j N`, lai sadalītu skenēšanu starp N darbplūsmām. Greph darbplūsmu kopai izmanto `pcntl_fork()` un pārslēdzas uz viena procesa izpildi, ja `ext-pcntl` nav pieejams.

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

Fasāde pēc failu skaita, režīma un raksta formas aprēķina, vai paralēlā izpilde ir tā vērta. Ja slieksnis nav sasniegts, tā paliek viena procesa režīmā. Heiristiku aprakstu skatiet sadaļā [Advanced / Parallel Workers](https://greph.inline0.dev/lv/docs/advanced/parallel).

## JSON izvade

`--json` izvada strukturētu datu kopu, ko pakārtotie rīki var parsēt, neparsējot grep formātu no ekrāna:

```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` aplauzējs tā vietā izvada ripgrep notikumu formas JSON. Izmantojiet to, ja esošais patērētājs sagaida ripgrep shēmu.

## Izmantošana programmā

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

Rezultātu objekti ir aprakstīti sadaļā [API / Result objects](https://greph.inline0.dev/lv/docs/api#result-objects).

## Kā tas darbojas

Teksta dzinējam ir divi ceļi:

- **Burtiskais ceļš**: ja iestatīts `-F`, meklēšana tiek veikta ar `strpos()`, izmantojot 64 KiB buferētu lasītāju, kas seko jaunajām rindām, lai noteiktu rindu numurus. Regulārā izteiksme netiek kompilēta.
- **Regulāro izteiksmju ceļš**: ja `-F` nav iestatīts, Greph ar nelielu PCRE tipa analizatoru (`Greph\Text\LiteralExtractor`) izvelk no raksta burtiskās apakšvirknes un izmanto tās kā `strpos()` priekšfiltru. Rindas, kas iztur priekšfiltru, pēc tam tiek salīdzinātas ar kompilēto PCRE2 rakstu, kurā iespējots JIT.

Abos ceļos I/O vajadzībām tiek izmantots viens un tas pats `BufferedReader`. Lasītājs nolasa datus 64 KiB blokos, nevis `fgets()` katrai rindai, tādējādi ievērojami samazinot sistēmas izsaukumu skaitu lielos failos.

Atkārtotām slodzēm [indeksētais teksta režīms](https://greph.inline0.dev/lv/docs/indexed/text) buferēto lasītāju aizstāj ar iesildītu triagrammu un identifikatoru ierakstu krātuvi un pilnībā izlaiž lielāko daļu failu.