Merge branch 'master' into pass-manager

docs/Tree/Pattern.pod

@@ -51,6 +51,10 @@ to modify the behavior of matching:
 
 =over 4
 
+=item * C<exact>
+
+The C<exact> option causes the pattern to only attempt to match the exact supplied.
+
 =item * C<g> or C<global>
 
 The C<global> option, also named C<g>, causes the match to search through the
@@ -59,14 +63,16 @@ Tree::Pattern::Match.
 
 This match result will not have a .orig method.
 
-=item * C<p> or C<pos>
+=item * C<p> or C<pos> (DEPRECATED)
 
 The ACCEPTS method with the C<pos> option, also named C<p>, checks only the top
 of the tree for matching the pattern.
 
 It will not recursively search the tree's children until it finds a matching
 sub-tree.
 
+The C<p> or C<pos> option is deprecated. Please use the C<exact> option instead.
+
 =back
 
 =item transform(tree, transform, adverbs :named :slurpy)

src/PCT/Pattern.nqp

@@ -66,7 +66,7 @@ class PCT::Pattern is Tree::Pattern {
         my $nAttr := $node.attr($attribute, null, 0);
         my $result := 
           ($pAttr ~~ Tree::Pattern
-           ?? $pAttr.ACCEPTS($nAttr, :p($nAttr))
+           ?? $pAttr.ACCEPTS($nAttr, :exact(1))
            !! $nAttr ~~ $pAttr);
         if ($result) {
             $/{$attribute} := $result;
@@ -94,7 +94,7 @@ class PCT::Pattern is Tree::Pattern {
                 $pChild := self[$index];
                 if ($result := 
                     ($pChild ~~ Tree::Pattern
-                     ?? $pChild.ACCEPTS($nChild, :p($nChild))
+                     ?? $pChild.ACCEPTS($nChild, :exact(1))
                      !! $nChild ~~ $pChild)) {
                     $/[$index] := $result;
                 }

src/Tree/Pattern.nqp

@@ -9,12 +9,19 @@ INIT {
 class Tree::Pattern is Capture {
     sub patternize ($value) {
         if ($value ~~ Regex::Method) {
+            # Regexes are subs, but we just want to treat them as a normal
+            # pattern.
             $value;
         } elsif (pir::isa__IPP($value, Sub)) {
+            # We have to check for Sub-ness before we check for ACCEPTs.
+            # Otherwise, some HLLs may get weird results if they add an
+            # ACCEPTS method to Sub.
             Tree::Pattern::Closure.new($value);
         } elsif (pir::can__IPS($value, 'ACCEPTS')) {
+            # Things with accepts are treated as patterns.
             $value;
         } else {
+            # If all else fails, let's try iseq.
             Tree::Pattern::Constant.new($value);
         }
     }
@@ -43,18 +50,27 @@ class Tree::Pattern is Capture {
         $transformer.walk($node);
     }
 
+    # .transformer_class is used so that subclasses can override the
+    # behavior of the transformer.
     method transformer_class () {
         Tree::Pattern::Transformer;
     }
 
     method ACCEPTS ($node, *%opts) {
+        # Find every match.
         my $global := ?%opts<g> || ?%opts<global>;
+        # Only attempt to match an exact node.
         my $pos := %opts<p> || %opts<pos>;
+        # New way of doing exacting matching.
+        my $exact := %opts<exact> || 0;
         pir::die("ACCEPTS cannot take both :global and :pos modifiers.")
             if $global && $pos;
+        pir::die("ACCEPTS cannot take both :exact and :Global modifiers")
+            if $global && $exact;
         return self.ACCEPTSGLOBALLY($node) if $global;
         return self.ACCEPTSEXACTLY($pos) if $pos;
-        my $/ := self.ACCEPTSEXACTLY($node);
+        return self.ACCEPTSEXACTLY($node) if $exact;
+        my $/ := self.ACCEPTS($node, :exact(1));
         if (!$/ && pir::isa__iPP($node, Capture)) {
             my $index := 0;
             my $max := pir::elements__IP($node);
@@ -70,7 +86,7 @@ class Tree::Pattern is Capture {
 
     method ACCEPTSGLOBALLY ($node) {
         my $/;
-        my $first := self.ACCEPTSEXACTLY($node);
+        my $first := self.ACCEPTS($node, :exact(1));
         if (pir::isa__iPP($node, Capture)) {
             my $matches := ?$first;
             my $index := 0;

src/Tree/Pattern/Any.nqp

@@ -21,7 +21,7 @@ class Tree::Pattern::Any is Tree::Pattern {
         my $max := pir::elements(self);
         my $/;
         while ($index < $max) {
-            if ($/ := self[$index].ACCEPTS($node, :p($node))) {
+            if ($/ := self[$index].ACCEPTS($node, :exact(1))) {
                 return $/;
             }
             $index++;

src/Tree/Pattern/Transformer.nqp

@@ -94,7 +94,7 @@ module Tree::Walker {
             $shouldTransform := 0;
         }
         elsif ($pattern ~~ Tree::Pattern) {
-            $shouldTransform := $pattern.ACCEPTS($node, :pos($node));
+            $shouldTransform := $pattern.ACCEPTS($node, :exact(1));
         }
         else {
             $shouldTransform := $pattern.ACCEPTS($node);
@@ -113,7 +113,7 @@ module Tree::Walker {
         }
         elsif ($walker.descend_until ~~ Tree::Pattern) {
             $shouldDescend := !$walker.descend_until.ACCEPTS($node,
-                                                            :pos($node));
+                                                             :exact(1));
         }
         else {
             $shouldDescend := !$walker.descend_until.ACCEPTS($node);

src/Tree/Transformer.nqp

@@ -15,6 +15,8 @@ class Tree::Transformer {
 module Tree::Walker {
     our multi sub walk (Tree::Transformer $walker, Capture $node) {
         my $result := $node;
+        # If we want to transform the children, we must do this
+        # walkChildren -> replaceChildren dance.
         replaceChildren($result, walkChildren($walker, $node));
         $result;
     }
@@ -43,6 +45,7 @@ module Tree::Walker {
         }
         my $max := pir::elements__IP($newChildren);
         while ($index < $max) {
+            # The new child may be null, in which case we simply drop it.
             pir::push($node, $newChildren[$index])
                 if pir::defined__IP($newChildren[$index]);
             $index++;

src/Tree/Walker.nqp

@@ -3,11 +3,17 @@
 # $Id$
 
 class Tree::Walker {
+
     our multi sub walk (Tree::Walker $walker, Capture $node) {
+        # By default, just walk the children of $node.
         walkChildren($walker, $node);
     }
 
     our multi sub walkChildren (Tree::Walker $walker, Capture $tree) {
+        # We walk only the array part of the Capture by default, because
+        # the attributes of PAST::Nodes, for example, can sometimes contain
+        # cycles. In addition, in general, attributes are not used
+        # for simple sub-trees.
         my $index := 0;
         my $len := pir::elements__iP($tree);
         while ($index < $len) {