Μετάβαση στο περιεχόμενο

Ξεκινώντας

Προβολή ως Markdown Επεξεργασία στο GitHub Τεκμηρίωση στο d105217

Εγκατάσταση

Εγκαταστήστε το Greph μέσω Composer:

Κέλυφος
composer require greph/greph

Αυτό εγκαθιστά τη βιβλιοθήκη μαζί με τέσσερα εκτελέσιμα στο vendor/bin/:

  • greph: εγγενής αναζήτηση κειμένου, αναζήτηση AST και αναδιατύπωση AST
  • greph-index: προθερμασμένο ευρετήριο κειμένου, ευρετήριο δεδομένων AST και προσωρινά αποθηκευμένη αναζήτηση AST
  • rg: επίπεδο συμβατότητας τύπου ripgrep
  • sg: επίπεδο συμβατότητας τύπου ast-grep

Αυτά τα εκτελέσιμα λειτουργούν από το vendor/bin/ του έργου σας, αφού Greph 0.2.3. Οι παλαιότερες εκδόσεις εντόπιζαν τον αυτόματο φορτωτή Composer μόνο μέσα σε κλώνο του αποθετηρίου Greph, επομένως απαιτείται τουλάχιστον αυτή η έκδοση:

Κέλυφος
composer require greph/greph:^0.2.3

Απαιτήσεις

  • PHP 8.2+ για readonly classes, enums, σύνταξη callable πρώτης κατηγορίας και προαγωγή παραμέτρων κατασκευαστή
  • ext-json για έξοδο JSON και payload ευρετηρίου στον δίσκο
  • ext-ctype για ανάλυση μοτίβων και επιλογών
  • ext-tokenizer για PHP-Parser και τα AST prefilters
  • ext-zlib για την προσωρινά αποθηκευμένη βάση AST (greph-index ast-cache)
  • nikic/php-parser (εγκαθίσταται αυτόματα ως εξάρτηση του Composer)

Τα ext-json, ext-ctype και ext-tokenizer είναι ενεργοποιημένα σχεδόν σε κάθε έκδοση του PHP. Το composer.json δηλώνει προς το παρόν μόνο το ext-json (#5), επομένως το Composer δεν προειδοποιεί όταν λείπει κάποιο από τα υπόλοιπα.

Προαιρετικά:

  • ext-pcntl για παράλληλες σαρώσεις. Το Greph υποβαθμίζεται ομαλά σε εκτέλεση μίας διεργασίας όταν απουσιάζει.
  • Εξωτερικά δυαδικά αρχεία rg, grep και sg για συγκρίσεις επιδόσεων. Δεν απαιτούνται ποτέ κατά την εκτέλεση.

Η αναζήτηση, η επανεγγραφή και η δημιουργία ευρετηρίου δεν καλούν ποτέ τα proc_open() ή shell_exec()· μόνο οι παράλληλες σαρώσεις δημιουργούν διεργασίες και, χωρίς το pcntl_fork(), χρησιμοποιούν μία διεργασία. Δείτε τους Κεντρικούς υπολογιστές με περιορισμούς διεργασιών για κεντρικούς υπολογιστές που απενεργοποιούν τα proc_open(), shell_exec() ή pcntl_fork().

Η πρώτη σας αναζήτηση κειμένου

Η προεπιλεγμένη λειτουργία του Greph είναι η αναζήτηση κειμένου με συμβατή έξοδο grep:

Κέλυφος
vendor/bin/greph -F "function" src

Η έξοδος χρησιμοποιεί την κανονική μορφή file:line:content, την οποία αναμένουν τα grep, ripgrep και οι περισσότερες ενσωματώσεις επεξεργαστών κώδικα.

Text
src/Greph.php:41:    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList
src/Greph.php:50:    public static function searchText(string $pattern, string|array $paths, ?TextSearchOptions $options = null): array
src/Greph.php:81:    public static function buildTextIndex(

Προσθέστε το -i για αντιστοίχιση χωρίς διάκριση πεζών-κεφαλαίων, το -w για αντιστοίχιση ολόκληρων λέξεων, το -c για πλήθος αποτελεσμάτων, το -l για εμφάνιση μόνο διαδρομών αρχείων, το -C 2 για δύο γραμμές περιβάλλοντος και ούτω καθεξής. Η πλήρης λίστα βρίσκεται στην αναφορά του CLI.

Δώστε το -p και ένα μοτίβο σε μορφή PHP για να μεταβείτε στη δομική αναζήτηση:

Κέλυφος
vendor/bin/greph -p 'new $CLASS()' src

Το $CLASS είναι μια μεταβλητή μετα-επιπέδου που συλλαμβάνει οποιοδήποτε όνομα κλάσης. Το μοτίβο new $CLASS() αντιστοιχίζει κάθε έκφραση new χωρίς ορίσματα, ανεξάρτητα από την κλάση, τη μορφοποίηση ή τα σχόλια. Χρησιμοποιήστε το new $CLASS($$$ARGS) για να αντιστοιχίσετε κλήσεις με οποιαδήποτε ορίσματα.

Κάθε αντιστοίχιση AST εμφανίζεται ως αρχείο, γραμμή έναρξης και αντιστοιχισμένος κώδικας:

Text
src/Greph.php:43:new FileWalker()
src/Greph.php:52:new TextSearchOptions()
src/Greph.php:54:new TextSearcher()

Άλλα χρήσιμα μοτίβα:

Κέλυφος
# Any method call with any arguments
vendor/bin/greph -p '$obj->$method($$$ARGS)' src

# Any function declaration with a void return type
vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

# Old-style array calls
vendor/bin/greph -p 'array($$$ITEMS)' src

Δείτε τις Λειτουργίες / Αναζήτηση AST για την πλήρη σύνταξη των μοτίβων.

Η πρώτη σας επανεγγραφή

Προσθέστε το -r για να μετατρέψετε την αναζήτηση AST σε επανεγγραφή:

Κέλυφος
# Preview only
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Οι επανεγγραφές διατηρούν τη μορφοποίηση εκτός της αντιστοίχισης: αντικαθίσταται μόνο ο αντιστοιχισμένος κόμβος, ενώ τα γύρω κενά, η εσοχή και τα σχόλια παραμένουν άθικτα. Ο ίδιος ο αντιστοιχισμένος κόμβος δημιουργείται εκ νέου από το πρότυπο, οπότε η διάταξή του κανονικοποιείται και μπορεί να χαθεί ένα σχόλιο στο εσωτερικό του. Δείτε τις Λειτουργίες / Επανεγγραφή για λεπτομέρειες.

PHP API

Η στατική πρόσοψη Greph\Greph παρέχει τις ίδιες λειτουργίες με το CLI:

PHP
use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true, caseInsensitive: true),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

$matches = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}

Η πλήρης επιφάνεια λειτουργιών καλύπτεται στις API.

Τα επαναλαμβανόμενα φορτία εργασίας ωφελούνται από ευρετήρια που έχουν ήδη προθερμανθεί. Δημιουργήστε το ευρετήριο μία φορά και έπειτα εκτελέστε πολλά ερωτήματα:

Κέλυφος
# Text index
vendor/bin/greph-index build .
vendor/bin/greph-index search -F "function" .

# AST fact index
vendor/bin/greph-index ast-index build .
vendor/bin/greph-index ast-index search 'new $CLASS()' src

# Cached parsed-tree index
vendor/bin/greph-index ast-cache build .
vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src

Από προεπιλογή, τα ευρετήρια αποθηκεύονται στα .greph-index, .greph-ast-index και .greph-ast-cache στη ρίζα του έργου.

Για δέντρα που αλλάζουν συχνά, επιλέξτε ένα προφίλ κύκλου ζωής αντί να αντιμετωπίζετε όλα τα προθερμασμένα ευρετήρια με τον ίδιο τρόπο:

Κέλυφος
vendor/bin/greph-index build . --lifecycle static
vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576
vendor/bin/greph-index stats . --dry-refresh

Το συνηθισμένο μοτίβο είναι:

  • διατηρήστε μια σταθερή βάση ως static
  • διατηρήστε τις επικαλύψεις που αλλάζουν συχνά ως opportunistic-refresh
  • ελέγξτε τη συμπεριφορά παρωχημένων δεδομένων με το stats --dry-refresh

Μπορείτε να αναζητήσετε σε πολλά προθερμασμένα ευρετήρια με μία εντολή:

Κέλυφος
vendor/bin/greph-index search -F "apply_filters" . \
  --index-dir wordpress/.greph-index \
  --index-dir wp-content/plugins/my-plugin/.greph-index \
  --show-index-origin

vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir wordpress/.greph-ast-index \
  --index-dir wp-content/plugins/my-plugin/.greph-ast-index \
  --show-index-origin

Ονομασμένα σύνολα ευρετηρίων

Αν το κάνετε επανειλημμένα, ορίστε τη διάταξη στο .greph-index-set.json και χρησιμοποιήστε τις υποεντολές συνόλων αντί να επαναλαμβάνετε τις σημαίες:

Κέλυφος
vendor/bin/greph-index set build
vendor/bin/greph-index set stats --dry-refresh
vendor/bin/greph-index set search --show-index-origin -F "apply_filters" .
vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

Ίχνος σχεδιασμού

Για να δείτε πώς η αναζήτηση με προθερμασμένο ευρετήριο περιορίζει τα υποψήφια αποτελέσματα, προσθέστε το --trace-plan:

Κέλυφος
vendor/bin/greph-index search --trace-plan -F "function" .
vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' .

Δείτε τις Ευρετήριο / Κείμενο και Ευρετήριο / AST για την πλήρη ροή εργασίας με προθερμασμένα ευρετήρια.

Περιβλήματα συμβατότητας

Αν έχετε εργαλεία ή agents που χρησιμοποιούν ήδη το ripgrep ή το ast-grep, χρησιμοποιήστε τα περιβλήματα:

Κέλυφος
vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php

Και τα δύο περιβλήματα επαναχρησιμοποιούν την ίδια μηχανή και έχουν επαληθευτεί με δοκιμές έναντι των upstream δυαδικών αρχείων. Η επαληθευμένη λειτουργικότητα τεκμηριώνεται στις Συμβατότητα / rg και Συμβατότητα / sg και αναπαράγεται στον παραγόμενο πίνακα λειτουργιών.

Διαμόρφωση

Το Greph αναγνωρίζει δύο συμβάσεις αποθήκευσης στον δίσκο:

  • .gitignore: εφαρμόζεται από προεπιλογή. Περάστε το --no-ignore για να το απενεργοποιήσετε.
  • .grephignore: ίδια σύνταξη με το .gitignore, εφαρμοζόμενη επιπλέον. Χρήσιμο για εξαιρέσεις συγκεκριμένου εργαλείου που δεν θέλετε να παρακολουθούνται από τον έλεγχο εκδόσεων.

Οι προεπιλεγμένοι κατάλογοι ευρετηρίων είναι οι .greph-index, .greph-ast-index και .greph-ast-cache στη ρίζα που επιλέχθηκε. Παρακάμψτε τους με το --index-dir σε οποιαδήποτε υποεντολή greph-index ή χρησιμοποιήστε το .greph-index-set.json για επαναλήψιμες διατάξεις πολλών ευρετηρίων.