Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Rename .ast method to .made
This makes much more sense when paired with "make".  It also makes the generic
examples of make that jnthn++ used in his

  http://jnthn.net/papers/2014-fosdem-perl6-today.pdf

(slide #24 and following) much more sensible to naive, or even experienced
Perl 6 users.  Perhaps the .ast method should be kept as a synonym for .made,
and may even have a check for AST-nodeness added, to give it additional
implicit documentational value in the Perl 6 internals.

Please note that this has bugged me since the Rakudo and NQP Internals workshop
last September.  It came back to me in full force after seeing jnthn++'s talk.
  • Loading branch information
lizmat committed Feb 3, 2014
1 parent fcaf02c commit 24373dc
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 20 deletions.
6 changes: 3 additions & 3 deletions S02-bits.pod
Expand Up @@ -2308,9 +2308,9 @@ hash, all named arguments.

All prefix sigil operators accept one positional argument, evaluated in
item context as a rvalue. They can interpolate in strings if called with
parentheses. The special syntax form C<$()> translates into C<$( $.ast // Str($/) )>
to operate on the current match object; similarly C<@()> and C<%()> can
extract positional and named submatches.
parentheses. The special syntax form C<$()> translates into
C<$( $.made // Str($/) )> to operate on the current match object; similarly
C<@()> and C<%()> can extract positional and named submatches.

C<Parcel> and C<Capture> objects fill the ecological niche of references in Perl 6.
You can think of them as "fat" references, that is, references that
Expand Down
36 changes: 19 additions & 17 deletions S05-regex.pod
Expand Up @@ -967,7 +967,7 @@ string, instead of the string. The C<Remainder> part is matched and
returned as part of the C<Match> object but is not returned
as part of the abstract object. Since the abstract object usually
represents the top node of an abstract syntax tree, the abstract object
may be extracted from the C<Match> object by use of the C<.ast> method.
may be extracted from the C<Match> object by use of the C<.made> method.

A second call to C<make> overrides any previous call to C<make>.
C<make> is also available as a method on each match object.
Expand Down Expand Up @@ -2966,8 +2966,8 @@ However, sometimes you would like an alternate scalar value to
ride along with the match. The C<Match> object itself describes
a concrete parse tree, so this extra value is called an I<abstract>
object; it rides along as an attribute of the C<Match> object.
The C<.ast> method by default returns an undefined value.
C<$()> is a shorthand for C<$($/.ast // ~$/)>.
The C<.made> method by default returns an undefined value.
C<$()> is a shorthand for C<$($/.made // ~$/)>.

Therefore C<$()> is usually just the entire match string, but
you can override that by calling C<make> inside a regex:
Expand All @@ -2978,20 +2978,22 @@ you can override that by calling C<make> inside a regex:
# match succeeds -- ignore the rest of the regex
]);

This puts the new abstract node into C<$/.ast>. An AST node
may be of any type.
This makes it convenient to build up an abstract syntax tree of
arbitrary node types.
This puts the new abstract node into C<$/.made>. An AST node may be of any
type. Using the make/.made mechanism, it is convenient to build up an
abstract syntax tree of arbitrary node types.

The C<make> function does not impose any item or list context onto its argument,
so if you say something ambiguously listy like
However, the C<make> function is not limited to be used for storing AST
nodes and building abstract syntax trees only. This is just a specific Perl 6
internal use of this functionality. Nor does the C<make> function impose any
item or list context onto its argument, so if you say something ambiguously
listy like

make ()
make @array
make foo()

the value returned from C<.ast> will interpolate into a list. To suppress this, use
one of these:
the value returned from C<.made> will interpolate into a list. To suppress
this, use one of these:

make ().item
make []
Expand All @@ -3000,7 +3002,7 @@ one of these:
make foo().item
make $(foo())

or use C<.ast.item> or a C<$> variable on the receiving end.
or use C<.made.item> or a C<$> variable on the receiving end.

=item *

Expand All @@ -3011,7 +3013,7 @@ You may also capture a subset of the match using the C<< <(...)> >> construct:

In this case C<$()> is always a string when doing string
matching, and a list of one or more elements when doing list matching.
This construct does not set the C<.ast> attribute.
This construct does not set the C<.made> attribute.

=item *

Expand Down Expand Up @@ -3097,7 +3099,7 @@ The currently defined methods are
$/.chars # $/.to - $/.from
$/.orig # the original match string
$/.Str # substr($/.orig, $/.from, $/.chars)
$/.ast # the abstract result associated with this node
$/.made # the abstract result associated with this node (from make)
$/.caps # sequential captures
$/.chunks # sequential tokenization
$/.prematch # $/.orig.substr(0, $/.from)
Expand Down Expand Up @@ -3130,7 +3132,7 @@ they were originally in the text. The interleaved bits are also
returned as pairs, where the key is '~' and the value
is a simple C<Match> object containing only the string, even if unbound
subrules such as C<.ws> were called to traverse the text in the first
place. Calling C<.ast> on such a C<Match> object always returns a C<Str>.
place. Calling C<.made> on such a C<Match> object always returns a C<Str>.

A warning will be issued if either C<.caps> or C<.chunks> discovers
that it has overlapping bindings. In the absence of such overlap,
Expand Down Expand Up @@ -3181,8 +3183,8 @@ like a C<return>, but doesn't clobber the match state:
/;
say $(); # says 'bar'

The abstract object of any C<Match> object is available via the
C<< .ast >> method. Hence these abstract objects can be managed
The value of any C<Match> object (such as an abstract object) is available via
the C<< .made >> method. Hence these abstract objects can be managed
independently of the returned cursor objects.

The current cursor object must always be derived from C<Cursor>, or the
Expand Down

0 comments on commit 24373dc

Please sign in to comment.