This is Info file ProgrammersManual.txt, produced by Makeinfo-1.64 from the input file ProgrammersManual.tex-no-info. ************************************* *** LambdaMOO Programmer's Manual *** ************************************* For LambdaMOO Version 1.8.0p6 March 1997 by Pavel Curtis aka Haakon aka Lambda Copyright (C) 1991, 1992, 1993, 1995, 1996 by Pavel Curtis. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author. Introduction ************ LambdaMOO is a network-accessible, multi-user, programmable, interactive system well-suited to the construction of text-based adventure games, conferencing systems, and other collaborative software. Its most common use, however, is as a multi-participant, low-bandwidth virtual reality, and it is with this focus in mind that I describe it here. Participants (usually referred to as "players") connect to LambdaMOO using Telnet or some other, more specialized, "client" program. Upon connection, they are usually presented with a "welcome message" explaining how to either create a new "character" or connect to an existing one. Characters are the embodiment of players in the virtual reality that is LambdaMOO. Having connected to a character, players then give one-line commands that are parsed and interpreted by LambdaMOO as appropriate. Such commands may cause changes in the virtual reality, such as the location of a character, or may simply report on the current state of that reality, such as the appearance of some object. The job of interpreting those commands is shared between the two major components in the LambdaMOO system: the "server" and the "database". The server is a program, written in a standard programming language, that manages the network connections, maintains queues of commands and other tasks to be executed, controls all access to the database, and executes other programs written in the MOO programming language. The database contains representations of all the objects in the virtual reality, including the MOO programs that the server executes to give those objects their specific behaviors. Almost every command is parsed by the server into a call on a MOO procedure, or "verb", that actually does the work. Thus, programming in the MOO language is a central part of making non-trivial extensions to the database and thus, the virtual reality. In the next chapter, I describe the structure and contents of a LambdaMOO database. The following chapter gives a complete description of how the server performs its primary duty: parsing the commands typed by players. Next, I describe the complete syntax and semantics of the MOO programming language. Finally, I describe all of the database conventions assumed by the server. *Note:* This manual describes only those aspects of LambdaMOO that are entirely independent of the contents of the database. It does not describe, for example, the commands or programming interfaces present in the LambdaCore database. The LambdaMOO Database ********************** In this chapter, I begin by describing in detail the various kinds of data that can appear in a LambdaMOO database and that, therefore, MOO programs can manipulate. In a few places, I refer to the "LambdaCore" database. This is one particular LambdaMOO database, created every so often by extracting the "core" of the current database for the original LambdaMOO. *Note*: The original LambdaMOO resides on the host `lambda.parc.xerox.com' (the numeric address for which is `192.216.54.2'), on port 8888. Feel free to drop by! A copy of the most recent release of the LambdaCore database can be obtained by anonymous FTP from host `ftp.parc.xerox.com' in the directory `pub/MOO'. MOO Value Types =============== There are only a few kinds of values that MOO programs can manipulate: * integers (in a specific, large range) * real numbers (represented with floating-point numbers) * strings (of characters) * objects (in the virtual reality) * errors (arising during program execution) * lists (of all of the above, including lists) MOO supports the integers from -2^31 (that is, negative two to the power of 31) up to 2^31 - 1 (one less than two to the power of 31); that's from -2147483648 to 2147483647, enough for most purposes. In MOO programs, integers are written just as you see them here, an optional minus sign followed by a non-empty sequence of decimal digits. In particular, you may not put commas, periods, or spaces in the middle of large integers, as we sometimes do in English and other natural languages (e.g., `2,147,483,647'). Real numbers in MOO are represented as they are in almost all other programming languages, using so-called "floating-point" numbers. These have certain (large) limits on size and precision that make them useful for a wide range of applications. Floating-point numbers are written with an optional minus sign followed by a non-empty sequence of digits punctuated at some point with a decimal point (`.') and/or followed by a scientific-notation marker (the letter `E' or `e' followed by an optional sign and one or more digits). Here are some examples of floating-point numbers: 325.0 325. 3.25e2 0.325E3 325.E1 .0325e+4 32500e-2 All of these examples mean the same number. The third of these, as an example of scientific notation, should be read "3.25 times 10 to the power of 2". *Fine points:* The MOO represents floating-point numbers using the local meaning of the C-language `double' type, which is almost always equivalent to IEEE 754 double precision floating point. If so, then the smallest positive floating-point number is no larger than `2.2250738585072014e-308' and the largest floating-point number is `1.7976931348623157e+308'. IEEE infinities and NaN values are not allowed in MOO. The error `E_FLOAT' is raised whenever an infinity would otherwise be computed; `E_INVARG' is raised whenever a NaN would otherwise arise. The value `0.0' is always returned on underflow. Character "strings" are arbitrarily-long sequences of normal, ASCII printing characters. When written as values in a program, strings are enclosed in double-quotes, like this: "This is a character string." To include a double-quote in the string, precede it with a backslash (`\'), like this: "His name was \"Leroy\", but nobody ever called him that." Finally, to include a backslash in a string, double it: "Some people use backslash ('\\') to mean set difference." MOO strings may not include special ASCII characters like carriage-return, line-feed, bell, etc. The only non-printing characters allowed are spaces and tabs. *Fine point:* There is a special kind of string used for representing the arbitrary bytes used in general, binary input and output. In a "binary string", any byte that isn't an ASCII printing character or the space character is represented as the three-character substring "~XX", where XX is the hexadecimal representation of the byte; the input character `~' is represented by the three-character substring "~7E". This special representation is used by the functions `encode_binary()' and `decode_binary()' and by the functions `notify()' and `read()' with network connections that are in binary mode. See the descriptions of the `set_connection_option()', `encode_binary()', and `decode_binary()' functions for more details. "Objects" are the backbone of the MOO database and, as such, deserve a great deal of discussion; the entire next section is devoted to them. For now, let it suffice to say that every object has a number, unique to that object. In programs, we write a reference to a particular object by putting a hash mark (`#') followed by the number, like this: #495 Object numbers are always integers. There are three special object numbers used for a variety of purposes: `#-1', `#-2', and `#-3', usually referred to in the LambdaCore database as `$nothing', `$ambiguous_match', and `$failed_match', respectively. "Errors" are, by far, the least frequently used values in MOO. In the normal case, when a program attempts an operation that is erroneous for some reason (for example, trying to add a number to a character string), the server stops running the program and prints out an error message. However, it is possible for a program to stipulate that such errors should not stop execution; instead, the server should just let the value of the operation be an error value. The program can then test for such a result and take some appropriate kind of recovery action. In programs, error values are written as words beginning with `E_'. The complete list of error values, along with their associated messages, is as follows: E_NONE No error E_TYPE Type mismatch E_DIV Division by zero E_PERM Permission denied E_PROPNF Property not found E_VERBNF Verb not found E_VARNF Variable not found E_INVIND Invalid indirection E_RECMOVE Recursive move E_MAXREC Too many verb calls E_RANGE Range error E_ARGS Incorrect number of arguments E_NACC Move refused by destination E_INVARG Invalid argument E_QUOTA Resource limit exceeded E_FLOAT Floating-point arithmetic error The final kind of value in MOO programs is "lists". A list is a sequence of arbitrary MOO values, possibly including other lists. In programs, lists are written in mathematical set notation with each of the elements written out in order, separated by commas, the whole enclosed in curly braces (`{' and `}'). For example, a list of the names of the days of the week is written like this: {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"} Note that it doesn't matter that we put a line-break in the middle of the list. This is true in general in MOO: anywhere that a space can go, a line-break can go, with the same meaning. The only exception is inside character strings, where line-breaks are not allowed. Objects in the MOO Database =========================== Objects are, in a sense, the whole point of the MOO programming language. They are used to represent objects in the virtual reality, like people, rooms, exits, and other concrete things. Because of this, MOO makes a bigger deal out of creating objects than it does for other kinds of value, like integers. Numbers always exist, in a sense; you have only to write them down in order to operate on them. With objects, it is different. The object with number `#958' does not exist just because you write down its number. An explicit operation, the `create()' function described later, is required to bring an object into existence. Symmetrically, once created, objects continue to exist until they are explicitly destroyed by the `recycle()' function (also described later). The identifying number associated with an object is unique to that object. It was assigned when the object was created and will never be reused, even if the object is destroyed. Thus, if we create an object and it is assigned the number `#1076', the next object to be created will be assigned `#1077', even if `#1076' is destroyed in the meantime. Every object is made up of three kinds of pieces that together define its behavior: "attributes", "properties", and "verbs". Fundamental Object Attributes ----------------------------- There are three fundamental "attributes" to every object: 1. A flag (either true or false) specifying whether or not the object represents a player, 2. The object that is its "parent", and 3. A list of the objects that are its "children"; that is, those objects for which this object is their parent. The act of creating a character sets the player attribute of an object and only a wizard (using the function `set_player_flag()') can change that setting. Only characters have the player bit set to 1. The parent/child hierarchy is used for classifying objects into general classes and then sharing behavior among all members of that class. For example, the LambdaCore database contains an object representing a sort of "generic" room. All other rooms are "descendants" (i.e., children or children's children, or ...) of that one. The generic room defines those pieces of behavior that are common to all rooms; other rooms specialize that behavior for their own purposes. The notion of classes and specialization is the very essence of what is meant by "object-oriented" programming. Only the functions `create()', `recycle()', `chparent()', and `renumber()' can change the parent and children attributes. Properties on Objects --------------------- A "property" is a named "slot" in an object that can hold an arbitrary MOO value. Every object has eight built-in properties whose values are constrained to be of particular types. In addition, an object can have any number of other properties, none of which have type constraints. The built-in properties are as follows: name a string, the usual name for this object owner an object, the player who controls access to it location an object, where the object is in virtual reality contents a list of objects, the inverse of `location' programmer a bit, does the object have programmer rights? wizard a bit, does the object have wizard rights? r a bit, is the object publicly readable? w a bit, is the object publicly writable? f a bit, is the object fertile? The `name' property is used to identify the object in various printed messages. It can only be set by a wizard or by the owner of the object. For player objects, the `name' property can only be set by a wizard; this allows the wizards, for example, to check that no two players have the same name. The `owner' identifies the object that has owner rights to this object, allowing them, for example, to change the `name' property. Only a wizard can change the value of this property. The `location' and `contents' properties describe a hierarchy of object containment in the virtual reality. Most objects are located "inside" some other object and that other object is the value of the `location' property. The `contents' property is a list of those objects for which this object is their location. In order to maintain the consistency of these properties, only the `move()' function is able to change them. The `wizard' and `programmer' bits are only applicable to characters, objects representing players. They control permission to use certain facilities in the server. They may only be set by a wizard. The `r' bit controls whether or not players other than the owner of this object can obtain a list of the properties or verbs in the object. Symmetrically, the `w' bit controls whether or not non-owners can add or delete properties and/or verbs on this object. The `r' and `w' bits can only be set by a wizard or by the owner of the object. The `f' bit specifies whether or not this object is "fertile", whether or not players other than the owner of this object can create new objects with this one as the parent. It also controls whether or not non-owners can use the `chparent()' built-in function to make this object the parent of an existing object. The `f' bit can only be set by a wizard or by the owner of the object. All of the built-in properties on any object can, by default, be read by any player. It is possible, however, to override this behavior from within the database, making any of these properties readable only by wizards. See the chapter on server assumptions about the database for details. As mentioned above, it is possible, and very useful, for objects to have other properties aside from the built-in ones. These can come from two sources. First, an object has a property corresponding to every property in its parent object. To use the jargon of object-oriented programming, this is a kind of "inheritance". If some object has a property named `foo', then so will all of its children and thus its children's children, and so on. Second, an object may have a new property defined only on itself and its descendants. For example, an object representing a rock might have properties indicating its weight, chemical composition, and/or pointiness, depending upon the uses to which the rock was to be put in the virtual reality. Every defined property (as opposed to those that are built-in) has an owner and a set of permissions for non-owners. The owner of the property can get and set the property's value and can change the non-owner permissions. Only a wizard can change the owner of a property. The initial owner of a property is the player who added it; this is usually, but not always, the player who owns the object to which the property was added. This is because properties can only be added by the object owner or a wizard, unless the object is publicly writable (i.e., its `w' property is 1), which is rare. Thus, the owner of an object may not necessarily be the owner of every (or even any) property on that object. The permissions on properties are drawn from this set: `r' (read), `w' (write), and `c' (change ownership in descendants). Read permission lets non-owners get the value of the property and, of course, write permission lets them set that value. The `c' permission bit is a little more complicated. Recall that every object has all of the properties that its parent does and perhaps some more. Ordinarily, when a child object inherits a property from its parent, the owner of the child becomes the owner of that property. This is because the `c' permission bit is "on" by default. If the `c' bit is not on, then the inherited property has the same owner in the child as it does in the parent. As an example of where this can be useful, the LambdaCore database ensures that every player has a `password' property containing the encrypted version of the player's connection password. For security reasons, we don't want other players to be able to see even the encrypted version of the password, so we turn off the `r' permission bit. To ensure that the password is only set in a consistent way (i.e., to the encrypted version of a player's password), we don't want to let anyone but a wizard change the property. Thus, in the parent object for all players, we made a wizard the owner of the password property and set the permissions to the empty string, `""'. That is, non-owners cannot read or write the property and, because the `c' bit is not set, the wizard who owns the property on the parent class also owns it on all of the descendants of that class. Another, perhaps more down-to-earth example arose when a character named Ford started building objects he called "radios" and another character, yduJ, wanted to own one. Ford kindly made the generic radio object fertile, allowing yduJ to create a child object of it, her own radio. Radios had a property called `channel' that identified something corresponding to the frequency to which the radio was tuned. Ford had written nice programs on radios (verbs, discussed below) for turning the channel selector on the front of the radio, which would make a corresponding change in the value of the `channel' property. However, whenever anyone tried to turn the channel selector on yduJ's radio, they got a permissions error. The problem concerned the ownership of the `channel' property. As I explain later, programs run with the permissions of their author. So, in this case, Ford's nice verb for setting the channel ran with his permissions. But, since the `channel' property in the generic radio had the `c' permission bit set, the `channel' property on yduJ's radio was owned by her. Ford didn't have permission to change it! The fix was simple. Ford changed the permissions on the `channel' property of the generic radio to be just `r', without the `c' bit, and yduJ made a new radio. This time, when yduJ's radio inherited the `channel' property, yduJ did not inherit ownership of it; Ford remained the owner. Now the radio worked properly, because Ford's verb had permission to change the channel. Verbs on Objects ---------------- The final kind of piece making up an object is "verbs". A verb is a named MOO program that is associated with a particular object. Most verbs implement commands that a player might type; for example, in the LambdaCore database, there is a verb on all objects representing containers that implements commands of the form `put OBJECT in CONTAINER'. It is also possible for MOO programs to invoke the verbs defined on objects. Some verbs, in fact, are designed to be used only from inside MOO code; they do not correspond to any particular player command at all. Thus, verbs in MOO are like the `procedures' or `methods' found in some other programming languages. As with properties, every verb has an owner and a set of permission bits. The owner of a verb can change its program, its permission bits, and its argument specifiers (discussed below). Only a wizard can change the owner of a verb. The owner of a verb also determines the permissions with which that verb runs; that is, the program in a verb can do whatever operations the owner of that verb is allowed to do and no others. Thus, for example, a verb owned by a wizard must be written very carefully, since wizards are allowed to do just about anything. The permission bits on verbs are drawn from this set: `r' (read), `w' (write), `x' (execute), and `d' (debug). Read permission lets non-owners see the program for a verb and, symmetrically, write permission lets them change that program. The other two bits are not, properly speaking, permission bits at all; they have a universal effect, covering both the owner and non-owners. The execute bit determines whether or not the verb can be invoked from within a MOO program (as opposed to from the command line, like the `put' verb on containers). If the `x' bit is not set, the verb cannot be called from inside a program. The `x' bit is usually set. The setting of the debug bit determines what happens when the verb's program does something erroneous, like subtracting a number from a character string. If the `d' bit is set, then the server "raises" an error value; such raised errors can be "caught" by certain other pieces of MOO code. If the error is not caught, however, the server aborts execution of the command and, by default, prints an error message on the terminal of the player whose command is being executed. (See the chapter on server assumptions about the database for details on how uncaught errors are handled.) If the `d' bit is not set, then no error is raised, no message is printed, and the command is not aborted; instead the error value is returned as the result of the erroneous operation. *Note:* the `d' bit exists only for historical reasons; it used to be the only way for MOO code to catch and handle errors. With the introduction of the `try'-`except' statement and the error-catching expression, the `d' bit is no longer useful. All new verbs should have the `d' bit set, using the newer facilities for error handling if desired. Over time, old verbs written assuming the `d' bit would not be set should be changed to use the new facilities instead. In addition to an owner and some permission bits, every verb has three `argument specifiers', one each for the direct object, the preposition, and the indirect object. The direct and indirect specifiers are each drawn from this set: `this', `any', or `none'. The preposition specifier is `none', `any', or one of the items in this list: with/using at/to in front of in/inside/into on top of/on/onto/upon out of/from inside/from over through under/underneath/beneath behind beside for/about is as off/off of The argument specifiers are used in the process of parsing commands, described in the next chapter. The Built-in Command Parser *************************** The MOO server is able to do a small amount of parsing on the commands that a player enters. In particular, it can break apart commands that follow one of the following forms: VERB VERB DIRECT-OBJECT VERB DIRECT-OBJECT PREPOSITION INDIRECT-OBJECT Real examples of these forms, meaningful in the LambdaCore database, are as follows: look take yellow bird put yellow bird in cuckoo clock Note that English articles (i.e., `the', `a', and `an') are not generally used in MOO commands; the parser does not know that they are not important parts of objects' names. To have any of this make real sense, it is important to understand precisely how the server decides what to do when a player types a command. First, the server checks whether or not the first non-blank character in the command is one of the following: " : ; If so, that character is replaced by the corresponding command below, followed by a space: say emote eval For example, the command "Hi, there. is treated exactly as if it were as follows: say Hi, there. The server next breaks up the command into words. In the simplest case, the command is broken into words at every run of space characters; for example, the command `foo bar baz' would be broken into the words `foo', `bar', and `baz'. To force the server to include spaces in a "word", all or part of a word can be enclosed in double-quotes. For example, the command foo "bar mumble" baz" "fr"otz" bl"o"rt is broken into the words `foo', `bar mumble', `baz frotz', and `blort'. Finally, to include a double-quote or a backslash in a word, they can be preceded by a backslash, just like in MOO strings. Having thus broken the string into words, the server next checks to see if the first word names any of the six "built-in" commands: `.program', `PREFIX', `OUTPUTPREFIX', `SUFFIX', `OUTPUTSUFFIX', or the connection's defined "flush" command, if any (`.flush' by default). The first one of these is only available to programmers, the next four are intended for use by client programs, and the last can vary from database to database or even connection to connection; all six are described in the final chapter of this document, "Server Commands and Database Assumptions". If the first word isn't one of the above, then we get to the usual case: a normal MOO command. The server next gives code in the database a chance to handle the command. If the verb `$do_command()' exists, it is called with the words of the command passed as its arguments and `argstr' set to the raw command typed by the user. If `$do_command()' does not exist, or if that verb-call completes normally (i.e., without suspending or aborting) and returns a false value, then the built-in command parser is invoked to handle the command as described below. Otherwise, it is assumed that the database code handled the command completely and no further action is taken by the server for that command. If the built-in command parser is invoked, the server tries to parse the command into a verb, direct object, preposition and indirect object. The first word is taken to be the verb. The server then tries to find one of the prepositional phrases listed at the end of the previous section, using the match that occurs earliest in the command. For example, in the very odd command `foo as bar to baz', the server would take `as' as the preposition, not `to'. If the server succeeds in finding a preposition, it considers the words between the verb and the preposition to be the direct object and those after the preposition to be the indirect object. In both cases, the sequence of words is turned into a string by putting one space between each pair of words. Thus, in the odd command from the previous paragraph, there are no words in the direct object (i.e., it is considered to be the empty string, `""') and the indirect object is `"bar to baz"'. If there was no preposition, then the direct object is taken to be all of the words after the verb and the indirect object is the empty string. The next step is to try to find MOO objects that are named by the direct and indirect object strings. First, if an object string is empty, then the corresponding object is the special object `#-1' (aka `$nothing' in LambdaCore). If an object string has the form of an object number (i.e., a hash mark (`#') followed by digits), and the object with that number exists, then that is the named object. If the object string is either `"me"' or `"here"', then the player object itself or its location is used, respectively. Otherwise, the server considers all of the objects whose location is either the player (i.e., the objects the player is "holding", so to speak) or the room the player is in (i.e., the objects in the same room as the player); it will try to match the object string against the various names for these objects. The matching done by the server uses the `aliases' property of each of the objects it considers. The value of this property should be a list of strings, the various alternatives for naming the object. If it is not a list, or the object does not have an `aliases' property, then the empty list is used. In any case, the value of the `name' property is added to the list for the purposes of matching. The server checks to see if the object string in the command is either exactly equal to or a prefix of any alias; if there are any exact matches, the prefix matches are ignored. If exactly one of the objects being considered has a matching alias, that object is used. If more than one has a match, then the special object `#-2' (aka `$ambiguous_match' in LambdaCore) is used. If there are no matches, then the special object `#-3' (aka `$failed_match' in LambdaCore) is used. So, now the server has identified a verb string, a preposition string, and direct- and indirect-object strings and objects. It then looks at each of the verbs defined on each of the following four objects, in order: 1. the player who typed the command, 2. the room the player is in, 3. the direct object, if any, and 4. the indirect object, if any. For each of these verbs in turn, it tests if all of the the following are true: * the verb string in the command matches one of the names for the verb, * the direct- and indirect-object values found by matching are allowed by the corresponding argument specifiers for the verb, and * the preposition string in the command is matched by the preposition specifier for the verb. I'll explain each of these criteria in turn. Every verb has one or more names; all of the names are kept in a single string, separated by spaces. In the simplest case, a verb-name is just a word made up of any characters other than spaces and stars (i.e., ` ' and `*'). In this case, the verb-name matches only itself; that is, the name must be matched exactly. If the name contains a single star, however, then the name matches any prefix of itself that is at least as long as the part before the star. For example, the verb-name `foo*bar' matches any of the strings `foo', `foob', `fooba', or `foobar'; note that the star itself is not considered part of the name. If the verb name *ends* in a star, then it matches any string that begins with the part before the star. For example, the verb-name `foo*' matches any of the strings `foo', `foobar', `food', or `foogleman', among many others. As a special case, if the verb-name is `*' (i.e., a single star all by itself), then it matches anything at all. Recall that the argument specifiers for the direct and indirect objects are drawn from the set `none', `any', and `this'. If the specifier is `none', then the corresponding object value must be `#-1' (aka `$nothing' in LambdaCore); that is, it must not have been specified. If the specifier is `any', then the corresponding object value may be anything at all. Finally, if the specifier is `this', then the corresponding object value must be the same as the object on which we found this verb; for example, if we are considering verbs on the player, then the object value must be the player object. Finally, recall that the argument specifier for the preposition is either `none', `any', or one of several sets of prepositional phrases, given above. A specifier of `none' matches only if there was no preposition found in the command. A specifier of `any' always matches, regardless of what preposition was found, if any. If the specifier is a set of prepositional phrases, then the one found must be in that set for the specifier to match. So, the server considers several objects in turn, checking each of their verbs in turn, looking for the first one that meets all of the criteria just explained. If it finds one, then that is the verb whose program will be executed for this command. If not, then it looks for a verb named `huh' on the room that the player is in; if one is found, then that verb will be called. This feature is useful for implementing room-specific command parsing or error recovery. If the server can't even find a `huh' verb to run, it prints an error message like `I couldn't understand that.' and the command is considered complete. At long last, we have a program to run in response to the command typed by the player. When the code for the program begins execution, the following built-in variables will have the indicated values: player an object, the player who typed the command this an object, the object on which this verb was found caller an object, the same as `player' verb a string, the first word of the command argstr a string, everything after the first word of the command args a list of strings, the words in `argstr' dobjstr a string, the direct object string found during parsing dobj an object, the direct object value found during matching prepstr a string, the prepositional phrase found during parsing iobjstr a string, the indirect object string iobj an object, the indirect object value The value returned by the program, if any, is ignored by the server. The MOO Programming Language **************************** MOO stands for "MUD, Object Oriented." MUD, in turn, has been said to stand for many different things, but I tend to think of it as "Multi-User Dungeon" in the spirit of those ancient precursors to MUDs, Adventure and Zork. MOO, the programming language, is a relatively small and simple object-oriented language designed to be easy to learn for most non-programmers; most complex systems still require some significant programming ability to accomplish, however. Having given you enough context to allow you to understand exactly what MOO code is doing, I now explain what MOO code looks like and what it means. I begin with the syntax and semantics of expressions, those pieces of code that have values. After that, I cover statements, the next level of structure up from expressions. Next, I discuss the concept of a task, the kind of running process initiated by players entering commands, among other causes. Finally, I list all of the built-in functions available to MOO code and describe what they do. First, though, let me mention comments. You can include bits of text in your MOO program that are ignored by the server. The idea is to allow you to put in notes to yourself and others about what the code is doing. To do this, begin the text of the comment with the two characters `/*' and end it with the two characters `*/'; this is just like comments in the C programming language. Note that the server will completely ignore that text; it will *not* be saved in the database. Thus, such comments are only useful in files of code that you maintain outside the database. To include a more persistent comment in your code, try using a character string literal as a statement. For example, the sentence about peanut butter in the following code is essentially ignored during execution but will be maintained in the database: for x in (players()) "Grendel eats peanut butter!"; player:tell(x.name, " (", x, ")"); endfor MOO Language Expressions ======================== Expressions are those pieces of MOO code that generate values; for example, the MOO code 3 + 4 is an expression that generates (or "has" or "returns") the value 7. There are many kinds of expressions in MOO, all of them discussed below. Errors While Evaluating Expressions ----------------------------------- Most kinds of expressions can, under some circumstances, cause an error to be generated. For example, the expression `x / y' will generate the error `E_DIV' if `y' is equal to zero. When an expression generates an error, the behavior of the server is controlled by setting of the `d' (debug) bit on the verb containing that expression. If the `d' bit is not set, then the error is effectively squelched immediately upon generation; the error value is simply returned as the value of the expression that generated it. *Note:* this error-squelching behavior is very error prone, since it affects *all* errors, including ones the programmer may not have anticipated. The `d' bit exists only for historical reasons; it was once the only way for MOO programmers to catch and handle errors. The error-catching expression and the `try'-`except' statement, both described below, are far better ways of accomplishing the same thing. If the `d' bit is set, as it usually is, then the error is "raised" and can be caught and handled either by code surrounding the expression in question or by verbs higher up on the chain of calls leading to the current verb. If the error is not caught, then the server aborts the entire task and, by default, prints a message to the current player. See the descriptions of the error-catching expression and the `try'-`except' statement for the details of how errors can be caught, and the chapter on server assumptions about the database for details on the handling of uncaught errors. Writing Values Directly in Verbs -------------------------------- The simplest kind of expression is a literal MOO value, just as described in the section on values at the beginning of this document. For example, the following are all expressions: 17 #893 "This is a character string." E_TYPE {"This", "is", "a", "list", "of", "words"} In the case of lists, like the last example above, note that the list expression contains other expressions, several character strings in this case. In general, those expressions can be of any kind at all, not necessarily literal values. For example, {3 + 4, 3 - 4, 3 * 4} is an expression whose value is the list `{7, -1, 12}'. Naming Values Within a Verb --------------------------- As discussed earlier, it is possible to store values in properties on objects; the properties will keep those values forever, or until another value is explicitly put there. Quite often, though, it is useful to have a place to put a value for just a little while. MOO provides local variables for this purpose. Variables are named places to hold values; you can get and set the value in a given variable as many times as you like. Variables are temporary, though; they only last while a particular verb is running; after it finishes, all of the variables given values there cease to exist and the values are forgotten. Variables are also "local" to a particular verb; every verb has its own set of them. Thus, the variables set in one verb are not visible to the code of other verbs. The name for a variable is made up entirely of letters, digits, and the underscore character (`_') and does not begin with a digit. The following are all valid variable names: foo _foo this2that M68000 two_words This_is_a_very_long_multiword_variable_name Note that, along with almost everything else in MOO, the case of the letters in variable names is insignificant. For example, these are all names for the same variable: fubar Fubar FUBAR fUbAr A variable name is itself an expression; its value is the value of the named variable. When a verb begins, almost no variables have values yet; if you try to use the value of a variable that doesn't have one, the error value `E_VARNF' is raised. (MOO is unlike many other programming languages in which one must `declare' each variable before using it; MOO has no such declarations.) The following variables always have values: INT FLOAT OBJ STR LIST ERR player this caller verb args argstr dobj dobjstr prepstr iobj iobjstr NUM The values of some of these variables always start out the same: `INT' an integer, the type code for integers (see the description of the function `typeof()', below) `NUM' the same as `INT' (for historical reasons) `FLOAT' an integer, the type code for floating-point numbers `LIST' an integer, the type code for lists `STR' an integer, the type code for strings `OBJ' an integer, the type code for objects `ERR' an integer, the type code for error values For others, the general meaning of the value is consistent, though the value itself is different for different situations: `player' an object, the player who typed the command that started the task that involved running this piece of code. `this' an object, the object on which the currently-running verb was found. `caller' an object, the object on which the verb that called the currently-running verb was found. For the first verb called for a given command, `caller' has the same value as `player'. `verb' a string, the name by which the currently-running verb was identified. `args' a list, the arguments given to this verb. For the first verb called for a given command, this is a list of strings, the words on the command line. The rest of the so-called "built-in" variables are only really meaningful for the first verb called for a given command. Their semantics is given in the discussion of command parsing, above. To change what value is stored in a variable, use an "assignment" expression: VARIABLE = EXPRESSION For example, to change the variable named `x' to have the value 17, you would write `x = 17' as an expression. An assignment expression does two things: * it changes the value of of the named variable, and * it returns the new value of that variable. Thus, the expression 13 + (x = 17) changes the value of `x' to be 17 and returns 30. Arithmetic Operators -------------------- All of the usual simple operations on numbers are available to MOO programs: + - * / % These are, in order, addition, subtraction, multiplication, division, and remainder. In the following table, the expressions on the left have the corresponding values on the right: 5 + 2 => 7 5 - 2 => 3 5 * 2 => 10 5 / 2 => 2 5.0 / 2.0 => 2.5 5 % 2 => 1 5.0 % 2.0 => 1.0 5 % -2 => 1 -5 % 2 => -1 -5 % -2 => -1 -(5 + 2) => -7 Note that integer division in MOO throws away the remainder and that the result of the remainder operator (`%') has the same sign as the left-hand operand. Also, note that `-' can be used without a left-hand operand to negate a numeric expression. *Fine point:* Integers and floating-point numbers cannot be mixed in any particular use of these arithmetic operators; unlike some other programming languages, MOO does not automatically coerce integers into floating-point numbers. You can use the `tofloat()' function to perform an explicit conversion. The `+' operator can also be used to append two strings. The expression "foo" + "bar" has the value "foobar" Unless both operands to an arithmetic operator are numbers of the same kind (or, for `+', both strings), the error value `E_TYPE' is raised. If the right-hand operand for the division or remainder operators (`/' or `%') is zero, the error value `E_DIV' is raised. MOO also supports the exponentiation operation, also known as "raising to a power," using the `^' operator: 3 ^ 4 => 81 3 ^ 4.5 error--> E_TYPE 3.5 ^ 4 => 150.0625 3.5 ^ 4.5 => 280.741230801382 Note that if the first operand is an integer, then the second operand must also be an integer. If the first operand is a floating-point number, then the second operand can be either kind of number. Although it is legal to raise an integer to a negative power, it is unlikely to be terribly useful. Comparing Values ---------------- Any two values can be compared for equality using `==' and `!='. The first of these returns 1 if the two values are equal and 0 otherwise; the second does the reverse: 3 == 4 => 0 3 != 4 => 1 3 == 3.0 => 0 "foo" == "Foo" => 1 #34 != #34 => 0 {1, #34, "foo"} == {1, #34, "FoO"} => 1 E_DIV == E_TYPE => 0 3 != "foo" => 1 Note that integers and floating-point numbers are never equal to one another, even in the `obvious' cases. Also note that comparison of strings (and list values containing strings) is case-insensitive; that is, it does not distinguish between the upper- and lower-case version of letters. To test two values for case-sensitive equality, use the `equal' function described later. *Warning*: It is easy (and very annoying) to confuse the equality-testing operator (`==') with the assignment operator (`='), leading to nasty, hard-to-find bugs. Don't do this. Numbers, object numbers, strings, and error values can also be compared for ordering purposes using the following operators: < <= >= > meaning "less than," "less than or equal," "greater than or equal," and "greater than," respectively. As with the equality operators, these return 1 when their operands are in the appropriate relation and 0 otherwise: 3 < 4 => 1 3 < 4.0 error--> E_TYPE #34 >= #32 => 1 "foo" <= "Boo" => 0 E_DIV > E_TYPE => 1 Note that, as with the equality operators, strings are compared case-insensitively. To perform a case-sensitive string comparison, use the `strcmp' function described later. Also note that the error values are ordered as given in the table in the section on values. If the operands to these four comparison operators are of different types (even integers and floating-point numbers are considered different types), or if they are lists, then `E_TYPE' is raised. Values as True and False ------------------------ There is a notion in MOO of "true" and "false" values; every value is one or the other. The true values are as follows: * all integers other than zero, * all floating-point numbers not equal to `0.0', * all non-empty strings (i.e., other than `""'), and * all non-empty lists (i.e., other than `{}'). All other values are false: * the integer zero, * the floating-point numbers `0.0' and `-0.0', * the empty string (`""'), * the empty list (`{}'), * all object numbers, and * all error values. There are four kinds of expressions and two kinds of statements that depend upon this classification of MOO values. In describing them, I sometimes refer to the "truth value" of a MOO value; this is just "true" or "false", the category into which that MOO value is classified. The conditional expression in MOO has the following form: EXPRESSION-1 ? EXPRESSION-2 | EXPRESSION-3 First, EXPRESSION-1 is evaluated. If it returns a true value, then EXPRESSION-2 is evaluated and whatever it returns is returned as the value of the conditional expression as a whole. If EXPRESSION-1 returns a false value, then EXPRESSION-3 is evaluated instead and its value is used as that of the conditional expression. 1 ? 2 | 3 => 2 0 ? 2 | 3 => 3 "foo" ? 17 | {#34} => 17 Note that only one of EXPRESSION-2 and EXPRESSION-3 is evaluated, never both. To negate the truth value of a MOO value, use the `!' operator: ! EXPRESSION If the value of EXPRESSION is true, `!' returns 0; otherwise, it returns 1: ! "foo" => 0 ! (3 >= 4) => 1 The negation operator is usually read as "not." It is frequently useful to test more than one condition to see if some or all of them are true. MOO provides two operators for this: EXPRESSION-1 && EXPRESSION-2 EXPRESSION-1 || EXPRESSION-2 These operators are usually read as "and" and "or," respectively. The `&&' operator first evaluates EXPRESSION-1. If it returns a true value, then EXPRESSION-2 is evaluated and its value becomes the value of the `&&' expression as a whole; otherwise, the value of EXPRESSION-1 is used as the value of the `&&' expression. Note that EXPRESSION-2 is only evaluated if EXPRESSION-1 returns a true value. The `&&' expression is equivalent to the conditional expression EXPRESSION-1 ? EXPRESSION-2 | EXPRESSION-1 except that EXPRESSION-1 is only evaluated once. The `||' operator works similarly, except that EXPRESSION-2 is evaluated only if EXPRESSION-1 returns a false value. It is equivalent to the conditional expression EXPRESSION-1 ? EXPRESSION-1 | EXPRESSION-2 except that, as with `&&', EXPRESSION-1 is only evaluated once. These two operators behave very much like "and" and "or" in English: 1 && 1 => 1 0 && 1 => 0 0 && 0 => 0 1 || 1 => 1 0 || 1 => 1 0 || 0 => 0 17 <= 23 && 23 <= 27 => 1 Indexing into Lists and Strings ------------------------------- Both strings and lists can be seen as ordered sequences of MOO values. In the case of strings, each is a sequence of single-character strings; that is, one can view the string `"bar"' as a sequence of the strings `"b"', `"a"', and `"r"'. MOO allows you to refer to the elements of lists and strings by number, by the "index" of that element in the list or string. The first element in a list or string has index 1, the second has index 2, and so on. Extracting an Element from a List or String ........................................... The indexing expression in MOO extracts a specified element from a list or string: EXPRESSION-1[EXPRESSION-2] First, EXPRESSION-1 is evaluated; it must return a list or a string (the "sequence"). Then, EXPRESSION-2 is evaluated and must return an integer (the "index"). If either of the expressions returns some other type of value, `E_TYPE' is returned. The index must be between 1 and the length of the sequence, inclusive; if it is not, then `E_RANGE' is raised. The value of the indexing expression is the index'th element in the sequence. Anywhere within EXPRESSION-2, you can use the symbol `$' as an expression returning the length of the value of EXPRESSION-1. "fob"[2] => "o" "fob"[1] => "f" {#12, #23, #34}[$ - 1] => #23 Note that there are no legal indices for the empty string or list, since there are no integers between 1 and 0 (the length of the empty string or list). *Fine point:* The `$' expression actually returns the length of the value of the expression just before the nearest enclosing `[...]' indexing or subranging brackets. For example: "frob"[{3, 2, 4}[$]] => "b" Replacing an Element of a List or String ........................................ It often happens that one wants to change just one particular slot of a list or string, which is stored in a variable or a property. This can be done conveniently using an "indexed assignment" having one of the following forms: VARIABLE[INDEX-EXPR] = RESULT-EXPR OBJECT-EXPR.NAME[INDEX-EXPR] = RESULT-EXPR OBJECT-EXPR.(NAME-EXPR)[INDEX-EXPR] = RESULT-EXPR $NAME[INDEX-EXPR] = RESULT-EXPR The first form writes into a variable, and the last three forms write into a property. The usual errors (`E_TYPE', `E_INVIND', `E_PROPNF' and `E_PERM' for lack of read/write permission on the property) may be raised, just as in reading and writing any object property; see the discussion of object property expressions below for details. Correspondingly, if VARIABLE does not yet have a value (i.e., it has never been assigned to), `E_VARNF' will be raised. If INDEX-EXPR is not an integer, or if the value of VARIABLE or the property is not a list or string, `E_TYPE' is raised. If RESULT-EXPR is a string, but not of length 1, `E_INVARG' is raised. Now suppose INDEX-EXPR evaluates to an integer K. If K is outside the range of the list or string (i.e. smaller than 1 or greater than the length of the list or string), `E_RANGE' is raised. Otherwise, the actual assignment takes place. For lists, the variable or the property is assigned a new list that is identical to the original one except at the K-th position, where the new list contains the result of RESULT-EXPR instead. For strings, the variable or the property is assigned a new string that is identical to the original one, except the K-th character is changed to be RESULT-EXPR. The assignment expression itself returns the value of RESULT-EXPR. For the following examples, assume that `l' initially contains the list `{1, 2, 3}' and that `s' initially contains the string "foobar": l[5] = 3 error--> E_RANGE l["first"] = 4 error--> E_TYPE s[3] = "baz" error--> E_INVARG l[2] = l[2] + 3 => 5 l => {1, 5, 3} l[2] = "foo" => "foo" l => {1, "foo", 3} s[2] = "u" => "u" s => "fuobar" s[$] = "z" => "z" s => "fuobaz" Note that the `$' expression may also be used in indexed assignments with the same meaning as before. *Fine point:* After an indexed assignment, the variable or property contains a *new* list or string, a copy of the original list in all but the K-th place, where it contains a new value. In programming-language jargon, the original list is not mutated, and there is no aliasing. (Indeed, no MOO value is mutable and no aliasing ever occurs.) In the list case, indexed assignment can be nested to many levels, to work on nested lists. Assume that `l' initially contains the list {{1, 2, 3}, {4, 5, 6}, "foo"} in the following examples: l[7] = 4 error--> E_RANGE l[1][8] = 35 error--> E_RANGE l[3][2] = 7 error--> E_TYPE l[1][1][1] = 3 error--> E_TYPE l[2][2] = -l[2][2] => -5 l => {{1, 2, 3}, {4, -5, 6}, "foo"} l[2] = "bar" => "bar" l => {{1, 2, 3}, "bar", "foo"} l[2][$] = "z" => "z" l => {{1, 2, 3}, "baz", "foo"} The first two examples raise `E_RANGE' because 7 is out of the range of `l' and 8 is out of the range of `l[1]'. The next two examples raise `E_TYPE' because `l[3]' and `l[1][1]' are not lists. Extracting a Subsequence of a List or String ............................................ The range expression extracts a specified subsequence from a list or string: EXPRESSION-1[EXPRESSION-2..EXPRESSION-3] The three expressions are evaluated in order. EXPRESSION-1 must return a list or string (the "sequence") and the other two expressions must return integers (the "low" and "high" indices, respectively); otherwise, `E_TYPE' is raised. The `$' expression can be used in either or both of EXPRESSION-2 and EXPRESSION-3 just as before, meaning the length of the value of EXPRESSION-1. If the low index is greater than the high index, then the empty string or list is returned, depending on whether the sequence is a string or a list. Otherwise, both indices must be between 1 and the length of the sequence; `E_RANGE' is raised if they are not. A new list or string is returned that contains just the elements of the sequence with indices between the low and high bounds. "foobar"[2..$] => "oobar" "foobar"[3..3] => "o" "foobar"[17..12] => "" {"one", "two", "three"}[$ - 1..$] => {"two", "three"} {"one", "two", "three"}[3..3] => {"three"} {"one", "two", "three"}[17..12] => {} Replacing a Subsequence of a List or String ........................................... The subrange assigment replaces a specified subsequence of a list or string with a supplied subsequence. The allowed forms are: VARIABLE[START-INDEX-EXPR..END-INDEX-EXPR] = RESULT-EXPR OBJECT-EXPR.NAME[START-INDEX-EXPR..END-INDEX-EXPR] = RESULT-EXPR OBJECT-EXPR.(NAME-EXPR)[START-INDEX-EXPR..END-INDEX-EXPR] = RESULT-EXPR $NAME[START-INDEX-EXPR..END-INDEX-EXPR] = RESULT-EXPR As with indexed assigments, the first form writes into a variable, and the last three forms write into a property. The same errors (`E_TYPE', `E_INVIND', `E_PROPNF' and `E_PERM' for lack of read/write permission on the property) may be raised. If VARIABLE does not yet have a value (i.e., it has never been assigned to), `E_VARNF' will be raised. As before, the `$' expression can be used in either START-INDEX-EXPR or END-INDEX-EXPR, meaning the length of the original value of the expression just before the `[...]' part. If START-INDEX-EXPR or END-INDEX-EXPR is not an integer, if the value of VARIABLE or the property is not a list or string, or RESULT-EXPR is not the same type as VARIABLE or the property, `E_TYPE' is raised. `E_RANGE' is raised if END-INDEX-EXPR is less than zero or if START-INDEX-EXPR is greater than the length of the list or string plus one. Note: the length of RESULT-EXPR does not need to be the same as the length of the specified range. In precise terms, the subrange assigment V[START..END] = VALUE is equivalent to V = {@V[1..START - 1], @VALUE, @V[END + 1..$]} if V is a list and to V = V[1..START - 1] + VALUE + V[END + 1..$] if V is a string. The assigment expression itself returns the value of RESULT-EXPR. For the following examples, assume that `l' initially contains the list `{1, 2, 3}' and that `s' initially contains the string "foobar": l[5..6] = {7, 8} error--> E_RANGE l[2..3] = 4 error--> E_TYPE l[#2..3] = {7} error--> E_TYPE s[2..3] = {6} error--> E_TYPE l[2..3] = {6, 7, 8, 9} => {6, 7, 8, 9} l => {1, 6, 7, 8, 9} l[2..1] = {10, "foo"} => {10, "foo"} l => {1, 10, "foo", 6, 7, 8, 9} l[3][2..$] = "u" => "u" l => {1, 10, "fu", 6, 7, 8, 9} s[7..12] = "baz" => "baz" s => "foobarbaz" s[1..3] = "fu" => "fu" s => "fubarbaz" s[1..0] = "test" => "test" s => "testfubarbaz" Other Operations on Lists ------------------------- As was mentioned earlier, lists can be constructed by writing a comma-separated sequence of expressions inside curly braces: {EXPRESSION-1, EXPRESSION-2, ..., EXPRESSION-N} The resulting list has the value of EXPRESSION-1 as its first element, that of EXPRESSION-2 as the second, etc. {3 < 4, 3 <= 4, 3 >= 4, 3 > 4} => {1, 1, 0, 0} Additionally, one may precede any of these expressions by the splicing operator, `@'. Such an expression must return a list; rather than the old list itself becoming an element of the new list, all of the elements of the old list are included in the new list. This concept is easy to understand, but hard to explain in words, so here are some examples. For these examples, assume that the variable `a' has the value `{2, 3, 4}' and that `b' has the value `{"Foo", "Bar"}': {1, a, 5} => {1, {2, 3, 4}, 5} {1, @a, 5} => {1, 2, 3, 4, 5} {a, @a} => {{2, 3, 4}, 2, 3, 4} {@a, @b} => {2, 3, 4, "Foo", "Bar"} If the splicing operator (`@') precedes an expression whose value is not a list, then `E_TYPE' is raised as the value of the list construction as a whole. The list membership expression tests whether or not a given MOO value is an element of a given list and, if so, with what index: EXPRESSION-1 in EXPRESSION-2 EXPRESSION-2 must return a list; otherwise, `E_TYPE' is raised. If the value of EXPRESSION-1 is in that list, then the index of its first occurrence in the list is returned; otherwise, the `in' expression returns 0. 2 in {5, 8, 2, 3} => 3 7 in {5, 8, 2, 3} => 0 "bar" in {"Foo", "Bar", "Baz"} => 2 Note that the list membership operator is case-insensitive in comparing strings, just like the comparison operators. To perform a case-sensitive list membership test, use the `is_member' function described later. Note also that since it returns zero only if the given value is not in the given list, the `in' expression can be used either as a membership test or as an element locator. Spreading List Elements Among Variables --------------------------------------- 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 *could* write statements like these: first = args[1]; second = args[2]; if (length(args) > 2) third = args[3]; else third = 0; endif 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 *extra* list elements were present, adding to the tedium. MOO provides a special kind of assignment expression, called "scattering assignment" made just for cases such as these. A scattering assignment expression looks like this: {TARGET, ...} = EXPR where each TARGET describes a place to store elements of the list that results from evaluating EXPR. A TARGET has one of the following forms: `VARIABLE' 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 "required" target, since the assignment is required to put one of the list elements into the variable. `?VARIABLE' This is called an "optional" 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. `?VARIABLE = DEFAULT-EXPR' 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 DEFAULT-EXPR is assigned to it instead. Thus, DEFAULT-EXPR provides a "default value" for the variable. The default value expressions are evaluated and assigned working from left to right *after* all of the other assignments have been performed. `@VARIABLE' By analogy with the `@' 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 "rest" target, since it gets the rest of the elements. There may be at most one rest target in each scattering assignment expression. 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 `E_ARGS' is raised. Here are some examples of how this works. Assume first that the verb `me:foo()' contains the following code: b = c = e = 17; {a, ?b, ?c = 8, @d, ?e = 9, f} = args; return {a, b, c, d, e, f}; Then the following calls return the given values: 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} Using scattering assignment, the example at the begining of this section could be rewritten more simply, reliably, and readably: {first, second, ?third = 0} = args; 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. Getting and Setting the Values of Properties -------------------------------------------- Usually, one can read the value of a property on an object with a simple expression: EXPRESSION.NAME EXPRESSION must return an object number; if not, `E_TYPE' is raised. If the object with that number does not exist, `E_INVIND' is raised. Otherwise, if the object does not have a property with that name, then `E_PROPNF' is raised. Otherwise, if the named property is not readable by the owner of the current verb, then `E_PERM' is raised. Finally, assuming that none of these terrible things happens, the value of the named property on the given object is returned. I said "usually" in the paragraph above because that simple expression only works if the name of the property obeys the same rules as for the names of variables (i.e., consists entirely of letters, digits, and underscores, and doesn't begin with a digit). Property names are not restricted to this set, though. Also, it is sometimes useful to be able to figure out what property to read by some computation. For these more general uses, the following syntax is also allowed: EXPRESSION-1.(EXPRESSION-2) As before, EXPRESSION-1 must return an object number. EXPRESSION-2 must return a string, the name of the property to be read; `E_TYPE' is raised otherwise. Using this syntax, any property can be read, regardless of its name. Note that, as with almost everything in MOO, case is not significant in the names of properties. Thus, the following expressions are all equivalent: foo.bar foo.Bar foo.("bAr") The LambdaCore database uses several properties on `#0', the "system object", for various special purposes. For example, the value of `#0.room' is the "generic room" object, `#0.exit' is the "generic exit" object, etc. This allows MOO programs to refer to these useful objects more easily (and more readably) than using their object numbers directly. To make this usage even easier and more readable, the expression $NAME (where NAME obeys the rules for variable names) is an abbreviation for #0.NAME Thus, for example, the value `$nothing' mentioned earlier is really `#-1', the value of `#0.nothing'. As with variables, one uses the assignment operator (`=') to change the value of a property. For example, the expression 14 + (#27.foo = 17) changes the value of the `foo' property of the object numbered 27 to be 17 and then returns 31. Assignments to properties check that the owner of the current verb has write permission on the given property, raising `E_PERM' otherwise. Read permission is not required. Calling Built-in Functions and Other Verbs ------------------------------------------ MOO provides a large number of useful functions for performing a wide variety of operations; a complete list, giving their names, arguments, and semantics, appears in a separate section later. As an example to give you the idea, there is a function named `length' that returns the length of a given string or list. The syntax of a call to a function is as follows: NAME(EXPR-1, EXPR-2, ..., EXPR-N) where NAME is the name of one of the built-in functions. The expressions between the parentheses, called "arguments", are each evaluated in turn and then given to the named function to use in its appropriate way. Most functions require that a specific number of arguments be given; otherwise, `E_ARGS' is raised. Most also require that certain of the arguments have certain specified types (e.g., the `length()' function requires a list or a string as its argument); `E_TYPE' is raised if any argument has the wrong type. As with list construction, the splicing operator `@' can precede any argument expression. The value of such an expression must be a list; `E_TYPE' is raised otherwise. The elements of this list are passed as individual arguments, in place of the list as a whole. Verbs can also call other verbs, usually using this syntax: EXPR-0:NAME(EXPR-1, EXPR-2, ..., EXPR-N) EXPR-0 must return an object number; `E_TYPE' is raised otherwise. If the object with that number does not exist, `E_INVIND' is raised. If this task is too deeply nested in verbs calling verbs calling verbs, then `E_MAXREC' is raised; the default limit is 50 levels, but this can be changed from within the database; see the chapter on server assumptions about the database for details. If neither the object nor any of its ancestors defines a verb matching the given name, `E_VERBNF' is raised. Otherwise, if none of these nasty things happens, the named verb on the given object is called; the various built-in variables have the following initial values in the called verb: `this' an object, the value of EXPR-0 `verb' a string, the NAME used in calling this verb `args' a list, the values of EXPR-1, EXPR-2, etc. `caller' an object, the value of `this' in the calling verb `player' an object, the same value as it had initially in the calling verb or, if the calling verb is running with wizard permissions, the same as the current value in the calling verb. All other built-in variables (`argstr', `dobj', etc.) are initialized with the same values they have in the calling verb. As with the discussion of property references above, I said "usually" at the beginning of the previous paragraph because that syntax is only allowed when the NAME follows the rules for allowed variable names. Also as with property reference, there is a syntax allowing you to compute the name of the verb: EXPR-0:(EXPR-00)(EXPR-1, EXPR-2, ..., EXPR-N) The expression EXPR-00 must return a string; `E_TYPE' is raised otherwise. The splicing operator (`@') can be used with verb-call arguments, too, just as with the arguments to built-in functions. In many databases, a number of important verbs are defined on `#0', the "system object". As with the `$foo' notation for properties on `#0', the server defines a special syntax for calling verbs on `#0': $NAME(EXPR-1, EXPR-2, ..., EXPR-N) (where NAME obeys the rules for variable names) is an abbreviation for #0:NAME(EXPR-1, EXPR-2, ..., EXPR-N) Catching Errors in Expressions ------------------------------ It is often useful to be able to "catch" an error that an expression raises, to keep the error from aborting the whole task, and to keep on running as if the expression had returned some other value normally. The following expression accomplishes this: ` EXPR-1 ! CODES => EXPR-2 ' *Note:* the open- and close-quotation marks in the previous line are really part of the syntax; you must actually type them as part of your MOO program for this kind of expression. The CODES part is either the keyword `ANY' or else a comma-separated list of expressions, just like an argument list. As in an argument list, the splicing operator (`@') can be used here. The `=> EXPR-2' part of the error-catching expression is optional. First, the CODES part is evaluated, yielding a list of error codes that should be caught if they're raised; if CODES is `ANY', then it is equivalent to the list of all possible MOO values. Next, EXPR-1 is evaluated. If it evaluates normally, without raising an error, then its value becomes the value of the entire error-catching expression. If evaluating EXPR-1 results in an error being raised, then call that error E. If E is in the list resulting from evaluating CODES, then E is considered "caught" by this error-catching expression. In such a case, if EXPR-2 was given, it is evaluated to get the outcome of the entire error-catching expression; if EXPR-2 was omitted, then E becomes the value of the entire expression. If E is *not* in the list resulting from CODES, then this expression does not catch the error at all and it continues to be raised, possibly to be caught by some piece of code either surrounding this expression or higher up on the verb-call stack. Here are some examples of the use of this kind of expression: `x + 1 ! E_TYPE => 0' Returns `x + 1' if `x' is an integer, returns `0' if `x' is not an integer, and raises `E_VARNF' if `x' doesn't have a value. `x.y ! E_PROPNF, E_PERM => 17' Returns `x.y' if that doesn't cause an error, `17' if `x' doesn't have a `y' property or that property isn't readable, and raises some other kind of error (like `E_INVIND') if `x.y' does. `1 / 0 ! ANY' Returns `E_DIV'. Parentheses and Operator Precedence ----------------------------------- As shown in a few examples above, MOO allows you to use parentheses to make it clear how you intend for complex expressions to be grouped. For example, the expression 3 * (4 + 5) performs the addition of 4 and 5 before multiplying the result by 3. If you leave out the parentheses, MOO will figure out how to group the expression according to certain rules. The first of these is that some operators have higher "precedence" than others; operators with higher precedence will more tightly bind to their operands than those with lower precedence. For example, multiplication has higher precedence than addition; thus, if the parentheses had been left out of the expression in the previous paragraph, MOO would have grouped it as follows: (3 * 4) + 5 The table below gives the relative precedence of all of the MOO operators; operators on higher lines in the table have higher precedence and those on the same line have identical precedence: ! - (without a left operand) ^ * / % + - == != < <= > >= in && || ... ? ... | ... (the conditional expression) = Thus, the horrendous expression x = a < b && c > d + e * f ? w in y | - q - r would be grouped as follows: x = (((a < b) && (c > (d + (e * f)))) ? (w in y) | ((- q) - r)) It is best to keep expressions simpler than this and to use parentheses liberally to make your meaning clear to other humans. MOO Language Statements ======================= Statements are MOO constructs that, in contrast to expressions, perform some useful, non-value-producing operation. For example, there are several kinds of statements, called `looping constructs', that repeatedly perform some set of operations. Fortunately, there are many fewer kinds of statements in MOO than there are kinds of expressions. Errors While Executing Statements --------------------------------- Statements do not return values, but some kinds of statements can, under certain circumstances described below, generate errors. If such an error is generated in a verb whose `d' (debug) bit is not set, then the error is ignored and the statement that generated it is simply skipped; execution proceeds with the next statement. *Note:* this error-ignoring behavior is very error prone, since it affects *all* errors, including ones the programmer may not have anticipated. The `d' bit exists only for historical reasons; it was once the only way for MOO programmers to catch and handle errors. The error-catching expression and the `try'-`except' statement are far better ways of accomplishing the same thing. If the `d' bit is set, as it usually is, then the error is "raised" and can be caught and handled either by code surrounding the expression in question or by verbs higher up on the chain of calls leading to the current verb. If the error is not caught, then the server aborts the entire task and, by default, prints a message to the current player. See the descriptions of the error-catching expression and the `try'-`except' statement for the details of how errors can be caught, and the chapter on server assumptions about the database for details on the handling of uncaught errors. Simple Statements ----------------- The simplest kind of statement is the "null" statement, consisting of just a semicolon: ; It doesn't do anything at all, but it does it very quickly. The next simplest statement is also one of the most common, the expression statement, consisting of any expression followed by a semicolon: EXPRESSION; The given expression is evaluated and the resulting value is ignored. Commonly-used kinds of expressions for such statements include assignments and verb calls. Of course, there's no use for such a statement unless the evaluation of EXPRESSION has some side-effect, such as changing the value of some variable or property, printing some text on someone's screen, etc. Statements for Testing Conditions --------------------------------- The `if' statement allows you to decide whether or not to perform some statements based on the value of an arbitrary expression: if (EXPRESSION) STATEMENTS endif EXPRESSION is evaluated and, if it returns a true value, the statements are executed in order; otherwise, nothing more is done. One frequently wants to perform one set of statements if some condition is true and some other set of statements otherwise. The optional `else' phrase in an `if' statement allows you to do this: if (EXPRESSION) STATEMENTS-1 else STATEMENTS-2 endif This statement is executed just like the previous one, except that STATEMENTS-1 are executed if EXPRESSION returns a true value and STATEMENTS-2 are executed otherwise. Sometimes, one needs to test several conditions in a kind of nested fashion: if (EXPRESSION-1) STATEMENTS-1 else if (EXPRESSION-2) STATEMENTS-2 else if (EXPRESSION-3) STATEMENTS-3 else STATEMENTS-4 endif endif endif Such code can easily become tedious to write and difficult to read. MOO provides a somewhat simpler notation for such cases: if (EXPRESSION-1) STATEMENTS-1 elseif (EXPRESSION-2) STATEMENTS-2 elseif (EXPRESSION-3) STATEMENTS-3 else STATEMENTS-4 endif Note that `elseif' is written as a single word, without any spaces. This simpler version has the very same meaning as the original: evaluate EXPRESSION-I for I equal to 1, 2, and 3, in turn, until one of them returns a true value; then execute the STATEMENTS-I associated with that expression. If none of the EXPRESSION-I return a true value, then execute STATEMENTS-4. Any number of `elseif' phrases can appear, each having this form: elseif (EXPRESSION) STATEMENTS The complete syntax of the `if' statement, therefore, is as follows: if (EXPRESSION) STATEMENTS ZERO-OR-MORE-ELSEIF-PHRASES AN-OPTIONAL-ELSE-PHRASE endif Statements for Looping ---------------------- MOO provides three different kinds of looping statements, allowing you to have a set of statements executed (1) once for each element of a given list, (2) once for each integer or object number in a given range, and (3) over and over until a given condition stops being true. To perform some statements once for each element of a given list, use this syntax: for VARIABLE in (EXPRESSION) STATEMENTS endfor The expression is evaluated and should return a list; if it does not, `E_TYPE' is raised. The STATEMENTS are then executed once for each element of that list in turn; each time, the given VARIABLE is assigned the value of the element in question. For example, consider the following statements: odds = {1, 3, 5, 7, 9}; evens = {}; for n in (odds) evens = {@evens, n + 1}; endfor The value of the variable `evens' after executing these statements is the list {2, 4, 6, 8, 10} To perform a set of statements once for each integer or object number in a given range, use this syntax: for VARIABLE in [EXPRESSION-1..EXPRESSION-2] STATEMENTS endfor The two expressions are evaluated in turn and should either both return integers or both return object numbers; `E_TYPE' is raised otherwise. The STATEMENTS are then executed once for each integer (or object number, as appropriate) greater than or equal to the value of EXPRESSION-1 and less than or equal to the result of EXPRESSION-2, in increasing order. Each time, the given variable is assigned the integer or object number in question. For example, consider the following statements: evens = {}; for n in [1..5] evens = {@evens, 2 * n}; endfor The value of the variable `evens' after executing these statements is just as in the previous example: the list {2, 4, 6, 8, 10} The following loop over object numbers prints out the number and name of every valid object in the database: for o in [#0..max_object()] if (valid(o)) notify(player, tostr(o, ": ", o.name)); endif endfor The final kind of loop in MOO executes a set of statements repeatedly as long as a given condition remains true: while (EXPRESSION) STATEMENTS endwhile The expression is evaluated and, if it returns a true value, the STATEMENTS are executed; then, execution of the `while' statement begins all over again with the evaluation of the expression. That is, execution alternates between evaluating the expression and executing the statements until the expression returns a false value. The following example code has precisely the same effect as the loop just shown above: evens = {}; n = 1; while (n <= 5) evens = {@evens, 2 * n}; n = n + 1; endwhile *Fine point:* It is also possible to give a `name' to a `while' loop, using this syntax: while NAME (EXPRESSION) STATEMENTS endwhile which has precisely the same effect as while (NAME = EXPRESSION) STATEMENTS endwhile This naming facility is only really useful in conjunction with the `break' and `continue' statements, described in the next section. With each kind of loop, it is possible that the statements in the body of the loop will never be executed at all. For iteration over lists, this happens when the list returned by the expression is empty. For iteration on integers, it happens when EXPRESSION-1 returns a larger integer than EXPRESSION-2. Finally, for the `while' loop, it happens if the expression returns a false value the very first time it is evaluated. Terminating One or All Iterations of a Loop ------------------------------------------- Sometimes, it is useful to exit a loop before it finishes all of its iterations. For example, if the loop is used to search for a particular kind of element of a list, then it might make sense to stop looping as soon as the right kind of element is found, even if there are more elements yet to see. The `break' statement is used for this purpose; it has the form break; or break NAME; Each `break' statement indicates a specific surrounding loop; if NAME is not given, the statement refers to the innermost one. If it is given, NAME must be the name appearing right after the `for' or `while' keyword of the desired enclosing loop. When the `break' statement is executed, the indicated loop is immediately terminated and executing continues just as if the loop had completed its iterations normally. MOO also allows you to terminate just the current iteration of a loop, making it immediately go on to the next one, if any. The `continue' statement does this; it has precisely the same forms as the `break' statement: continue; or continue NAME; Returning a Value from a Verb ----------------------------- The MOO program in a verb is just a sequence of statements. Normally, when the verb is called, those statements are simply executed in order and then the integer 0 is returned as the value of the verb-call expression. Using the `return' statement, one can change this behavior. The `return' statement has one of the following two forms: return; or return EXPRESSION; When it is executed, execution of the current verb is terminated immediately after evaluating the given EXPRESSION, if any. The verb-call expression that started the execution of this verb then returns either the value of EXPRESSION or the integer 0, if no EXPRESSION was provided. Handling Errors in Statements ----------------------------- Normally, whenever a piece of MOO code raises an error, the entire task is aborted and a message printed to the user. Often, such errors can be anticipated in advance by the programmer and code written to deal with them in a more graceful manner. The `try'-`except' statement allows you to do this; the syntax is as follows: try STATEMENTS-0 except VARIABLE-1 (CODES-1) STATEMENTS-1 except VARIABLE-2 (CODES-2) STATEMENTS-2 ... endtry where the VARIABLEs may be omitted and each CODES part is either the keyword `ANY' or else a comma-separated list of expressions, just like an argument list. As in an argument list, the splicing operator (`@') can be used here. There can be anywhere from 1 to 255 `except' clauses. First, each CODES part is evaluated, yielding a list of error codes that should be caught if they're raised; if a CODES is `ANY', then it is equivalent to the list of all possible MOO values. Next, STATEMENTS-0 is executed; if it doesn't raise an error, then that's all that happens for the entire `try'-`except' statement. Otherwise, let E be the error it raises. From top to bottom, E is searched for in the lists resulting from the various CODES parts; if it isn't found in any of them, then it continues to be raised, possibly to be caught by some piece of code either surrounding this `try'-`except' statement or higher up on the verb-call stack. If E is found first in CODES-I, then VARIABLE-I (if provided) is assigned a value containing information about the error being raised and STATEMENTS-I is executed. The value assigned to VARIABLE-I is a list of four elements: {CODE, MESSAGE, VALUE, TRACEBACK} where CODE is E, the error being raised, MESSAGE and VALUE are as provided by the code that raised the error, and TRACEBACK is a list like that returned by the `callers()' function, including line numbers. The TRACEBACK list contains entries for every verb from the one that raised the error through the one containing this `try'-`except' statement. Unless otherwise mentioned, all of the built-in errors raised by expressions, statements, and functions provide `tostr(CODE)' as MESSAGE and zero as VALUE. Here's an example of the use of this kind of statement: try result = object:(command)(@arguments); player:tell("=> ", toliteral(result)); except v (ANY) tb = v[4]; if (length(tb) == 1) player:tell("** Illegal command: ", v[2]); else top = tb[1]; tb[1..1] = {}; player:tell(top[1], ":", top[2], ", line ", top[6], ":", v[2]); for fr in (tb) player:tell("... called from ", fr[1], ":", fr[2], ", line ", fr[6]); endfor player:tell("(End of traceback)"); endif endtry Cleaning Up After Errors ------------------------ Whenever an error is raised, it is usually the case that at least some MOO code gets skipped over and never executed. Sometimes, it's important that a piece of code *always* be executed, whether or not an error is raised. Use the `try'-`finally' statement for these cases; it has the following syntax: try STATEMENTS-1 finally STATEMENTS-2 endtry First, STATEMENTS-1 is executed; if it completes without raising an error, returning from this verb, or terminating the current iteration of a surrounding loop (we call these possibilities "transferring control"), then STATEMENTS-2 is executed and that's all that happens for the entire `try'-`finally' statement. Otherwise, the process of transferring control is interrupted and STATMENTS-2 is executed. If STATEMENTS-2 itself completes without transferring control, then the interrupted control transfer is resumed just where it left off. If STATEMENTS-2 does transfer control, then the interrupted transfer is simply forgotten in favor of the new one. In short, this statement ensures that STATEMENTS-2 is executed after control leaves STATEMENTS-1 for whatever reason; it can thus be used to make sure that some piece of cleanup code is run even if STATEMENTS-1 doesn't simply run normally to completion. Here's an example: try start = time(); object:(command)(@arguments); finally end = time(); this:charge_user_for_seconds(player, end - start); endtry Executing Statements at a Later Time ------------------------------------ It is sometimes useful to have some sequence of statements execute at a later time, without human intervention. For example, one might implement an object that, when thrown into the air, eventually falls back to the ground; the `throw' verb on that object should arrange to print a message about the object landing on the ground, but the message shouldn't be printed until some number of seconds have passed. The `fork' statement is intended for just such situations and has the following syntax: fork (EXPRESSION) STATEMENTS endfork The `fork' statement first executes the expression, which must return a integer; call that integer N. It then creates a new MOO "task" that will, after at least N seconds, execute the statements. When the new task begins, all variables will have the values they had at the time the `fork' statement was executed. The task executing the `fork' statement immediately continues execution. The concept of tasks is discussed in detail in the next section. By default, there is no limit to the number of tasks any player may fork, but such a limit can be imposed from within the database. See the chapter on server assumptions about the database for details. Occasionally, one would like to be able to kill a forked task before it even starts; for example, some player might have caught the object that was thrown into the air, so no message should be printed about it hitting the ground. If a variable name is given after the `fork' keyword, like this: fork NAME (EXPRESSION) STATEMENTS endfork then that variable is assigned the "task ID" of the newly-created task. The value of this variable is visible both to the task executing the fork statement and to the statements in the newly-created task. This ID can be passed to the `kill_task()' function to keep the task from running and will be the value of `task_id()' once the task begins execution. MOO Tasks ========= A "task" is an execution of a MOO program. There are five kinds of tasks in LambdaMOO: * Every time a player types a command, a task is created to execute that command; we call these "command tasks". * Whenever a player connects or disconnects from the MOO, the server starts a task to do whatever processing is necessary, such as printing out `Munchkin has connected' to all of the players in the same room; these are called "server tasks". * The `fork' statement in the programming language creates a task whose execution is delayed for at least some given number of seconds; these are "forked tasks". * The `suspend()' function suspends the execution of the current task. A snapshot is taken of whole state of the execution, and the execution will be resumed later. These are called "suspended tasks". * The `read()' function also suspends the execution of the current task, in this case waiting for the player to type a line of input. When the line is received, the task resumes with the `read()' function returning the input line as result. These are called "reading tasks". The last three kinds of tasks above are collectively known as "queued tasks" or "background tasks", since they may not run immediately. To prevent a maliciously- or incorrectly-written MOO program from running forever and monopolizing the server, limits are placed on the running time of every task. One limit is that no task is allowed to run longer than a certain number of seconds; command and server tasks get five seconds each while other tasks get only three seconds. This limit is, in practice, rarely reached. The reason is that there is also a limit on the number of operations a task may execute. The server counts down "ticks" as any task executes. Roughly speaking, it counts one tick for every expression evaluation (other than variables and literals), one for every `if', `fork' or `return' statement, and one for every iteration of a loop. If the count gets all the way down to zero, the task is immediately and unceremoniously aborted. By default, command and server tasks begin with an store of 30,000 ticks; this is enough for almost all normal uses. Forked, suspended, and reading tasks are allotted 15,000 ticks each. These limits on seconds and ticks may be changed from within the database, as can the behavior of the server after it aborts a task for running out; see the chapter on server assumptions about the database for details. Because queued tasks may exist for long periods of time before they begin execution, there are functions to list the ones that you own and to kill them before they execute. These functions, among others, are discussed in the following section. Built-in Functions ================== There are a large number of built-in functions available for use by MOO programmers. Each one is discussed in detail in this section. The presentation is broken up into subsections by grouping together functions with similar or related uses. For most functions, the expected types of the arguments are given; if the actual arguments are not of these types, `E_TYPE' is raised. Some arguments can be of any type at all; in such cases, no type specification is given for the argument. Also, for most functions, the type of the result of the function is given. Some functions do not return a useful result; in such cases, the specification `none' is used. A few functions can potentially return any type of value at all; in such cases, the specification `value' is used. Most functions take a certain fixed number of required arguments and, in some cases, one or two optional arguments. If a function is called with too many or too few arguments, `E_ARGS' is raised. Functions are always called by the program for some verb; that program is running with the permissions of some player, usually the owner of the verb in question (it is not always the owner, though; wizards can use `set_task_perms()' to change the permissions `on the fly'). In the function descriptions below, we refer to the player whose permissions are being used as the "programmer". Many built-in functions are described below as raising `E_PERM' unless the programmer meets certain specified criteria. It is possible to restrict use of any function, however, so that only wizards can use it; see the chapter on server assumptions about the database for details. Object-Oriented Programming --------------------------- One of the most important facilities in an object-oriented programming language is ability for a child object to make use of a parent's implementation of some operation, even when the child provides its own definition for that operation. The `pass()' function provides this facility in MOO. - Function: value pass (ARG, ...) Often, it is useful for a child object to define a verb that *augments* the behavior of a verb on its parent object. For example, in the LambdaCore database, the root object (which is an ancestor of every other object) defines a verb called `description' that simply returns the value of `this.description'; this verb is used by the implementation of the `look' command. In many cases, a programmer would like the description of some object to include some non-constant part; for example, a sentence about whether or not the object was `awake' or `sleeping'. This sentence should be added onto the end of the normal description. The programmer would like to have a means of calling the normal `description' verb and then appending the sentence onto the end of that description. The function `pass()' is for exactly such situations. `pass' calls the verb with the same name as the current verb but as defined on the parent of the object that defines the current verb. The arguments given to `pass' are the ones given to the called verb and the returned value of the called verb is returned from the call to `pass'. The initial value of `this' in the called verb is the same as in the calling verb. Thus, in the example above, the child-object's `description' verb might have the following implementation: return pass() + " It is " + (this.awake ? "awake." | "sleeping."); That is, it calls its parent's `description' verb and then appends to the result a sentence whose content is computed based on the value of a property on the object. In almost all cases, you will want to call `pass()' with the same arguments as were given to the current verb. This is easy to write in MOO; just call `pass(@args)'. Manipulating MOO Values ----------------------- There are several functions for performing primitive operations on MOO values, and they can be cleanly split into two kinds: those that do various very general operations that apply to all types of values, and those that are specific to one particular type. There are so many operations concerned with objects that we do not list them in this section but rather give them their own section following this one. General Operations Applicable to all Values ........................................... - Function: int typeof (VALUE) Takes any MOO value and returns an integer representing the type of VALUE. The result is the same as the initial value of one of these built-in variables: `INT', `FLOAT', `STR', `LIST', `OBJ', or `ERR'. Thus, one usually writes code like this: if (typeof(x) == LIST) ... and not like this: if (typeof(x) == 3) ... because the former is much more readable than the latter. - Function: str tostr (VALUE, ...) Converts all of the given MOO values into strings and returns the concatenation of the results. tostr(17) => "17" tostr(1.0/3.0) => "0.333333333333333" tostr(#17) => "#17" tostr("foo") => "foo" tostr({1, 2}) => "{list}" tostr(E_PERM) => "Permission denied" tostr("3 + 4 = ", 3 + 4) => "3 + 4 = 7" Note that `tostr()' does not do a good job of converting lists into strings; all lists, including the empty list, are converted into the string `"{list}"'. The function `toliteral()', below, is better for this purpose. - Function: str toliteral (VALUE) Returns a string containing a MOO literal expression that, when evaluated, would be equal to VALUE. toliteral(17) => "17" toliteral(1.0/3.0) => "0.333333333333333" toliteral(#17) => "#17" toliteral("foo") => "\"foo\"" toliteral({1, 2}) => "{1, 2}" toliteral(E_PERM) => "E_PERM" - Function: int toint (VALUE) - Function: int tonum (VALUE) Converts the given MOO value into an integer and returns that integer. Floating-point numbers are rounded toward zero, truncating their fractional parts. Object numbers are converted into the equivalent integers. Strings are parsed as the decimal encoding of a real number which is then converted to an integer. Errors are converted into integers obeying the same ordering (with respect to `<=' as the errors themselves. `Toint()' raises `E_TYPE' if VALUE is a list. If VALUE is a string but the string does not contain a syntactically-correct number, then `toint()' returns 0. toint(34.7) => 34 toint(-34.7) => -34 toint(#34) => 34 toint("34") => 34 toint("34.7") => 34 toint(" - 34 ") => -34 toint(E_TYPE) => 1 - Function: obj toobj (VALUE) Converts the given MOO value into an object number and returns that object number. The conversions are very similar to those for `toint()' except that for strings, the number *may* be preceded by `#'. toobj("34") => #34 toobj("#34") => #34 toobj("foo") => #0 toobj({1, 2}) error--> E_TYPE - Function: float tofloat (VALUE) Converts the given MOO value into a floating-point number and returns that number. Integers and object numbers are converted into the corresponding integral floating-point numbers. Strings are parsed as the decimal encoding of a real number which is then represented as closely as possible as a floating-point number. Errors are first converted to integers as in `toint()' and then converted as integers are. `Tofloat()' raises `E_TYPE' if VALUE is a list. If VALUE is a string but the string does not contain a syntactically-correct number, then `tofloat()' returns 0. tofloat(34) => 34.0 tofloat(#34) => 34.0 tofloat("34") => 34.0 tofloat("34.7") => 34.7 tofloat(E_TYPE) => 1.0 - Function: int equal (VALUE1, VALUE2) Returns true if VALUE1 is completely indistinguishable from VALUE2. This is much the same operation as "`VALUE1 == VALUE2'" except that, unlike `==', the `equal()' function does not treat upper- and lower-case characters in strings as equal. "Foo" == "foo" => 1 equal("Foo", "foo") => 0 equal("Foo", "Foo") => 1 - Function: int value_bytes (VALUE) Returns the number of bytes of the server's memory required to store the given VALUE. - Function: str value_hash (VALUE) Returns the same string as `string_hash(toliteral(VALUE))'; see the description of `string_hash()' for details. Operations on Numbers ..................... - Function: int random ([int MOD]) MOD must be a positive integer; otherwise, `E_INVARG' is raised. An integer is chosen randomly from the range `[1..MOD]' and returned. If MOD is not provided, it defaults to the largest MOO integer, 2147483647. - Function: num min (num X, ...) - Function: num max (num X, ...) These two functions return the smallest or largest of their arguments, respectively. All of the arguments must be numbers of the same kind (i.e., either integer or floating-point); otherwise `E_TYPE' is raised. - Function: num abs (num X) Returns the absolute value of X. If X is negative, then the result is `-X'; otherwise, the result is X. The number X can be either integer or floating-point; the result is of the same kind. - Function: str floatstr(float X, int PRECISION [, SCIENTIFIC]) Converts X into a string with more control than provided by either `tostr()' or `toliteral()'. PRECISION is the number of digits to appear to the right of the decimal point, capped at 4 more than the maximum available precision, a total of 19 on most machines; this makes it possible to avoid rounding errors if the resulting string is subsequently read back as a floating-point value. If SCIENTIFIC is false or not provided, the result is a string in the form `"MMMMMMM.DDDDDD"', preceded by a minus sign if and only if X is negative. If SCIENTIFIC is provided and true, the result is a string in the form `"M.DDDDDDe+EEE"', again preceded by a minus sign if and only if X is negative. - Function: float sqrt (float X) Returns the square root of X. Raises `E_INVARG' if X is negative. - Function: float sin (float X) - Function: float cos (float X) - Function: float tan (float X) Returns the sine, cosine, or tangent of X, respectively. - Function: float asin (float X) - Function: float acos (float X) Returns the arc-sine or arc-cosine (inverse sine or cosine) of X, in the range `[-pi/2..pi/2]' or `[0..pi]', respectively. Raises `E_INVARG' if X is outside the range `[-1.0..1.0]'. - Function: float atan (float Y [, float X]) Returns the arc-tangent (inverse tangent) of Y in the range `[-pi/2..pi/2]' if X is not provided, or of `Y/X' in the range `[-pi..pi]' if X is provided. - Function: float sinh (float X) - Function: float cosh (float X) - Function: float tanh (float X) Returns the hyperbolic sine, cosine, or tangent of X, respectively. - Function: float exp (float X) Returns E raised to the power of X. - Function: float log (float X) - Function: float log10 (float X) Returns the natural or base 10 logarithm of X. Raises `E_INVARG' if X is not positive. - Function: float ceil (float X) Returns the smallest integer not less than X, as a floating-point number. - Function: float floor (float X) Returns the largest integer not greater than X, as a floating-point number. - Function: float trunc (float X) Returns the integer obtained by truncating X at the decimal point, as a floating-point number. For negative X, this is equivalent to `ceil()'; otherwise it is equivalent to `floor()'. Operations on Strings ..................... - Function: int length (str STRING) Returns the number of characters in STRING. It is also permissible to pass a list to `length()'; see the description in the next section. length("foo") => 3 length("") => 0 - Function: str strsub (str SUBJECT, str WHAT, str WITH [, CASE-MATTERS]) Replaces all occurrences in SUBJECT of WHAT with WITH, performing string substitution. The occurrences are found from left to right and all substitutions happen simultaneously. By default, occurrences of WHAT are searched for while ignoring the upper/lower case distinction. If CASE-MATTERS is provided and true, then case is treated as significant in all comparisons. strsub("%n is a fink.", "%n", "Fred") => "Fred is a fink." strsub("foobar", "OB", "b") => "fobar" strsub("foobar", "OB", "b", 1) => "foobar" - Function: int index (str STR1, str STR2 [, CASE-MATTERS]) - Function: int rindex (str STR1, str STR2 [, CASE-MATTERS]) The function `index()' (`rindex()') returns the index of the first character of the first (last) occurrence of STR2 in STR1, or zero if STR2 does not occur in STR1 at all. By default the search for an occurrence of STR2 is done while ignoring the upper/lower case distinction. If CASE-MATTERS is provided and true, then case is treated as significant in all comparisons. index("foobar", "o") => 2 rindex("foobar", "o") => 3 index("foobar", "x") => 0 index("foobar", "oba") => 3 index("Foobar", "foo", 1) => 0 - Function: int strcmp (str STR1, str STR2) Performs a case-sensitive comparison of the two argument strings. If STR1 is lexicographically less than STR2, the `strcmp()' returns a negative integer. If the two strings are identical, `strcmp()' returns zero. Otherwise, `strcmp()' returns a positive integer. The ASCII character ordering is used for the comparison. - Function: list decode_binary (str BIN-STRING [, FULLY]) Returns a list of strings and/or integers representing the bytes in the binary string BIN_STRING in order. If FULLY is false or omitted, the list contains an integer only for each non-printing, non-space byte; all other characters are grouped into the longest possible contiguous substrings. If FULLY is provided and true, the list contains only integers, one for each byte represented in BIN_STRING. Raises `E_INVARG' if BIN_STRING is not a properly-formed binary string. (See the early section on MOO value types for a full description of binary strings.) decode_binary("foo") => {"foo"} decode_binary("~~foo") => {"~foo"} decode_binary("foo~0D~0A") => {"foo", 13, 10} decode_binary("foo~0Abar~0Abaz") => {"foo", 10, "bar", 10, "baz"} decode_binary("foo~0D~0A", 1) => {102, 111, 111, 13, 10} - Function: str encode_binary (ARG, ...) Each argument must be an integer between 0 and 255, a string, or a list containing only legal arguments for this function. This function translates each integer and string in turn into its binary string equivalent, returning the concatenation of all these substrings into a single binary string. (See the early section on MOO value types for a full description of binary strings.) encode_binary("~foo") => "~7Efoo" encode_binary({"foo", 10}, {"bar", 13}) => "foo~0Abar~0D" encode_binary("foo", 10, "bar", 13) => "foo~0Abar~0D" - Function: list match (str SUBJECT, str PATTERN [, CASE-MATTERS]) - Function: list rmatch (str SUBJECT, str PATTERN [, CASE-MATTERS]) The function `match()' (`rmatch()') searches for the first (last) occurrence of the regular expression PATTERN in the string SUBJECT. If PATTERN is syntactically malformed, then `E_INVARG' is raised. The process of matching can in some cases consume a great deal of memory in the server; should this memory consumption become excessive, then the matching process is aborted and `E_QUOTA' is raised. If no match is found, the empty list is returned; otherwise, these functions return a list containing information about the match (see below). By default, the search ignores upper-/lower-case distinctions. If CASE-MATTERS is provided and true, then case is treated as significant in all comparisons. The list that `match()' (`rmatch()') returns contains the details about the match made. The list is in the form: {START, END, REPLACEMENTS, SUBJECT} where START is the index in SUBJECT of the beginning of the match, END is the index of the end of the match, REPLACEMENTS is a list described below, and SUBJECT is the same string that was given as the first argument to the `match()' or `rmatch()'. The REPLACEMENTS list is always nine items long, each item itself being a list of two integers, the start and end indices in STRING matched by some parenthesized sub-pattern of PATTERN. The first item in REPLACEMENTS carries the indices for the first parenthesized sub-pattern, the second item carries those for the second sub-pattern, and so on. If there are fewer than nine parenthesized sub-patterns in PATTERN, or if some sub-pattern was not used in the match, then the corresponding item in REPLACEMENTS is the list {0, -1}. See the discussion of `%)', below, for more information on parenthesized sub-patterns. match("foo", "^f*o$") => {} match("foo", "^fo*$") => {1, 3, {{0, -1}, ...}, "foo"} match("foobar", "o*b") => {2, 4, {{0, -1}, ...}, "foobar"} rmatch("foobar", "o*b") => {4, 4, {{0, -1}, ...}, "foobar"} match("foobar", "f%(o*%)b") => {1, 4, {{2, 3}, {0, -1}, ...}, "foobar"} "Regular expression" matching allows you to test whether a string fits into a specific syntactic shape. You can also search a string for a substring that fits a pattern. A regular expression describes a set of strings. The simplest case is one that describes a particular string; for example, the string `foo' when regarded as a regular expression matches `foo' and nothing else. Nontrivial regular expressions use certain special constructs so that they can match more than one string. For example, the regular expression `foo%|bar' matches either the string `foo' or the string `bar'; the regular expression `c[ad]*r' matches any of the strings `cr', `car', `cdr', `caar', `cadddar' and all other such strings with any number of `a''s and `d''s. Regular expressions have a syntax in which a few characters are special constructs and the rest are "ordinary". An ordinary character is a simple regular expression that matches that character and nothing else. The special characters are `$', `^', `.', `*', `+', `?', `[', `]' and `%'. Any other character appearing in a regular expression is ordinary, unless a `%' precedes it. For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does *not*, for example, match the string `ff'.) Likewise, `o' is a regular expression that matches only `o'. Any two regular expressions A and B can be concatenated. The result is a regular expression which matches a string if A matches some amount of the beginning of that string and B matches the rest of the string. As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial. The following are the characters and character sequences that have special meaning within regular expressions. Any character not mentioned here is not special; it stands for exactly itself for the purposes of searching and matching. `.' is a special character that matches any single character. Using concatenation, we can make regular expressions like `a.b', which matches any three-character string that begins with `a' and ends with `b'. `*' is not a construct by itself; it is a suffix that means that the preceding regular expression is to be repeated as many times as possible. In `fo*', the `*' applies to the `o', so `fo*' matches `f' followed by any number of `o''s. The case of zero `o''s is allowed: `fo*' does match `f'. `*' always applies to the *smallest* possible preceding expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. The matcher processes a `*' construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, it backtracks, discarding some of the matches of the `*''d construct in case that makes it possible to match the rest of the pattern. For example, matching `c[ad]*ar' against the string `caddaar', the `[ad]*' first matches `addaa', but this does not allow the next `a' in the pattern to match. So the last of the matches of `[ad]' is undone and the following `a' is tried again. Now it succeeds. `+' `+' is like `*' except that at least one match for the preceding pattern is required for `+'. Thus, `c[ad]+r' does not match `cr' but does match anything else that `c[ad]*r' would match. `?' `?' is like `*' except that it allows either zero or one match for the preceding pattern. Thus, `c[ad]?r' matches `cr' or `car' or `cdr', and nothing else. `[ ... ]' `[' begins a "character set", which is terminated by a `]'. In the simplest case, the characters between the two brackets form the set. Thus, `[ad]' matches either `a' or `d', and `[ad]*' matches any string of `a''s and `d''s (including the empty string), from which it follows that `c[ad]*r' matches `car', etc. Character ranges can also be included in a character set, by writing two characters with a `-' between them. Thus, `[a-z]' matches any lower-case letter. Ranges may be intermixed freely with individual characters, as in `[a-z$%.]', which matches any lower case letter or `$', `%' or period. Note that the usual special characters are not special any more inside a character set. A completely different set of special characters exists inside character sets: `]', `-' and `^'. To include a `]' in a character set, you must make it the first character. For example, `[]a]' matches `]' or `a'. To include a `-', you must use it in a context where it cannot possibly indicate a range: that is, as the first character, or immediately after a range. `[^ ... ]' `[^' begins a "complement character set", which matches any character except the ones specified. Thus, `[^a-z0-9A-Z]' matches all characters *except* letters and digits. `^' is not special in a character set unless it is the first character. The character following the `^' is treated as if it were first (it may be a `-' or a `]'). `^' is a special character that matches the empty string - but only if at the beginning of the string being matched. Otherwise it fails to match anything. Thus, `^foo' matches a `foo' which occurs at the beginning of the string. `$' is similar to `^' but matches only at the *end* of the string. Thus, `xx*$' matches a string of one or more `x''s at the end of the string. `%' has two functions: it quotes the above special characters (including `%'), and it introduces additional special constructs. Because `%' quotes special characters, `%$' is a regular expression that matches only `$', and `%[' is a regular expression that matches only `[', and so on. For the most part, `%' followed by any character matches only that character. However, there are several exceptions: characters that, when preceded by `%', are special constructs. Such characters are always ordinary when encountered on their own. No new special characters will ever be defined. All extensions to the regular expression syntax are made by defining new two-character constructs that begin with `%'. `%|' specifies an alternative. Two regular expressions A and B with `%|' in between form an expression that matches anything that either A or B will match. Thus, `foo%|bar' matches either `foo' or `bar' but no other string. `%|' applies to the largest possible surrounding expressions. Only a surrounding `%( ... %)' grouping can limit the grouping power of `%|'. Full backtracking capability exists for when multiple `%|''s are used. `%( ... %)' is a grouping construct that serves three purposes: 1. To enclose a set of `%|' alternatives for other operations. Thus, `%(foo%|bar%)x' matches either `foox' or `barx'. 2. To enclose a complicated expression for a following `*', `+', or `?' to operate on. Thus, `ba%(na%)*' matches `bananana', etc., with any number of `na''s, including none. 3. To mark a matched substring for future reference. This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that happens to be assigned as a second meaning to the same `%( ... %)' construct because there is no conflict in practice between the two meanings. Here is an explanation of this feature: `%DIGIT' After the end of a `%( ... %)' construct, the matcher remembers the beginning and end of the text matched by that construct. Then, later on in the regular expression, you can use `%' followed by DIGIT to mean "match the same text matched by the DIGIT'th `%( ... %)' construct in the pattern." The `%( ... %)' constructs are numbered in the order that their `%(''s appear in the pattern. The strings matching the first nine `%( ... %)' constructs appearing in a regular expression are assigned numbers 1 through 9 in order of their beginnings. `%1' through `%9' may be used to refer to the text matched by the corresponding `%( ... %)' construct. For example, `%(.*%)%1' matches any string that is composed of two identical halves. The `%(.*%)' matches the first half, which may be anything, but the `%1' that follows must match the same exact text. `%b' matches the empty string, but only if it is at the beginning or end of a word. Thus, `%bfoo%b' matches any occurrence of `foo' as a separate word. `%bball%(s%|%)%b' matches `ball' or `balls' as a separate word. For the purposes of this construct and the five that follow, a word is defined to be a sequence of letters and/or digits. `%B' matches the empty string, provided it is *not* at the beginning or end of a word. `%<' matches the empty string, but only if it is at the beginning of a word. `%>' matches the empty string, but only if it is at the end of a word. `%w' matches any word-constituent character (i.e., any letter or digit). `%W' matches any character that is not a word constituent. - Function: str substitute (str TEMPLATE, list SUBS) Performs a standard set of substitutions on the string TEMPLATE, using the information contained in SUBS, returning the resulting, transformed TEMPLATE. SUBS should be a list like those returned by `match()' or `rmatch()' when the match succeeds; otherwise, `E_INVARG' is raised. In TEMPLATE, the strings `%1' through `%9' will be replaced by the text matched by the first through ninth parenthesized sub-patterns when `match()' or `rmatch()' was called. The string `%0' in TEMPLATE will be replaced by the text matched by the pattern as a whole when `match()' or `rmatch()' was called. The string `%%' will be replaced by a single `%' sign. If `%' appears in TEMPLATE followed by any other character, `E_INVARG' will be raised. subs = match("*** Welcome to LambdaMOO!!!", "%(%w*%) to %(%w*%)"); substitute("I thank you for your %1 here in %2.", subs) => "I thank you for your Welcome here in LambdaMOO." - Function: str crypt (str TEXT [, str SALT]) Encrypts the given TEXT using the standard UNIX encryption method. If provided, SALT should be a string at least two characters long, the first two characters of which will be used as the extra encryption "salt" in the algorithm. If SALT is not provided, a random pair of characters is used. In any case, the salt used is also returned as the first two characters of the resulting encrypted string. Aside from the possibly-random selection of the salt, the encryption algorithm is entirely deterministic. In particular, you can test whether or not a given string is the same as the one used to produce a given piece of encrypted text; simply extract the first two characters of the encrypted text and pass the candidate string and those two characters to `crypt()'. If the result is identical to the given encrypted text, then you've got a match. crypt("foobar") => "J3fSFQfgkp26w" crypt("foobar", "J3") => "J3fSFQfgkp26w" crypt("mumble", "J3") => "J3D0.dh.jjmWQ" crypt("foobar", "J4") => "J4AcPxOJ4ncq2" - Function: str string_hash (str TEXT) - Function: str binary_hash (str BIN-STRING) Returns a 32-character hexadecimal string encoding the result of applying the MD5 cryptographically secure hash function to the contents of the string TEXT or the binary string BIN-STRING. MD5, like other such functions, has the property that, if string_hash(X) == string_hash(Y) then, almost certainly, equal(X, Y) This can be useful, for example, in certain networking applications: after sending a large piece of text across a connection, also send the result of applying `string_hash()' to the text; if the destination site also applies `string_hash()' to the text and gets the same result, you can be quite confident that the large text has arrived unchanged. Operations on Lists ................... - Function: int length (list LIST) Returns the number of elements in LIST. It is also permissible to pass a string to `length()'; see the description in the previous section. length({1, 2, 3}) => 3 length({}) => 0 - Function: int is_member (VALUE, list LIST) Returns true if there is an element of LIST that is completely indistinguishable from VALUE. This is much the same operation as "`VALUE in LIST'" except that, unlike `in', the `is_member()' function does not treat upper- and lower-case characters in strings as equal. "Foo" in {1, "foo", #24} => 2 is_member("Foo", {1, "foo", #24}) => 0 is_member("Foo", {1, "Foo", #24}) => 2 - Function: list listinsert (list LIST, VALUE [, int INDEX]) - Function: list listappend (list LIST, VALUE [, int INDEX]) These functions return a copy of LIST with VALUE added as a new element. `listinsert()' and `listappend()' add VALUE before and after (respectively) the existing element with the given INDEX, if provided. The following three expressions always have the same value: listinsert(LIST, ELEMENT, INDEX) listappend(LIST, ELEMENT, INDEX - 1) {@LIST[1..INDEX - 1], ELEMENT, @LIST[INDEX..length(LIST)]} If INDEX is not provided, then `listappend()' adds the VALUE at the end of the list and `listinsert()' adds it at the beginning; this usage is discouraged, however, since the same intent can be more clearly expressed using the list-construction expression, as shown in the examples below. x = {1, 2, 3};