<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
<html>
<head>
<title></title>
<style type="text/css">
<!--
th, td { padding-right: 2em; }
th p { margin: 3pt;
text-align: left;
border-bottom: thin solid;
}
td p { margin: 3pt; }
-->
</style>
</head>
<body>
<h3><a name="Ambient aliases"><a name="25524540">Ambient aliases </a></a></h3>
<p>The <code>A<></code> formatting code specifies an <strong>alias to an
ambient antecedent</strong>.
This is like a <a href="#Placement links">placement link</a>, except
that the text that is inserted to replace the <code>A<></code>
formatting code is
some portion of the <a href="#General syntactic structure">ambient
section(s)</a>
of the current document, rather than the entire contents of some
external document.
</p>
<p>Hence, the <code>A<></code> code makes it possible to incorporate
pieces of
ambient text (typically source code) into Pod documentation.
Specifically, the <code>A<></code> code is replaced by searching
backwards through
all preceding non-Pod parts of the document, to locate the nearest prior
substring that matches the contents of the <code>A<></code> code.
</p>
<p>The contents of an <code>A<></code> code can specify a back-reference
of this type
in one of two ways:
</p>
<ul><li>as a <em>prefix keyword</em>, or
</li>
<li>as a <em>delimited text range</em>.
</li>
</ul><p>By default, <code>A<></code> aliases are "keyword oriented".
That is, the contents
of an <code>A<></code> block are treated as a keyword or prefix that
introduces
the desired text. That text is located by searching backwards from the
location of the <code>A<></code> code, to find the nearest preceding
instance of
the specified prefix in any previous ambient block. The text that is
then used to replace the <code>A<></code> is the first "symbol"
following that
located prefix. In this context, a "symbol" is defined as a sequence of
non-whitespace characters terminated by a transition from an identifier
character to a non-identifier character.
</p>
<p>For example, in the following:
</p>
<blockquote><pre>class Pet {
has $name;
=DESCRIPTION
The class A<class> provides a A<has> attribute.
</pre></blockquote><p>the <code>A<class></code> formatting code would be
replaced by "Pet", since that
is the sequence of non-whitespace characters that immediately follows
"class" in the preceding ambient source code. Likewise, the
<code>A<has></code>
formatting code would be replaced by "$name", because that is the
longest sequence of non-whitespace characters that follows a "has" and
terminates in an identifier-to-nonidentifier boundary.
</p>
<p>In other words, any formatting code of the form
<code>A<<var>prefix</var>></code>
is replaced by the substring of the nearest preceding
ambient block that matches the pattern:
</p>
<blockquote><pre>/ .* <var>prefix</var> \s* <( \S*? \w )> [\W | $] /
</pre></blockquote><p>This default is designed to work well for the commonest
kind of
back-reference in ambient text: a reference to a code construct that
was defined using a prefix keyword and whose name ends in an identifier.
</p>
<p>The second and more general way of specifying an alias is to specify
both a prefix and a postfix delimiter for the replacement text. If the
contents of an <code>A<></code> formatting code include a range marker
(<code>..</code>),
the sequence before the <code>..</code> is treated as the left delimiter of the
replacement text, and the sequence after the <code>..</code> is the right
delimiter. In this case, there are no other constraints on the
replacement text. In particular, it may contain any number of non-
identifier or whitespace characters. For example:
</p>
<blockquote><pre>class Pet {
</pre></blockquote><blockquote><pre>method eat(Food $meal) {...}
</pre></blockquote><blockquote><pre>=for DESCRIPTION
The A<method>() method has the following argument list: A<(..)>
</pre></blockquote><p>This would be interpreted as:
</p>
<blockquote><pre>The eat() method has the following argument list: Food $meal
</pre></blockquote><p>because the <code>A<(..)></code> specifies an
alias to the closest preceding ambient
text that is left-delimited by a '(' and right-delimited by a ')'.
</p>
<p>To specify an alias in which the sequence <code>..</code> is itself
a left- or right-delimiter (rather than the separator between the two),
use a <code>V<></code> code:
</p>
<blockquote><pre>constant @range = 0..99;
</pre></blockquote><blockquote><pre>=para
The maximum value is A<V<..>..;>
</pre></blockquote><h4><a name="Explicit aliasing"><a name="25834848">Explicit
aliasing </a></a></h4>
<p>The replacement strings for <code>A<></code> formatting codes are
normally
specified implicitly, by the closest preceding ambient text that matches
the contents of the <code>A<></code> code.
</p>
<p>However, it is possible to override this behaviour and create an
<em>explicitly defined</em> alias, using the <code>=alias</code> directive:
</p>
<blockquote><pre>class Agent {...}
=alias component Agent
</pre></blockquote><blockquote><pre>class Transaction is Activity {
</pre></blockquote><blockquote><pre>=DESCRIPTION
The A<class> class represents a transaction activity between two
A<component> objects.
</pre></blockquote><p>In the preceding example, <code>A<class></code> is
a normal "keyword" alias
(which would be replaced by the closest preceding prefixed match:
"Transaction"). However, <code>A<component></code> is a defined alias
(which would be replaced by the explicitly specified text: "Agent").
</p>
<p>Each back-reference name defined by an <=alias> directive is lexically
scoped within the block structure of the surrounding Pod. To create
"global" aliases, define them at the start of the Pod document, at the
outermost block level.
</p>
<p>Explicitly defined aliases always override normal prefix or delimited
aliases, and thereby allow you to refer to ambient constructs that would
otherwise be inaccessible to an implicit back-reference.
</p>
<p>For example, within the <code>DESCRIPTION</code> block of the previous
example,
the Agent class couldn't be referred to as <code>A<class></code>, since
the
intervening Transaction class "hides" it from the look-behind matching
of implicit back-reference mechanism. But the <code>=alias</code> command allows
the name of the earlier class to be associated with a distinct symbolic
alias (i.e. "component"), which then allows it to be referred to
unambiguously, regardless of other intervening code.
</p>
<p>Another way of thinking of this is that explicitly defined aliases
change the normal <code>A<></code> substitution behaviour from being
determined
<em>relatively</em> by the location of the <code>A<></code> code, to
being determined
<em>absolutely</em> by the alias name itself.
</p>
<p>An <code>=alias</code> directive expects two arguments:
</p>
<ul><li>The name of the new alias
</li>
<li>The text with which that new alias is to be replaced
</li>
</ul><p>The alias name may be any sequence of non-whitespace characters. The
remainder of the line (ignoring the whitespace immediately after the
name) is treated as the replacement text. For example:
</p>
<blockquote><pre>=alias Smith Jones
=alias G&T green tea
=alias [EMAIL PROTECTED] Gosh darn
</pre></blockquote><blockquote><pre>=para
A<[EMAIL PROTECTED]> it, A<Smith>, you spilled my A<G&T>!
</pre></blockquote><p>is equivalent to:
</p>
<blockquote><pre>=para
Gosh darn it, Jones, you spilled my green tea!
</pre></blockquote><p>To specify an alias name that includes a whitespace, or
a replacement
text with surrounding whitespace, use a <code>V<></code> formatting code:
</p>
<blockquote><pre>=alias slow V< >...slow
=alias V<extra slow> s-l-o-w
=alias V<ultra slow> V< >s l o wV< >
</pre></blockquote><blockquote><pre>=para
The service was not merely A<slow>, or even A<extra slow>.
It was A<ultra slow>
</pre></blockquote><p>Although only the <code>V<></code> code is
significant within the name of an alias,
you can use <em>any</em> formatting code(s) within the replacement text:
</p>
<blockquote><pre>=alias V<ultra slow> S< s l o w >
=alias V<hyper slow> B<...s...l...o...w...>
</pre></blockquote><p>In particular, you can use an <code>A<></code>
code in the replacement text of an
<code>=alias</code>. This is useful to preserve the abstract relationship
between
ambient code and Pod documentation. For example, in the earlier Agent
example, instead of:
</p>
<blockquote><pre>class Agent {...}
=alias component Agent
</pre></blockquote><p>the alias could have been defined:
</p>
<blockquote><pre>class Agent {...}
=alias component A<class>
</pre></blockquote><p>so that the class name did not have to be repeated as
part of the alias.
This approach has the important benefit that the alias would not have
to be modified in any way if the name of the Agent class were
subsequently changed:
</p>
<blockquote><pre>class Operative {...}
=alias component A<class>
</pre></blockquote><p>Likewise, in the earlier range example, it would have
been cleaner and
more maintainable to write:
</p>
<blockquote><pre>constant @range = 0..99;
=alias max A<V<..>..;>
</pre></blockquote><blockquote><pre>=para
The maximum value is A<max>
</pre></blockquote><p>Explicit aliases also provide a way to "retarget"
implicit back-references
if they are later invalidated by keyword changes in the
source code. For example, given the following documented code:
</p>
<blockquote><pre>class Transaction {
my Int $trans_counter;
=DESCRIPTION
The A<my Int> variable is used to track the total number of
transactions active at any one time. The value of A<my Int> is
incremented by A<class>'s C<BUILD> submethod and decremented by
the A<class> destructor.
</pre></blockquote><p>If a subsequent redesign requires that the class be
changed to a role,
and the lexical counter converted to a state variable, then every
corresponding <code>A<></code> code in the documentation would have to be
altered too:
</p>
<blockquote><pre>role Transaction {
state Int $trans_counter;
=DESCRIPTION
The A<state Int> variable is used to track the total number of
transactions active at any one time. The value of A<state Int> is
incremented by A<role>'s C<BUILD> submethod and decremented by
the A<role> destructor.
</pre></blockquote><p>A less onerous and error-prone solution would be to
leave the original
<code>A<></code> codes "as is", and insert aliases to override the
default prefix
back-matching:
</p>
<blockquote><pre>role Transaction {
=alias class A<role>
state Int $trans_counter;
=alias V<my Int> A<state Int>
=DESCRIPTION
The A<my Int> variable is used to track the total number of transactions
active at any one time. The value of A<my Int> is incremented by the
A<class> C<BUILD> submethod and decremented by the A<class>
destructor.
</pre></blockquote><p>Note that <code>=alias</code> is a fundamental Perldoc
directive, like <code>=begin</code>
or <code>=for</code>; it is <em>not</em> an instance of an
<a href="#Abbreviated blocks">abbreviated block</a>. Hence there is no paragraph
or delimited form of the <code>=encoding</code> directive (just as there is no
paragraph or delimited form of <code>=begin</code>).
</p>
</body>
</html>
