lambda-moo-programming/tutorials/src/moo-programmers-manual-updated.html at master · sevenecks/lambda-moo-programming · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
    <title>LambdaMOO Programmer's Manual</title>
    <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Source+Code+Pro|Quantico:400,400italic,700" />
    <link rel="stylesheet" href="//www.sindome.org/css/dome.css" />
</head>
<body style="padding-left: 30px; padding-right: 30px;">
<h1 id="lambdamoo-programmers-manual">LambdaMOO Programmer's Manual</h1>
<h2 id="for-lambdamoo-version-1.8">For LambdaMOO Version 1.8.*</h2>
<p>Originally written <time datetime="1997-03-01 16:00">March, 1997</time>:</p>
<address>by Pavel Curtis, aka Haakon, aka Lambda</address>
<p>Updated <time datetime="2019-06-02 14:00">June, 2019</time> (<a href="https://github.com/SevenEcks/lambda-moo-programming/blob/master/CHANGELOG.md" target="_blank">CHANGE LOG</a>):
<address>By <a href="http://github.com/sevenecks" target="_blank">Brendan Butts</a>, aka Slither, aka Fengshui</address>
<h2>Versions of This Document</h2>
<p>I highly recommend you use the Hosted HTML5 version of this document for anything more than quick references. It is better styled and easier to read. The markdown version exists as for 'quick reference' purposes.</p>
<ul>
    <li><a href="https://github.com/SevenEcks/lambda-moo-programming/blob/master/tutorials/moo-programmers-manual-updated.md">GitHub Markdown Version</a></li>
    <li><a href="https://www.sindome.org/moo-manual.html">Hosted HTML5 Version</a></li>
</ul>
<p>For older versions of this document please see the resources section.</p>
<h2>Table of Contents</h2>
<ul>
    <li><a href="#foreword">Foreword</a></li>
    <li><a href="#lambdamoo-resources">LambdaMOO Resources</a></li>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#lambdamoo-database">The LambdaMOO Database</a></li>
    <li>
        <ul>
            <li><a href="#moo-value-types">MOO Value Types</a></li>
            <li><a href="#objects-in-the-moo-database">Objects in the MOO Database</a></li>
            <li>
                <ul>
                    <li><a href="#fundamental-object-attributes">Fundamental Object Attributes</a></li>
                    <li><a href="#properties-on-objects">Properties on Objects</a></li>
                    <li><a href="#verbs-on-objects">Verbs on Objects</a></li>
                </ul>
            </li>
        </ul>
    </li>
    <li><a href="#the-built-in-command-parser">The Built-in Command Parser</a></li>
    <li><a href="#the-moo-programming-language">The MOO Programming Language</a></li>
    <li>
        <ul>
            <li><a href="#moo-language-expressions">MOO Language Expressions</a></li>
            <li>
                <ul>
                    <li><a href="#errors-while_evaluating-expressions">Errors While Evaluating Expressions</a></li>
                    <li><a href="#writing-values-directly-in-verbs">Writing Values Directly in Verbs</a></li>
                    <li><a href="#naming-values-within-a-verb">Naming Values Within a Verb</a></li>
                    <li><a href="#arithmetic-operators">Arithmetic Operators</a></li>
                    <li><a href="#comparing-values">Comparing Values</a></li>
                    <li><a href="#values-as-true-or-false">Values as True and False</a></li>
                    <li><a href="#indexing-into-lists-and-strings">Indexing into Lists and Strings</a></li>
                    <li>
                        <ul>
                            <li><a href="#extracting-an-element-from-a-list-or-string">Extracting an Element from a List or String</a></li>
                            <li><a href="#extracting-a-subsequence-of-a-list-or-string">Extracting a Subsequence of a List or String</a></li>
                            <li><a href="#replacing-a-subsequence-of-a-list-or-string">Replacing a Subsequence of a List or String</a></li>
                        </ul>
                    </li>
                </ul>
            </li>
            <li><a href="#other-operations-on-lists">Other Operations on Lists</a></li>
            <li><a href="#spreading-list-elements-among-variables">Spreading List Elements Among Variables</a></li>
            <li><a href="#getting-and-setting-the-values-of-properties">Getting and Setting the Values of Properties</a></li>
            <li><a href="#calling-built-in-functions-and-other-verbs">Calling Built-in Functions and Other Verbs</a></li>
            <li><a href="#catching-errors-in-expressions">Catching Errors in Expressions</a></li>
            <li><a href="#parentheses-and-operator-precedence">Parentheses and Operator Precedence</a></li>
        </ul>
        </li>
        <li><a href="#moo-langauge-statements">MOO Language Statements</a></li>
            <li>
                <ul>
                    <li><a href="#errors-while-executing-statements">Errors While Executing Statements</a></li>
                    <li><a href="#simple-statements">Simple Statements</a></li>
                    <li><a href="#statements-for-testing-conditionals">Statements for Testing Conditions</a></li>
                    <li><a href="#statements-for-looping">Statements for Looping</a></li>
                    <li>
                        <ul>
                            <li><a href="#the-for-in-loop">The for-in loop</a></li>
                            <li><a href="#the-for-range-loop">The For-Range Loop</a></li>
                            <li><a href="#the-while-loop">The While Loop</a></li>
                        </ul>
                    </li>
                    <li><a href="#terminating-one-or-all-iterations-of-a-loop">Terminating One or All Iterations of a Loop</a></li>
                    <li><a href="#returning-a-value-from-a-verb">Returning a Value from a Verb</a></li>
                    <li><a href="#returning-a-value-from-a-verb">Returning a Value from a Verb</a></li>
                    <li><a href="#handling-errors-in-statements">Handling Errors in Statements</a></li>
                    <li><a href="#cleaning-up-after-errors">Cleaning Up After Errors</a></li>
                    <li><a href="#executing-statements-at-a-later-time">Executing Statements at a Later Time</a></li>
                </ul>
            </li>
        <li><a href="#moo-tasks">MOO Tasks</a></li>
        <li><a href="#built-in-functions">Built-in Functions</a></li>
            <li>
                <ul>
                <li><a href="#object-oriented-programming">Object-Oriented Programming</a></li>
                <li><a href="#manipulating-moo-values">Manipulating MOO Values</a></li>
                <li>
                    <ul>
                        <li><a href="#general-operations-applicable-to-all-values">General Operations Applicable to all Values</a></li>
                        <li><a href="#operations-on-numbers">Operations on Numbers</a></li>
                        <li><a href="#regular-expressions">Regular Expressions</a></li>
                        <li><a href="#operations-on-strings">Operations on Strings</a></li>
                    </ul>
                </li>
                <li><a href="#manipulating-objects">Manipulating Objects</a></li>
                <li>
                    <ul>
                        <li><a href="#fundamental-operations-on-objects">Fundamental Operations on Objects</a></li>
                        <li><a href="#object-movement">Object Movement</a></li>
                        <li><a href="#operations-on-properties">Operations on Properties</a></li>
                        <li><a href="#operations-on-player-objects">Operations on Player Objects</a></li>
                        <li><a href="#operations-on-network-connections">Operations on Network Connections</a></li>
                        <li><a href="#operations-involving-times-and-dates">Operations Involving Times and Dates</a></li>
                        <li><a href="#moo-code-evaluation-and-task-management">MOO-Code Evaluation and Task Manipulation</a></li>
                        <li><a href="#administrative-questions">Administrative Operations</a></li>
                    </ul>
                </li>
            </ul>
        </li>
        <li><a href="#server-commands-and-database-assumptions">Server Commands and Database Assumptions</a></li>
        <li>
            <ul>
                <li><a href="#bult-in-commands">Built-in Commands</a></li>
                <li><a href="#command-output-delimiters">Command-Output Delimiters</a></li>
                <li><a href="#programming">Programming</a></li>
                <li><a href="#flushing-unprocessed-input">Flushing Unprocessed Input</a></li>
                <li><a href="#initial-punctuation-in-commands">Initial Punctuation in Commands</a></li>
            </ul>
        </li>
        <li><a href="#server-assumptions-about-the-database">Server Assumptions About the Database</a></li>
        <li>
            <ul>
                <li><a href="#server-options-set-in-the-database">Server Options Set in the Database</a></li>
                <li><a href="#server-messages-set-in-the-database">Server Messages Set in the Database</a></li>
                <li><a href="#checkpointing-the-database">Checkpointing the Database</a></li>
            </ul>
        </li>
        <li><a href="#networking">Networking</a></li>
        <li>
            <ul>
                <li><a href="#accepting-and-initiating-network-connections">Accepting and Initiating Network Connections</a></li>
                <li><a href="#associating-network-connections-with-playes">Associating Network Connections with Players</a></li>
            </ul>
        </li>
        <li><a href="#the-first-tasks-run-by-the-server">The First Tasks Run By the Server</a></li>
        <li><a href="#controlling-the-execution-of-tasks">Controlling the Execution of Tasks</a></li>
        <li><a href="#controlling-the-handling-of-aborted-tasks">Controlling the Handling of Aborted Tasks</a></li>
        <li><a href="#matching-in-command-parsing">Matching in Command Parsing</a></li>
        <li><a href="#restricting-accessing-to-built-in-properties-and-functions">Restricting Access to Built-in Properties and Functions</a></li>
        <li><a href="#creating-and-recycling-objects">Creating and Recycling Objects</a></li>
        <li><a href="#object-movement-caveats">Object Movement Caveats</a></li>
        <li><a href="#temporarily-enabling-obsolete-server-features">Temporarily Enabling Obsolete Server Features</a></li>
</ul>
<hr>
<h2 id="foreword">Foreword</h2>
<p>Hey, it's me: Brendan. The guy updating this document. The idea of updating the MOO Programming Manual has crossed my mind a few times. It's a bit of a daunting task. This document is pretty comprehensive and I'm endeavouring to make it even more so. I'm adding some much needed styling so that it looks more modern.  Things were once hosted primarily on FTP servers and we now have GitHub, so many links and resources mentioned in this document have been updated and I've even added some additional ones.</p>
<p>If you want an up to date manual on MOO, this is the guide for you. If you want to read the historic document which contains the unedited text, I recommend reviewing the links toward the top of the page that point to unedited versions of the guide.</p>
<h2 id="lambdamoo-resources">LambdaMOO Resources</h2>
<ul>
    <li><a href="https://github.com/SevenEcks/lambda-moo-programming" target="_blank">Lambda MOO Programming Resources GitHub</a>
    <li><a href="http://www.lisdude.com/moo/" target="_blank">lisdude MOO resources</a></li>
    <li><a href="http://www.hayseed.net/MOO/manuals/ProgrammersManual.html" target="_blank">Unedited MOO Programmers Manual</a></li>
    <li><a href="http://www2.iath.virginia.edu/courses/moo/ProgrammersManual.texinfo_toc.html" target="_blank">Older Unedited MOO Programmers Mnaual</a></li>
    <li><a href="https://github.com/SevenEcks/LambdaMOO" target="_blank">LambdaMOO Source (github)</a></li>
    <li><a href="http://lambda.moo.mud.org/pub/MOO/" target="_blank">LambdaMOO Databases (and other resources)</a></li>
    <li><a href="https://groups.google.com/forum/#!forum/MOO-talk" target="_blank">MOO Talk Mailing List</a></li>
    <li><a href="https://github.com/JavaChilly/dome-client.js" target="_blank">Dome Client Web Socket MOO Client</a></li>
</ul>
<h2 id="introduction">Introduction</h2>
<p>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.</p>
<p>Participants (usually referred to as <em>players</em>) connect to LambdaMOO using Telnet or some other, more specialized, <em>client</em> program. Upon connection, they are usually presented with a <em>welcome message</em> explaining how to either create a new <em>character</em> or connect to an existing one.  Characters are the embodiment of players in the virtual reality that is LambdaMOO.</p>
<div class="well">
    <span class="label label-info">Note:</span> No one really connects to a MOO over telnet these days. MOO Clients and MUD Clients are relatively common. See the resources section for more information on these. There are even some web based clients (dome-client) out there that use websockets to connect to a MOO directly from the browser.
</div>
<p>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.</p>
<p>The job of interpreting those commands is shared between the two major components in the LambdaMOO system: the <em>server</em> and the <em>database</em>.  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.</p>
<p>Almost every command is parsed by the server into a call on a MOO procedure, or <em>verb</em>, 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.</p>
<p>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.</p>
<div class="well">
    <span class="label label-info">Note:</span> For the most part, 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. There are exceptions to this, for situations where it seems prudent to delve deeper into these areas.
</div>
<h2 id="lambdamoo-database">The LambdaMOO Database</h2>
<p>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 <em>LambdaCore</em> database. This is one particular LambdaMOO database, created every so often by extracting the "core" of the current database for the original LambdaMOO.</p>
<div class="well">
    <span class="label label-info">Note:</span> The original LambdaMOO resides on the host <span class="cmd">lambda.parc.xerox.com</span> (the numeric address for which is <span class="cmd">192.216.54.2</span>), 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 <span class="cmd">ftp.parc.xerox.com</span> in the directory <span class="cmd">pub/MOO</span>.
</div>
<div class="alert alert-info">
    The above information may be out of date, but the most recent dump of the <em>LambdaCore</em> can be found <a href="http://lambda.moo.mud.org/pub/MOO/" target="_blank">here</a>.
</div>
<h3 id="moo-value-types">MOO Value Types</h3>
<p>There are only a few kinds of values that MOO programs can manipulate:
<ul>
    <li>integers (in a specific, large range)</li>
    <li>real numbers (represented with floating-point numbers)</li>
    <li>strings (of characters)</li>
    <li>objects (in the virtual reality)</li>
    <li>errors (arising during program execution)</li>
    <li>lists (of all of the above, including lists)</li>
</ul>
<p>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').</p>
<p>Real numbers in MOO are represented as they are in almost all other programming languages, using so-called <em>floating-point</em> 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:</p>
<pre>325.0   325.  3.25e2   0.325E3   325.E1   .0325e+4   32500e-2</pre>
<p>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".</p>
<div class="well">
    <span class="label label-info">Fine point:</span> The MOO represents floating-point numbers using the local meaning of the C-language <span class="cmd">double</span> 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 <span class="cmd">2.2250738585072014e-308</span> and the largest floating-point number is <span class="cmd">1.7976931348623157e+308</span>.
        <ul>
            <li>IEEE infinities and NaN values are not allowed in MOO.</li>
            <li>The error <span class="cmd">E_FLOAT</span> is raised whenever an infinity would otherwise be computed.</li>
            <li>The error <span class="cmd">E_INVARG</span> is raised whenever a NaN would otherwise arise.</li>
            <li>The value <span class="cmd">0.0</span> is always returned on underflow.</li>
    </ul>
</div>
<p>Character <em>strings</em> are arbitrarily-long sequences of normal, ASCII printing characters. When written as values in a program, strings are enclosed in double-quotes, like this:</p>
<pre>"This is a character string."</pre>
<p>To include a double-quote in the string, precede it with a backslash (<span class="cmd">\</span>), like this:
<pre>"His name was \"Leroy\", but nobody ever called him that."</pre>
<p>Finally, to include a backslash in a string, double it:</p>
<pre>"Some people use backslash ('\\') to mean set difference."</pre>
<p>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.</p>
<div class="well">
    <span class="label label-info">Fine point:</span> There is a special kind of string used for representing the arbitrary bytes used in general, binary input and output. In a <em>binary string</em>, 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 <span class="cmd">encode_binary()</span> and <span class="cmd">decode_binary()</span> and by the functions <span class="cmd">notify()</span> and <span class="cmd">read()</span> with network connections that are in binary mode. See the descriptions of the <span class="cmd">set_connection_option()</span>, <span class="cmd">encode_binary()</span>, and <span class="cmd">decode_binary()</span> functions for more details.
</div>
<p><em>Objects</em> 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.</p>
<p>In programs, we write a reference to a particular object by putting a hash mark (<span class="cmd">#</span>) followed by the number, like this:</p>
<pre>#495</pre>
<div class="well">
    <span class="label label-info">Note:</span> Referencing object numbers in your code should be discouraged. An object only exists until it is recycled. It is technically possible for an object number to change under some circumstances. Thus, you should use a corified reference to an object ($my_special_object) instead. More on corified references later.
</div>
<p>Object numbers are always integers.</p>
<p>There are three special object numbers used for a variety of purposes: <span class="cmd">#-1</span>, <span class="cmd">#-2</span>, and <span class="cmd">#-3</span>, usually referred to in the LambdaCore database as <span class="cmd">$nothing</span>, <span class="cmd">$ambiguous_match</span>, and <span class="cmd">$failed_match</span>, respectively.</p>
<p><em>Errors</em> 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 <span class="cmd">E_</span>. The complete list of error values, along with their associated messages, is as follows:</p>
<dl class="dl-horizontal">
    <dt>E_NONE</dt>
    <dd>No error</dd>
    <dt>E_TYPE</dt>
    <dd>Type mismatch</dd>
    <dt>E_DIV</dt>
    <dd>Division by zero</dd>
    <dt>E_PERM</dt>
    <dd>Permission denied</dd>
    <dt>E_PROPNF</dt>
    <dd>Property not found</dd>
    <dt>E_VERBNF</dt>
    <dd>Verb not found</dd>
    <dt>E_VARNF</dt>
    <dd>Variable not found</dd>
    <dt>E_INVIND</dt>
    <dd>Invalid indirection</dd>
    <dt>E_RECMOVE</dt>
    <dd>Recursive move</dd>
    <dt>E_MAXREC</dt>
    <dd>Too many verb calls</dd>
    <dt>E_RANGE</dt>
    <dd>Range error</dd>
    <dt>E_ARGS</dt>
    <dd>Incorrect number of arguments</dd>
    <dt>E_NACC</dt>
    <dd>Move refused by destination</dd>
    <dt>E_INVARG</dt>
    <dd>Invalid argument</dd>
    <dt>E_QUOTA</dt>
    <dd>Resource limit exceeded</dd>
    <dt>E_FLOAT</dt>
    <dd>Floating-point arithmetic error</dd>
</dl>
<div class="well">
    <span class="label label-info">Note:</span> The MOO can be extended using extensions. These are plugins that usually contain patch files that are applied directly to your LambdaMOO source code. One very popular extension is the FileIO plugin, which allows you to read and write files to disk. Extensions can throw their own errors, though it's not as common. Old versions of FileIO threw a fake error "E_FILE", though a recently updated version throws true E_FILE errors.
</div>
<p>The final kind of value in MOO programs is <em>lists</em>. 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 (<span class="cmd">{</span> and <span class="cmd">}</span>). For example, a list of the names of the days of the week is written like this:</p>
<pre>{"Sunday", "Monday", "Tuesday", "Wednesday",
 "Thursday", "Friday", "Saturday"}
</pre>
<div class="well">
    <span class="label label-info">Note:</span> 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.
</div>
<h3 id="objects-in-the-moo-database">Objects in the MOO Database</h3>
<p>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.</p>
<p>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 <span class="cmd">#958</span> does not exist just because you write down its number. An explicit operation, the <span class="cmd">create()</span> 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 <span class="cmd">recycle()</span> function (also described later).</p>
<p>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 <span class="cmd">#1076</span>, the next object to be created will be assigned <span class="cmd">#1077</span>, even if <span class="cmd">#1076</span> is destroyed in the meantime.</p>
<div class="alert alert-info">
    The above limitation led to design of systems to manage object reuse. The <span class="cmd">$recycler</span> is one example of such a system. This is <strong>not</strong> present in the <span class="cmd">minimal.db</span> which is included in the LambdaMOO source, however it is present in the latest dump of the <a href="http://lambda.moo.mud.org/pub/MOO/">LambdaCore DB</a> which is the recommended starting point for new development.
</div>
<p>Every object is made up of three kinds of pieces that together define its behavior: <em>attributes</em>, <em>properties</em>, and <em>verbs</em>.</p>
<h4 id="fundamental-object-attributes">Fundamental Object Attributes</h4>
<p>There are three fundamental <em>attributes</em> to every object:</p>
<ol>
    <li>A flag (either true or false) specifying whether or not the object represents a player</li>
    <li>The object that is its <em>parent</em></li>
    <li>A list of the objects that are its <em>children</em>; that is, those objects for which this object is their parent.</li>
</ol>
<p>The act of creating a character sets the player attribute of an object and only a wizard (using the function <span class="cmd">set_player_flag()</span>) can change that setting. Only characters have the player bit set to 1.</p>
<p>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 <em>descendants</em> (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 <em>object-oriented</em> programming. Only the functions <span class="cmd">create()</span>, <span class="cmd">recycle()</span>, <span class="cmd">chparent()</span>, and <span class="cmd">renumber()</span> can change the parent and children attributes.</p>
<h4 id="properties-on-objects">Properties on Objects</h4>
<p>A <em>property</em> 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:</p>
<dl class="dl-horizontal">
    <dt>name</dt>
    <dd>a string, the usual name for this object</dd>
    <dt>owner</dt>
    <dd>an object, the player who controls access to it</dd>
    <dt>location</dt>
    <dd>an object, where the object is in virtual reality</dd>
    <dt>contents</dt>
    <dd>a list of objects, the inverse of <span class="cmd">location</span></dd>
    <dt>programmer</dt>
    <dd>a bit, does the object have programmer rights?</dd>
    <dt>wizard</dt>
    <dd>a bit, does the object have wizard rights?</dd>
    <dt>r</dt>
    <dd>a bit, is the object publicly readable?</dd>
    <dt>w</dt>
    <dd>a bit, is the object publicly writable?</dd>
    <dt>f</dt>
    <dd>a bit, is the object fertile?</dd>
</dl>
<p>The <span class="cmd">name</span> 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 <span class="cmd">name</span> property can only be set by a wizard; this allows the wizards, for example, to check that no two players have the same name.</p>
<p>The <span class="cmd">owner</span> identifies the object that has owner rights to this object, allowing them, for example, to change the <span class="cmd">name</span> property. Only a wizard can change the value of this property.</p>
<p>The <span class="cmd">location</span> and <span class="cmd">contents</span> 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 <span class="cmd">location</span> property.</p>
<p>The <span class="cmd">contents</span> 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 <span class="cmd">move()</span> function is able to change them.</p>
<p>The <span class="cmd">wizard</span> and <span class="cmd">programmer</span> 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.</p>
<p>The <span class="cmd">r</span> 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.</p>
<p>Symmetrically, the <span class="cmd">w</span> bit controls whether or not non-owners can add or delete properties and/or verbs on this object. The <span class="cmd">r</span> and <span class="cmd">w</span> bits can only be set by a wizard or by the owner of the object.</p>
<p>The <span class="cmd">f</span> bit specifies whether or not this object is <em>fertile</em>, 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 <span class="cmd">chparent()</span> built-in function to make this object the parent of an existing object. The <span class="cmd">f</span> bit can only be set by a wizard or by the owner of the object.</p>
<p>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.</p>
<p>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.</p>
<p>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 <em>inheritance</em>. If some object has a property named <span class="cmd">foo</span>, then so will all of its children and thus its children's children, and so on.</p>
<p>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.</p>
<p>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.</p>
<p>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 <span class="cmd">w</span> 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.</p>
<p>The permissions on properties are drawn from this set: <span class="cmd">r</span> (read), <span class="cmd">w</span> (write), and <span class="cmd">c</span> (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 <span class="cmd">c</span> permission bit is a little more complicated.</p>
<p>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 <span class="cmd">c</span> permission bit is "on" by default. If the <span class="cmd">c</span> bit is not on, then the inherited property has the same owner in the child as it does in the parent.</p>
<p>As an example of where this can be useful, the LambdaCore database ensures that every player has a <span class="cmd">password</span> 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 <span class="cmd">r</span> 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, <span class="cmd">""</span>. That is, non-owners cannot read or write the property and, because the <span class="cmd">c</span> 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.</p>
<div class="alert alert-warning">
    <strong>Warning:</strong> The MOO will only hash the first 8 characters of a password. In practice this means that the passwords <span class="cmd">password</span> and <span class="cmd">password12345</span> are exactly the same and either one can be used to login.
</div>
<p>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 <span class="cmd">channel</span> 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 <span class="cmd">channel</span> 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 <span class="cmd">channel</span> property.</p>
<p>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 <span class="cmd">channel</span> property in the generic radio had the <span class="cmd">c</span> permission bit set, the <span class="cmd">channel</span> 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 <span class="cmd">channel</span> property of the generic radio to be just <span class="cmd">r</span>, without the <span class="cmd">c</span> bit, and yduJ made a new radio. This time, when yduJ's radio inherited the <span class="cmd">channel</span> 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.</p>
<h4 id="verbs-on-objects">Verbs on Objects</h4>
<p>The final kind of piece making up an object is <em>verbs</em>. 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 <span class="cmd">put <var>object</var> in <var>container</var></span>.</p>
<p>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 <em>procedures</em> or <em>methods</em> found in some other programming languages.</p>
<div class="alert alert-info">
    <span class="label label-info">Note:</span> There are even more ways to refer to <em>verbs</em> and their counterparts in other programming language: <em>procedure</em>, <em>function</em>, <em>subroutine</em>, <em>subprogram</em>, and <em>method</em> are the primary onces. However, in <em>Object Oriented Programming</em> abbreviated <em>OOP</em> you may primarily know them as methods.
</div>
<p>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.</p>
<p>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.</p>
<div class="alert alert-warning">
    <span class="label label-warning">Warning:</span> This is serious business. The MOO has a variety of checks in place for permissions (at the object, verb and property levels) that are all but ignored when a verb is executing with a wizard's permisisons. You may want to create a non-wizard character and give them the programmer bit, and write much of your code there, leaving the wizard bit for things that actually require access to everything, despite permissions.
</div>
<p>The permission bits on verbs are drawn from this set: <span class="cmd">r</span> (read), <span class="cmd">w</span> (write), <span class="cmd">x</span> (execute), and <span class="cmd">d</span> (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.</p>
<p>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 <span class="cmd">put</span> verb on containers). If the <span class="cmd">x</span> bit is not set, the verb cannot be called from inside a program. The <span class="cmd">x</span> bit is usually set.</p>
<p>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 <span class="cmd">d</span> bit is set, then the server <em>raises</em> an error value; such raised errors can be <em>caught</em> 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 <span class="cmd">d</span> 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.</p>
<div class="well">
    <span class="label label-info">Note:</span> The <span class="cmd">d</span> 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 <span class="cmd">try</span>-<span class="cmd">except</span> statement and the error-catching expression, the <span class="cmd">d</span> bit is no longer useful. All new verbs should have the <span class="cmd">d</span> bit set, using the newer facilities for error handling if desired. Over time, old verbs written assuming the <span class="cmd">d</span> bit would not be set should be changed to use the new facilities instead.
</div>
<p>In addition to an owner and some permission bits, every verb has three <em>argument specifiers</em>, one each for the <span class="cmd">direct object</span>, the <span class="cmd">preposition</span>, and the <span class="cmd">indirect object</span>. The direct and indirect specifiers are each drawn from this set: <span class="cmd">this</span>, <span class="cmd">any</span>, or <span class="cmd">none</span>. The preposition specifier is <span class="cmd">none</span>, <span class="cmd">any</span>, or one of the items in this list:</p>
<ul>
    <li>with/using</li>
    <li>at/to</li>
    <li>in front of</li>
    <li>in/inside/into</li>
    <li>on top of/on/onto/upon</li>
    <li>out of/from inside/from</li>
    <li>over</li>
    <li>through</li>
    <li>under/underneath/beneath</li>
    <li>behind</li>
    <li>beside</li>
    <li>for/about</li>
    <li>is</li>
    <li>as</li>
    <li>off/off of</li>
</ul>
<p>The argument specifiers are used in the process of parsing commands, described in the next chapter.</p>
<h2 id="the-built-in-command-parser">The Built-in Command Parser</h2>
<p>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:</p>
<ul>
    <li><var>verb</var></li>
    <li><var>verb</var> <var>direct-object</var></li>
    <li><var>verb</var> <var>direct-object</var> <var>preposition</var> <var>indirect-object</var></li>
</ul>
<p>Real examples of these forms, meaningful in the LambdaCore database, are as follows:</p>
<pre>
look
take yellow bird
put yellow bird in cuckoo clock
</pre>
<p>Note that English articles (i.e., <span class="cmd">the</span>, <span class="cmd">a</span>, and <span class="cmd">an</span>) are not generally used in MOO commands; the parser does not know that they are not important parts of objects' names.</p>
<p>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.</p>
<p>First, the server checks whether or not the first non-blank character in the command is one of the following:</p>
<ul>
    <li><span class="cmd"><var>"</var></span></li>
    <li><span class="cmd"><var>:</var></span></li>
    <li><span class="cmd"><var>;</var></span></li>
</ul>
<p>If so, that character is replaced by the corresponding command below, followed by a space:</p>
<ul>
    <li><span class="cmd"><var>say</var></span></li>
    <li><span class="cmd"><var>emote</var></span></li>
    <li><span class="cmd"><var>eval</var></span></li>
</ul>
<p>For example this command:</p>
<pre>
"Hi, there.
</pre>
<p>will be treated exactly as if it were as follows:</p>
<pre>
say Hi, there.
</pre>
<p>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 <span class="cmd">foo bar baz</span> would be broken into the words <span class="cmd">foo</span>, <span class="cmd">bar</span>, and <span class="cmd">baz</span>. 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:</p>
<pre>
foo "bar mumble" baz" "fr"otz" bl"o"rt
</pre>
<p>is broken into the words <span class="cmd">foo</span>, <span class="cmd">bar mumble</span>, <span class="cmd">baz frotz</span>, and <span class="cmd">blort</span>.</p>
<p>Finally, to include a double-quote or a backslash in a word, they can be preceded by a backslash, just like in MOO strings.</p>
<p>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:</p>
<ul>
    <li><span class="cmd">.program</span></li>
    <li><span class="cmd">PREFIX</span></li>
    <li><span class="cmd">OUTPUTPREFIX</span></li>
    <li><span class="cmd">SUFFIX</span></li>
    <li><span class="cmd">OUTPUTSUFFIX</span></li>
    <li>or the connection's defined <em>flush</em> command, if any (<span class="cmd">.flush</span> by default).</li>
</ul>
<p>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.</p>
<p>The server next gives code in the database a chance to handle the command. If the verb <span class="cmd">$do_command()</span> exists, it is called with the words of the command passed as its arguments and <span class="cmd">argstr</span> set to the raw command typed by the user. If <span class="cmd">$do_command()</span> 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.</p>
<p>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 <span class="cmd">foo as bar to baz</span>, the server would take <span class="cmd">as</span> as the preposition, not <span class="cmd">to</span>.</p>
<p>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, <span class="cmd">""</span>) and the indirect object is <span class="cmd">"bar to baz"</span>.</p>
<p>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.</p>
<p>The next step is to try to find MOO objects that are named by the direct and indirect object strings.</p>
<p>First, if an object string is empty, then the corresponding object is the special object <span class="cmd">#-1</span> (aka <span class="cmd">$nothing</span> in LambdaCore). If an object string has the form of an object number (i.e., a hash mark (<span class="cmd">#</span>) followed by digits), and the object with that number exists, then that is the named object. If the object string is either <span class="cmd">"me"</span> or <span class="cmd">"here"</span>, then the player object itself or its location is used, respectively.</p>
<div class="alert alert-info">
    <p><span class="label label-info">Note:</span> $nothing is considered a <span class="cmd">corified</span> object.  This means that a <em>property</em> has been created on <span class="cmd">#0</span> named <span class="cmd">nothing</span> with the value of <span class="cmd">#-1</span>. For example (after creating the property): <span class="cmd">;#0.nothing = #-1</span></p>
    <p>This allows you to reference the <span class="cmd">#-1</span> object via it's corified reference of <span class="cmd">$nothing</span>. In practice this can be very useful as you can use corified references in your code (and should!) instead of object numbers.</p>
    <p>Among other benefits this allows you to write your code (which references other objects) once and then swap out the corified reference, pointing to a different object.</p>
    <p>For instance if you have a new errror logging system and you want to replace the old $error_logger reference with your new one, you wont have to find all the references to the old error logger object number in your code. You can just change the property on <span class="cmd">#0</span> to reference the new object.</p>
</div>
<p>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.</p>
<p>The matching done by the server uses the <span class="cmd">aliases</span> 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 <span class="cmd">aliases</span> property, then the empty list is used.  In any case, the value of the <span class="cmd">name</span> property is added to the list for the purposes of matching.</p>
<p>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 <span class="cmd">#-2</span> (aka <span class="cmd">$ambiguous_match</span> in LambdaCore) is used.  If there are no matches, then the special object <span class="cmd">#-3</span> (aka <span class="cmd">$failed_match</span> in LambdaCore) is used.</p>
<p>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:</p>
<ol>
    <li>the player who typed the command</li>
    <li>the room the player is in</li>
    <li>the direct object, if any</li>
    <li>the indirect object, if any.</li>
</ol>
<p>For each of these verbs in turn, it tests if all of the the following are true:</p>
<ul>
    <li>the verb string in the command matches one of the names for the verb</li>
    <li>the direct- and indirect-object values found by matching are allowed by the corresponding <em>argument specifiers</em>
    for the verb</li>
    <li>the preposition string in the command is matched by the <em>preposition specifier</em> for the verb.</li>
</ul>
<p>I'll explain each of these criteria in turn.</p>
<p>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 <span class="cmd">*</span>). In this case, the verb-name matches only itself; that is, the name must be matched exactly.</p>
<p>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 <span class="cmd">foo*bar</span> matches any of the strings <span class="cmd">foo</span>, <span class="cmd">foob</span>, <span class="cmd">fooba</span>, or <span class="cmd">foobar</span>; note that the star itself is not considered part of the name.</p>
<p>If the verb name <em>ends</em> in a star, then it matches any string that begins with the part before the star. For example, the verb-name <span class="cmd">foo*</span> matches any of the strings <span class="cmd">foo</span>, <span class="cmd">foobar</span>, <span class="cmd">food</span>, or <span class="cmd">foogleman</span>, among many others. As a special case, if the verb-name is <span class="cmd">*</span> (i.e., a single star all by itself), then it matches anything at all.</p>
<p>Recall that the argument specifiers for the direct and indirect objects are drawn from the set <span class="cmd">none</span>, <span class="cmd">any</span>, and <span class="cmd">this</span>. If the specifier is <span class="cmd">none</span>, then the corresponding object value must be <span class="cmd">#-1</span> (aka <span class="cmd">$nothing</span> in LambdaCore); that is, it must not have been specified. If the specifier is <span class="cmd">any</span>, then the corresponding object value may be anything at all. Finally, if the specifier is <span class="cmd">this</span>, 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.</p>
<p>Finally, recall that the argument specifier for the preposition is either <span class="cmd">none</span>, <span class="cmd">any</span>, or one of several sets of prepositional phrases, given above. A specifier of <span class="cmd">none</span> matches only if there was no preposition found in the command. A specifier of <span class="cmd">any</span> 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.</p>
<p>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 <span class="cmd">huh</span> 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 <span class="cmd">huh</span> verb to run, it prints an error message like <span class="cmd">I couldn't understand that.</span> and the command is considered complete.</p>
<p>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:</p>
<dl class="dl-horizontal">
    <dt>player</dt>
    <dd>an object, the player who typed the command</dd>
    <dt>this</dt>
    <dd>an object, the object on which this verb was found</dd>
    <dt>caller</dt>
    <dd>an object, the same as <span class="cmd">player</span></dd>
    <dt>verb</dt>
    <dd>a string, the first word of the command</dd>
    <dt>argstr</dt>
    <dd>a string, everything after the first word of the command</dd>
    <dt>args</dt>
    <dd>a list of strings, the words in <span class="cmd">argstr</span></dd>
    <dt>dobjstr</dt>
    <dd>a string, the direct object string found during parsing</dd>
    <dt>dobj</dt>
    <dd>an object, the direct object value found during matching</dd>
    <dt>prepstr</dt>
    <dd>a string, the prepositional phrase found during parsing</dd>
    <dt>iobjstr</dt>
    <dd>a string, the indirect object string</dd>
    <dt>iobj</dt>
    <dd>an object, the indirect object value</dd>
</dl>
<p>The value returned by the program, if any, is ignored by the server.</p>
<h2 id="the-moo-programming-language">The MOO Programming Language</h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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 <span class="cmd">/*</span> and end it with the two characters <span class="cmd">*/</span>; this is just like comments in the C programming language. Note that the server will completely ignore that text; it will <em>not</em> be saved in the database. Thus, such comments are only useful in files of code that you maintain outside the database.</p>
<p>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:</p>
<pre>
for x in (players())
  "Grendel eats peanut butter!";
  player:tell(x.name, " (", x, ")");
endfor
</pre>
<div class="alert alert-info">
    <span class="label label-info">Note:</span> In practice, the only style of comments you will use is quoted strings of text. Get used to it. Another thing of note is that these strings ARE evaluated. Nothing is done with the results of the evaluation, because the value is not stored anywhere-- however, it may be prudent to keep string comments out of nested loops to make your code a bit faster.
</div>
<h3 id="moo-language-expressions">MOO Language Expressions</h3>
<p>Expressions are those pieces of MOO code that generate values; for example, the MOO code</p>
<pre>
3 + 4
</pre>
<p>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.</p>
<h4 id="errors-while_evaluating-expressions">Errors While Evaluating Expressions</h4>
<p>Most kinds of expressions can, under some circumstances, cause an error to be generated. For example, the expression <span class="cmd">x / y</span> will generate the error <span class="cmd">E_DIV</span> if <span class="cmd">y</span> is equal to zero. When an expression generates an error, the behavior of the server is controlled by setting of the <span class="cmd">d</span> (debug) bit on the verb containing that expression. If the <span class="cmd">d</span> 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.</p>
<div class="well">
    <span class="label label-info">Note:</span> This error-squelching behavior is very error prone, since it affects <em>all</em> errors, including ones the programmer may not have anticipated. The <span class="cmd">d</span> 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 <span class="cmd">try</span>-<span class="cmd">except</span> statement, both described below, are far better ways of accomplishing the same thing.
</div>
<p>If the <span class="cmd">d</span> bit is set, as it usually is, then the error is <em>raised</em> 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 <span class="cmd">try</span>-<span class="cmd">except</span> 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.</p>
<h4 id="writing-values-directly-in-verbs">Writing Values Directly in Verbs</h4>
<p>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:</p>
<ul>
    <li>17</li>
    <li>#893</li>
    <li>"This is a character string."</li>
    <li>E_TYPE</li>
    <li>{"This", "is", "a", "list", "of", "words"}</li>
</ul>
<p>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,</p>
<pre>
{3 + 4, 3 - 4, 3 * 4}
</pre>
<p>is an expression whose value is the list <span class="cmd">{7, -1, 12}</span>.</p>
<h4 id="naming-values-within-a-verb">Naming Values Within a Verb</h4>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>The name for a variable is made up entirely of letters, digits, and the underscore character (<span class="cmd">_</span>) and does not begin with a digit. The following are all valid variable names:</p>
<ul>
    <li>foo</li>
    <li>_foo</li>
    <li>this2that</li>
    <li>M68000</li>
    <li>two_words</li>
    <li>This_is_a_very_long_multiword_variable_name</li>
</ul>
<p>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:</p>
<ul>
    <li>fubar</li>
    <li>Fubar</li>
    <li>FUBAR</li>
    <li>fUbAr</li>
</ul>
<p>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 <span class="cmd">E_VARNF</span> is raised. (MOO is unlike many other programming languages in which one must <em>declare</em> each variable before using it; MOO has no such declarations.)  The following variables always have values:</p>
<ul>
    <li>INT</li>
    <li>FLOAT</li>
    <li>OBJ</li>
    <li>STR</li>
    <li>LIST</li>
    <li>ERR</li>
    <li>player</li>
    <li>this</li>
    <li>caller</li>
    <li>verb</li>
    <li>args</li>
    <li>argstr</li>
    <li>dobj</li>
    <li>dobjstr</li>
    <li>prepstr</li>
    <li>iobj</li>
    <li>iobjstr</li>
    <li>NUM</li>
</ul>
<p>The values of some of these variables always start out the same:</p>
<dl class="dl-horizontal">
    <dt><span class="cmd">INT</span></dt>
    <dd>an integer, the type code for integers (see the description of the function <span class="cmd">typeof()</span>, below)</dd>
    <dt><span class="cmd">NUM</span></dt>
    <dd>the same as <span class="cmd">INT</span> (for historical reasons)</dd>
    <dt><span class="cmd">FLOAT</span></dt>
    <dd>an integer, the type code for floating-point numbers</dd>
    <dt><span class="cmd">LIST</span></dt>
    <dd>an integer, the type code for lists</dd>
    <dt><span class="cmd">STR</span></dt>
    <dd>an integer, the type code for strings</dd>
    <dt><span class="cmd">OBJ</span>
    <dd>an integer, the type code for objects</dd>
    <dt><span class="cmd">ERR</span></dt>
    <dd>an integer, the type code for error values</dd>
</dl>
<p>For others, the general meaning of the value is consistent, though the value itself is different for different situations:</p>
<dl class="dl-horizontal">
    <dt><span class="cmd">player</span></dt>
    <dd>an object, the player who typed the command that started the task that involved running this piece of code.</dd>
    <dt><span class="cmd">this</span></dt>
    <dd>an object, the object on which the currently-running verb was found.</dd>
    <dt><span class="cmd">caller</span></dt>
    <dd>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, <span class="cmd">caller</span> has the same value as <span class="cmd">player</span>.</dd>
    <dt><span class="cmd">verb</span></dt>
    <dd>a string, the name by which the currently-running verb was identified.</dd>
    <dt><span class="cmd">args</span></dt>
    <dd>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.</dd>
</dl>
<p>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.</p>
<p>To change what value is stored in a variable, use an <em>assignment</em> expression:</p>
<pre>
<var>variable</var> = <var>expression</var>
</pre>
<p>For example, to change the variable named <span class="cmd">x</span> to have the value 17, you would write <span class="cmd">x = 17</span> as an expression. An assignment expression does two things:</p>
<ul>
    <li>it changes the value of of the named variable</li>
    <li>it returns the new value of that variable</li>
</ul>
<p>Thus, the expression</p>
<pre>
13 + (x = 17)
</pre>
<p>changes the value of <span class="cmd">x</span> to be 17 and returns 30.</p>
<h4 id="arithmetic-operators">Arithmetic Operators</h4>
<p>All of the usual simple operations on numbers are available to MOO programs:</p>
<ul>
    <li>+</li>
    <li>-</li>
    <li>*</li>
    <li>/</li>
    <li>%</li>
</ul>
<p>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:</p>
<pre>
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
</pre>
<p>Note that integer division in MOO throws away the remainder and that the result of the remainder operator (<span class="cmd">%</span>) has the same sign as the left-hand operand. Also, note that <span class="cmd">-</span> can be used without a left-hand operand to negate a numeric expression.</p>
<div class="well">
    <span class="label label-info">Fine point:</span> 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 <span class="cmd">tofloat()</span> function to perform an explicit conversion.
</div>
<p>The <span class="cmd">+</span> operator can also be used to append two strings. The expression <span class="cmd">"foo" + "bar"</span>
 has the value <span class="cmd">"foobar"</span></p>
<p>Unless both operands to an arithmetic operator are numbers of the same kind (or, for <span class="cmd">+</span>, both strings), the error value <span class="cmd">E_TYPE</span> is raised. If the right-hand operand for the division or remainder operators (<span class="cmd">/</span> or <span class="cmd">%</span>) is zero, the error value <span class="cmd">E_DIV</span> is raised.</p>
<p>MOO also supports the exponentiation operation, also known as "raising to a power," using the <span class="cmd">^</span> operator:</p>
<pre>
3 ^ 4       =>   81
3 ^ 4.5     error-->   E_TYPE
3.5 ^ 4     =>   150.0625
3.5 ^ 4.5   =>   280.741230801382
</pre>
<p>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.</p>
<h4 id="comparing-values">Comparing Values</h4>
<p>Any two values can be compared for equality using <span class="cmd">==</span> and <span class="cmd">!=</span>. The first of these returns 1 if the two values are equal and 0 otherwise; the second does the reverse:</p>
<pre>
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
</pre>
<p>Note that integers and floating-point numbers are never equal to one another, even in the <em>obvious</em> 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 <span class="cmd">equal</span> function described later.</p>
<div class="alert alert-warning">
    <span class="label label-warning">Warning:</span> It is easy (and very annoying) to confuse the equality-testing operator (<span class="cmd">==</span>) with the assignment operator (<span class="cmd">=</span>), leading to nasty, hard-to-find bugs. Don't do this.
</div>
<p>Numbers, object numbers, strings, and error values can also be compared for ordering purposes using the following operators:</p>
<dl class="dl-horizontal">
    <dt>&#60;</dt>
    <dd>meaning "less than"</dd>
    <dt>&#60;=</dt>
    <dd>"less than or equal"</dd>
    <dt>&#62;=</dt>
    <dd>"greater than or equal"</dd>
    <dt>&#62;</dt>
    <dd>"greater than"</dd>
</dl>
<p>As with the equality operators, these return 1 when their operands are in the appropriate relation and 0 otherwise:</p>
<pre>
3 &#60; 4           =>  1
3 &#60; 4.0         =>  E_TYPE (an error)
#34 &#62;= #32      =>  1
"foo" &#60;= "Boo"  =>  0
E_DIV &#62; E_TYPE  =>  1
</pre>
<p>Note that, as with the equality operators, strings are compared case-insensitively. To perform a case-sensitive string comparison, use the <span class="cmd">strcmp</span> 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 <span class="cmd">E_TYPE</span> is raised.</p>
<h4 id="values-as-true-or-false">Values as True and False</h4>
<p>There is a notion in MOO of <em>true</em> and <em>false</em> values; every value is one or the other. The true values are as follows:</p>
<ul>
    <li>all integers other than zero (positive or negative)</li>
    <li>all floating-point numbers not equal to <span class="cmd">0.0</span></li>
    <li>all non-empty strings (i.e., other than <span class="cmd">""</span>)</li>
    <li>all non-empty lists (i.e., other than <span class="cmd">{}</span>)</li>
</ul>
<p>All other values are false:</p>
<ul>
    <li>the integer zero</li>
    <li>the floating-point numbers <span class="cmd">0.0</span> and <span class="cmd">-0.0</span></li>
    <li>the empty string (<span class="cmd">""</span>)</li>
    <li>the empty list (<span class="cmd">{}</span>)</li>
    <li>all object numbers</li>
    <li>all error values</li>
</ul>
<div class="alert alert-info">
    <span class="label label-info">Note:</span> Objects are considered false. If you need to evaluate if a value is of the type object, you can use <span class="cmd">typeof(potential_object) == OBJ</span> however, keep in mind that this does not mean that the object referenced actually exists. IE: #100000000 will return true, but that does not mean that object exists in your MOO.
</div>
<p>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 <em>truth value</em> of a MOO value; this is just <em>true</em> or <em>false</em>, the category into which that MOO value is classified.</p>
<p>The conditional expression in MOO has the following form:</p>
<pre>
<var>expression-1</var> ? <var>expression-2</var> | <var>expression-3</var>
</pre>
<div class="alert alert-info">
    <span class="label label-info">Note:</span> This is commonly refered to as a ternary statement in most programming languages. In MOO the commonly used ! is replaced with a |.
</div>
<p>First, <var>expression-1</var> is evaluated. If it returns a true value, then <var>expression-2</var> is evaluated and whatever it returns is returned as the value of the conditional expression as a whole. If <var>expression-1</var> returns a false value, then <var>expression-3</var> is evaluated instead and its value is used as that of the conditional expression.</p>
<pre>
1 ? 2 | 3           =>  2
0 ? 2 | 3           =>  3
"foo" ? 17 | {#34}  =>  17
</pre>
<p>Note that only one of <var>expression-2</var> and <var>expression-3</var> is evaluated, never both.</p>
<p>To negate the truth value of a MOO value, use the <span class="cmd">!</span> operator:</p>
<pre>
! <var>expression</var>
</pre>
<p>If the value of <var>expression</var> is true, <span class="cmd">!</span> returns 0; otherwise, it returns 1:</p>
<pre>
! "foo"     =>  0
! (3 &#62;= 4)  =>  1
</pre>
<p>The negation operator is usually read as "not."</p>
<div class="alert alert-info">
    <span class="label label-info">Note:</span> The "negation" or "not" operator is commonly referred to as "bang" in modern parlance.
</div>
<p>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:</p>
<pre>
<var>expression-1</var> &#38;&#38; <var>expression-2</var>
<var>expression-1</var> || <var>expression-2</var>
</pre>
<p>These operators are usually read as "and" and "or," respectively.</p>
<p>The <span class="cmd">&#38;&#38;</span> operator first evaluates <var>expression-1</var>. If it returns a true value, then <var>expression-2</var> is evaluated and its value becomes the value of the <span class="cmd">&#38;&#38;</span> expression as a whole; otherwise, the value of <var>expression-1</var> is used as the value of the <span class="cmd">&#38;&#38;</span> expression.</p>
<div class="alert alert-info">
    <span class="alert alert-info">Note:</span> <var>expression-2</var> is only evaluated if <var>expression-1</var> returns a true value.
</div>
<p>The <span class="cmd">&#38;&#38;</span> expression is equivalent to the conditional expression:</p>
<pre>
<var>expression-1</var> ? <var>expression-2</var> | <var>expression-1</var>
</pre>
<p>except that <var>expression-1</var> is only evaluated once.</p>
<p>The <span class="cmd">||</span> operator works similarly, except that <var>expression-2</var> is evaluated only if <var>expression-1</var> returns a false value. It is equivalent to the conditional expression:</p>
<pre>
<var>expression-1</var> ? <var>expression-1</var> | <var>expression-2</var>
</pre>
<p>except that, as with <span class="cmd">&#38;&#38;</span>, <var>expression-1</var> is only evaluated once.</p>
<p>These two operators behave very much like "and" and "or" in English:</p>
<pre>
1 &#38;&#38; 1                  =>  1
0 &#38;&#38; 1                  =>  0
0 &#38;&#38; 0                  =>  0
1 || 1                  =>  1
0 || 1                  =>  1
0 || 0                  =>  0
17 &#60;= 23  &#38;&#38;  23 &#60;= 27  =>  1
</pre>
<h4 id="indexing-into-lists-and-strings">Indexing into Lists and Strings</h4>
<p>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 <span class="cmd">"bar"</span> as a sequence of the strings <span class="cmd">"b"</span>, <span class="cmd">"a"</span>, and <span class="cmd">"r"</span>. MOO allows you to refer to the elements of lists and strings by number, by the <em>index</em> 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.</p>
<div class="alert alert-warning">
    <span class="alert alert-warning">Warning:</span> It is very important to note that unlike many programming languages (which use 0 as the starting index), MOO uses 1.
</div>
<h5 id="extracting-an-element-from-a-list-or-string">Extracting an Element from a List or String</h5>
<p>The indexing expression in MOO extracts a specified element from a list or string:</p>
<pre>
<var>expression-1</var>[<var>expression-2</var>]
</pre>
<p>First, <var>expression-1</var> is evaluated; it must return a list or a string (the <em>sequence</em>). Then, <var>expression-2</var> is evaluated and must return an integer (the <em>index</em>). If either of the expressions returns some other type of value, <span class="cmd">E_TYPE</span> is returned. The index must be between 1 and the length of the sequence, inclusive; if it is not, then <span class="cmd">E_RANGE</span> is raised.  The value of the indexing expression is the index'th element in the sequence.  Anywhere within <var>expression-2</var>, you can use the symbol <span class="cmd">$</span> as an expression returning the length of the value of <var>expression-1</var>.</p>
<pre>
"fob"[2]                =>  "o"
"fob"[1]                =>  "f"
{#12, #23, #34}[$ - 1]  =>  #23
</pre>
<p>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).</p>
<div class="well">
    <span class="label label-info">Fine point:</span> The <span class="cmd">$</span> expression actually returns the length of the value of the expression just before the nearest enclosing <span class="cmd">[...]</span> indexing or subranging brackets. For example:
<pre>
"frob"[{3, 2, 4}[$]]     =>  "b"
</pre>
    is possible because $ in this case represents the 3rd index of the list next to it, which evaluates to the value 4, which in turn is applied as the index to the string, which evaluates to the b.
</div>
<h5 id="replacing-an-element-of-a-list-or-string">Replacing an Element of a List or String</h5>
<p>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 <em>indexed assignment</em> having one of the following forms:</p>
<pre>
<var>variable</var>[<var>index-expr</var>] = <var>result-expr</var>
<var>object-expr</var>.<var>name</var>[<var>index-expr</var>] = <var>result-expr</var>
<var>object-expr</var>.(<var>name-expr</var>)[<var>index-expr</var>] = <var>result-expr</var>
$<var>name</var>[<var>index-expr</var>] = <var>result-expr</var>
</pre>
<p>The first form writes into a variable, and the last three forms write into a property. The usual errors (<span class="cmd">E_TYPE</span>, <span class="cmd">E_INVIND</span>, <span class="cmd">E_PROPNF</span> and <span class="cmd">E_PERM</span> 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.</p>
<p>Correspondingly, if <var>variable</var> does not yet have a value (i.e., it has never been assigned to), <span class="cmd">E_VARNF</span> will be raised.</p> <p>If <var>index-expr</var> is not an integer, or if the value of <var>variable</var> or the property is not a list or string, <span class="cmd">E_TYPE</span> is raised. If <var>result-expr</var> is a string, but not of length 1, <span class="cmd">E_INVARG</span> is raised. Now suppose <var>index-expr</var> evaluates to an integer <var>n</var>. If <var>n</var> is outside the range of the list or string (i.e. smaller than 1 or greater than the length of the list or string), <span class="cmd">E_RANGE</span> is raised. Otherwise, the actual assignment takes place.</p>
<p>For lists, the variable or the property is assigned a new list that is identical to the original one except at the <var>n</var>-th position, where the new list contains the result of <var>result-expr</var> instead. For strings, the variable or the property is assigned a new string that is identical to the original one, except the <var>n</var>-th character is changed to be <var>result-expr</var>.</p>
<p>The assignment expression itself returns the value of <var>result-expr</var>. For the following examples, assume that <span class="cmd">l</span> initially contains the list <span class="cmd">{1, 2, 3}</span> and that <span class="cmd">s</span> initially contains the string "foobar":</p>
<pre>
l[5] = 3          =>   E_RANGE (error)
l["first"] = 4    =>   E_TYPE  (error)
s[3] = "baz"      =>   E_INVARG (error)
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"
</pre>
<div class="alert alert-info">
    <span class="label label-info">Note:</span> (error) is only used for formatting and identification purposes in these examples and is not present in an actual raised error on the MOO.
</div>
<div class="alert alert-info">
    <span class="label label-info">Note:</span> The <span class="cmd">$</span> expression may also be used in indexed assignments with the same meaning as before.
</div>
<div class="well">
    <span class="label label-info">Fine point:</span> After an indexed assignment, the variable or property contains a <em>new</em> list or string, a copy of the original list in all but the <var>n</var>-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.)
</div>
<p>In the list case, indexed assignment can be nested to many levels, to work on nested lists. Assume that <span class="cmd">l</span> initially contains the list:</p>
<pre>
{{1, 2, 3}, {4, 5, 6}, "foo"}
</pre>
<p>in the following examples:</p>
<pre>
l[7] = 4             =>   E_RANGE (error)
l[1][8] = 35         =>   E_RANGE (error)
l[3][2] = 7          =>   E_TYPE (error)
l[1][1][1] = 3       =>   E_TYPE (error)
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"}
</pre>
<p>The first two examples raise <span class="cmd">E_RANGE</span> because 7 is out of the range of <span class="cmd">l</span> and 8 is out of the range of <span class="cmd">l[1]</span>. The next two examples raise <span class="cmd">E_TYPE</span> because <span class="cmd">l[3]</span> and <span class="cmd">l[1][1]</span> are not lists.</p>
<h5 id="extracting-a-subsequence-of-a-list-or-string">Extracting a Subsequence of a List or String</h5>
<p>The range expression extracts a specified subsequence from a list or string:</p>
<pre>
<var>expression-1</var>[<var>expression-2</var>..<var>expression-3</var>]
</pre>
<p>The three expressions are evaluated in order. <var>Expression-1</var> must return a list or string (the <em>sequence</em>) and the other two expressions must return integers (the <em>low</em> and <em>high</em> indices, respectively); otherwise, <span class="cmd">E_TYPE</span> is raised. The <span class="cmd">$</span> expression can be used in either or both of <var>expression-2</var> and <var>expression-3</var> just as before, meaning the length of the value of <var>expression-1</var>.</p>
<p>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; <span class="cmd">E_RANGE</span> 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.</p>
<pre>
"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]      =>  {}
</pre>
<h5 id="replacing-a-subsequence-of-a-list-or-string">Replacing a Subsequence of a List or String</h5>
<p>The subrange assigment replaces a specified subsequence of a list or string with a supplied subsequence. The allowed forms are:</p>
<pre>
<var>variable</var>[<var>start-index-expr</var>..<var>end-index-expr</var>] = <var>result-expr</var>
<var>object-expr</var>.<var>name</var>[<var>start-index-expr</var>..<var>end-index-expr</var>] = <var>result-expr</var>
<var>object-expr</var>.(<var>name-expr</var>)[<var>start-index-expr</var>..<var>end-index-expr</var>] = <var>result-expr</var>
$<var>name</var>[<var>start-index-expr</var>..<var>end-index-expr</var>] = <var>result-expr</var>
</pre>
<p>As with indexed assigments, the first form writes into a variable, and the last three forms write into a property. The same errors (<span class="cmd">E_TYPE</span>, <span class="cmd">E_INVIND</span>, <span class="cmd">E_PROPNF</span> and <span class="cmd">E_PERM</span> for lack of read/write permission on the property) may be raised. If <var>variable</var> does not yet have a value (i.e., it has never been assigned to), <span class="cmd">E_VARNF</span> will be raised.</p>
<p>As before, the <span class="cmd">$</span> expression can be used in either <var>start-index-expr</var> or <var>end-index-expr</var>, meaning the length of the original value of the expression just before the <span class="cmd">[...]</span> part.</p>
<p>If <var>start-index-expr</var> or <var>end-index-expr</var> is not an integer, if the value of <var>variable</var> or the property is not a list or string, or <var>result-expr</var> is not the same type as <var>variable</var> or the property, <span class="cmd">E_TYPE</span> is raised. <span class="cmd">E_RANGE</span> is raised if <var>end-index-expr</var> is less than zero or if <var>start-index-expr</var> is greater than the length of the list or string plus one. Note: the length of <var>result-expr</var> does not need to be the same as the length of the specified range.</p>
<p>In precise terms, the subrange assigment</p>
<pre>
<var>v</var>[<var>start</var>..<var>end</var>] = <var>value</var>
</pre>
<p>is equivalent to</p>
<pre>
<var>v</var> = {@<var>v</var>[1..<var>start</var> - 1], @<var>value</var>, @<var>v</var>[<var>end</var> + 1..$]}
</pre>
<p>if <var>v</var> is a list and to</p>
<pre>
<var>v</var> = <var>v</var>[1..<var>start</var> - 1] + <var>value</var> + <var>v</var>[<var>end</var> + 1..$]
</pre>
<p>if <var>v</var> is a string. The assigment expression itself returns the value of <var>result-expr</var>.</p>
<div class="alert alert-info">
    <span class="label label-info">Note:</span> The use of preceeding a list with the @ symbol is covered in just a bit.
</div>
<p>For the following examples, assume that <span class="cmd">l</span> initially contains the list <span class="cmd">{1, 2, 3}</span> and that <span class="cmd">s</span> initially contains the string "foobar":</p>
<pre>
l[5..6] = {7, 8}       =>   E_RANGE (error)
l[2..3] = 4            =>   E_TYPE (error)
l[#2..3] = {7}         =>   E_TYPE (error)
s[2..3] = {6}          =>   E_TYPE (error)
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"
</pre>
<h4 id="other-operations-on-lists">Other Operations on Lists</h4>
<p>As was mentioned earlier, lists can be constructed by writing a comma-separated sequence of expressions inside curly braces:</p>
<pre>
{<var>expression-1</var>, <var>expression-2</var>, ..., <var>expression-N</var>}
</pre>
<p>The resulting list has the value of <var>expression-1</var> as its first element, that of <var>expression-2</var> as the second, etc.</p>
<pre>
{3 &#60; 4, 3 &#60;= 4, 3 &#62;= 4, 3 &#62; 4}  =>  {1, 1, 0, 0}
</pre>
<p>Additionally, one may precede any of these expressions by the splicing operator, <span class="cmd">@</span>. 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 <span class="cmd">a</span> has the value <span class="cmd">{2, 3, 4}</span> and that <span class="cmd">b</span> has the value <span class="cmd">{"Foo", "Bar"}</span>:</p>
<pre>
{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"}
</pre>
<p>If the splicing operator (<span class="cmd">@</span>) precedes an expression whose value is not a list, then <span class="cmd">E_TYPE</span> is raised as the value of the list construction as a whole.</p>
<p>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:</p>
<pre>
<var>expression-1</var> in <var>expression-2</var>
</pre>
<p><var>Expression-2</var> must return a list; otherwise, <span class="cmd">E_TYPE</span> is raised.  If the value of <var>expression-1</var> is in that list, then the index of its first occurrence in the list is returned; otherwise, the <span class="cmd">in</span> expression returns 0.</p>
<pre>
2 in {5, 8, 2, 3}               =>  3
7 in {5, 8, 2, 3}               =>  0
"bar" in {"Foo", "Bar", "Baz"}  =>  2
</pre>
<p>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 <span class="cmd">is_member</span> function described later. Note also that since it returns zero only if the given value is not in the given list, the <span class="cmd">in</span> expression can be used either as a membership test or as an element locator.</p>
<h4 id="spreading-list-elements-among-variables">Spreading List Elements Among Variables</h4>
<p>It is often the case in MOO programming that you will want to access the elements of a list individually, with each element stored in a separate variables. This desire arises, for example, at the beginning of almost every MOO verb, since the arguments to all verbs are delivered all bunched together in a single list. In such circumstances, you <em>could</em> write statements like these:</p>
<pre>
first = args[1];
second = args[2];
if (length(args) &#62; 2)
  third = args[3];
else
  third = 0;
endif
</pre>
<p>This approach gets pretty tedious, both to read and to write, and it's prone to errors if you mistype one of the indices. Also, you often want to check whether or not any <em>extra</em> list elements were present, adding to the tedium.</p>
<p>MOO provides a special kind of assignment expression, called <em>scattering assignment</em> made just for cases such as these. A scattering assignment expression looks like this:</p>
<pre>
{<var>target</var>, ...} = <var>expr</var>
</pre>
<p>where each <var>target</var> describes a place to store elements of the list that results from evaluating <var>expr</var>. A <var>target</var> has one of the following forms:</p>
<dl class="dl-horizontal">
    <dt><span class="cmd"><var>variable</var></span></dt>
    <dd>This is the simplest target, just a simple variable; the list element in the corresponding position is assigned to the variable. This is called a <em>required</em> target, since the assignment is required to put one of the list elements into the variable.</dd>
    <dt><span class="cmd">?<var>variable</var></span></dt>
    <dd>This is called an <em>optional</em> 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.</dd>
    <dt><span class="cmd">?<var>variable</var> = <var>default-expr</var></span></dt>
    <dd>This is also an optional target, but if there aren't enough list elements available to assign one to this target, the result of evaluating <var>default-expr</var> is assigned to it instead. Thus, <var>default-expr</var> provides a <em>default value</em> for the variable. The default value expressions are evaluated and assigned working from left to right <em>after</em> all of the other assignments have been performed.</dd>
    <dt><span class="cmd">@<var>variable</var></span></dt>
    <dd>By analogy with the <span class="cmd">@</span> 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 <em>rest</em> target, since it gets the rest of the elements. There may be at most one rest target in each scattering assignment expression.</dd>
</dl>
<p>If there aren't enough list elements to fill all of the required targets, or if there are more than enough to fill all of the required and optional targets but there isn't a rest target to take the leftover ones, then <span class="cmd">E_ARGS</span> is raised.</p>
<p>Here are some examples of how this works. Assume first that the verb <span class="cmd">me:foo()</span> contains the following code:</p>
<pre>
b = c = e = 17;
{a, ?b, ?c = 8, @d, ?e = 9, f} = args;
return {a, b, c, d, e, f};
</pre>

<p>Then the following calls return the given values:</p>
<pre>
me:foo(1)                        =>   E_ARGS (error)
me:foo(1, 2)                     =>   {1, 17, 8, {}, 9, 2}
me:foo(1, 2, 3)                  =>   {1, 2, 8, {}, 9, 3}
me:foo(1, 2, 3, 4)               =>   {1, 2, 3, {}, 9, 4}
me:foo(1, 2, 3, 4, 5)            =>   {1, 2, 3, {}, 4, 5}
me:foo(1, 2, 3, 4, 5, 6)         =>   {1, 2, 3, {4}, 5, 6}
me:foo(1, 2, 3, 4, 5, 6, 7)      =>   {1, 2, 3, {4, 5}, 6, 7}
me:foo(1, 2, 3, 4, 5, 6, 7, 8)   =>   {1, 2, 3, {4, 5, 6}, 7, 8}
</pre>
<p>Using scattering assignment, the example at the begining of this section could be rewritten more simply, reliably, and readably:</p>
<pre>
{first, second, ?third = 0} = args;
</pre>
<div class="alert alert-info">
    <span class="label label-info">Fine point:</span> If you are familiar with JavaScript, the 'rest' and 'spread' functionality should look pretty familiar. It is good MOO programming style to use a scattering assignment at the top of nearly every verb (at least ones that are 'this none this'), since it shows so clearly just what kinds of arguments the verb expects.
</div>
<h4 id="getting-and-setting-the-values-of-properties">Getting and Setting the Values of Properties</h4>
<p>Usually, one can read the value of a property on an object with a simple expression:</p>
<pre>
<var>expression</var>.<var>name</var>
</pre>
<p><var>Expression</var> must return an object number; if not, <span class="cmd">E_TYPE</span> is raised. If the object with that number does not exist, <span class="cmd">E_INVIND</span> is raised. Otherwise, if the object does not have a property with that name, then <span class="cmd">E_PROPNF</span> is raised. Otherwise, if the named property is not readable by the owner of the current verb, then <span class="cmd">E_PERM</span> is raised.  Finally, assuming that none of these terrible things happens, the value of the named property on the given object is returned.</p>
<p>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:</p>
<pre>
<var>expression-1</var>.(<var>expression-2</var>)
</pre>
<p>As before, <var>expression-1</var> must return an object number. <var>Expression-2</var> must return a string, the name of the property to be read; <span class="cmd">E_TYPE</span> is raised otherwise. Using this syntax, any property can be read, regardless of its name.</p>