<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.51
from ProgrammersManual.texinfo on 4 March 1997 -->
<TITLE>LambdaMOO Programmer's Manual - Scattering</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="ProgrammersManual_1.html">first</A>, <A HREF="ProgrammersManual_22.html">previous</A>, <A HREF="ProgrammersManual_24.html">next</A>, <A HREF="ProgrammersManual_77.html">last</A> section, <A HREF="ProgrammersManual_toc.html">table of contents</A>.
<P><HR><P>
<H3><A NAME="SEC23" HREF="ProgrammersManual_toc.html#TOC23">Spreading List Elements Among Variables</A></H3>
<P>
It is often the case in MOO programming that you will want to access the
elements of a list individually, with each element stored in a separate
variables. This desire arises, for example, at the beginning of almost every
MOO verb, since the arguments to all verbs are delivered all bunched together
in a single list. In such circumstances, you <EM>could</EM> write statements
like these:
</P>
<PRE>
first = args[1];
second = args[2];
if (length(args) > 2)
third = args[3];
else
third = 0;
endif
</PRE>
<P>
This approach gets pretty tedious, both to read and to write, and it's prone to
errors if you mistype one of the indices. Also, you often want to check
whether or not any <EM>extra</EM> list elements were present, adding to the
tedium.
</P>
<P>
MOO provides a special kind of assignment expression, called <STRONG>scattering
assignment</STRONG> made just for cases such as these. A scattering assignment
expression looks like this:
</P>
<PRE>
{<VAR>target</VAR>, ...} = <VAR>expr</VAR>
</PRE>
<P>
where each <VAR>target</VAR> describes a place to store elements of the list that
results from evaluating <VAR>expr</VAR>. A <VAR>target</VAR> has one of the following
forms:
</P>
<DL COMPACT>
<DT><CODE><VAR>variable</VAR></CODE>
<DD>
This is the simplest target, just a simple variable; the list element in the
corresponding position is assigned to the variable. This is called a
<STRONG>required</STRONG> target, since the assignment is required to put one of the list
elements into the variable.
<DT><CODE>?<VAR>variable</VAR></CODE>
<DD>
This is called an <STRONG>optional</STRONG> target, since it doesn't always get assigned
an element. If there are any list elements left over after all of the required
targets have been accounted for (along with all of the other optionals to the
left of this one), then this variable is treated like a required one and the
list element in the corresponding position is assigned to the variable. If
there aren't enough elements to assign one to this target, then no assignment
is made to this variable, leaving it with whatever its previous value was.
<DT><CODE>?<VAR>variable</VAR> = <VAR>default-expr</VAR></CODE>
<DD>
This is also an optional target, but if there aren't enough list elements
available to assign one to this target, the result of evaluating
<VAR>default-expr</VAR> is assigned to it instead. Thus, <VAR>default-expr</VAR>
provides a <STRONG>default value</STRONG> for the variable. The default value expressions
are evaluated and assigned working from left to right <EM>after</EM> all of the
other assignments have been performed.
<DT><CODE>@<VAR>variable</VAR></CODE>
<DD>
By analogy with the <CODE>@</CODE> syntax in list construction, this variable is
assigned a list of all of the `leftover' list elements in this part of the list
after all of the other targets have been filled in. It is assigned the empty
list if there aren't any elements left over. This is called a <STRONG>rest</STRONG>
target, since it gets the rest of the elements. There may be at most one rest
target in each scattering assignment expression.
</DL>
<P>
If there aren't enough list elements to fill all of the required targets, or if
there are more than enough to fill all of the required and optional targets but
there isn't a rest target to take the leftover ones, then <CODE>E_ARGS</CODE> is
raised.
</P>
<P>
Here are some examples of how this works. Assume first that the verb
<CODE>me:foo()</CODE> contains the following code:
</P>
<PRE>
b = c = e = 17;
{a, ?b, ?c = 8, @d, ?e = 9, f} = args;
return {a, b, c, d, e, f};
</PRE>
<P>
Then the following calls return the given values:
</P>
<PRE>
me:foo(1) error--> E_ARGS
me:foo(1, 2) => {1, 17, 8, {}, 9, 2}
me:foo(1, 2, 3) => {1, 2, 8, {}, 9, 3}
me:foo(1, 2, 3, 4) => {1, 2, 3, {}, 9, 4}
me:foo(1, 2, 3, 4, 5) => {1, 2, 3, {}, 4, 5}
me:foo(1, 2, 3, 4, 5, 6) => {1, 2, 3, {4}, 5, 6}
me:foo(1, 2, 3, 4, 5, 6, 7) => {1, 2, 3, {4, 5}, 6, 7}
me:foo(1, 2, 3, 4, 5, 6, 7, 8) => {1, 2, 3, {4, 5, 6}, 7, 8}
</PRE>
<P>
Using scattering assignment, the example at the begining of this section could
be rewritten more simply, reliably, and readably:
</P>
<PRE>
{first, second, ?third = 0} = args;
</PRE>
<P>
It is good MOO programming style to use a scattering assignment at the top of
nearly every verb, since it shows so clearly just what kinds of arguments the
verb expects.
</P>
<P><HR><P>
Go to the <A HREF="ProgrammersManual_1.html">first</A>, <A HREF="ProgrammersManual_22.html">previous</A>, <A HREF="ProgrammersManual_24.html">next</A>, <A HREF="ProgrammersManual_77.html">last</A> section, <A HREF="ProgrammersManual_toc.html">table of contents</A>.
</BODY>
</HTML>