[svn:parrot] r47630 - branches/gsoc_past_optimization/docs/pct/pattern

[tcurtis at svn.parrot.org]

Author: tcurtis
Date: Tue Jun 15 00:08:39 2010
New Revision: 47630
URL: https://trac.parrot.org/parrot/changeset/47630

Log:
Added docs for PAST::Pattern::Match.

Added:
   branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_match.pod

Added: branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_match.pod
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ branches/gsoc_past_optimization/docs/pct/pattern/past_pattern_match.pod	Tue Jun 15 00:08:39 2010	(r47630)
@@ -0,0 +1,80 @@
+=head1 NAME
+
+PAST::Pattern::Match - the result object from matching a PAST::Pattern.
+
+=head1 SYNOPSIS
+
+=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.
+
+=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<$/>.
+
+=head2 Attributes
+
+=over 4
+
+=item I<$!success>
+
+1 if the match succeeded, otherwise 0.
+It can be accessed or set with the C<success([I<value>])> method.
+
+=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<$/>.
+
+=item I<$!from>
+
+Contains the matching node(or other value). It can be accessed or set with the C<from([I<value>])> method.
+
+=back
+
+=head2 Methods
+
+=over 4
+
+=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.
+
+=item C<Bool()>
+
+Converts the PAST::Pattern::Match object to a boolean by producing the I<$!success> attribute.
+
+=item C<ast()>
+
+Returns the value of the I<$!ast> attribute.
+
+=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>)>.
+
+=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.
+
+=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.
+
+=back
+
+=head2 Vtables
+
+=over 4
+
+=item C<INTVAL get_bool()>
+
+Returns 1 if the match succeeded, 0 otherwise.
+
+=back
+
+=cut