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

Εισαγωγή

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

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

  • Αναζήτηση κειμένου με έξοδο συμβατή με grep και ευχρηστία τύπου ripgrep.
  • Αναζήτηση AST με δομικά μοτίβα τύπου PHP και μεταβλητές μετα-επιπέδου.
  • Επανεγγραφή AST με δομική αναδιαμόρφωση που διατηρεί τη μορφοποίηση.

Περιλαμβάνει επίσης λειτουργίες με προθερμασμένο ευρετήριο για φόρτους εργασίας κειμένου και AST, πολιτικές ανανέωσης με βάση τον κύκλο ζωής, σύνολα προθερμασμένων ευρετηρίων με δηλωτικό αρχείο και περιβλήματα συμβατότητας rg / sg για περιβάλλοντα εργαλείων και agents.

Γιατί υπάρχει το Greph

Οι εφαρμογές και οι agents PHP που χρειάζονται γρήγορη αναζήτηση κώδικα συνήθως καλούν εγγενή εργαλεία μέσω κελύφους (grep, ripgrep, ast-grep), θυσιάζοντας τη φορητότητα και προσθέτοντας δυσκολίες στην ανάπτυξη. Η δομική αναζήτηση και επανεγγραφή είναι ακόμη δυσκολότερη: συνήθως απαιτεί να εγκαταλείψετε εντελώς τη διεργασία PHP.

Το Greph καλύπτει αυτό το κενό. Ο κώδικάς σας σε PHP μπορεί να εκτελεί αναζητήσεις κειμένου, δομικές αντιστοιχίσεις και επανεγγραφές αναδιαμόρφωσης χρησιμοποιώντας μόνο την τυπική βιβλιοθήκη και το nikic/php-parser. Η έξοδος και οι κωδικοί εξόδου είναι συμβατοί με τα καθιερωμένα εργαλεία, επομένως τα υπάρχοντα script και οι agents δεν χρειάζεται να αλλάξουν.

Τι κάνει

  • Αναζήτηση κειμένου με σταθερές συμβολοσειρές και κανονικές εκφράσεις, με λειτουργίες για ολόκληρες λέξεις, διάκριση πεζών-κεφαλαίων, περιβάλλον κειμένου, πλήθος αποτελεσμάτων και μόνο αρχεία
  • Δομική αναζήτηση AST PHP με $VAR, $$$VARIADIC και επαναλαμβανόμενες μεταβλητές μετα-επιπέδου
  • Επανεγγραφή AST που διατηρεί τη μορφοποίηση, με λειτουργίες προεπισκόπησης, διαδραστικής επεξεργασίας και εγγραφής
  • Προθερμασμένα ευρετήρια κειμένου (τριγράμματα + καταχωρίσεις αναγνωριστικών) για επαναλαμβανόμενα φορτία εργασίας
  • Προθερμασμένο ευρετήριο δεδομένων AST και προσωρινά αποθηκευμένη αναζήτηση AST για επαναλαμβανόμενα δομικά ερωτήματα
  • Προθερμασμένα ευρετήρια με επίγνωση του κύκλου ζωής: static, manual-refresh, opportunistic-refresh, strict-stale-check
  • Αναζήτηση σε πολλά ευρετήρια και ονομασμένα σύνολα, σε προθερμασμένα αποθηκευτικά μέσα κειμένου, δεδομένων AST και προσωρινής μνήμης AST
  • Διαγνωστικά σχεδιασμού με το --trace-plan και επισήμανση προέλευσης ευρετηρίου στις αναζητήσεις με προθερμασμένο ευρετήριο
  • Περιβλήματα συμβατότητας ripgrep και ast-grep CLI που βασίζονται στην ίδια μηχανή
  • Παράλληλη ομάδα εργαζομένων βάσει pcntl με εναλλακτική εκτέλεση μίας διεργασίας
  • Περιήγηση αρχείων με υποστήριξη των gitignore και .grephignore, καθώς και εντοπισμό δυαδικών αρχείων

Απαιτήσεις

  • PHP 8.2 ή νεότερη έκδοση
  • ext-json, ext-ctype και ext-tokenizer, που είναι ενεργοποιημένα σχεδόν σε κάθε έκδοση του PHP
  • ext-zlib για την προσωρινά αποθηκευμένη βάση AST (greph-index ast-cache)
  • nikic/php-parser (η μόνη εξάρτηση Composer)

Οι βασικές λειτουργίες κειμένου και AST εκτελούνται σε καθαρό PHP. Οι προαιρετικές συγκρίσεις επιδόσεων εξαρτώνται από εξωτερικά εργαλεία όπως τα rg, grep και sg, αλλά το ίδιο το Greph δεν τα χρειάζεται για να λειτουργήσει. Οι παράλληλες σαρώσεις χρησιμοποιούν το ext-pcntl όταν είναι διαθέσιμο και διαφορετικά υποβαθμίζονται ομαλά σε εκτέλεση μίας διεργασίας. Για κεντρικούς υπολογιστές που απαγορεύουν τα proc_open() και shell_exec(), δείτε τους Κεντρικούς υπολογιστές με περιορισμούς διεργασιών.

Γρήγορο παράδειγμα

Τα εκτελέσιμα αρχεία vendor/bin χρειάζονται Greph 0.2.3 ή νεότερη έκδοση όταν το Greph εγκαθίσταται ως εξάρτηση του έργου σας.

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

# Structural search
vendor/bin/greph -p 'new $CLASS()' src

# Structural rewrite preview
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
PHP
use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

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

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

$rewrites = Greph::rewriteAst(
    'array($$$ITEMS)',
    '[$$$ITEMS]',
    'src',
);

Ξεκινήστε από τις Οδηγίες έναρξης και στη συνέχεια δείτε τις CLI και API για τις υπόλοιπες λειτουργίες. Οι ενότητες Λειτουργίες, Με ευρετήριο και Συμβατότητα καλύπτουν αναλυτικά συγκεκριμένες ροές εργασίας.