xref: /PHP-Parser/lib/PhpParser/NodeVisitor.php (revision afe1628a)
1<?php declare(strict_types=1);
2
3namespace PhpParser;
4
5interface NodeVisitor {
6    /**
7     * If NodeVisitor::enterNode() returns DONT_TRAVERSE_CHILDREN, child nodes
8     * of the current node will not be traversed for any visitors.
9     *
10     * For subsequent visitors enterNode() will still be called on the current
11     * node and leaveNode() will also be invoked for the current node.
12     */
13    public const DONT_TRAVERSE_CHILDREN = 1;
14
15    /**
16     * If NodeVisitor::enterNode() or NodeVisitor::leaveNode() returns
17     * STOP_TRAVERSAL, traversal is aborted.
18     *
19     * The afterTraverse() method will still be invoked.
20     */
21    public const STOP_TRAVERSAL = 2;
22
23    /**
24     * If NodeVisitor::leaveNode() returns REMOVE_NODE for a node that occurs
25     * in an array, it will be removed from the array.
26     *
27     * For subsequent visitors leaveNode() will still be invoked for the
28     * removed node.
29     */
30    public const REMOVE_NODE = 3;
31
32    /**
33     * If NodeVisitor::enterNode() returns DONT_TRAVERSE_CURRENT_AND_CHILDREN, child nodes
34     * of the current node will not be traversed for any visitors.
35     *
36     * For subsequent visitors enterNode() will not be called as well.
37     * leaveNode() will be invoked for visitors that has enterNode() method invoked.
38     */
39    public const DONT_TRAVERSE_CURRENT_AND_CHILDREN = 4;
40
41    /**
42     * If NodeVisitor::enterNode() or NodeVisitor::leaveNode() returns REPLACE_WITH_NULL,
43     * the node will be replaced with null. This is not a legal return value if the node is part
44     * of an array, rather than another node.
45     */
46    public const REPLACE_WITH_NULL = 5;
47
48    /**
49     * Called once before traversal.
50     *
51     * Return value semantics:
52     *  * null:      $nodes stays as-is
53     *  * otherwise: $nodes is set to the return value
54     *
55     * @param Node[] $nodes Array of nodes
56     *
57     * @return null|Node[] Array of nodes
58     */
59    public function beforeTraverse(array $nodes);
60
61    /**
62     * Called when entering a node.
63     *
64     * Return value semantics:
65     *  * null
66     *        => $node stays as-is
67     *  * array (of Nodes)
68     *        => The return value is merged into the parent array (at the position of the $node)
69     *  * NodeVisitor::REMOVE_NODE
70     *        => $node is removed from the parent array
71     *  * NodeVisitor::REPLACE_WITH_NULL
72     *        => $node is replaced with null
73     *  * NodeVisitor::DONT_TRAVERSE_CHILDREN
74     *        => Children of $node are not traversed. $node stays as-is
75     *  * NodeVisitor::DONT_TRAVERSE_CURRENT_AND_CHILDREN
76     *        => Further visitors for the current node are skipped, and its children are not
77     *           traversed. $node stays as-is.
78     *  * NodeVisitor::STOP_TRAVERSAL
79     *        => Traversal is aborted. $node stays as-is
80     *  * otherwise
81     *        => $node is set to the return value
82     *
83     * @param Node $node Node
84     *
85     * @return null|int|Node|Node[] Replacement node (or special return value)
86     */
87    public function enterNode(Node $node);
88
89    /**
90     * Called when leaving a node.
91     *
92     * Return value semantics:
93     *  * null
94     *        => $node stays as-is
95     *  * NodeVisitor::REMOVE_NODE
96     *        => $node is removed from the parent array
97     *  * NodeVisitor::REPLACE_WITH_NULL
98     *        => $node is replaced with null
99     *  * NodeVisitor::STOP_TRAVERSAL
100     *        => Traversal is aborted. $node stays as-is
101     *  * array (of Nodes)
102     *        => The return value is merged into the parent array (at the position of the $node)
103     *  * otherwise
104     *        => $node is set to the return value
105     *
106     * @param Node $node Node
107     *
108     * @return null|int|Node|Node[] Replacement node (or special return value)
109     */
110    public function leaveNode(Node $node);
111
112    /**
113     * Called once after traversal.
114     *
115     * Return value semantics:
116     *  * null:      $nodes stays as-is
117     *  * otherwise: $nodes is set to the return value
118     *
119     * @param Node[] $nodes Array of nodes
120     *
121     * @return null|Node[] Array of nodes
122     */
123    public function afterTraverse(array $nodes);
124}
125