[svn:parrot] r47698 - branches/gsoc_past_optimization/docs/pct/pattern
tcurtis at svn.parrot.org
tcurtis at svn.parrot.org
Sat Jun 19 02:08:01 UTC 2010
Author: tcurtis
Date: Sat Jun 19 02:08:01 2010
New Revision: 47698
URL: https://trac.parrot.org/parrot/changeset/47698
Log:
Please codetest. Also fix a copy-paste fail in past_pattern_constant.pod.
Modified:
branches/gsoc_past_optimization/docs/pct/pattern/past_pattern.pod (contents, props changed)
branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_closure.pod (contents, props changed)
branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_constant.pod (contents, props changed)
branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_match.pod (contents, props changed)
branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_node.pod (contents, props changed)
Modified: branches/gsoc_past_optimization/docs/pct/pattern/past_pattern.pod
==============================================================================
--- branches/gsoc_past_optimization/docs/pct/pattern/past_pattern.pod Sat Jun 19 02:03:31 2010 (r47697)
+++ branches/gsoc_past_optimization/docs/pct/pattern/past_pattern.pod Sat Jun 19 02:08:01 2010 (r47698)
@@ -15,7 +15,8 @@
=head1 DESCRIPTION
-PAST::Pattern and its subclasses allow determining whether a PAST::Node matches a certain pattern, in addition to allowing modification of any matches sub-trees similarly to regex substitution.
+PAST::Pattern and its subclasses allow determining whether a PAST::Node matches a certain pattern,
+in addition to allowing modification of any matches sub-trees similarly to regex substitution.
=head1 PAST::Pattern is Capture
@@ -25,7 +26,9 @@
=item C<patternize(I<value>)>
-Converts an object that is not a pattern(does not implement the C<ACCEPTS> method) into one that is. If I<value> does the C<invokable> role, it is used to create a C<PAST::Pattern::Closure> pattern. Otherwise, it is used to create a C<PAST::Pattern::Constant> pattern.
+Converts an object that is not a pattern(does not implement the C<ACCEPTS> method) into one that
+is. If I<value> does the C<invokable> role, it is used to create a C<PAST::Pattern::Closure>
+pattern. Otherwise, it is used to create a C<PAST::Pattern::Constant> pattern.
=back
@@ -35,11 +38,20 @@
=item C<transform(I<past>, I<transform>)>
-Uses the C<invokable> object or C<PAST::Transformer> in I<transform> to transform any sub-trees of I<past> that match the pattern.
+Uses the C<invokable> object or C<PAST::Transformer> in I<transform> to transform any sub-trees of
+I<past> that match the pattern.
=item C<ACCEPTS(I<node>, [option1 => value1, option2 => value2, ...])>
-Tests whether the I<node> or any sub-tree thereof matches the pattern. Returns a C<PAST::Pattern::Match> result object. Valid options are C<g> or C<global> and C<p> or C<pos>. If C<g> or C<global> are true, the match is global. After the first match is found, the search will continue until every sub-tree has been checked for matching. If no matches are found, a false C<PAST::Pattern::Match> object will be returned. If only one match is found, C<ACCEPTS> returns the same value with or without C<g> or C<global>. If multiple matches are found, the result is a true C<PAST::Pattern::Match> object whose array part contains the individual match results. If C<p> or C<pos> are provided, they specify a PAST::Node that must exactly match the pattern. Supplying one of both C<g> or C<global> and C<p> or C<pos> produces an error.
+Tests whether the I<node> or any sub-tree thereof matches the pattern. Returns a
+C<PAST::Pattern::Match> result object. Valid options are C<g> or C<global> and C<p> or C<pos>.
+If C<g> or C<global> are true, the match is global. After the first match is found, the search will
+continue until every sub-tree has been checked for matching. If no matches are found, a false
+C<PAST::Pattern::Match> object will be returned. If only one match is found, C<ACCEPTS> returns the
+same value with or without C<g> or C<global>. If multiple matches are found, the result is a true
+C<PAST::Pattern::Match> object whose array part contains the individual match results. If C<p> or
+C<pos> are provided, they specify a PAST::Node that must exactly match the pattern. Supplying one
+of both C<g> or C<global> and C<p> or C<pos> produces an error.
=back
@@ -51,7 +63,8 @@
=item C<ACCEPTSEXACTLY(I<node>)>
-Tests whether the specific node matches the pattern without recursing into children. The result should be a PAST::Pattern::Match object. Every PAST::Pattern subclass B<MUST> implement this method.
+Tests whether the specific node matches the pattern without recursing into children. The result
+should be a PAST::Pattern::Match object. Every PAST::Pattern subclass B<MUST> implement this method.
=back
Modified: branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_closure.pod
==============================================================================
--- branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_closure.pod Sat Jun 19 02:03:31 2010 (r47697)
+++ branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_closure.pod Sat Jun 19 02:08:01 2010 (r47698)
@@ -13,13 +13,18 @@
=head1 DESCRIPTION
-A PAST::Pattern::Closure matches any pattern for which its associated subroutine or other invokable object returns a true result.
+A PAST::Pattern::Closure matches any pattern for which its associated subroutine or other invokable
+object returns a true result.
=head1 PAST::Pattern::Closure is PAST::Pattern
-A PAST::Pattern::Closure contains a predicate subroutine or other object that can be invoked. This predicate sub is used to determine whether or not an object matches the pattern. If the predicate, when called with the object to be matched, produces a true result, the object matches the pattern. Otherwise, it does not.
+A PAST::Pattern::Closure contains a predicate subroutine or other object that can be invoked. This
+predicate sub is used to determine whether or not an object matches the pattern. If the predicate,
+when called with the object to be matched, produces a true result, the object matches the pattern.
+Otherwise, it does not.
-PAST::Pattern::patternize produces a PAST::Pattern::Closure when called with an object which provides the invokable role.
+PAST::Pattern::patternize produces a PAST::Pattern::Closure when called with an object which
+provides the invokable role.
=head2 Attributes
@@ -27,7 +32,8 @@
=item code
-The code attribute holds the predicate invokable object that is used to determine whether the pattern matches an object.
+The code attribute holds the predicate invokable object that is used to determine whether the
+pattern matches an object.
=back
@@ -41,11 +47,13 @@
=item code([value])
-If value is provided, set the code attribute of the pattern to value. Otherwise, return the current value of the code attribute.
+If value is provided, set the code attribute of the pattern to value. Otherwise, return the current
+value of the code attribute.
=item ACCEPTSEXACTLY(node)
-Used internally by the inherited ACCEPTS method to determine whether a node exactly matches the pattern.
+Used internally by the inherited ACCEPTS method to determine whether a node exactly matches the
+pattern.
=back
Modified: branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_constant.pod
==============================================================================
--- branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_constant.pod Sat Jun 19 02:03:31 2010 (r47697)
+++ branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_constant.pod Sat Jun 19 02:08:01 2010 (r47698)
@@ -4,13 +4,17 @@
=head1 DESCRIPTION
-A PAST::Pattern::Constant matches objects that are equal to(according to the is_equal vtable) its value.
+A PAST::Pattern::Constant matches objects that are equal to(according to the is_equal vtable) its
+value.
=head1 PAST::Pattern::Constant is PAST::Pattern
-A PAST::Pattern::Constant contains a constant value. This constant value specifies what objects the pattern matches. The pattern matches if the is_equal vtable of the value produces a true result when called with the object to be matched.
+A PAST::Pattern::Constant contains a constant value. This constant value specifies what objects the
+pattern matches. The pattern matches if the is_equal vtable of the value produces a true result
+when called with the object to be matched.
-PAST::Pattern::patternize produces a PAST::Pattern::Constant when called with an object which neither has an ACCEPTS method nor provides the invokable role.
+PAST::Pattern::patternize produces a PAST::Pattern::Constant when called with an object which
+neither has an ACCEPTS method nor provides the invokable role.
=head2 Attributes
@@ -18,11 +22,11 @@
=item value
-The value attribute holds the constant value that must be equal to any matching objects. If the value lacks an is_equal vtable, the ACCEPTSEXACTLY method will throw an exception.
+The value attribute holds the constant value that must be equal to any matching objects. If the
+value lacks an is_equal vtable, the ACCEPTSEXACTLY method will throw an exception.
=back
-
=head2 Methods
=over 4
@@ -33,30 +37,13 @@
=item value([new_value])
-If new_value is provided, set the value attribute of the pattern to new_value. Otherwise, return the current value of the value attribute.
-
-=item ACCEPTSEXACTLY(node)
-
-Used internally by the inherited ACCEPTS method to determine whether a node exactly matches the pattern.
-
-=back
-
-=cut
-=head2 Methods
-
-=over 4
-
-=item new(code)
-
-Creates a PAST::Pattern::Closure with code as its associated predicate.
-
-=item code([value])
-
-If value is provided, set the code attribute of the pattern to value. Otherwise, return the current value of the code attribute.
+If new_value is provided, set the value attribute of the pattern to new_value. Otherwise, return the
+current value of the value attribute.
=item ACCEPTSEXACTLY(node)
-Used internally by the inherited ACCEPTS method. to determine whether a node exactly matches the pattern.
+Used internally by the inherited ACCEPTS method to determine whether a node exactly matches the
+pattern.
=back
Modified: branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_match.pod
==============================================================================
--- branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_match.pod Sat Jun 19 02:03:31 2010 (r47697)
+++ branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_match.pod Sat Jun 19 02:08:01 2010 (r47698)
@@ -6,17 +6,26 @@
=head1 DESCRIPTION
-Any matching operation with a C<PAST::Pattern> produces a C<PAST::Pattern::Match> object. It can be used to determine whether the match was successful, to find the matching node, and to find the results of the child and attribute sub-patterns.
+Any matching operation with a C<PAST::Pattern> produces a C<PAST::Pattern::Match> object. It can be
+used to determine whether the match was successful, to find the matching node, and to find the
+results of the child and attribute sub-patterns.
=head1 PAST::Pattern::Match is Capture
=head2 Sub-pattern result objects
-Some C<PAST::Pattern> subclasses allow supplying child or attribute sub-patterns. When matching these patterns, the C<PAST::Pattern::Match> result object can be used to access the results of the sub-patterns.
-
-The results of child sub-patterns are accessible through array indexing on the result object. The result of the first child sub-pattern of the pattern will be C<match_result[0]>, the result of the second will be C<match_result[1]>, and so on.
-
-The results of attribute sub-patterns are accessible through hash indexing on the result object. The result of the "foo" attribute sub-pattern will be C<match_result['foo']>, for example. In NQP, these can also be accessed using the I<$<foo>> syntax if the C<PAST::Pattern::Match> object is bound to I<$/>.
+Some C<PAST::Pattern> subclasses allow supplying child or attribute sub-patterns. When matching
+these patterns, the C<PAST::Pattern::Match> result object can be used to access the results of the
+sub-patterns.
+
+The results of child sub-patterns are accessible through array indexing on the result object. The
+result of the first child sub-pattern of the pattern will be C<match_result[0]>, the result of the
+second will be C<match_result[1]>, and so on.
+
+The results of attribute sub-patterns are accessible through hash indexing on the result object. The
+result of the "foo" attribute sub-pattern will be C<match_result['foo']>, for example. In NQP, these
+can also be accessed using the I<$<foo>> syntax if the C<PAST::Pattern::Match> object is bound to
+I<$/>.
=head2 Attributes
@@ -29,11 +38,14 @@
=item I<$!ast>
-An "abstract object" that has been associated with the C<PAST::Pattern::Match> object. It can be accessed with the C<ast()> method. It can be set with the C<!make(I<ast>)>, or using the C<make> statement in NQP if the C<PAST::Pattern::Match> object is bound to I<$/>.
+An "abstract object" that has been associated with the C<PAST::Pattern::Match> object. It can be
+accessed with the C<ast()> method. It can be set with the C<!make(I<ast>)>, or using the C<make>
+statement in NQP if the C<PAST::Pattern::Match> object is bound to I<$/>.
=item I<$!from>
-Contains the matching node(or other value). It can be accessed or set with the C<from([I<value>])> method.
+Contains the matching node(or other value). It can be accessed or set with the C<from([I<value>])>
+method.
=back
@@ -43,7 +55,8 @@
=item C<new([I<success>, [I<from>]])>
-Creates a new C<PAST::Pattern::Match> object with the I<$!success> and I<$!from> attributes set to the values of I<success> and I<from>, if provided.
+Creates a new C<PAST::Pattern::Match> object with the I<$!success> and I<$!from> attributes set to
+the values of I<success> and I<from>, if provided.
=item C<Bool()>
@@ -55,15 +68,18 @@
=item C<!make(I<ast>)>
-Sets the value of the I<$!ast> attribute to I<ast>. In NQP, if I<$/> is a C<PAST::Pattern::Match> object, C<make I<foo>> is equivalent to C<$/."!make"(I<foo>)>.
+Sets the value of the I<$!ast> attribute to I<ast>. In NQP, if I<$/> is a C<PAST::Pattern::Match>
+object, C<make I<foo>> is equivalent to C<$/."!make"(I<foo>)>.
=item C<from([I<from>])>
-If I<from> is provide, sets the I<$!from> attribute to I<from>. Otherwise, returns the value of the I<$!from> attribute.
+If I<from> is provide, sets the I<$!from> attribute to I<from>. Otherwise, returns the value of the
+I<$!from> attribute.
=item C<success([I<success>])>
-If I<success> is provide, sets the I<$!success> attribute to I<success>. Otherwise, returns the value of the I<$!success> attribute.
+If I<success> is provide, sets the I<$!success> attribute to I<success>. Otherwise, returns the
+value of the I<$!success> attribute.
=back
Modified: branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_node.pod
==============================================================================
--- branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_node.pod Sat Jun 19 02:03:31 2010 (r47697)
+++ branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_node.pod Sat Jun 19 02:08:01 2010 (r47698)
@@ -6,20 +6,35 @@
=head1 DESCRIPTION
-C<PAST::Pattern::Node> subclasses correspond to C<PAST::Node> subclasses. They match nodes of the corresponding types. If the pattern has child sub-patterns, the matched node must have the same number of children and each child of the node must match the corresponding child of the pattern. If the pattern has attribute sub-patterns, the matched node must have each attribute that the pattern has, and that attribute value must match the value of the corresponding attribute of the pattern.
+C<PAST::Pattern::Node> subclasses correspond to C<PAST::Node> subclasses. They match nodes of the
+corresponding types. If the pattern has child sub-patterns, the matched node must have the same
+number of children and each child of the node must match the corresponding child of the pattern. If
+the pattern has attribute sub-patterns, the matched node must have each attribute that the pattern
+has, and that attribute value must match the value of the corresponding attribute of the pattern.
=head1 PAST::Pattern::Node is PAST::Pattern
-C<PAST::Pattern::Node> is the superclass for all the C<PAST::Pattern> types that are specific to a certain C<PAST::Node> subclass.
+C<PAST::Pattern::Node> is the superclass for all the C<PAST::Pattern> types that are specific to a
+certain C<PAST::Node> subclass.
=head2 Attributes
-Each attribute can contain a PAST::Pattern or other object with an C<ACCEPTS> method, an object that does the C<invokable> role(such as a C<Sub>), or any other object. If the value of an attribute does not have an C<ACCEPTS> method, C<PAST::Pattern::patternize> is called on it to produce an object that does. C<Invokable> objects are used to create C<PAST::Pattern::Closure> objects, which match any object for which their associated C<invokable> object returns true. For other objects without an C<ACCEPTS> method, the object is used to create a C<PAST::Pattern::Constant> object which matches any object for which the result of the C<is_equal> vtable of the object is true.
-
-Attributes can be set or accessed using hash indexing(in which case, you must manually call C<PAST::Pattern::patternize> if necessary), using the C<attr> method, or as named arguments to the C<new> method.
-
-The attributes of C<PAST::Nodes> and their subclasses can be set or accessed using accessor methods with the appropriate name.
-C<PAST::Pattern::Node> has attributes with accessors for the following C<PAST::Node> and C<PCT::Node> attributes:
+Each attribute can contain a PAST::Pattern or other object with an C<ACCEPTS> method, an object that
+does the C<invokable> role(such as a C<Sub>), or any other object. If the value of an attribute does
+not have an C<ACCEPTS> method, C<PAST::Pattern::patternize> is called on it to produce an object
+that does. C<Invokable> objects are used to create C<PAST::Pattern::Closure> objects, which match
+any object for which their associated C<invokable> object returns true. For other objects without an
+C<ACCEPTS> method, the object is used to create a C<PAST::Pattern::Constant> object which matches
+any object for which the result of the C<is_equal> vtable of the object is true.
+
+Attributes can be set or accessed using hash indexing(in which case, you must manually call
+C<PAST::Pattern::patternize> if necessary), using the C<attr> method, or as named arguments to the
+C<new> method.
+
+The attributes of C<PAST::Nodes> and their subclasses can be set or accessed using accessor methods
+with the appropriate name.
+C<PAST::Pattern::Node> has attributes with accessors for the following C<PAST::Node> and
+C<PCT::Node> attributes:
=over 4
@@ -59,21 +74,34 @@
=item C<check_attribute(I<pattern>, I<node>, I<attr>, I<match>)>
-Verifies that I<node>'s attribute I<attr> matches I<pattern>'s attribute I<attr>, if one exists. The success and attributes of I<match>, which should be a C<PAST::Pattern::Match> object, will are then modified appropriately. If a sub-pattern is not found, it returns 1. Otherwise, it returns the boolean value of the result of attempting to match I<node>'s I<attr> attribute with the sub-pattern. If there is a sub-pattern and it matches, then I<match>'s attribute I<attr> is set to the result. If the sub-pattern does not match, then the success value of I<match> will be set to 0.
+Verifies that I<node>'s attribute I<attr> matches I<pattern>'s attribute I<attr>, if one exists. The
+success and attributes of I<match>, which should be a C<PAST::Pattern::Match> object, will are then
+modified appropriately. If a sub-pattern is not found, it returns 1. Otherwise, it returns the
+boolean value of the result of attempting to match I<node>'s I<attr> attribute with the sub-pattern.
+If there is a sub-pattern and it matches, then I<match>'s attribute I<attr> is set to the result. If
+the sub-pattern does not match, then the success value of I<match> will be set to 0.
=item C<check_children(I<pattern>, I<node>, I<match>)>
-Verifies that the children of I<pattern> match the corresponding children of I<node>. The I<match> argument should be a C<PAST::Pattern::Match> variable. If there are no child sub-patterns of I<pattern> or all of the child sub-patterns match the corresponding children of I<node>, it returns 1. The children of I<match> with the same index as the child sub-patterns are set to the result of their matches if they are successful. If any child sub-patterns do not match the corresponding child of I<node>, the success value of I<match> is set to 0 and 0 is returned.
+Verifies that the children of I<pattern> match the corresponding children of I<node>. The I<match>
+argument should be a C<PAST::Pattern::Match> variable. If there are no child sub-patterns of
+I<pattern> or all of the child sub-patterns match the corresponding children of I<node>, it returns
+1. The children of I<match> with the same index as the child sub-patterns are set to the result of
+their matches if they are successful. If any child sub-patterns do not match the corresponding child
+of I<node>, the success value of I<match> is set to 0 and 0 is returned.
=item C<check_node_attributes(I<pattern>, I<node>, I<match>)>
-A convenience sub for checking the PAST::Node attributes of I<pattern> and I<node>. C<check_attribute> is called with I<pattern>, I<node>, each attribute, and I<match>. The checking aborts as soon as any existing I<pattern> attribute does not match.
+A convenience sub for checking the PAST::Node attributes of I<pattern> and I<node>.
+C<check_attribute> is called with I<pattern>, I<node>, each attribute, and I<match>. The checking
+aborts as soon as any existing I<pattern> attribute does not match.
=back
=head1 PAST::Pattern::Block is PAST::Pattern::Node
-C<PAST::Pattern::Block> patterns are used to match C<PAST::Block> nodes. Their attributes correspond to those of C<PAST::Block>.
+C<PAST::Pattern::Block> patterns are used to match C<PAST::Block> nodes. Their attributes correspond
+to those of C<PAST::Block>.
=head2 Attributes
@@ -111,7 +139,8 @@
=head1 PAST::Pattern::Op is PAST::Pattern::Node
-C<PAST::Pattern::Op> patterns are used to match C<PAST::Op> nodes. Their attributes correspond to those of C<PAST::Op>.
+C<PAST::Pattern::Op> patterns are used to match C<PAST::Op> nodes. Their attributes correspond to
+those of C<PAST::Op>.
=head2 Attributes
@@ -127,11 +156,14 @@
=head1 PAST::Pattern::Stmts is PAST::Pattern::Node
-C<PAST::Pattern::Stmts> patterns are used to match C<PAST::Stmts> nodes. They have no additional attributes beyond those of C<PAST::Pattern::Node>.
+C<PAST::Pattern::Stmts> patterns are used to match C<PAST::Stmts> nodes. They have no additional
+attributes beyond those of C<PAST::Pattern::Node>.
=head1 PAST::Pattern::Val is PAST::Pattern::Node
-C<PAST::Pattern::Val> patterns are used to match C<PAST::Val> nodes. Their attributes correspond to those of C<PAST::Val>. Since C<PAST::Val> nodes cannot have I<lvalue> attributes, the I<lvalue> attribute of C<PAST::Pattern::Node> is unimportant for C<PAST::Pattern::Val> nodes.
+C<PAST::Pattern::Val> patterns are used to match C<PAST::Val> nodes. Their attributes correspond to
+those of C<PAST::Val>. Since C<PAST::Val> nodes cannot have I<lvalue> attributes, the I<lvalue>
+attribute of C<PAST::Pattern::Node> is unimportant for C<PAST::Pattern::Val> nodes.
=head2 Attributes
@@ -143,7 +175,8 @@
=head1 PAST::Pattern::Var is PAST::Pattern::Node
-C<PAST::Pattern::Var> patterns are used to match C<PAST::Var> nodes. Their attributes correspond to those of C<PAST::Var>.
+C<PAST::Pattern::Var> patterns are used to match C<PAST::Var> nodes. Their attributes correspond to
+those of C<PAST::Var>.
=head2 Attributes
@@ -169,6 +202,7 @@
=head1 PAST::Pattern::VarList is PAST::Pattern::Node
-C<PAST::Pattern::VarList> patterns are used to match C<PAST::VarList> nodes. They have no additional attributes beyond those of C<PAST::Pattern::Node>
+C<PAST::Pattern::VarList> patterns are used to match C<PAST::VarList> nodes. They have no additional
+attributes beyond those of C<PAST::Pattern::Node>
=cut
More information about the parrot-commits
mailing list