dark-sleep-lambdamoo-programming-tutorial-non-html5.html

<H1>LambaMOO Programming Tutorial (very rough draft)</H1>
<P><EM>by Steven J. Owens (unless otherwise attributed)</EM></P>
<!-- There are 422 paragraphs -->
<P>MOO, of which LambaMOO is the first and biggest, is an interactive,
multiplayer online game that includes the ability for players to build
and even program new things or features into the game.  The language
lacks a formal name but is generally referred to as "moo code" or
sometimes "moocode".

</P>

<P>While there is a fair amount of information about LambdaMOO
programming in various places, there is also a lack of a comprehensive
explanation, especially of much of the programming environment.  These
incomplete notes are the start of an attempt to remedy that.  This is
just a beginning, but maybe someday it'll be an end.

</P>

<P>There are a bunch of other resources out there, starting with the LambdaMOO
Programmer's Manual:

</P>

<P><A HREF="http://www.moo-cows.com/docs/manuals/ProgrammersManual.html">http://www.moo-cows.com/docs/manuals/ProgrammersManual.html</A>

</P>

<P>Also there are a variety of tutorials.  I'm not trying to duplicate or
replace them.  Instead, this is a combination of filling in the gaps
about the MOO programming environment and jumpstarting you into MOO
programming.

</P>

<H3>Outline of Current Draft</H3>
  <UL>
       <LI>Basic Terminology
       <LI>Verb Invocation and Property Access
       <LI>Data Types
       <LI>Lists
       <LI>Eval
       <LI>Comments
       <LI>Variable Declaration and Scoping
       <LI>Perms and Args
       <LI>Flow Control, for, if, while, suspend, fork
       <LI>Type Conversion
       <LI>Threading, Ticks and Tasks
       <LI>Core Classes
       <LI>Sight and Sound in MOOCode
       <LI>Location in MOOCode
  </UL><P><B>Note:</B><EM> See end for draft outline of planned revision</EM>

</P>

<H2>Basic Terminology</H2><P>I'm going to assume you have a basic familiarity with programming
concepts, but don't get too stressed out if you don't, you'll be able
to pick that up as you go along.  If you're totally, completely
new at this, I explain some general concepts at the end of this page,
in a section titled:

</P>

<A HREF="#RealBasics">Real Basics of Programming in Moocode"</A><P>I'm going to assume you have a basic familiarity with moo concepts,
but just to be clear:

</P>

<H3>The Server and the Db</H3><P>You have the server and the database (colloquially "the db").  The server
is the foundation; it loads and runs the database, which defines the
objects and their properties and verbs.  Much of the code that makes
the up the basic moo-ishness of things is implemented in the db, in
moocode.

</P>

<P><B>Note:</B><EM> Most people tend to associate the term "database" with a
"relational database", and most relational database programs tend to
keep most of their data in disk storage.  The purely technical meaning
of "database" is "an organized collection of information."
LambdaMOO's database is not relational, it is an object database, and
it is kept entirely in-memory.  The only reason I'm pointing this out
is to head off any chance of you confusing the moo database for a
relational database.</EM>

</P>

<H4>Objects, Verbs and Properties</H4><P>MOO consists of objects.  

</P>

<P>MOO objects have properties and verbs.

</P>

<P>Properties are values stored on the object and referenced in code via
the "." syntax, for example:

</P>

<PRE>somevariable = object.propertyname ;</PRE><P>Verbs are code stored on the object and invoked in code via the ":"
syntax, for example:

</P>

<PRE>somevariable = object:verbname() ;</PRE><H4>Object Oriented</H4><P>MOO stands for "Mud, Object-Oriented".  If you don't understand what
"object oriented" means, it's an approach for organizing the code and
data in a system.  

</P>

<P>MOO's object-oriented approach is slightly different from many
object-oriented programming langauges.  In most object-oriented
languages, you have a division between object definition (its
blueprint, so to speak) and instances of the object in the system. 
The object definitions (called classes) exist off in some abstract
place, but your code in the system never deals with them directly.
Instead you create "instances" of a given class and use the instance.

</P>

<P>In the MOO world, the object is defined by example.  You create an
object instance in the system and then dynamically (aka "on the fly")
add verbs and properties to make your prototype.  Then you can create
a new object that is "descended" from the first object.  The new
object in turn can be dynamically modified with more verbs and
properties, and then you can create more objects that descend from the
second object.

</P>

<P>If object-oriented programming is new to you, here's a brief
explanation:

</P>

<P>The simplest approach is procedural - a sequential series of
instructions.  Procedural languages have concepts for organizing the
code, like subroutines (also called functions or methods, depending on
what programming language you're talking about).

</P>

<P>Object-oriented languages usually have their own version of
subroutines (typically they're called methods, or in MOOcode, verbs),
but they also have the concept of organizing groups of subroutines
(methods, verbs) as well as data (instance variables, or properties).
This conceptual grouping is what we call an "object".

</P>

<H4>Core Db, MinimalCore and LambdaCore</H4><P>The "core db" is the infrastructure that most moos start from, the
initial set of objects, verbs and properties that provide handy
utilities and predefined types of objects.  These are all that exists
when the MOO is first started up, until the users start adding custom
code.  For example, player objects, room objects, exit objects and
thing objects are all part of the moo core db.

</P>

<P>There are, generally speaking, two different versions of the core db
in use.  The minimal db and the lambdacore.  The minimaldb is just
about exactly what the name suggests, just the bare bones minimum of
objects to get your MOO up and running.  The lambdacore has a whole
bunch of additional objects and features that the lambdamoo wizards
found useful.

</P>

<H4>Built-in Functions, Utils and the System Object</H4><P>The moo language has a number of predefined functions, which are
generally referred to as functions or sometimes as "built-in
functions" or "built-ins" for short.

</P>

<P>Most built-ins are documented in MOO's online help Sometimes there's
more than one help entry that matches a built-in function name, so as
a rule of thumb append an empty parentheses to the functionname() when
you use the help command.  For example "help tonum()" will get you
help on the built-in function named tonum (see "Data Types", below).

</P>

<P>In addition to the built-ins, there are a large number of handy little
utility verbs.  Since verbs have to be defined on objects, these
utility verbs are organized on several objects, one object per
category of verbs.  They are generally referred to as "the utils" or
sometimes "the $utils", because the individual grouping objects tend
to be kept track of in properties on the #0 object, and you can refer
to these properties by using $propertyname, like $string&lowbar;utils, or
$list&lowbar;utils.

</P>

<P>Speaking of object #0, object #0 is The System Object.  This is used
as a central place to stick values that the wizards want to keep track
of on a moo wide basis, in properties on #0.  You can reference these
properties with #0.propertyname, but there's a shortcut, as I used
above, the dollar sign, $, so you can reference the properties in your
code by simply using $propertyname.

</P>

<P>Anytime you see $ in a moo verb, mentally translate it to "#0.", i.e.:

</P>

<PRE>$string&lowbar;utils:english&lowbar;ordinal</PRE><P>is really

</P>

<PRE>#0.string&lowbar;utils:english&lowbar;ordinal</PRE><P>There are a great many such useful properties on #0 besides the utils,
but here are the utils defined on LambdaMOO's #0 as of this writing:

</P>

    <LI> #0.building&lowbar;utils
    <LI> #0.byte&lowbar;quota&lowbar;utils
    <LI> #0.code&lowbar;utils
    <LI> #0.command&lowbar;utils
    <LI> #0.convert&lowbar;utils
    <LI> #0.gender&lowbar;utils
    <LI> #0.generic&lowbar;utils
    <LI> #0.list&lowbar;utils
    <LI> #0.lock&lowbar;utils
    <LI> #0.match&lowbar;utils
    <LI> #0.math&lowbar;utils
    <LI> #0.matrix&lowbar;utils
    <LI> #0.object&lowbar;quota&lowbar;utils
    <LI> #0.object&lowbar;utils
    <LI> #0.perm&lowbar;utils
    <LI> #0.quota&lowbar;utils
    <LI> #0.seq&lowbar;utils
    <LI> #0.set&lowbar;utils
    <LI> #0.string&lowbar;utils
    <LI> #0.time&lowbar;utils
    <LI> #0.trig&lowbar;utils
    <LI> #0.wiz&lowbar;utils


<P>There are also several verbs defined directly on #0, but most of them
are system related and are not particularly relevant to your average
moo coder.

</P>

<H4>The Root Class, Nothing and $nothing</H4><P>Object #1 is The Root Class.  All objects are descended from Object #1.

</P>

<P>Object #-1 is "nothing"	, the null object, the object that does not
exist.  Things that are not located anywhere in particular have their
location property set to #-1.  Verbs or functions that do not come up
with a valid result typically return the value #-1.

</P>

<P>There's actually a root property, $nothing, that contains the value
#-1, but I'm pretty sure that $nothing does not define #-1, it merely
points to it and gives you a more expressive way to use the value #-1.
I.e. instead of putting the characters #-1 in your code, you put
$nothing and anyone reading the code (including you, a few months or
years later!) finds it easier to understand what your intent was.

</P>

<H3>Verb Invocation and Property Access</H3><P>In code you invoke verbs with the ":" operator.

</P>

<PRE>foo = object:methodname() ;</PRE><P>In code you reference properties to get the values in them with the "."  operator.

</P>

<PRE>foo = object.propertyname ;</PRE><P>You can generally chain properties for verb or property reference,
assuming that each link in the chain is a valid object reference,
e.g.:

</P>

<PRE>title = player.foo.bar:title();</PRE>
<PRE>name = player.foo.bar.name ;</PRE><P>Here's a more realistic example of that:

</P>

<PRE>roomtitle = player.location.title();</PRE>
<PRE>name = player.location.name ;</PRE><H3>Case Insensitivity</H3><P>Moo, unlike unix, linux, etc, doesn't care whether letters are upper
case or lower case.  This seems to be generally true for variable
names, object names, verb names, etc.  I guess Pavel (or Ghond before
him) just didn't want to deal with an endless number of users getting
their capitalization mixed up and screaming "This is broken!".

</P>

<PRE>>;;foo=5; me:tell(Foo)
5
=> 0
[used 154 ticks, 0 seconds.]
>;;foo=5; me:tell(FOO)
5
=> 0
[used 154 ticks, 0 seconds.]
>;;foo=5; me:tell(fOO)
5
=> 0
[used 154 ticks, 0 seconds.]
></PRE><H3>Data Types</H3><P>MOO has four data types: 

</P>

    <LI> numbers (integers and floats)
    <LI> strings (i.e. text)
    <LI> lists of elements
    <LI> moo object numbers (sometimes called objnums).


<P>Numbers default to integers.  Integers is a math term commonly used in
programming languages, it means no fractions or decimal places.  If
you divide 1/2 in MOO, you get 0.  Surprisingly, you get get a heck of
a lot done with just integers.

</P>

<P>Originally MOO only did integers, but these days MOO also does floats,
aka floating point numbers, i.e. numbers with a decimal point.  That's
how MOO knows that a number is a float, by the presence of a decimal
point:

</P>

<PRE>somefloat = 5.0 ;
someotherfloat = 5.0/2.0;
otherotherfloat = somefloat/someotherfloat ;
</PRE><P>In the example above, "someotherfloat" will contain the value "2.5"
and "otherotherfloat" will contain the value "2.0".

</P>

<P>You can't mix integers and floats, so in MOOcode you need
to either include the decimal point in all the numbers in a statement
or use the "tofloat()" built-in function to convert the value in a
variable into a float (see "Type Conversion", below).  Otherwise you
get a type mismatch error:

</P>

<PRE>;1/2.0
#-1:Input to EVAL, line 3:  Type mismatch
... called from built-in function eval()
... called from #217:eval_cmd_string (this == #1449), line 19
... called from #217:eval*-d (this == #1449), line 13
(End of traceback)</PRE><P>You can use two periods to indicate a range of values, i.e. 1..10
means 1, 2, 3, 4, 5, 6, 7, 8, 9 and 10.  The two periods are called
the "range operator" and this mostly comes up in lists (although
can also use it in other places, like foreach loops) so I'll talk
about it more down in the section titled "Lists".

</P>

<P>Strings is just programmerspeak for "text", i.e. "a string of
characters".  The term dates all the way back to 1959 and the really
early computer languages.  Moo knows something is text because it's
surrounded by double-quotes:

</P>

<PRE>astringvariable = "some text"</PRE><P>Lists are really fancy and get their own section (below).

</P>

<P>Object numbers are references to objects in the MOO database.  Moo
recognizes object numbers because they're preceded by a pound
sign #, also called a hash sign and officially named the octothorpe :-).

</P>

<PRE>puffsobjectnumber = #1449</PRE><H3>Lists</H3><P>You define a list by enclosing a comma-separated series of
elements in curly braces 

</P>

<PRE>foo = {"a", "b", "c"} ;</PRE>
<PRE>bar = {1, 2, 3} ;</PRE>
<PRE>baz = {1, "two", 3} ;</PRE><P>You reference a specific element in a list by appending a number in
[square brackets] to the variable name.  The number is called an
index, and accessing a list element this way is called indexing:

</P>

<PRE>xyzzy = foo[2] ;</PRE><P>The index of the very first item in the list is 1, as you would expect
if you're a normal human being:

</P>

<PRE>foo = {"a", "b", "c"} ;
player:tell("The element at index 1 is: ", foo[1])</PRE><P>The player sees:  

</P>

<PRE>The element at index 1 is: a</PRE><P>If you're a programmer rather than a normal human being, you expect
the index of the very first element to be 0, for technical reasons
which I will skip for now.  Getting used to this is usually a major
early stumbling block for non-programmers, which is probably why moo's
inventors (Pavel and Ghond) decided to go with 1 instead.  But if
you're already a programmer, you're going to expect it to be zero,
which is why I'm pointing this out.

</P>

<P>Note that lists can contain any sort of data, including other lists:

</P>

<PRE>foo = {"a", b", c", {1, 2, 3} } ;</PRE><P>Nested lists can get quite complicated.  One particularly common form
of nested lists is called associative lists, or alists for short, and
the $list_utils have a number of special verbs for dealing wtih
alists.  Other languages usually use what's called a dictionary type
(often "dict" for short) or "hashtable" or "map" to serve the same
purpose.

</P>

<P><B>Note:</B><EM> hashtable as a name describes how it's implemented; map as a
name describes the act of using one value to look up another value.
I'm explaining this mainly because the terms sometimes come up in
programming discussions, so it's useful to be familiar with them.</EM>

</P>

<PRE>somealist = {{1, "January"}, {2, "February"}, {3, "March"}}</PRE><P>Note that the above isn't really a good example of an alist, since you
could just make a list of month names and use the position (index) of
each month name instead of needing use the associative list utility
functions to look them up.  Here's a more realistic example, where
you're storing players high scores in some in-moo game, using their
object numbers as the key:

</P>

<PRE>somealist = {{#1449, 65050}, {#68, 743634}, {#107439, 34544}, {#93202, 235423}, {#94285, 10025}}</PRE><P>Most of the examples above are lists with elements that are all the
same data type, but lists can contain mixed data types:

</P>

<PRE>{"foo", 1, "bar", 1.5, #-1}</PRE><P>Sometimes you'll have a list of mixed data types like above, but of
course the order of the data types is something your code has to keep
track of.  For example, you might have a message system where each
list contains the time received as an integer, the person the message
was from as an objectnumber, and the message text as a string.  And
then you'd store all of your {time, personnumber, messagetext} lists
in another big list.

</P>

<P>The trick with lists is not the syntax, it's the way lists are
used in day-to-day MOO coding.  For example, if you do this, you end up having a list that contains two lists:

</P>

<PRE>
foo = {1, 2, 3}  ;
bar = {4, 5} ;
baz = {foo, bar} ;
</PRE><P>baz will now contain {{1, 2, 3}, {4, 5}} 

</P>

<P>You expand a list with the at sign @:

</P>

<PRE>
foo = {1, 2, 3}  ;
bar = {4, 5} ;
baz = {@foo, @bar} ;
</PRE><P>baz will now contain {1, 2, 3, 4, 5} 

</P>

<P>While you only use { and } when you're creating a list, and @ when you
expand a list, the "moo way" is that you do a whole lot of list
creation and expansion.  For example the "right" way to append to a
list is:

</P>

<PRE>baz = {1, 2, 3, 4, 5};
baz = {@baz, 6} ;</PRE><P>baz will now contain {1, 2, 3, 4, 5, 6}

</P>

<P>What you are literally doing here is creating a new list that contains
both the contents of the old list, baz, and the new value, 6, and then
storing the reference to that new list in the variable name that baz,
which previously used to store the reference to the old list.  In a more
longer form, it might look like this:

</P>

<PRE>baz = {1, 2, 3, 4, 5};
bat = {@baz, 6} ;
baz = bat</PRE><P>bat will now contain {1, 2, 3, 4, 5, 6} and 

</P>

<P>baz will now contain {1, 2, 3, 4, 5 ,6}

</P>

<P>But of course, that's longer and using the extra variable name "bat"
doesn't serve much purpose; usually in cases like this you'll never
use the bat variable again.  

</P>

<P>Using the shorter version may seem a little less clear at first, but
you end up doing this sort of thing so often that you quickly get used
to it, and it's worth shortening it that way because it makes the code
less cluttered and that makes it easier to read.

</P>

<P><B>Note:</B><EM> Sometimes it may make the code more clear if you be more
explicit, as in the longer version.  Sometimes making it shorter makes
that bit a little less clear but makes it easier to understand the
rest of the code.  That's a judgement call that you'll learn to make
as you get better at programming.  In fact a great majority of
programming is making that kind of judgement call.</EM>

</P>

<P>You can use the range operator (..) in a list index to indicate a
range of elements.  So for example if you wanted to get the second,
third and fourth element of a list, you'd index mixedlist[2..4].

</P>

<PRE>foo = {"a", "b", "c", "d", "e", "f"}  ;
bar = foo[2..4] ;</PRE><P>bar will now contain {"b", "c", "d"}.

</P>

<P>MOO list indexes and ranges can't do the things that fancier languages
can, they have to be just a single number [4] or two numbers separated
by two periods [2..4].  You have to do any fancy math yourself.  For
example, if you want to get from element 3 to the end of the list, you
have to use the built-in function length() to get the length of the
list:

</P>

<PRE>foo = {"a", "b", "c", "d", "e", "f"}  ;
bar = foo[2..length(foo)] ;</PRE><P>You'll also want to take a close look at the $list<EM>utils functions ("help $list</EM>utils").

</P>

<H3>Eval</H3><P>Eval is a really, really handy command that basically allows you to write little one-line MOOCode programs and execute them.  It works just the same as say or emote, e.g. 

</P>

<P>Enter: "foo&lt;enter&gt;<BR>
See: You say, "Foo"

</P>

<P>Enter: :grins toothily&lt;enter&gt;<BR>
See:   Puff grins toothily.

</P>

<P>Enter: ;1+1&lt;enter&gt;<BR>
See:   =&gt;2

</P>

<P>One minor but important distinction is that only you see the results
of your eval.

</P>

<P>Eval is handy for exploring and experimenting, and also really useful
for setting and looking at property values on your own objects, and
directly invoking verbs.

</P>

<P>One of the first property values you should set with eval is your
player.eval&lowbar;env property. This may already be set for you; to check,
just type the following:

</P>

<PRE>;player.eval&lowbar;env&lt;enter&gt;</PRE><P>You should see:

</P>

<PRE>=> "here=player.location;me=player;"</PRE><P>If it's not set, type the following:

</P>

<PRE>;player.eval&lowbar;env="here=player.location;me=player;"&lt;enter&gt;</PRE><P>Once you execute this command, you'll be able to use the eval
shortcuts "me" for your player object, and "here" for your player
object's current location.  This turns out to be incredibly handy.

</P>

<P>There's also a nifty little property, player.eval&lowbar;ticks.  See the
section below "Threads, Ticks and Tasks" for more on that.

</P>

<P>I never really got in the habit of using multi-statement
evals. Generally I find when I hit that point that it's simpler/easier
to just create a real verb to mess with.  "Help eval" will explain how
it works, but here's the basics:

</P>

<P>You start a multi-line eval with a double-semicolon, i.e.:

</P>

<PRE>;;foo = {1, 2, 3}; bar = {4, 5};  for x in ({@foo, @bar}) me:tell(x) ; endfor&lt;enter&gt;
</PRE><P>Also note that multi-line evals don't automatically print the return
value of the statement, so you need to explicitly print whatever you
want to see in the body of your eval statement by calling me:tell().  The built-in function
toliteral() is helpful for this, you can just call:me:tell(toliteral(whatevervariable)):

</P>

<PRE>>;;foo = {"a", "b", "c", "d", "e", "f"}  ; bar = foo[2..length(foo)] ; me:tell(toliteral(bar)) ;
{"b", "c", "d", "e", "f"}
=> 0
[used 161 ticks, 0 seconds.]
</PRE><H2>Basic MOOCode Gotchas</H2><H3>Comments</H3><P>Effectively, MOOCode doesn't have comments.  MOO actually has
comments, but nobody uses them and nobody, AFAIK, ever has.  I can't
even remember what the comment character is - // maybe?

</P>

<P>The problem is, early MOO was designed with the idea that the users
would store/maintain their own source code, and thus the compiler
discarded comments, didn't bother to save them in the compiled verb
bytecodes.  When users used the in-server editing tools, which decompiled
the code for the user to edit it, presto, the comments were gone.
(This compiling/decompiling also led to the happy accident that code
indenting/formatting is defacto specified by the decompiler.)

</P>

<P>As a result of this, the custom of using string literals for comments
arose.  E.g.:

</P>

<PRE>"this is a string literal" ;</PRE><P>This is so ingrained that by default the help command "help
objectname:verbname" will give the user any string-literal comments at
the top of of the verb source.

</P>

<P>So, current usage is to use string-literals, as follows:

</P>

<PRE>
"this is a MOOCode faux comment." ;
</PRE><P>Of course, note that you need a semi-colon to terminate the line, and
of course any embedded quotes must be escaped with a backslash, i.e.:

</P>

<PRE>
"this is a MOOCode faux comment with some \"embedded quotes\" in it." ;
</PRE><H2>Variable Declaration and Scoping</H2><P>In the MOO world you have objects, which have verbs and properties.
A verb is a method, function, subroutine, whatever.  It's invoked on
an object using the ":", like so:

</P>

<PRE>
object:verb(argument) 
</PRE><P>Objects, and data stored in properties on objects are the only
persistent things in the moo world.  

</P>

<P>Within a verb, variables are dynamically declared, and exist only
within the scope of the verb.  If you call out to another verb and
include parameters in that call, the value is passed, not the original
variable (i.e. all verb arguments are pass-by-value).  The second
verb can modify the parameter value all it wants, but the original
variable, in the first verb, will remain unchanged.

</P>

<P>Note that although a verb call can pass an object, it's really passing
an object reference by value.  The second verb can't do anything to
that object reference to change the object reference in the first
verb.  But the second verb <EM>can</EM> use that reference to access verbs
and properties on the object, thus changing the persistent object.

</P>

<H3>A Short Digression on Dynamically Typed Variables</H3><P>Moo code is dynamically typed.  This means that you don't have to go
through a lot of bureacracy to set up a variable, you can just throw a
variable assignment in anywhere and presto!  It's a variable.

</P>

<PRE>
foo = 3 ;
</PRE><P>This is a lot more convenient (and fun) but it also gives you a lot
more rope to hang yourself.  You can be in the middle of a verb and
accidentally typo for variable name as "foop" instead of "foot" (don't
ask me how you typoed a "p" instead of a "t", maybe you have a weird
keyboard layout) and moo will happily create the new variable "foop"
and assign it, leading to all sorts of unexpected craziness.

</P>

<P>Fortunately, hanging yourself isn't all that dangerous in the MOO
world, so you'll usually get a chance to spot the problem and fix it.

</P>

<P>However, unlike a lot of dynamically typed languages, moocode isn't as
friendly at letting you mix types.  In perl, for example, you could do:

</P>

<PRE>$message = "The number is " + $somenumvariable; </PRE><P>And perl will try to Do Something Useful and assume that you really
meant to convert $somenumbervariable into a string and concatenate
them.  However, in moocode, the compiler will complain because
somenumvariable is a number, not a string.  You have to use the
builtin function tostr() to convert it to a string:

</P>

<PRE>message = "The number is " + tostr(somenumvariable); </PRE><P>There are other towhatever() builtins, mainly tonum() which converts
to a numeric value and toobj() which converts to an object reference
number.  See "Type Conversion" below.

</P>

<H2>Perms and Args</H2><P>You can see the existing verbs on your object using the @display
command (I consider this command indispensable as an object browser).

</P>

<P>You can set the permissions using @chmod.

</P>

<P>You can set the parser arguments using @args.

</P>

<P>Now we get into how the args work.  This immediately gets into parsing
and matching, since that's the whole point of verb args.  These topics
deserve a section of their own, and I hope to find time to write it.
However, you can't really do any moocoding without some arg basics, so
here's a short primer meant to give you just sufficient info to get
started.

</P>

<P>In moo programming, "arguments" generally refers to the somewhat
Zork-like command-line parser, though "@args" refers to the verb
arguments.

</P>

<P>When somebody types an interactive moo command, like "look at
objectname", which ends up making your verb code run, any arguments
included in that interactice command (called the invocation) will be
stored in a list. That list will be automatically available to your
verb code, stored in a variable named "args". In your verb code,
usually one of the first things you do is use the @ sign (i.e. @args)
to expand that list.  So "@args" became moo coder shorthand for
referring to the parsed verb argument list.

</P>

<P><B>Note:</B><EM> args is what is called a "context variable".  There are some
other standard context variables, some of them are discussed in the
following paragraphs.</EM>

</P>

<P>Command-line arguments consist of three elements, (after the verbname) e.g.:

</P>

    <LI> verbname any in this
    <LI> verbname this to any
    <LI> verbname any in any
    <LI> verbname none none none
    <LI> verbname any any any


<P>And so forth.

</P>

<P>The "foo preposition bar" form gets automatically
parsed by the MOO's command-line parser; it finds the verb name and
argument structure that best matches, and invokes it.  

</P>

<P>"this" is a string that matches of the object the verb is defined on,
i.e. the object name or one of the object aliases (see note below on
aliases).

</P>

<P>"any" is any string. It might match an object in the same location
(room) or it might just be a string that the user arbitrarily chose.
Your verb code has to decide what to do with that.

</P>

<P><B>Note:</B><EM> Besides the object.name property, which just about every object
in the moo db has, most objects also have object.aliases, which
contains a list of alternative names for the object.  These are also
used by the arg parsing and object matching code.</EM>

</P>

<P>There are some rules for precedence - the parser will try to match to
player:verbname() before trying player.location:verbname(), and so
forth.

</P>

<H3>Context Variables</H3><P>As mentioned above, the "args" variable is automatically available
to any code inside a verb.  The args variable contains a list of
all of the arguments passed into the variable.  Since it's so often
immediately expanded with the @ sign, it's often referred to ind
discussion as "@args".

</P>

<P>The args variable is one example of a "context variable".  There are
several of these super handy context variables.  Besides the
parser-related ocntext variables I'll get into below, there are:

</P>

    <LI> "this", contains the object reference for the object that the verb is defined on.


    <LI> "player", contains the object reference for whichever player started the current chain of execution, usually by invoking a verb interactively, using the command line.


    <LI> "here" and "me" aren't actually context variables, but they're customarily defined in your player.eval&lowbar;env property for use with the eval command, both of which are discussed further below.


<P><B>Note:</B><EM> player doesn't <STRONG>always</STRONG> contain the invoking player's object
reference, there's a special built-in function named
set&lowbar;task&lowbar;perms() that will set it to the verb owner's
player object reference, or if the verb owner has wizard perms
(player.wizard=1), can be used to set it to an arbitrary player.  This
gets into tricky moo security topics, however.  If you're curious
about it, also see the built-in function callers().</EM>

</P>

<P>Somewhat related to the topic, there're also several standard error or
result code values that are available in verb code, much like the $
variable.  These are mainly related to the built-in function typeof(),
and are discussed a little in the section "Type Conversion" below.

</P>

<H3>Parser-related Context Variables</H3><P>When the parser invokes the verbs, it pre-populates several special
context variables that each verb starts with; argstr, dobjstr,
iobjstr, and several others.  Let's look at an example:

</P>

<P>You have an object named "box" with a "put" verb and the arguments
"any in this", which defined by using the @verb command:

</P>

<P>@verb box:put any in this

</P>

<P>You could also define it in two steps:

</P>

<P>@verb box:put
@args box:put any in this

</P>

<P>You type "put gold in box".

</P>

<P>The parser looks for a player:put command, doesn't find one

</P>

<P>The parser looks for a room:put command, doesn't fine one

</P>

<P>The parser looks for a "gold" with a put command and the appropriate args, doesn't find one.

</P>

<P>The parser looks for a "box" with a put command and the appropriate args, and gets a match.

</P>

<P>The parser invokes box:put().

</P>

<P>The code inside the verb box:put can assume that there will be a
dobjstr (direct object string) variable containing the string "gold"
and an iobjstr (indirect object sring) variable containing the string
"box".

</P>

<P>The parser will also try to match the dobjstr (direct object string)
and iobjstr (indirect object string) and set the dobj variable and
iobj variable for the verb to any matched objects.

</P>

<P>Note that verbs with args of "none none none" aren't meant to have
parameters at all.  

</P>

<P>Args of "any any any" is for verbs that expect to do some sort of
custom parsing on their own.

</P>

<H4>this none this and @chmod +x</H4><P>There's also a special set of arguments, "this none this" for verbs
meant to be invoked only by other verbs:

</P>

<P>Generally speaking, if your verb doesn't have its args set to "this
none this", you won't be able to invoke it from another verb.

</P>

<P>In addition, such not-to-be-directly-invoked verbs must be @chmodded
to +x, to allow them to be invoked.  If they're not +x, the moo will
report a rather confusing "verb not found" error.

</P>

<P>@chmod +x box:put<EM>helper</EM>verb 

</P>

<P>The reason for this is that not-to-be-directly-invoked verbs are
expected (in well-designed code) to do the heavy lifting, the
important and tricky stuff, and Pavel (or possibly Ghond) wanted to
avoid having lots of half-done code be invocable by anybody.

</P>

<H3>Flow Control: if, for, while, suspend, fork</H3><P>A simple list of instructions, one after the other, is technically a
program, but you probably want some more sophisticated options than
just a straight one-after-the-other list of instructions.  You want
things like being able to check something and execute one set of
instructions or the other (if/endif), or being able to repeat an
instruction some number of times (for/endfor) .

</P>

<P>The built-in functions suspend() and fork() aren't really technically
flow control operators, but they play a similar role, so I'm going to
talk about them here.

</P>

<P>Some general rules of thumb:

</P>

    <LI> Every flow control structure starts with a keyword  (if, for, while).
    <LI> Every flow control structure ends with a matching keyword that starts with "end" (endif, endfor, endwhile).
    <LI> The lines between the start and end are called a "block" of code.
    <LI> The block is customarily indented 4 characters.  That's only for readability purposes, but the moo compiler/decompiler automatically does it that way.
    <LI> The line that starts the flow control structure usually contains an expression.


<P>Let's jump right in and show some examples of if, while, for, suspend
and fork.  I'll get into them in more detail after.

</P>

<P>Use "if" for conditionals - test some condition, and either carry out
the set of commands in the block or not.  

</P>

<PRE><HR>if (some expression that evaluates to 0 for false or not-0 for true)
  "do something" ;
endif</PRE><P>You can also use if/else for when you want have a set of instructions
for when the if test results in not-true.

</P>

<PRE><HR>if (some expression that evaluates to 0 or not-0)
  "it was not-zero, do something" ;
else
  "it was zero, do something else" ;
endif</PRE><P>The while and for flow controls are for looping, i.e. doing something one or more times:

</P>

<PRE><HR>while (some expression that evaluates to 0 or not-0)
  "do something repetitive";
endwhile</PRE><PRE><HR>for foo in (some expression that produces a list)
  "do something with foo" ;
endfor</PRE><P>The built-in function suspend() is for pausing.

</P>

<PRE><HR>suspend(some number of seconds you want the task to pause) ;</PRE><P>The built-in function fork() is for starting a new, separate task that
continues on and does its own thing.

</P>

<PRE><HR>fork (somenumber of seconds) 
  "do something somenumber of seconds later, in a separate task" ;
endfork
"immediately after scheduling the fork, continue on with the rest of the program" ;
</PRE><P>Sometimes that separate task can run for a long, long time, in which case it might
be handy to have the taskid:

</P>

<PRE>fork taskidvariable (somenumber of seconds) 
  "do something somenumber of seconds later, in a separate task" ;
endfork
"immediately after scheduling the fork, continue on with the rest of the program" ;</PRE><P>The taskidvariable is optional.  If it's there, it gets filled with the taskid for the task that the fork creates.  Typically the next thing you do is store the taskidvariable's contents in some property, so you can later on use it to check on, or if necessary kill, the task.

</P>

<h4>tests</h4><P>The if and while flow control structures have a "test".  In general,
this test an expression that evaluates to 0 for false or not-0 for
true.  Not-0 includes negative values and strings and object numbers.
Basically, it includes anything but the number 0.

</P>

<PRE>if (0)
  player:tell("This line never gets executed") ;
endif
if (1)
  player:tell("This line always gets executed.") ;
endif
if (player.iftest)
  player:tell("This line only gets executed if player.iftest contains a non-zero value.") ;
endif
while (1 == player.iftest)
  player:tell("This line keeps getting executed until somebody sets player.iftest to something besides 1.") ;
endwhile
</PRE><P>The test expression is often a comparison, using the double-equal-sign
comparison operator (x == y).  It returns 1 for true if the two
arguments are equal, otherwise returns 0 for false.  There's also !=
for not-equal, which returns 1 for true if they are not equal,
otherwise returns 0 for false.

</P>

<PRE>
if (1 == player.iftest)
  player:tell("This line only gets executed if player.iftest contains the value 1.") ;
endif
</PRE><P>The test expression can also invoke a verb:

</P>

<PRE>
if (player:iftestverbname())
  player:tell("This line only gets executed if the verb  player:iftestverbname() returns a non-zero value.") ;
endif
</PRE><h4>for loop</h4><P>For loops in moocode are kinda neat; "for x in (y)" is nice and
readable.  Hey, Java added something similar (foreach) in 2014, it
only took them an extra 17 years (ooh that makes me feel all
smalltalkerly/LISPerly inside).  The y part of "for x in (y)" can be
anything that returns a list, including:

</P>

<P>A list slice reference...

</P>

<PRE>
>;;for x in (me.owned&lowbar;objects[1..10]) me:tell(x) ; endfor
#1449
#1560
#1565
#1570
#1573
#1574
#1575
#1578
#1579
#1708
=> 0
[used 4001 ticks, 0 seconds.]</PRE><P>Or even just a range...

</P>

<PRE>
>;for x in [1..10] me:tell(x) ; endfor
1
2
3
4
5
6
7
8
9
10
=> 0
[used 3776 ticks, 0 seconds.]
</PRE><B>suspend</B><P>Suspend is pretty straight-forward; it just pauses the execution for
however many seconds.

</P>

<PRE>>;;suspend(20) ; me:tell("boo!") ;
...20 seconds pass...
boo!
=> 0</PRE><B>fork</B><P>Fork takes a little more discussion.  Fork fires off a separate task.
In this example I used all of the optional arguments.  The somenumber
of seconds part delays the new task from starting until some number of
seconds in the future.  Meanwhile, the rest of the verb continues on
without delay.  

</P>

<P>You're allowed to set the delay at 0 if you just want to fire off the
new task immediately.  This is useful when you want to do some things
that require time (perhaps a scripted set of comments by a robot) but
meanwhile you want the rest of the verb to proceed as usual.

</P>

<P>The body of the fork is what gets executed by the new task (I usually
just put a one-line callout to some other verb in there and put all
the gory stuff in the separate verb).

</P>

<P>The taskidvariable part lets you define a new variable to hold the
taskid of the new task.  Of course, you have to do something with the
taskid that gets put in that variable, like store it on an object
property so you can kill it later with @kill, when it's sucking down
all of your ticks like a great tick-sucking vortex of doom.

</P>

<P>(But, if you messed up and forgot to save the taskid, check out the @forked command).

</P>

<P>Here are some examples of if/for/while/forked in action. Note that I'm
demonstrating all of them via eval, so each example is all in one
line.  In normal code you'd have each bit on a separate line.  for
example, the first if/else/endif example would be five lines in a
normal verb (if, the body of the if, else, the body of the else,
endif).

</P>

<PRE>
&gt;;;if(1) player:tell("foo") ; else player:tell("bar") ; endif
foo
=&gt; 0
&gt;
&gt;;;if(0) player:tell("foo") ; else player:tell("bar") ; endif
bar
=&gt; 0
&gt;
&gt;;;if(-1) player:tell("foo") ; else player:tell("bar") ; endif
foo
=&gt; 0
&gt;
&gt;;; i = 3 ; while(i) me:tell("i is ", i) ; i = i -1 ; endwhile
i is 3
i is 2
i is 1
=&gt; 0
&gt;
&gt;;;fork taskidvar (2) me:tell("later.") ; endfork
=&gt; 0
(two seconds pass)
later.
&gt;
</PRE><H3>Type Conversion</H3><P>Moocode isn't friendly enough to auto-convert between types for you,
most of the time. You have objects references, ints, strings, floats.
Since it's MOO, by definition a lot of the time you're going to be
dealing wtih other people's data.  

</P>

<P>Use the typeof() function to see what type a particular parameter is.

</P>

<P>Use the toliteral() function to convert it to a string you can print
out (especially useful for looking at hairy lists-of-lists).

</P>

<P>Use the various tofoo() functions to convert back and forth:

</P>

    <LI> toobj() (converts a string like "#1449" into an objectnumber reference variable)
    <LI> toint() or tonum() (converts "1" to the value 1;  originally ints were the only numerics in moo)
    <LI> tostr() (converts the numeric value 1 to "1" or an objectnumber variable #1449 to "#1449")
    <LI> tofloat() (converts the string "1.1" to the float value 1.1 or the int value 1 to the float value 1.0)


    <LI> toliteral() (converts whatever value to a print-friendly value)
    <LI> typeof() (returns an int value corresponding to the type of the value you passed in)


<P>Note that typeof returns an int value, but there are several standard
values that are defined in moocode.  INT is 0, OBJ is 1, STR is 2, ERR
is 3, etc. See "help typeof" for more info. You could just check to
see if the return value is 0 or 1, etc, but it's a lot smarter to use
those predefined variables.  That way, when you look at a bunch of
code you wrote in a drunken binge, you'll have some vague idea wtf you
were intending to do.

</P>

<H2>MOOCode In The Large</H2><H3>Threading, Ticks and Tasks</H3><P>Like just about all computers, MOO doesn't really do many things at
once, it just fakes it.  Unlike other systems, MOO uses a rather
distinctive approach to faking it.  It's not <EM>really</EM> multitasking,
but it fakes it rather well, especially for a multi-user, multi-coder
system.

</P>

<P>At any given point in time, the MOO server is running only one verb
invocation.  This is called a task.  What happens if that task gets
out of hand?  What if some idiot codes a verb to calculate pi to the
final decimal place?

</P>

<P>To keep this from causing problems, MOOcode has some internal
cost-accounting.  Each task is given a certain number of "clock ticks"
at the start; last I looked I think it was 40,000 ticks.  Each
operation inside the task costs some number of ticks, arbitrarily
decided by the original developers of MOO, based on how expensive they
thought that operation would be.  If the task uses up all of the
ticks, the verb invocation dies with an error about being out of
ticks.

</P>

<P>Ticks get renewed over time, so verbs that have to do a whole lot of
stuff will periodically use suspend() to pause for some period of time and let
their ticks recharge. $command&lowbar;utils:suspend&lowbar;if&lowbar;needed(10) 
is often used for this, to only suspend() if the verb is in danger of
running out of ticks.  Of course, suspend&lowbar;if&lowbar;needed() burns up ticks
in itself, so it's wise to always give it an argument of at least 5,
more like 10 seconds for the pause.

</P>

<P>There's also a player-wide tick allocation, so if a particular player
has lots of verbs that have heavy tick usage, the performance impact
will fall more on that player, and less on the rest of the MOO.
(Hands up if you wrote ridiculously expensive 3D line of sight
elimination code that caused the wizards to priotirize completing
player-wide tick allocations in the moo server... anyone?  Buehler?).

</P>

<P>If you want to learn more about just what costs how many ticks, do:

</P>

<PRE>;me.eval&lowbar;env=1</PRE><P>And now the examples I gave you in the Flow Control section will
produce output like:

</P>

<PRE>
>;if(1) player:tell("foo") ; else player:tell("bar") ; endif
foo
=&gt; 0
[used 377 ticks, 0 seconds.]
>;if(0) player:tell("foo") ; else player:tell("bar") ; endif
bar
=&gt; 0
[used 382 ticks, 0 seconds.]
>;if(-1) player:tell("foo") ; else player:tell("bar") ; endif
foo
=&gt; 0
[used 377 ticks, 0 seconds.]
</PRE><P>Note that there are a lot of odd variables that go into actual tick
costs, so they will tend to vary a little from invocation to
invocation.  Don't get hung up on that facet.

</P>

<H2>Core Classes</H2><P>The real trick to moocoding is, just as with Java, learning the APIs.
With MOOCode, learning how the core infrastructure objects hook into
each other (and hence how you can code an object and drop it into this
system of interacting objects) is critical.

</P>

<P>The @classes command displays a list of the "important" classes for
one of about five or six subsets that the wizards have decided are
worth keeping track of.  One of the most important is the Generics,
and the key generics are:

</P>

<UL>
  <LI>$player
  <LI>$room
  <LI>$exit
  <LI>$thing
</UL><P>You should probably also study up on object #1, The Root Class, to see
what verbs you can expect to see on all objects, since The Root Class
is the grandaddy object from whom all objects are descended.

</P>

<P>While these classes aren't the only important classes, they account
for the fundamental MOO experience.  The vast majority of
player-created objects in the MOO database are descendants of $player, $room, $exit or $thing.

</P>

<H3>Overview</H3><P>There are help entries for $room ("help $room") and $exit ("help
$exit") but not for $player and $thing.  Here's a quick overview of
all four.

</P>

<P>Okay, so players are roughly self-explanatory, but the real essence of
a player is that player objects have incoming telnet connections
attached to them, and will feed incoming text to the MOO parser, and
feed output text back into the outgoing telnet.  

</P>

<P>Outgoing text usually reaches the player object via player:tell() and
usually is passed to the outgoing telnet connection when player:tell()
calls player:notify().  Generally speaking most code isn't supposed to
call player:notify() directly.

</P>

<P>In addition, players are generally descendants of various classes that
provide useful basic commands like say, emote, etc, and for other MOO
features that players care about, like the in-MOO mail system, @who,
some old features like setting line length and linewrapping (mostly
irrelevant now due to decent MUD client programs) and so forth.

</P>

<P>Rooms are locations; like any MOO object they have a contents property
containing a list of objects they contain, but they also have lots of
verbs oriented towards players who are contained in them.  Players
and rooms both work closely with the MOO parser to create the whole
MOO experience, both in terms of making the verbs work and in terms of
creating the sense of space and place.

</P>

<P>$room:look() is the verb that the parser invokes if you simply type "look" with no arguments.  

</P>

<P>$room:look() calls room:look&lowbar;self() to return text describing the room.  

</P>

<P>$room:look&lowbar;self() calls room:description() and
$room:tell&lowbar;contents() and sends the results to player:tell().

</P>

<P>$room:description() defaults to just returning the text in the property room.description

</P>

<P>$room:tell&lowbar;contents() defaults to just listing the objects in
the property room.contents, but they can and do often work
differently.

</P>

<P>There are some room generics, for example, that dynamically compose
the description from objects that are in the room that are designed to
work with such rooms, and then the room leaves any such objects out of
the room:tell&lowbar;contents() output.

</P>

<P>Rooms also have two properties, $room.entrances and $room.exits.  Both
properties contain a list of $exit objects. An entrance is just an
exit from some other room that has this room as a destination.  When
you enter a command, if the MOO parser can't find a verb whose name
and arguments match the command, it then tries to match an exit. If it
does, it calls the exit's :invoke() verb, which then moves you from
that room to the destination room.

</P>

<P>Finally we have $thing, which provides the basic features you expect
to find in well, a thing; something that is neither intrinsically a
part of the room, nor an autonomous entity like a player, nor an
abstraction for movement like an exit.  You can pick up a $thing using
its get verb. You can drop a thing using its drop verb, and so forth.
Things are kind of obvious and kind of minimal, but you have to start
somewhere.  A lot of stuff in LambdaMOO is ultimately a descendant of
$thing.

</P>

<H2>Detailed Examples</H2><P>The two examples that come to mind are also probably the two most
common cases as well as fundamental to that sense of there-ness that
makes MOO work, which are:  sight/sound and location.

</P>

<H2>Sight and Sound in MOOCode</H2><P>Sight/sound is pretty straight-forward.  I lump them together because
really, they're just lines of text that are being sent to the player's
network connection.  

</P>

<P>Everything has a :tell() verb, starting with #1:tell(), which just
does nothing.  This makes it very convenient to code verbs that emit
text and just send it to all objects in the room.

</P>

<P>The player object has a special verb, player:notify(), that sends a
line of text to the player's network connection.  player:notify() is
so special that nobody actually invokes it directly; it's almost only
ever used by player:tell() (and occasionally by player:tell&lowbar;lines(),
see note below).  In fact, player:notify() has a special permission
check in its code to prevent it from being called from anything else
but verbs on the player.

</P>

<P>player:tell(), at its simplest, relays lines to player:notify().  More
complicated versions of :tell() do checking for unwanted messages or
attempts to "spoof" the player.

</P>

<P>(Note: spoofing is when you send text to a player with the intent to
deceive, usually by having the text not identify its source or
pretending to be output that resulted from a player command; it's
generally considered rude on its own, and when done for malicious
purposes extremely rude and/or socially objectionable).

</P>

<P><B>Note:</B><EM> player:tell&lowbar;lines() works much like player:tell() except it can
take a list of strings as an argument; it, in turn, calls
player:notify&lowbar;lines(), which loops through the list and calls
player:notify() with each individual line.</EM>

</P>

<P>Okay, so now we know what happens to a line of text after it gets to
the player.  This is the mechanism that everything in the MOO uses to
send text to your player object's network connection.  When you look
at the room, for example, the room's verbs in turn call player:tell()
to feed you descriptions, a list of what's in the room, etc.  This is
a fairly common practice and is considered normal.

</P>

<H2>Location in MOOCode</H2><P>Location in MOO is based on two special object properties:
"object.location" and "object.contents". All objects in MOO have these
two properties built into them.  Every object always has a location
value (always a single object number), and every object has a contents
value (always a list, possibly empty). The server itself inherently
keeps track of these, so every object can only have one location at a
time, and will only (and can only) be in a single other
object.contents list.

</P>

<P>The built-in function, "move()" updates three different object
properties in one atomic step, so they can never get out of sync:

</P>

<UL>
<LI>object.location
<LI>source.contents
<LI>destination.contents
</UL><P>However, you shouldn't be messing with move(), instead you'll use
object:moveto(#destination).

</P>

<P>When you move an object, the object's :moveto() verb may have some
special checks coded in it to prevent you moving it.  Most players
don't like being moved around by random people.  See "help locking";
also, a lot of older players use a player class that has a "sessile"
property that, when set to 1, keeps anything from moving them.  These
days players mostly just use the (relatively) more recently @refuse
command ("@refuse moves") to protect themselves from idiots.

</P>

<P>For the most part, objects are moved into/out of rooms, and into/out
of players (the stuff you're "carrying").  There are also generic
container objects - things that you can put stuff into and get stuff
out of.  And, when all else fails, you can probably expect to find
your missing object off in #-1, which appears to be where the server
sticks anything when it can't figure out where to put it.

</P>

<P>For the most part what happens when you move something is that the
following verbs are called in something vaguely like this order:

</P>

    <LI> call objecttobemoved:moveto(destinationobject)
    <LI> objecttobemoved:moveto() calls destination:accept(objecttobemoved)
    <LI> destinationobject:accept(objectobemoved) calls through to destination:acceptable(objecttobemoved) to figure out if an object actually is acceptable, then returns the value
    <LI> destinationobject:enterfunc(objecttobemoved) gives the destination an opportunity to react to the arrival of the object after it has entered the destination (though normally special effects are taken care of by the exits or by the verb that's calling object:moveto()).
    <LI> sourceobject:exitfunc(objecttobemoved) gives the source an opportunity to do/say something after the object has left the source.


<P>When you are in a room and you issue the "look" command, the parser
finds $room:look(), which in turn calls $room:look&lowbar;self().
look&lowbar;self() is the generic verb for an object to assemble what a
player sees when the object is looked at.  As is often the case in
moocode, the look&lowbar;self verb doesn't just return a description, it in
turn calls player:tell().

</P>

<P>What follows is pretty much the same process for most objects:

</P>

    <LI> player types "look<enter>"
    <LI> parser matches player.location:look_self()
    <LI> room:look&lowbar;self() is called.
    <LI> room:look&lowbar;self() calls room:title()
    <LI> room:look&lowbar;self() calls room:description()
    <LI> room:look&lowbar;self() calls room:tell&lowbar;contents()
    <LI> the above verbs call player:tell()


<P>As it turns out, room:description() is not part of $room:look&lowbar;self().
I'm not sure where that get added to look&lowbar;self() (though the
:description() verb is defined on the Root Class, #1).

</P>

<H3>The End of the MooCode Stuff</H3><P>That's all for now.  The sections below are two things.  

</P>

<P>At the very end is an outline for my next draft of this tutorial.
Really, this draft was just a brain dump of a lot of different topics
that I thought were underexplored by the current docs, back when I
wrote this.  The brain dump is a bit jumbled and some things get
talked about multiple times, etc.  The outline is for a more
organized attack on the whole topic.

</P>

<P>In between the outline and here is a section adapted from an article I
originally wrote about Java, that tries to help an absolute beginner
and gets into things like "what's a statement" and "what is syntax",
etc.

</P>

<a NAME="RealBasics"><H3>Real Basics of Programming in Moocode</H3></A><P>These details get skipped a lot.  If you've played a little bit
with some programming language, like BASIC, you may want to skip this,
but unless you're confident, I suggest you at least skim it.  Even if
you are confident, I get into some programming in-jokes and stuff,
further on, that might help ease the shock of getting into the
programming world.</P><P>If you're confident, go back to the top of the article.<P><B>Note:</B> <I>The following is focused on really basic stuff, but
it still assumes the context is the moo programming language.  For
example, when I give a bit of code as example I'm not going to stop
and point out the details that are particular to moocode and maybe don't
work the same way in some other programming language.  Sorry, but
there's too much to explain here already :-).</I></P><H4>A Program</H4><P>A program is a huge, complex list of step-by-step instructions that
the computer carries out.  These instructions are written in a
particular combination of words and punctuation.</P><H4>A Short Example</H4><P>Okay, so let's give you a short example of what a bit of program
might look like:</PRE><CODE>
<PRE>
player:tell("Hello.") ;
somenumber = 2 ;
anothernumber = 3 ; 
theothernumber ;
theothernumber = somenumber + anothernumber;
message = "the other number is " + tostr(theothernumber) ;
player:tell(message) ;
theothernumber = theothernumber + 1 ;
message2  = "the other number is now " + tostr(theothernumber) ;
player:tell(message2) ;
</PRE>
</CODE><P>This sort of human-readable stuff that makes up the program is
usually called the <EM>source code</EM>, not an important detail but
if you're curious as to why <A HREF="#CompiledInterpreted">read
this</A>.</P><P>If you open up the source code for a program in an editor, you see
a bunch of words, punctuation and <EM>whitespace</EM> (whitespace is
spaces, tabs, or carriage returns/newlines, basically any character 
in the source that doesn't produce a visible letter, number or punctuation,
but instead just changes the location of other characters).</P><P><I>By the way "editor" is the programmer term for a word processor.
Generally editors (classics like emacs, or vi, or programs like
(shudder) Notepad on windows) are much more focused on function and
less on form.  Editors are about moving words around, word processors
are about making them print out pretty.  And if you're wondering why
programmers have a special term for word processor programs, it's the
other way around - what do you think was used to write the source code
for the first word processor programs?</I></P><P><I>While we're at it, in the modern era a lot of programmers don't
use just plain old editors anymore, they use IDEs. IDE stands for
Integrated Development Environment and is a GUI programming editor
with a bunch of other extra tools and features.  Some programmers
swear by them, some swear at them.  MOO doesn't have any IDEs.</I></P><P>The first step the computer takes in converting the human-readable
words to computer instructions is breaking them down into
<EM>tokens</EM>, chunking them up according to certain rules.  For
starts, whitespace separates the words, and a change from letters to
punctuation usually separates the words.</P><P>Almost nobody in the programming world talks about tokens, unless
they're messing around with learning how programming langauges are
built. It's really just a fancier word for "chunks", and the main
reason I'm bringing it up is because it lets me say that when you get
right down to it, the "instructions" are a series of tokens; and now I
get to explain the different kinds of tokens without having to waffle
about keywords versus punctuation and various silly crap like that.
They're all just tokens.<A NAME="Identifiers:  Keywords, Variables, Literals"><H4>Identifiers:  Keywords, Variables, Literals</H4></A><P>Strings of letters like "somenumber", are <EM>identifiers</EM>.</P><P>An identifier is either:<UL>
<LI>a <EM>keyword</EM> (a predefined
word that is an instruction to the computer)
<LI>a name for a <EM>variable</EM> (a holder for some data)
<LI>a <EM>literal</EM> value
</UL><P>In the example, <CODE>player</CODE> is a keyword, while
<CODE>somenumber</CODE>,
<CODE>anothernumber</CODE>, and
<CODE>theothernumber</CODE> are variable names.</P><P><B>Variable</B> names account for most of the identifiers in any large
given program, since there're a limited number of keywords.  On the
other hand, those keywords get repeated a lot in any program.</P><P><B>Keywords</B> in moocode are often called <I>built-ins</I>, as in, "this
feature is built into the moo server", as opposed to the various <I>$util
libraries</I> that are written in moocode in the db but available to all
users.</P><P>In other languages keywords are sometimes called "reserved words"
(meaning that you can't use them for a variable name, because they're
reserved to mean something special).  Every now and then you even run
into a reserved word that doesn't actually do anything, the people who
designed that programming language just thought it would be a good
idea to keep that keyword reserved for some reason.</P><P>There are also rules for what you can put in a variable name, but
for now just use normal words (nouns mostly), avoid using a keyword,
and avoid doing anything fancy with punctuation or numbers, and you'll
be fine.</P><P>A <B>literal</B> means that instead of having a variable that
contains a value, you just literally have the value typed right there
in the code, like the number 343243, for example.</P><P>Programmer-speak for a bit of text is a <I>String</I>, as in "a
string of letters", or really "a string of characters", since text can
include number characters and punctuation characters, as well as
letter characters.  To put a literal String in a program, put quotes
around it, "like this".</P><H4>Punctuation</H4><P>Most punctuation in the code is one of two things, either 1)
operators or 2) start/end indicators for an expression, statement or
block.  See <A HREF="#Source Code">Fun With Punctuation</A> for a
little more detail.</P><A NAME="operators"><H5>Operators</H5></A><P>An <EM>operator</EM> is basically a bit of puncuation that
<STRONG>does something</STRONG>, like the plus character + adds to
values together, or the minus character - subtracts them.
</P><P>Most of the usual math symbols do what you'd expect them to, except
for the equals sign =, which is an important exception I'll get to in
just a second.</P><P>Another exception is that the plus sign "+" can be used to add two
strings of characters together, so <CODE>"foo" + "bar"</CODE>
works out to have the same value as <CODE>"foobar"</CODE>.  There's
not much use for <CODE>"foo" + "bar"</CODE> in programming, but
there's a lot of use for gluing together strings.</P><P>Note that in moocode you can only add strings to strings and
numbers to numbers.  If you want to concatenate a string to a number,
you have to use the built-in tostr() function, like this:<PRE><CODE>
message = "The number is:  " + tostr(somenumber) ;
</CODE></PRE><P>Many programming languages have increment "++" and decrement "--",
but moocode does not.  foo++ adds 1 to foo, foo-- subtracts one from
foo. A lot of languages use this to make it more succinct to loop
through a list, adding one at a time, but moocode doesn't need it as
much because it has "for x in y".</P><H5>The Equals Sign <CODE>=</CODE>, Assignment and Comparison</H5><P>The equals sign is used for <EM>assignment</EM>, meaning, storing a
value into a variable.  If you see:

</P>

<P><CODE>a = 5</CODE></P> <P>That means "store the value 5 in variable a."  When programmers
write this out, they usually say something like "let a equal five" or "a is
assigned the value five".</P><P>If you try to put a literal on the left side, like this:</P><P><CODE>5 = b</CODE></P><P>...the compiler yells at you.  This turns out to be a very good
thing, we'll talk about it in a moment.</P><P>You can also assign one variable to another, which means that the
value in the second variable gets copied to the first variable as
well:</P><P><CODE>a = b</CODE></P><P><B>Note</B>: A lot of programming languages require you to be very
formal about defining variables ahead of time, "initializing" them
(assigning the initial value), etc.  Moocode is all hippy and free
love, so you can pretty much create a new variable whenever you want,
simply by assigning a value to a variable name.  There's a downside to
this; if you try to assign a different value to an existing variable
but mistype the variable name, moo will happily create the new
variable and let things keep rolling on... and you'll have no idea WTF
happened when the wrong value causes problems somewhere entirely else
in your code.<H4>Equals Signs, Assignment and Comparison, or Stupid Programmer Mistakes</H4>    <P>Using a single equals sign for assignment is a very firmly
established tradition in programming.  This is sort of unfortunate,
because it leads to one of the most common, and most frustrating typos
in the programming world, which is "confusing assignment (=) with
comparison (==)".</P><P>Most people first learn about the equals sign for comparison, like
"is a equal to b?", and for finding out the value, like "two plus two
equals 4."  The motion sort of goes left-to-right, the same way you
read english.  In programming, when you see the equals sign, the
motion goes the other way, from right to left - the value on the right
gets stored in the variable on the left.</P><P>You use a double-equals sign <CODE>==</CODE> to do comparison.  You
write "is a equal to b?" like this:

</P>

<P><CODE>a == b</CODE></P><P>It is very, very easy, even for an experienced programmer, to slip
and write this instead:</P><P><CODE>a = b</CODE></P><P>When this does happen, it can lead to very weird behavior, which is
frustratingly hard to track down, and when you finally find it, you
feel really stupid.  Bear in mind, it's usually buried among pages
and pages of other code, so it's really easy to look at it and see
what you're expecting to see, not the error. </P><P>One really good rule of thumb that I picked up somewhere is
"literal on the left".  If you're doing a comparison with a literal
value, put the literal value on the left side.  For example:</P><P><CODE>5 == a</CODE></P><P>This is good because it forces you to think in a slightly different
way about it, and because the compiler will yell if you slip and write
<CODE>5 = a</CODE>.</P><A NAME="syntax"><H4>Syntax</H4></A><P>There are rules about how tokens can be used and how they can go
together.  These rules are called <EM>syntax</EM>.  As you start to
program, you'll be hearing about syntax a lot, mainly because a lot of
the more common mistakes beginners make are syntax errors, usually
finicky typos that are just damned hard to remember, until they become
ingrained by habit.  Don't get frustrated, it's not you; even
experienced programmers often (usually) make stupid typos in their
first draft of a piece of code.</P><A NAME="expressions"><H5>expressions</H5></A><P>An <EM>expression</EM> is the smallest piece of code that can be
treated like a value.  So a variable is an expression.  So is a
literal.  An operation, like <CODE>1 + 1</CODE> is an expression.  So
is <CODE>somenumber + anothernumber</CODE>.  I guess you could say, as
a rule of thumb, that anything that you could take out and replace
with a literal value, is an expression.</P><P>Another way to say that is, "anything that returns a value".
"Returns a value" is programmer-speak for "results in a value being
sent back".    There's a <CODE>return</CODE> keyword that does this
from a method (which is basically a grouping of code, also sometimes
called procedures, subroutines, or functions).  So a call to a method
that returns a value is also an expression.</P><H5>statements</H5><P>If an expression is a term, a <EM>statement</EM> is a phrase.
Since it's a phrase, not a sentence, you don't put a period at the end
of it, you put a semi-colon <CODE>;</CODE> at the end of it.</P><P>For example:  <CODE>int somenumber = 2 + 2 ;</CODE></P><A NAME="Source Code"><H4>Source Code and Fun With Punctuation</H4></A><P>Most punctuation is a single character, so there's nothing
complicated as to what separates different punctuation tokens.  There
are some two-character combinations and there are some matched sets.
The matched sets are usually used for organizing things, to start and
end sections:</P><P>Usually a left parenthesis "(" has to have a right parenthesis ")"
somewhere.  Mostly parentheses are used for verb calls and any verb
call parameters are put between the parentheses,
e.g. player:tell("hello").</P><P>The characters "{" and "}", most programmers call curly brackets
but appear to have a dozen or more possibly-correct names, depending
on who you ask.  Some programming languages use curly brackets to
define the start and stop of a program block, for example the contents
of a while loop.  Moocode uses "end-whatever" to indicate the end of a
block, for example if/endif, while/endwhile, for/endfor, and so forth.</P><P>What MOO actually uses curly brackets for is defining lists of
things.  A list is pretty much just what it says, a sequential
collection of elements.  If you're familiar with arrays, think of a
list as a smart array, that grows and shrinks as necessary.  Here's an
example:</P><PRE><CODE>stringslist = {"one", "two", "three"};</CODE></PRE><P>Here's another example: </P><PRE><CODE>numberslist = {1, 2, 3};</CODE></PRE><P>A list can contain mixed types of elements, for example: </P><PRE><CODE>mixedlist = {1, "two", 3};</CODE></PRE><P>Most languages use square brackets "[" and "]" to <I>index</I> into
an array or list, for example if you one the "two" from the mixedlist
example, you'd use:</P><PRE><CODE>twostring = mixedlist[2];</CODE></PRE><P>One exception to all this left-right nonsense is the angle brackets, "&lt;" and "&gt;".  
Moocode, like most languages, only uses angle brackets for mathematical
stuff, like greater-than or less-than, etc.</P><P>Qouble-quotes like " usually have to be in a matched set.  Pretty
much no programming language uses "smart quotes", where the quotes are
angled opposite each other.  When programmers specifically want to say
not-smart-quotes they usually say "straight quotes".</P><P>Some programming languages have special meanings for the
single-quote ' and back-tick ` characters.  Moocode did not at first,
but have since used them for catching errors, see the section "Catching
Errors in Expressions" in the LambdaMOO Programmer's Tutorial.</P><A NAME="Multitasking"><H4>Multitasking</H4></A><P>When you get right down to it, computers can only do one thing at a
time.  They can just do them so fast it looks like they're doing
several things at once.  This is called "multitasking." Juggling is a
popular metaphor for this, but I prefer the chess master metaphor.
</P><P>The computer acts sort of like a brilliant chess player who can
play against twenty ordinary people at once - make a move on this
chess board, move to the next chess board and make a move, move to the
next chess board, etc.  It may look like the chess player is doing
twenty things at once, but really he's just walking up to a chess
board, studying the context - the layout of the chess pieces - in a
glance and deciding on the right move.</P><P>Moo uses a system called tasks and ticks to manage this.  This is
discussed in more detail up above.</P><A NAME="CompiledInterpreted"><H4>Source Code:  Compiled and Interpreted Programs</H4></A><P>The human-readable version of the program is called the <EM>source
code</EM>.  Why this is, you don't really need to know, nor do you
really need to know what compiled or interpreted mean.  But if
you're interested, read on.</P><P>The computer itself only understands numbers.  Everything
that you see a computer do that looks like it deals with words, is in
the end boiled down to numbers.  The program is too - the
human-readable version is <STRONG>purely</STRONG> for your
convenience.  And believe me, it is one heck of a convenience.</P><P>Something has to convert that human-readable stuff to machine code
(pure 1s and 0s).  This is called a compiler, or sometimes an
interpreter.  A compiler converts just once.  The result is a set of
1s and 0s that the machine runs.  An interpreter converts on the fly;
it's a program that runs your program, interpreting your words and
issuing the right 1s-and-0s version of the commands as necessary.</P><P>But in real life, nothing is that simple.</P><P>First of all, there's a lot of give and take in terms of whether a
particular program is a compiler, per se, or an interpreter.  Many
"interpreters" actually compile the program right when you run the
program.  Some compilers (like the moo compiler, and also the java
compiler) compile the program halfway, to a generic format called
bytecode, and then it's run on a <EM>virtual machine</EM> (like the
moo server, or the Java Virtual Machine, JVM for short), which is
basically another take on the interpreter, a program that runs a
program.</P><P>Second of all, there is seldom a one-for-one word-to-code
translation.  Most often, a short set of words converts into dozens or
more machine codes.  On top of that, many compilers and interpreters
then rearrange commands to make it all run faster, while still doing
exactly what you said to do.</P><H4>RTFM, "Use The Source, Luke", and "ask smart questions"</H4><P>As you learn and ask people for help, you'll hear two
phrases very often, RTFM (Read The Fucking Manual) and "Use the
Source, Luke" (sometimes abbreviated UTSL).  A growing trend is the
third phrase, <A
HREF="http://www.catb.org/~esr/faqs/smart-questions.html">"learn how
to ask smart questions"</A>, after an essay written by Eric S. Raymond
about how to do just that.</P><P>All of these boil down to "do your own homework before you ask me
for help."  Like reading this page.  All of us have been there before,
and it sucks, we'll spend tons of energy to <STRONG>help</STRONG> you
figure out how to do it yourself, but we're not going to do it
<STRONG>for</STRONG> you.</P><A NAME="Foo, Bar, Baz:   Metasyntactic Variables and Stupid Programmer Jokes"><H4>Foo, Bar, Baz:   Metasyntactic Variables and Stupid Programmer Jokes</H4></A><P>A lot of programmers use the words <EM>foo</EM>, <EM>bar</EM>, and
<EM>baz</EM> a lot in examples.  This is so common that there's
actually now a jargon phrase for it, the metasyntactic variables.</P><P>The reason these show up so often is that often you need to explain
something, and you need to explain it with an example, and the example
has to refer to some things, purely for the purpose of the example.
So programmers use "foo" and "bar" (from the military slang FUBAR, for
"Fucked Up Beyond All Recognition).  The third variable "baz", is just
a corruption of "bar", because you often need a third example
variable.</P><P>Why not use real words?  Three reasons:</P><UL>
<LI>Because you may not want to distract yourself from the main
problem long enough to think of a good, plausible example.
<LI>Because you want your reader/listener to be concentrating on HOW
you're doing whatever, not on WHAT you're doing it to.
<LI>Because "foobar" is a stupid programmer joke of long-standing tradition.
</UL><H4>The End</H4><P>That's the end of our little "the really real realest basics of programming"
section, so you can go back to the top and read the regular tutorial.</P><H3>Outline of Planned Revision</H3>   <UL>
     <LI>Basic MOOCode Gotchas
        <UL>
          <LI>Comments<BR>
          <LI>Variable Declaration and Scoping
          <LI>Lists
          <LI>Flow Control: for, if, while, suspend, fork
          <LI>Types, typeof(), toobj(), toint() or tonum(), tostr(), toliteral(), tofloat()
       </UL>
    <LI>MOOCode In The Large
      <UL>
        <LI>Object References (Object Numbers)
        <LI>Implicit Environment References:  this, player, caller, callers()
        <LI>Verb Invocation, Property Access 
        <LI>Perms and Args
        <LI>Help
        <LI>Parameter Passing
        <LI>Threading, Ticks and Tasks
      </UL>
    <LI>The MOOCoder's Toolbox
      <UL>
        <LI>@display, @args, @chmod
        <LI>Eval ;
        <LI>Eval Environment:  ;player.eval&lowbar;env="here=player.location;me=player;"
        <LI>Multi-Line Evals ;;
      </UL>
    <LI>The Framework
      <UL>
        <LI>Parsing
        <LI>Matching
        <LI>Feature Objects 
        <LI>Core Classes
          <UL>
            <LI>$room
            <LI>$player
            <LI>$exit
            <LI>$thing
            <LI>$features
            <LI>$utils
            <LI>#0
            <LI>#-1
         </UL>
      </UL>
    <LI>Some "interesting" functions and properties
      <UL>
        <LI>max&lowbar;object()
        <LI>$playerdb
        <LI>player.owned&lowbar;objects
      </UL>
    </UL>
  </UL>
</UL>