# rg-yhteensopivuus

`vendor/bin/rg` on ripgrep-tyylinen yhteensopivuuskerros. Se hyväksyy yleisimmin käytetyt ripgrep-valitsimet, käy tiedostopuun läpi samalla tavalla kuin ripgrep ja tulostaa vastaavat osumat. Vahvistetut ominaisuudet on toisinnettu kokeista, jotka on ajettu alkuperäistä `rg`-binääriä vasten, ja ne löytyvät kohdasta [Lisäasetukset / Ominaisuusmatriisi](https://greph.inline0.dev/fi/docs/advanced/feature-matrix).

Yhteensopivuuskerros on ohut CLI-kääntäjä; varsinaisen haun tekee sama `Greph\Text\TextSearcher`-moottori, jota `vendor/bin/greph` käyttää.

## Milloin sitä kannattaa käyttää

Käytä yhteensopivuuskerrosta, kun:

- Käytössäsi on työkalu, agentti tai skripti, joka kutsuu jo komentoa `rg`.
- Haluat suoraan korvaavan työkalun, joka toimii ympäristöissä, joihin et voi asentaa itse ripgrep-ohjelmaa (jaettu hosting, vahvistetut säilöt, rajoitettu PaaS).
- Haluat ripgrep-käyttömukavuuden vain PHP-ympäristöön.

Käytä natiivia komentoa `vendor/bin/greph`, kun:

- Kirjoitat uutta koodia etkä tarvitse ripgrep CLI -muotoa.
- Haluat käyttää natiiveja valitsimia, joita yhteensopivuuskerros ei tarjoa (esimerkiksi AST-tilaa).

## Käyttö

```bash
rg [options] pattern [path...]
rg --files [options] [path...]
```

Pelkkä komento suorittaa rekursiivisen haun kohteessa `.`:

```bash
./vendor/bin/rg -F "function"
```

`--files` luettelee ehdokastiedostot haun sijaan:

```bash
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden
```

## JSON-tulostus

`--json` tuottaa saman tapahtumamuotoisen hyötykuorman kuin ripgrep:

```bash
./vendor/bin/rg --json -F "function walk" src/Greph.php
```

```json
{"type":"begin","data":{"path":{"text":"src/Greph.php"}}}
{"type":"match","data":{"path":{"text":"src/Greph.php"},"lines":{"text":"    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList\n"},"line_number":41,"absolute_offset":1034,"submatches":[{"match":{"text":"function walk"},"start":18,"end":31}]}}
{"type":"end","data":{"path":{"text":"src/Greph.php"},"binary_offset":null,"stats":{"elapsed":{"secs":0,"nanos":0,"human":"0.000000s"},"searches":1,"searches_with_match":1,"bytes_searched":13383,"bytes_printed":282,"matched_lines":1,"matches":1}}}
{"type":"summary","data":{"elapsed_total":{"human":"0.000000s","nanos":0,"secs":0},"stats":{"bytes_printed":282,"bytes_searched":13383,"matched_lines":1,"matches":1,"searches":1,"searches_with_match":1,"elapsed":{"human":"0.000000s","nanos":0,"secs":0}}}}
```

`stats`-objektien kestot ilmoitetaan aina nollana.

Tämä on skeema, jota jatkokäsittelytyökalut odottavat, kun ne ottavat käyttöön komennon ripgrep rakenteisen tulostuksen. Jos haluat yksinkertaisemman muodon, käytä sen sijaan komentoa `vendor/bin/greph --json`.

## Vahvistetut ominaisuudet

Seuraavat valitsimet on testattu suoraan komentoa `rg` vasten [ominaisuusmatriisissa](https://greph.inline0.dev/fi/docs/advanced/feature-matrix). Alkuperäinen binääri ja yhteensopivuuskerros tuottavat kunkin kokeen kohdalla vastaavan tulosteen. Jos valitsimella on lyhyt ja pitkä kirjoitusasu, kokeessa käytetään jompaakumpaa, ja yhteensopivuuskerros tulkitsee molemmat samaksi asetukseksi.

### Hakuvalitsimet

- `-F`, `--fixed-strings`
- `-i`, `--ignore-case`
- `-w`, `--word-regexp`
- `-v`, `--invert-match`
- `-c`, `--count`
- `-l`, `--files-with-matches`
- `--files-without-match`
- `-I`, `--no-filename`
- `-H`, `--with-filename`
- `-n`, `--line-number`
- `-A N`, `--after-context N`
- `-B N`, `--before-context N`
- `-C N`, `--context N`
- `-m N`, `--max-count N`
- `-e P`, `--regexp P`

### Läpikäynnin valitsimet

- `-L`, `--follow`
- `--glob GLOB`
- `--type NAME`
- `--type-not NAME`
- `--no-ignore`
- `--hidden`
- `--files`
- `--files --hidden`
- `--files --type NAME`

### Tulostusvalitsimet

- `--json`

### Hyväksytään ilman koetta

Yhteensopivuuskerros hyväksyy myös seuraavat valitsimet, mutta niitä ei ole vielä testattu ominaisuusmatriisissa:

- `-j N`, `--threads N` (työntekijöiden määrä, katso [Rinnakkaiset työntekijät](https://greph.inline0.dev/fi/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Rajoitukset

Greph-komennon `rg`-yhteensopivuuskerros kattaa haku- ja läpikäyntiominaisuudet, joita useimmat työkalut ja agentit käyttävät. Se ei tällä hetkellä tarjoa seuraavia ripgrep-ominaisuuksia:

- Moniriviset säännölliset lausekkeet (`-U`, `--multiline`)
- Korvaus (`-r`, `--replace`) tekstitilassa (käytä sen sijaan `vendor/bin/greph` AST-uudelleenkirjoitusta)
- Mukautetut tyyppimääritykset (`--type-add`, `--type-clear`)
- Koodausvalitsimet (`-E`, `--encoding`)
- `--pre`-suodatinskriptit
- `--sort`, `--sortr`

Jos jokin valitsin puuttuu, luo ilmoitus ja liitä mukaan alkuperäistä `rg`-komentoa vasten tekemäsi koe sekä odotettu tuloste. Uudet ominaisuudet lisätään yhdessä vertailutestien kanssa, joten vahvistetut ominaisuudet laajenevat jatkuvasti.

## Käyttäytymisen vastaavuus

Yhteensopivuuskerroin tavoitteena on vastaava toiminta, ei tavuntarkka vastaavuus. Rivien tulosteet vastaavat toisiaan, mutta kosmeettiset yksityiskohdat voivat erota (värikoodit, päätteen leveyden aiheuttamat katkaisut). [Ominaisuusmatriisin](https://greph.inline0.dev/fi/docs/advanced/feature-matrix) kokeissa tarkistetaan semanttinen vastaavuus, ei tavuntarkkoja eroja.

Tulostetta jäsentäville agenteille ja työkaluille jäsentimen kannalta olennaiset kentät (tiedostopolku, rivinumero, sisältö, osuman sijainti) ovat tavuntarkkoja alkuperäisen `rg`-komennon kanssa kaikissa vahvistetuissa kokeissa.