# Pencarian Teks

Mode teks Greph melakukan pencarian byte per baris pada pohon file yang ditelusuri. Ini adalah mode default untuk `greph` CLI dan facade `Greph::searchText()`. Keluaran menggunakan format `file:line:content` kanonis yang dapat diurai oleh grep, ripgrep, dan sebagian besar integrasi editor.

## Contoh singkat

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

## Pola

Secara default, pola diperlakukan sebagai ekspresi reguler PCRE2. Fungsi PHP `preg_*` mendukung mesinnya, sehingga sintaksnya sesuai dengan referensi PCRE [PCRE PHP](https://www.php.net/manual/en/pcre.pattern.php).

Nonaktifkan mesin regex dengan `-F` untuk memperlakukan pola sebagai urutan byte literal. Mode string tetap adalah jalur cepat: mode ini menggunakan `strpos()` untuk pencocokan dan sepenuhnya melewati langkah kompilasi PCRE2.

`-i` membuat kedua mode tidak peka huruf besar-kecil. `-w` menambahkan batas kata utuh di kedua sisi kecocokan.

## Memfilter file

Greph menelusuri pohon file sebelum mencari. Walker ini digunakan bersama oleh mode AST dan mode terindeks, sehingga flag pemfilteran yang sama berlaku di semua mode.

| Flag | Efek |
|---|---|
| `--type NAME` | Hanya sertakan file yang cocok dengan alias tipe bernama (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Kecualikan file yang cocok dengan alias tipe bernama |
| `--glob GLOB` | Hanya sertakan file yang path-nya cocok dengan GLOB. Dapat diulang. |
| `--no-ignore` | Jangan patuhi `.gitignore` atau `.grephignore` |
| `--hidden` | Sertakan file tersembunyi |

Secara default, walker mematuhi `.gitignore` dan `.grephignore`, melewati file biner (terdeteksi dari byte null pada 512 byte pertama), dan membatasi ukuran file hingga 10 MiB. Kedua batas tersebut dapat dikonfigurasi melalui `WalkOptions`.

Lihat [API / Filter Tipe File](https://greph.inline0.dev/id/docs/api#grephwalkerfiletypefilter) untuk daftar lengkap alias tipe bawaan.

## Konteks, jumlah, dan mode khusus file

```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`, dan `-L` melewati formatter lebih awal agar tidak perlu memuat setiap baris ke memori. Mode ini cocok untuk kueri "berapa banyak" dan "di mana".

## Pemindaian Paralel

Berikan `-j N` untuk menjalankan pemindaian di N worker. Greph menggunakan `pcntl_fork()` untuk kumpulan worker dan beralih ke eksekusi satu proses jika `ext-pcntl` tidak tersedia.

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

Facade menghitung apakah eksekusi paralel sepadan dengan overhead berdasarkan jumlah file, mode, dan bentuk pola. Di bawah ambang batas, proses tetap berjalan sebagai satu proses. Lihat [Lanjutan / Worker Paralel](https://greph.inline0.dev/id/docs/advanced/parallel) untuk heuristiknya.

## Output JSON

`--json` mengeluarkan payload terstruktur yang dapat diurai oleh alat downstream tanpa mengambil data dari format grep melalui scraping layar:

```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 `rg` mengeluarkan JSON berbentuk event ripgrep. Gunakan ini ketika konsumen yang sudah ada mengharapkan skema ripgrep.

## Penggunaan secara terprogram

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

Objek hasil didokumentasikan di [API / Objek hasil](https://greph.inline0.dev/id/docs/api#result-objects).

## Cara kerjanya

Mesin teks memiliki dua jalur:

- **Jalur literal**: ketika `-F` ditetapkan, pencarian menjalankan `strpos()` melalui pembaca berbuffer 64 KiB dan melacak baris baru untuk penomoran baris. Tidak ada langkah kompilasi regex.
- **Jalur regex**: ketika `-F` tidak ditetapkan, Greph mengekstrak substring literal dari pola menggunakan penganalisis kecil berbentuk PCRE (`Greph\Text\LiteralExtractor`) dan menggunakannya sebagai pra-filter `strpos()`. Baris yang lolos pra-filter kemudian dicocokkan dengan pola PCRE2 terkompilasi dengan JIT diaktifkan.

Kedua jalur menggunakan `BufferedReader` yang sama untuk I/O. Pembaca membaca dalam potongan 64 KiB, bukan `fgets()` per baris, sehingga jumlah syscall berkurang drastis pada file besar.

Untuk beban kerja berulang, [mode teks terindeks](https://greph.inline0.dev/id/docs/indexed/text) mengganti pembaca berbuffer dengan penyimpanan posting trigram + identifier yang telah dipanaskan, lalu melewati sebagian besar file sepenuhnya.