AST Visitor Reference

use PHPRegex\Parser\Node\BackrefNode;
use PHPRegex\Parser\Node\NodeInterface;
use PHPRegex\Parser\NodeFinder;
use PHPRegex\Parser\NodeWalker;
use PHPRegex\Parser\RegexParser;
use PHPRegex\Parser\TraversalAction;

$tree = RegexParser::create()->parse('/(a)(b)\\2\\1/');

NodeFinder::findInstanceOf($tree, BackrefNode::class);            // both references, in order

NodeWalker::walk($tree, static function (NodeInterface $node, array $ancestors): ?TraversalAction {
    // $ancestors: the nodes from the root down to $node's parent
    return null;  // or TraversalAction::SkipChildren, or TraversalAction::Stop
});

use PHPRegex\Parser\Node;
use PHPRegex\Parser\AbstractTraversingVisitor;
use PHPRegex\Toolkit\Regex;

class LiteralCollector extends AbstractTraversingVisitor
{
    private array $literals = [];

    public function visitLiteral(Node\LiteralNode $node)
    {
        $this->literals[] = $node->value;

        return parent::visitLiteral($node);
    }

    public function visitGroup(Node\GroupNode $node)
    {
        // Skip what lookaheads hold; descend into every other group.
        if (Node\GroupType::LookaheadPositive === $node->type) {
            return null;
        }

        return parent::visitGroup($node);
    }

    public function getLiterals(): array
    {
        return $this->literals;
    }
}

$visitor = new LiteralCollector();
Regex::create()->parse('/ab(?=cd)e/')->accept($visitor);

echo implode('', $visitor->getLiterals()); // abe

use PHPRegex\Parser\Node;
use PHPRegex\Parser\AbstractNodeVisitor;
use PHPRegex\Toolkit\Regex;

/** @extends AbstractNodeVisitor<bool> */
class StartsWithCaret extends AbstractNodeVisitor
{
    public function visitRegex(Node\RegexNode $node): bool
    {
        return $node->pattern->accept($this);
    }

    public function visitSequence(Node\SequenceNode $node): bool
    {
        return [] !== $node->children && $node->children[0]->accept($this);
    }

    public function visitAnchor(Node\AnchorNode $node): bool
    {
        return '^' === $node->value;
    }

    protected function defaultReturn(): bool
    {
        return false;
    }
}

var_dump(Regex::create()->parse('/^abc/')->accept(new StartsWithCaret())); // bool(true)

use PHPRegex\Toolkit\Regex;
use PHPRegex\Parser\Printer\PatternPrinter;

$ast = Regex::create()->parse('/foo/i');

// Compile back to string
$pattern = $ast->accept(new PatternPrinter());
echo $pattern;  // '/foo/i'

use PHPRegex\Toolkit\Regex;
use PHPRegex\Optimizer\Rewriter;

$ast = Regex::create()->parse('/(?:foo)/');
$optimized = $ast->accept(new Rewriter());

$pattern = $optimized->accept(new PatternPrinter());
echo $pattern;  // '/foo/'

use PHPRegex\Toolkit\Regex;
use PHPRegex\Optimizer\Modernizer;

$ast = Regex::create()->parse('/[0-9](?:foo)/');
$modernized = $ast->accept(new Modernizer());

$pattern = $modernized->accept(new PatternPrinter());
echo $pattern;  // '/\dfoo/'

use PHPRegex\Toolkit\Regex;

$result = Regex::create()->validate('/(?<n>a)\k<m>/');  // Invalid: no group "m"

var_dump($result->isValid);       // bool(false)
echo $result->errorCode?->value;  // regex.backref.missing_named_group

use PHPRegex\Toolkit\Regex;
use PHPRegex\Linter\PatternLinter;

$linter = new PatternLinter();
Regex::create()->parse('/(a+)+b/')->accept($linter);

foreach ($linter->getIssues() as $issue) {
    echo $issue->message, "\n";
}
// Nested quantifiers can cause catastrophic backtracking.
// Quantified capturing group "(...)" with "+": only the last iteration's capture is retained.

use PHPRegex\Toolkit\Regex;

$analysis = Regex::create()->redos('/(a+)+b/');
echo $analysis->severity->value;            // 'critical'
echo $analysis->proof->value;               // 'proven'
echo $analysis->confidenceLevel()->value;   // 'medium': not replayed on the engine yet

use PHPRegex\Toolkit\Regex;
use PHPRegex\Parser\Analysis\ComplexityScorer;

$ast = Regex::create()->parse('/^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/');
$score = $ast->accept(new ComplexityScorer());

echo $score;  // 65

use PHPRegex\Toolkit\Regex;
use PHPRegex\Parser\Analysis\MetricsCollector;

$ast = Regex::create()->parse('/\d{4}-\d{2}-\d{2}/');
$metrics = $ast->accept(new MetricsCollector());

echo $metrics['total'];                     // 10
echo $metrics['maxDepth'];                  // 4
echo $metrics['counts']['QuantifierNode'];  // 3

use PHPRegex\Toolkit\Regex;
use PHPRegex\Parser\Analysis\LengthRangeCalculator;

$ast = Regex::create()->parse('/a{2,4}b*/');
[$min, $max] = $ast->accept(new LengthRangeCalculator());

echo $min;        // 2 (aa)
var_dump($max);   // NULL (unbounded)

use PHPRegex\Toolkit\Regex;
use PHPRegex\Parser\Analysis\LiteralExtractor;

$ast = Regex::create()->parse('/user-\d{4}\.log/');
$literals = $ast->accept(new LiteralExtractor());

var_dump($literals->prefixes);            // ['user-']
var_dump($literals->suffixes);            // ['.log']
var_dump($literals->getLongestPrefix());  // 'user-'
var_dump($literals->getLongestSuffix());  // '.log'
var_dump($literals->complete);            // false

use PHPRegex\Toolkit\Regex;
use PHPRegex\Generator\SampleGenerator;

$ast = Regex::create()->parse('/[A-Z][a-z]{3,5}\d{2}/');
$sample = $ast->accept(new SampleGenerator());

echo $sample;  // e.g., "Word12"

use PHPRegex\Toolkit\Regex;
use PHPRegex\Generator\TestCaseGenerator;

$ast = Regex::create()->parse('/\d{3}-\d{4}/');
$cases = $ast->accept(new TestCaseGenerator());

// ['matching' => ['000-0000'], 'non_matching' => ['00.000', '00.00000', '0000.000']]

use PHPRegex\Toolkit\Regex;
use PHPRegex\Explain\TextExplainer;

$ast = Regex::create()->parse('/\d{3}-\d{4}/');
$explanation = $ast->accept(new TextExplainer());

echo $explanation;
/*
Regex matches
    Character Type: A digit: [0-9] (exactly 3 times)
  '-'
    Character Type: A digit: [0-9] (exactly 4 times)
*/

use PHPRegex\Toolkit\Regex;
use PHPRegex\Explain\HtmlExplainer;

$ast = Regex::create()->parse('/\w+@\w+\.\w+/');
$html = $ast->accept(new HtmlExplainer());

echo $html;
// <div class="regex-explain">
// <strong>Regex matches:</strong>
// <ul><li>(one or more times) <span title="Character Type: A word character: [a-zA-Z_0-9]">Character Type: <strong>\w</strong> (A word character: [a-zA-Z_0-9])</span></li>
// <li><span title="Literal: &#039;@&#039;">Literal: <strong>&#039;@&#039;</strong></span></li>
// <li>(one or more times) <span title="Character Type: A word character: [a-zA-Z_0-9]">Character Type: <strong>\w</strong> (A word character: [a-zA-Z_0-9])</span></li>
// <li><span title="Literal: &#039;.&#039;">Literal: <strong>&#039;.&#039;</strong></span></li>
// <li>(one or more times) <span title="Character Type: A word character: [a-zA-Z_0-9]">Character Type: <strong>\w</strong> (A word character: [a-zA-Z_0-9])</span></li></ul>
// </div>

use PHPRegex\Toolkit\Regex;
use PHPRegex\Parser\Printer\NodeDumper;

$ast = Regex::create()->parse('/foo/');
$dump = $ast->accept(new NodeDumper());

echo $dump;
/*
Regex(delimiter: /, flags: )
  Sequence:
    Literal('f')
    Literal('o')
    Literal('o')
*/

use PHPRegex\Toolkit\Regex;
use PHPRegex\Explain\MermaidRenderer;

$ast = Regex::create()->parse('/a|b/');
$mermaid = $ast->accept(new MermaidRenderer());

echo $mermaid;
/*
graph TD;
    node0["Regex: none"]
    node1{"Alternation"}
    node2["Literal: a"]
    node1 --> node2
    node3["Literal: b"]
    node1 --> node3
    node0 --> node1
*/

use PHPRegex\Toolkit\Regex;
use PHPRegex\Explain\AsciiTreeRenderer;

$ast = Regex::create()->parse('/^a+$/');
$tree = $ast->accept(new AsciiTreeRenderer());

echo $tree;
/*
Regex
\-- Sequence
    |-- Anchor (^)
    |-- Quantifier (+, greedy)
    |   \-- Literal ('a')
    \-- Anchor ($)
*/

use PHPRegex\Toolkit\Regex;
use PHPRegex\Explain\RailroadSvgRenderer;

$ast = Regex::create()->parse('/a|b/');
$svg = $ast->accept(new RailroadSvgRenderer());

echo $svg;
// <svg ...>...</svg>

use PHPRegex\Toolkit\Regex;
use PHPRegex\Explain\Highlighter\ConsoleHighlighter;

$ast = Regex::create()->parse('/\d+/');
$highlighted = $ast->accept(new ConsoleHighlighter());

echo $highlighted;
// "\033[38;2;78;201;176m\\d\033[0m\033[38;2;215;186;125m+\033[0m"

use PHPRegex\Parser\AbstractNodeVisitor;

class LiteralCountVisitor extends AbstractNodeVisitor
{
    public function visitRegex(Node\RegexNode $node): int
    {
        return $node->pattern->accept($this);
    }

    public function visitLiteral(Node\LiteralNode $node): int
    {
        return 1;
    }

    public function visitSequence(Node\SequenceNode $node): int
    {
        return array_sum(
            array_map(fn($child) => $child->accept($this), $node->children)
        );
    }
}

// Usage
$ast = Regex::create()->parse('/hello world/');
$visitor = new LiteralCountVisitor();
$count = $ast->accept($visitor);

echo $count;  // 11, one literal per character

use PHPRegex\Parser\AbstractTraversingVisitor;

class GroupCollectorVisitor extends AbstractTraversingVisitor
{
    private array $groups = [];

    public function visitGroup(Node\GroupNode $node)
    {
        if ($node->name !== null) {
            $this->groups[] = $node->name;
        }

        return parent::visitGroup($node); // keep descending: groups nest
    }

    public function getGroupNames(): array
    {
        return $this->groups;
    }
}

// Usage
$ast = Regex::create()->parse('/(?<year>\d{4})-(?<month>\d{2})/');
$visitor = new GroupCollectorVisitor();
$ast->accept($visitor);

print_r($visitor->getGroupNames());
// Array ( [0] => year [1] => month )

use PHPRegex\Parser\AbstractNodeVisitor;

class UppercaserVisitor extends AbstractNodeVisitor
{
    public function visitLiteral(Node\LiteralNode $node): Node\LiteralNode
    {
        return new Node\LiteralNode(
            strtoupper($node->value),
            $node->startPosition,
            $node->endPosition
        );
    }
}

// Usage: Transform /hello/ to /HELLO/
$ast = Regex::create()->parse('/hello/');
$visitor = new UppercaserVisitor();
$newAst = $ast->accept($visitor);

echo $newAst->accept(new PatternPrinter());  // '/HELLO/'