Introduction to ColdMUD and the Cold Dark
by Brandon Gillespie (Lynx)
Terminology
===========
This is an introduction to ColdMUD and the Cold Dark. Although there are
other core's under development when using the generic term "Cold" it is in
reference to the Cold Dark. The term "Driver" refers to any function or
ability inherent to the ColdMUD driver (something which is not database
specific). The term "Server" refers to the collective driver and database
running as a whole.
Transition from MOO to ColdMUD
==============================
Although ColdMUD can claim roots in MOO, and does have many similarities,
there are also many differences. ColdMUD has a much higher level of
encapsulation than MOO, it has a language which is closer to C or even object
oriented C, and it has an expanded capability. Most of the differences are
only noticed by programmers, as the user interface is but a finishing veneer
which can be easilly adjusted to the relative tastes of the user.
Data types
----------
The following is a list of MOO data types and their ColdMUD equivalents, as
well as ColdMUD additions:
MOO ColdMUD
INT 1 'integer 1
STR "String" 'string "String"
LIST {1,2,3} 'list [1,2,3]
OBJ #0 'objnum * #0
ERR 'error ~error
'dbref $sys
'dictionary #[["key", "value"]]
'symbol 'Symbol
'frob <object, value>
'buffer `[]
Method Structure (ColdC)
------------------------
In ColdC all variables and arguments must be defined (however their
relative types do not need to be defined, as in MOO). The basic syntax
of ColdC is closer to that of C.
Verbs and Methods
-----------------
In MOO the Verb has a two-fold functionality. It acts as a function, and it
acts as a command. In ColdMUD a method represents the function aspect of the
MOO Verb (Commands are discussed later). A Method reference does not use the
object:verb() syntax of MOO, but rather is: object.method().
Properties and Parameters
-------------------------
This is where encapsulation will be noticed the most. In MOO it is possible
to not only modify the value of a property remotely, but you can also modify
this value from any child of the defining parent. In ColdMUD the only object
which can modify the value of a parameter defined on a child is the object
which defines that parameter. What this means is in order for a descendant
to modify the value of a parameter, the parent must provide the means for
such manipulation. The following example will demonstrate:
An object exists which is called $text. This object has the parameter
'text', which is a list of strings. It has two methods:
$text.get_text
return text;
.
$text.set_text
arg value;
text = value;
.
The method $text.get_text() returns whatever text is set as. The method
$text.set_text(value) sets the value of text to whatever is submitted as the
argument. If $text has a child by the name of $text_1, and $text_1 defines
a method:
$text_1.see_text
return text;
.
Calling the method will fail, as $text_1 does not have a parameter by the
name of text. In order to find what $text_1 has as the value of $text, one
must call $text_1.get_text().
Although children cannot directly access parameters defined by their
ancestors, they do have their own 'copies' of this parameter. For instance,
in the above example if the parameter of text was set to an empty list on
$text, calling $text.get_text() would return an empty list. If one were to
call $text_1.get_text(), it would return 0 (the default uninitialized
parameter value). If one were to call $text_1.set_text(["text"]),
$text.get_text() would still return an emtpy list, but $text_1.get_text()
would return ["text"].
Commands
--------
In MOO commands (or Verbs) are inherent to the design of the driver. In
ColdMUD commands are simply a database interpretation of a string which
points to a method if there is a successful match. In the Cold Dark
commands are divided into 3 categories, depending upon what methodology
is used in their parsing:
Commands: Commands use the builtin function match_template() to
find matches to the command.
Shortcuts: Shortcuts are intented as wrap-arounds for commands,
using the builtin match_pattern() and passing the
arguments in the same fashion that the command would.
Verbs: Verbs are commands which include %this in the
template. Matching of %this is done in-db, after
match_template() is called.
Examples:
Command template: "@g?rep * to|until *"
match_template("@g?rep * to|until *", "@grep $bar to $foo")
=> ["@grep", "$bar", "to", "$foo"]
Shortcut for the above: "g* *", ["@grep", 1, "to", 2]
match_pattern("g* *", "g$bar $foo")
=> ["g", "$bar", "$boo"]
Which the matching routines parse into:
=> ["@grep", "$bar", "to", "$foo"]
Verb template: "l?ook at %this"
Which is converted (by the database) to:
"l?ook at *"
And becomes:
match_template("l?ook at *", "l at bob")
=> ["l", "at", "bob"]
At which point the database attempts to find "bob".
For each command available an associated method is defined. When a match is
found that method is called with the arguments being the output of the match.
As a convention methods bound to a command have the suffix _cmd and
methods bound to verbs have the suffix _vrb.
Programming in the Cold Dark
============================
Although I started in MOO, the command interface for the Cold Dark has changed
slightly. This is primarily because I felt the commands would be better in
the syntax I have given them. MOO equivalents:
MOO CDC
@program <object:method> @program <object.method>
or: @program <.method>
@show <object> @show <object>
@d*isplay <object[:.]> @d?isplay <object[.,]>
@list <object:method> @list|@nlist <object.method>
or: @list|@nlist <.method>
@com?mands [object]
@mcom?mands [object] (with methods)
@which <command>
eval <code> @eval <code>
;[;]<code> ;[;]<code>
@as <object> eval <code>
@definer <object> as <object> eval <code>
For a more comprehensive list of commands available in programming, type
`@commands $programmer`.
Note on commands: In the Cold Dark we have defined what the basic definition
of a command beginning with an at sign (@) is early on (because we found this
definition lacking and only partially supported in MOO). The definition we
use is that any command which does not begin with an at sign is one which
represents a function you would do in real life. For instance, you would not
describe yourself as being blue and suddenly be blue, therefore the command
`@describe` begins with an at sign. Another example would be movement. You
do `go north` and subsequently go north. You do not `go $home` and suddenly
appear at home, therefore there are two `go` commands, depending upon the
function. Shortcuts do not follow this convention.
Command Overview
================
This is a list of some commands available:
Commands on a Generic User Object ($user):
"@quit" 'quit_cmd
Returns 'disconnect to your connections.
"@name-aliases|@na <obj>" 'name_aliases_cmd
Returns a list of name aliases for <obj> (defaults to you)
"@add-name-alias|@ana <obj>" 'add_name_alias_cmd
"@del-name-alias|@dna <obj>" 'del_name_alias_cmd
Adds/Deletes a name alias from <obj> (defaults to you)
"@rename <obj> to <newname>" 'rename_cmd
Changes the name for an object, can have a command option of
-p or -u, to specify proper or unique names.
"@command-a?liases|@ca?liases <obj>" 'command_aliases_cmd
Returns a list of command aliases on <obj> (defaults to you)
"@add-command-a?lias|@aca?lias <obj>" 'add_command_alias_cmd
"@del-command-a?lias|@dca?lias <obj>" 'del_command_alias_cmd
Adds/Deletes a command alias, as well as adding/removing
the command alias parser from your parser stack, if necessary.
"@password <old> <new>" 'password_cmd
Change your password.
"@who [options]" 'who_cmd
Who is connected?
"@com?mands [<object>|all]" 'commands_cmd
Give me a list of commands, defaults to all.
"@prose|@describe <object> [-s|-l]" 'prose_cmd
Set the short and long prose for an object, flags define which
to use, -s is short, which is a single paragraph, -l is long which
can be multiple paragraphs. You will be prompted for whichever
shortcut.
"@status" 'status_cmd
Returns the status of the server (uptime, last db dump, etc)
"@spawn <obj> [named|called <name>]" 'spawn_cmd
Spawn a child off <object>, and if it is descended from $named
give it the name of <name>.
"@rehash?-commands" 'rehash_cmd
Rehash your command/shortcut/verb caches. (Note: caches were
implemented as they cut ~4000-5000 ticks out of command parsing).
Commands on a Generic Programmer ($programmer):
"@show <object>" 'show_cmd
Show the object.
"@d?isplay <object>[.,][wildcard]" 'display_cmd
Display features of an object, including a period or comma will
specify which to show (methods or parameters, relatively), you
can filter items with wildcards.
"@list|@nlist <object>.<method>" 'list_cmd
List a method, @nlist will list a method with line numbers.
"@program <object>.<method>" 'program_cmd
Program a method. Methods are defined as you program them.
"@dump <object> +|-[p|m|e|n]" 'dump_cmd
Dumps an object.
"@id <object>" 'id_cmd
Id an object.
"@go <place>" 'go_cmd
Teleport somewhere.
"@mcom?mands <object>" 'mcommands_cmd
Commands and their bound methods on <object>
"@info <object>" 'info_cmd
Information on <object>, will go away as help is implemented.
"@which <template>" 'which_cmd
Find command(s) matching <template>
"@mv|@move|@cp|@copy <reference> [to] <reference>" 'copy_move_cmd
Move or copy <reference> to <reference>.
"@del-m?ethod|@delm?ethod|@dm *" 'del_method_cmd
"@add-m?ethod|@addm?ethod|@am *" 'add_method_cmd
Add/Delete method from an object, rather redundant but some people
wanted it.
"@eval <code>" 'eval_cmd
";<code>" 'eval_cmd
Evaluate <code>.
"@add-c?ommand|@ac *" 'add_command_cmd
"@del-c?ommand|@dc *" 'del_command_cmd
Add/delete commands
"@as * eval *" 'eval_as_cmd
"@def?iner * this|as * eval *" 'eval_as_to_cmd