& FUNCTIONS
Functions are specialized commands used to manipulate strings and
other input. Function take the general form: [FUNCTION(<input>)]
The brackets are used to delimit and force evaluation of the function
(or nested functions). The brackets can also be used to group functions
for the purposes of string concatenation. In general, more than one pair
of brackets is not required, but liberal use of them makes code easier to
read. You can nest an arbitrary number of brackets.
Examples:
> say [first(rest(This is a nice day))]
You say, "is"
> @va me=This is a
Wizard - Set.
> @vb me=nice day
Wizard - Set.
> say [first([rest([v(va)] [v(vb)])])]
You say, "is"
See "help FUNCTIONS2" for more.
& FUNCTIONS2
A list of available built-in functions can be obtained via the command
"@config/functions". In the help text, the list is under the topic
"FUNCTION LIST".
In addition to these built-in functions are MUSH-defined "global user
functions." These are defined by wizards or those with the "Function"
power, via the "@function" command. To the user, they act just like
the built-in game functions. For details on global user functions,
see "help @function".
See also: MUSHCODE
& FUNCTION LIST
Several major variants of functions are available. The help topics
are listed below, together with a quick summary of the function type
and some examples of that type of function.
Attribute functions: attribute-related manipulations (GET, UFUN)
Bitwise functions: Manipulation of individual bits of numbers (SHL, BOR)
Boolean functions: produce 0 or 1 (false or true) answers (OR, AND)
Channel functions: Get information about channels (CTITLE, CWHO)
Communication functions: Send messages to objects (PEMIT, OEMIT)
Connection functions: Get information about a player's connection (CONN)
Dbref functions: return dbref info related to objects (LOC, LEXITS)
Html functions: output html tags for Pueblo-compatible clients
Information functions: find out something about objects (FLAGS, MONEY)
List functions: manipulate lists (REVWORDS, FIRST)
Mail functions: manipulate @mail (MAIL, FOLDERSTATS)
Math functions: number manipulation, generic or integers only (ADD, DIV)
Regular expression functions: Regular expressions (REGMATCH, REGEDIT)
SQL functions: Access SQL databases (SQL, SQLESCAPE)
String functions: string manipulation (ESCAPE, FLIP)
Time functions: Formatting and display of time (TIME, CONVSECS)
Utility functions: general utilities (ISINT, COMP)
The command "@config/functions" lists all of the game's built-in functions.
The command "@function" lists all of the game's custom global functions
defined via the @function command.
& Attribute functions
All these functions access attributes on an object.
aposs() default() edefault() eval() filter()
filterbool() fold() foreach() get() grep()
grepi() lattr() nattr() obj() poss()
regrep() regrepi() subj() udefault() ufun()
uldefault() ulocal() v-function xget() zfun()
See also: ATTRIBUTES, NON-STANDARD ATTRIBUTES
& Bitwise functions
These functions treat integers as a sequence of binary bits (Either 0
or 1) and manipulate them.
For example, 2 is represented as '0010' and 4 as '0100'. If these two
numbers are bitwise-or'ed together with BOR(), the result is 6, or
(In binary) '0110'. These functions are useful for storing small
lists of toggle (Yes/No) options efficiently.
baseconv() band() bnand() bnot() bor()
bxor() shl() shr()
& Boolean functions
Boolean functions all return 0 or 1 as an answer.
Your MUSH may be configured to use traditional PennMUSH booleans,
in which case non-zero numbers, non-negative db#'s, and strings
are all considered "true" when passed to these functions.
Alternatively, your MUSH may be using TinyMUSH 2.2 booleans,
in which case only non-zero numbers are "true".
and() cand() cor() eq() gt()
gte() lt() lte() nand() neq()
nor() not() or() t() xor()
See also: BOOLEAN VALUES, @config
& Channel functions
Channel functions work with the channel system.
cemit() cflags() channels() clock() cowner()
ctitle() cwho()
& Communication functions
Communication functions are side-effect functions that send a message
to an object or objects.
cemit() emit() lemit() nsemit() nslemit()
nsoemit() nspemit() nsremit() nszemit() oemit()
pemit() remit() zemit()
& Connection functions
Connection functions return information about the connections open
on a game, or about specific connections.
cmds() conn() doing() height() hostname()
hidden() idle() ipaddr() lports() lwho()
mwho() nmwho() nwho() ports() pueblo()
recv() sent() ssl() terminfo() width()
xmwho() xwho() zmwho() zwho()
& Dbref functions
Dbref functions return a dbref or list of dbrefs related to some value
on an object.
children() con() entrances() exit() followers()
following() home() lcon() lexits() loc()
locate() lparent() lplayers() lsearch() lvcon()
lvexits() lvplayers() next() num() owner()
parent() pmatch() rloc() rnum() room()
where() zone()
See also: DBREF
& Information functions
Information functions return values related to objects or the game.
andflags() andlflags() config() controls() ctime()
elock() findable() flags() fullname() hasattr()
hasattrp() hasflag() haspower() hastype() iname()
lflags() lock() lstats() money() mtime()
mudname() name() nattr() nearby() objid()
objmem() orflags() orlflags() playermem() poll()
powers() quota() restarts() type() version()
visible()
& Mail functions
Mail functions work with @mail.
folderstats() mail() maildstats() mailfrom() mailfstats()
mailsend() mailstats() mailstatus() mailsubject() mailtime()
malias()
& List functions
List functions take at least one list of elements and return transformed
lists or one or more members of those lists. Most of these functions
can take an arbitrary <delimiter> argument to specify what delimits
list elements; if none is provided, a space is used by default.
element() elements() extract() first() grab()
graball() index() insert() itemize() items()
iter() last() ldelete() map() match()
matchall() member() mix() munge() remove()
replace() rest() revwords() setdiff() setinter()
setunion() shuffle() sort() sortby() splice()
step() table() wordpos() words()
See also: LISTS
& Math functions
Math functions take one or more floating point numbers and return
a numeric value.
abs() acos() add() asin() atan()
atan2() bound() ceil() cos() ctu()
dist2d() dist3d() e() exp() fdiv()
floor() fmod() fraction() ln() lmath()
log() max() mean() median() min()
mul() pi() power() root() round()
sign() sin() sqrt() stddev() sub()
tan() trunc() val()
These functions operate only on integers (if passed floating point
numbers, they will return an error or misbehave):
dec() div() floordiv() inc() mod()
remainder()
These functions operate on n-dimensional vectors. A vector
is a delimiter-separated list of numbers (space-separated, by default):
vadd() vcross() vdim() vdot() vmag()
vmax() vmin() vmul() vsub() vunit()
& Regular expression functions
These functions take a regular expression (regexp, or re) and match
it against assorted things.
regedit() regeditall() regeditalli() regediti() regmatch()
regmatchi() regrab() regraball() regraballi() regrabi()
regrep() regrepi() reswitch() reswitchall() reswitchalli()
reswitchi()
See also: string functions, regexp
& SQL functions
These functions perform queries or other operations on an SQL
database to which the MUSH is connected, if SQL support is
available and enabled.
sql() sqlescape()
& String functions
String functions take at least one string and return a transformed
string, parts of a string, or a value related to the string(s).
accent() after() alphamin() alphamax() art()
before() brackets() capstr() case() caseall()
cat() center() comp() chr() decrypt()
delete() digest() edit() encrypt() escape()
if() ifelse() lcstr() left() lit()
ljust() merge() mid() ord() pos()
regedit() lpos() regmatch() repeat() reverse()
right() rjust() scramble() secure() sha0()
space() spellnum() squish() strcat() strinsert()
stripaccents()stripansi() strlen() strmatch() strreplace()
switch() trim() ucstr() wrap()
See also: STRINGS
& Time functions
These functions return times or format times.
convsecs() convutcsecs() convtime() ctime() etimefmt()
isdaylight() mtime() restarttime() secs() starttime()
time() timefmt() timestring() utctime()
& Utility functions
These functions don't quite fit into any other category.
allof() ansi() atrlock() beep() checkpass()
clone() create() die() dig() firstof()
functions() isdbref() isint() isnum() isword()
localize() link() list() lnum() null()
objeval() open() pcreate() r-function rand()
s-function scan() set() setq() setr()
soundex() soundslike() tel() textfile() valid()
wipe() @@()
& @@()
& NULL()
@@(<expression>)
null(<expression>[,<expression>,...])
The @@() function does nothing and returns nothing. It could be
used for commenting, perhaps. It does not evaluate its argument.
The null() function is similar, but does evaluate its argument(s),
so side-effects can occur within a null(). Useful for eating the
output of functions when you don't use that output.
& ABS()
abs(<number>)
Returns the absolute value of a number. i.e. ABS(-4) returns 4;
ABS(2) returns 2, etc.
& ACCENT()
accent(<string>, <template>)
The accent() function will return <string>, with characters in it
possibly changed to accented ones according to <template>. Both
arguments must be the same size.
Whether or not the resulting string is actually displayed correctly
is client-dependent. Some OSes uses different character sets than
the one assumes (ISO 8859-1), and some clients strip these 8-bit
characters.
See HELP ACCENT2 for a description of the template argument.
See also: stripaccents(), NOACCENTS
& ACCENT2
For each character in <string>, the corresponding character of
<template> is checked according to the table below, and a replacement
done. If either the current <string> or <template> characters aren't
in the table, the <string> character is passed through unchanged.
Accent Template String
Name Description Character Character
--------------------------------------------------------------
grave Backward slant ` A,E,I,O,U,a,e,i,o,u
above letter
acute Forward slant ' A,E,I,O,U,Y,a,e,i,o,u,y
above letter
tilde Wavy line above ~ A,N,O,a,n,o
letter
circumflex carat above ^ A,E,I,O,U,a,e,i,o,u
letter
umlaut Two dots above : A,E,I,O,U,,a,e,i,o,u,y
diaeresis letter
ring Small circle above o A,a
letter
cedilla Small tail below , C,c
letter
See HELP ACCENT3 for more
& ACCENT3
These are non-accent special characters, mostly punctuation and
non-roman letters.
Template String
Description Character Character
--------------------------------------------------------------
Upside-down ? u ?
Upside-down ! u !
<< quote mark " <
>> quote mark " >
German sharp s B s
Capital thorn | P
Lower-case thorn | p
Capital eth - D
Lower-case eth & o
See HELP ACCENT4 for examples
& ACCENT4
Some examples of accent() and their expected outputs:
> think accent(Aule, ---:)
Aul(e-with-diaeresis)
> think accent(The Nina was a ship, The Ni~a was a ship)
The Ni(n-with-~)a was a ship
> think accent(Khazad ai-menu!, Khaz^d ai-m^nu!)
Khaz(a-with-^)d ai-m(e-with-^)nu!
& ACOS()
acos(<cosine>[, <angle type>])
Returns the angle that has the given <cosine> (arc-cosine), with the
angle expressed in the given angle type, or radians by default.
See HELP CTU() for more on the angle type.
& ADD()
add(<number>,<number>,...)
Returns the sum of some numbers.
& AFTER()
after(<string1>, <string2>)
Returns the portion of <string1> that occurs after <string2>.
If <string2> isn't in <string1>, the function returns a null string.
This is case-sensitive.
Examples:
> think after(foo bar baz,bar)
baz
> think after(foo bar baz,ba)
r baz
& ALIGN()
align(<widths>,<col1>,..,<coln>[,<filler>[,<colsep>[,<rowsep>])
Creates columns of text, each column designated by <col1..coln>.
Each column is individually wrapped inside its own column, allowing
for easy creation of book pages, newsletters, or the like.
<widths> is a space-separated list of column widths. '10 10 10' for
the widths argument specifies that there are 3 columns, each 10
spaces wide. You can further modify this by prefixing the number
with '<', '-' or '>'. A < before a number causes the field to be
left-aligned. A '-' causes it to be centered, and '>' makes it
right-aligned. No prefix defaults to left-aligned. A '.' after the
number implies the column is to be repeated for as long as there is
a non-repeating column.
<filler> is a single character that, if given, is the character used
to fill empty columns and remaining spaces. <colsep>, if given, is
inserted between every column, on every row. <rowsep>, if given, is
inserted between every line. By default, <filler> and <colsep> are
a space, and <rowsep> is a newline.
Continued in HELP ALIGN2
& ALIGN2
Examples:
> &line me=align(<5 10 20,\([left(xget(%0,sex),1)]\),name(%0),name(%L))
> th iter(lwho(),u(line,##))
(M) Walker Tree
(F) Jane Doe Nowhere
> &haiku me = Alignment function,%rIt justifies your writing,%rBut the
words still suck.%rLuke
> th [align(5 -40 5,,[repeat(-,40)]%r[u(haiku)]%r[repeat(-,40)],,%b,+)
+----------------------------------------+
+ Alignment function, +
+ It justifies your writing, +
+ But the words still suck. +
+ Luke +
+----------------------------------------+
& ALLOF()
allof(<expr1>[, ...,<exprN>], <osep>)
Evaluates every expression argument (including side-effects) and returns
the results of those which are true, in a list separated by osep. The
output separator argument is required and must be a single character,
or can be left empty, in which case a space will be used to separate the
results by default.
The meaning of true or false depends on configuration options as
explained in the 'BOOLEAN VALUES' help topics.
> &s me=Bats are similar to Rats which are afraid of Cats
> say allof(grab(v(s),rats),grab(v(s),mats),grab(v(s),bats),)
You say, "Rats Bats"
> say allof(#-1,#101,#2970,,#-3,0,#319,null(This Doesn't Count),|)
You say, "#101|#2970|#319"
See also: firstof(), BOOLEAN VALUES
& ALPHAMAX()
alphamax(<word1>, <word2>, <word3>, ...)
Takes any number of arguments, and returns the word which is
lexicographically biggest. I.e., which word would be last in
alphabetical order.
& ALPHAMIN()
alphamin(<word1>, <word2>, <word3>, ...)
Takes any number of arguments, and returns the word which is
lexicographically smallest: the word that would be first in
alphabetical order.
& AND()
& CAND()
and(<boolean value 1>,<boolean value 2>[, ... , <boolean value N>])
cand(<boolean value 1>,<boolean value 2>[, ... , <boolean value N>])
Takes boolean values, and returns 1 if all of them are equivalent
to true(1). and() always evaluates all arguments (including side
effects), while cand() stops evaluation after the first argument
that evaluates to false.
See also: BOOLEAN VALUES, or(), xor(), not()
& ANDFLAGS()
andflags(<object>,<string of flag letters>)
This function returns 1 if <object> has all the flags in a specified
string, and 0 if it does not. The string is specified with a single
letter standing for each flag, like the output of the FLAGS()
function. A '!' preceding a flag letter means "not flag".
Thus, ANDFLAGS(me,WD) would return 1 if I was set WIZARD and DARK.
ANDFLAGS(me,W!Dc) would return 1 if I was set WIZARD, not DARK,
and CONNECTED.
If a letter does not correspond to any flag, <object> doesn't have it,
so the function returns 0. There can be an arbitrary number of flags. Do
not put spaces between flag letters.
& ANDLFLAGS()
andlflags(<object>,<list of flags>)
This function returns 1 if <object> has all the flags in a specified
list, and 0 if it does not. The list is a space-separated list of
flag names. A '!' preceding a flag name means "not flag".
Thus, ANDLFLAGS(me,wizard dark) would return 1 if I was set WIZARD
and DARK. ANDFLAGS(me,wizard !Dark connected) would return 1 if I
was set WIZARD, not DARK, and CONNECTED.
If a name does not correspond to any flag, <object> doesn't have it,
so the function returns 0. There can be an arbitrary number of flags.
& ANSI()
ansi(<codes>,<string>)
This allows you to highlight a string using ANSI terminal effects.
The codes are:
f - flash F - not flash
h - hilite H - not hilite
u - underscore U - not underscore
i - inverse I - not inverse
n - normal
x - black foreground X - black background
r - red foreground R - red background
g - green foreground G - green background
y - yellow foreground Y - yellow background
b - blue foreground B - blue background
m - magenta foreground M - magenta background
c - cyan foreground C - cyan background
w - white foreground W - white background
For example, "ansi(fc, Test)" would hilight "Test" in flashing cyan.
See also: ANSI, COLOR
& APOSS()
aposs(<object>)
Returns the absolute possessive pronoun - his/hers/its/theirs -
for an object.
& ART()
art(<string>)
This function returns the proper article, "a" or "an", based on whether
or not <string> begins with a vowel.
& ASIN()
asin(<sine>[, <angle type>])
Returns the angle with the given <sine> (arc-sine), with the angle
expressed in the given angle type, or radians by default.
See HELP CTU() for more on the angle type.
& ATAN()
& ATAN2()
atan(<tangent>[, <angle type>])
atan2(<number>, <number>[<, <angle type>])
Returns the angle with the given <tangent> (arc-tangent), with the
angle expressed in the given angle type, or radians by default.
atan2(y, x) is like atan(fdiv(y, x)), except x can be 0, and the
signs of both arguments are used in determining the sign of the
result. It is useful in converting between cartesian and polar
coordinates.
See HELP CTU() for more on the angle type.
& ATRLOCK()
atrlock(<object>/<attrib>[, <on|off>])
When given a single object/attribute pair as an argument, returns 1
if the attribute is locked, 0 if unlocked, and #-1 if the attribute
doesn't exist or can't be read by the function's caller.
When given a second argument of "on" (or "off"), attempts to lock
(unlock) the specified attribute, as per @atrlock.
& BAND()
band(<integer>,<integers>,...)
Does a bitwise AND of all its arguments, returning the result
(A number with only the bits set in every argument set in it).
& BASECONV()
baseconv(<number>, <from base>, <to base>)
Converts <number>, which is in base <from base> into base <to base>.
The bases can be between 2 (binary) and 36.
& BEEP()
beep([<number>])
Sends <number> "alert" bell characters. <number> must be in the range
1 to 5, or, if unspecified, defaults to 1.
This function may only be used by royalty and wizards.
& BEFORE()
before(<string1>, <string2>)
Returns the portion of <string1> that occurs before <string2>.
If <string2> isn't in <string1>, <string1> is returned.
This is case-sensitive.
Examples:
> think before(foo bar baz,bar)
foo
> think before(foo bar baz,r)
foo ba
& BRACKETS()
brackets([<string>])
Returns a count of the number of left and right square brackets,
parentheses, and curly braces in the string, in that order, as a
space-separated list of numbers. This is useful for finding missing
or extra brackets in MUSH code.
Example:
> @desc me=This is [ansi(h,a test)] of the { brackets() function.
> think brackets(v(desc))
1 1 2 2 1 0
& BNAND()
bnand(<integer>, <integer>)
Returns its first argument with every bit that was set in the second
argument cleared.
& BNOT()
bnot(<integer>)
Returns the bitwise complement of its argument. Every bit set in it
is cleared, and every clear bit is set.
& BOR()
bor(<integer>, <integer>, ...)
Does a bitwise OR of all its arguments, returning the result.
(A number with a bit set if that bit appears in any of its arguments).
& BOUND()
bound(<number>, <lower bound>, <higher bound>)
bound() returns <number> if it is between <lower bound> and
<higher bound>. If it's lower than the lower bound, the lower
bound is returned. If it's higher than the higher bound,
the higher bound is returned.
See also: ceil(), floor(), round(), trunc()
& BXOR()
bxor(<integer>, <integer>,...)
Does a bitwise XOR of all its arguments, returning the result.
(A number with a bit set if it's set in only one of its arguments).
& CAPSTR()
capstr(<string>)
Returns <string> with the first character capitalized.
Example: capstr(foo bar baz) returns "Foo bar baz"
See also: lcstr(), ucstr()
& CAT()
cat(<string1>,<string2>[,<string3>,<string4>,...])
cat() concatenates strings, separating each string by a space.
So "[cat(one, two)]" will return 'one two'.
& CEIL()
ceil(<number>)
Returns the least integral value greater than or equal to <number>.
See also: floor(), bound(), round(), trunc()
& CEMIT()
cemit(<channel>, <message>[, <noisy>])
Sends a message to all players listening to the given chat channel.
See help @cemit for details.
If the third argument is a true value, the channel name will be
prepended to the message, behaving like @cemit/noisy.
& CENTER()
center(<string>,<width>[,<fill>])
This function will center <string> within a field <width> characters wide,
using <fill> characters for padding on either end of the string for
centering. If <fill> is not specified, a space will be used.
Example:
> say center(X,5,-)
You say, "--X--"
> say center(.NEAT.,15)
You say, " .NEAT. "
& CFLAGS()
cflags(<channel>)
cflags(<channel>,<object>)
With one argument, cflags() returns a list of flags set on the
given channel, represented as a string of characters. See
'help channel-list' for the list of flags (they appear in the
"Access" column). You must be able to see the channel to use this
function.
With two arguments, cflags() returns a list of flags for that
object on that channel, currently a string consisting of zero
or more of "G" (gagging), "Q" (muted), and "H" (hidden).
You must be able to see that channel and to examine the object
to use this function. If the object is not on the channel, an
error is returned.
& CHANNELS()
channels([<delimiter>])
channels(<object>)
channels(<object>[,<delimiter>])
With no arguments, channels() returns the list of all channel names
which are visible to the player. With two arguments, returns the list
of channel names to which the object is listening, delimited by
<delimiter>.
With one argument, the behavior is ambiguous. If the argument
matches an object, returns the list of names to which the object
is listening, space-delimited. If not, it's treated as a no-argument
case with a delimiter.
If you don't have permission to examine the object, you only see
those channels to which the object belong for which you have
permission to join (or are joined to).
& CHECKPASS()
checkpass(<player>,<string>)
Returns 1 if <string> matches the player's password otherwise 0.
If <player> has no password, this function will always return 1.
<player> should be specified as a dbref or *<name>.
This function is restricted to wizards.
& CHR()
& ORD()
chr(<number>)
ord(<character>)
ord() returns the numerical value of the given character.
chr() returns the character with the given numerical value.
Examples:
> think ord(A)
65
> think chr(65)
A
& CLOCK()
clock(<channel>[/<locktype>][, <new lock>])
With one argument, returns the value of a lock on a channel, if you
own the channel or are See_All. If no locktype is given, "JOIN"
is assumed.
With two arguments, sets the lock if you would be able to do so via
@clock.
See also: @clock
& CLONE()
clone(<object>)
This function clones <object>, and returns the dbref number of the clone.
This is a side-effect function and may not be enabled on some MUSHes.
& CMDS()
cmds(<player|descriptor>)
Returns the number of commands issued by a player during this
connection as indicated by WHO.
The caller can use the function on himself, but using on any other
player requires privileged power such as Wizard, Royalty or SEE_ALL.
See also: Connection Functions
& SENT()
sent(<player|descriptor>)
Returns the number of characters sent by a player during this
connection as indicated by SESSION.
The caller can use the function on himself, but using on any other
player requires privileged power such as Wizard, Royalty or SEE_ALL.
See also: Connection Functions
& RECV()
recv(<player|descriptor>)
Returns the number of characters received by a player during this
connection as indicated by SESSION.
The caller can use the function on himself, but using on any other
player requires privileged power such as Wizard, Royalty or SEE_ALL.
See also: Connection Functions
& COMP()
comp(<value1>, <value2>[, <type>])
Comp compares two values. It returns 0 if they are the same, -1 if
value1 is less than/precedes alphabetically value2, and 1
otherwise.
By default the comparison is a case-sensitive lexicographic (string)
comparison. By giving the optional <type>, the comparison can
be specified:
<type> Comparison
A Maybe case-sensitive lexicographic (default)
I Always case-insensitive lexicographic
D Dbrefs of valid objects
N Integers
F Floating point numbers
Whether or not the a sort type is case-sensitive or not depends
on the particular mush and its environment.
& CON()
con(<object>)
Returns the dbref of the first object in a container.
You can get the complete contents of any container you may examine,
regardless of whether or not objects are dark. You can get the
partial contents (obeying DARK/LIGHT/etc.) of your current location
or the enactor (%#). You CANNOT get the contents of anything else,
regardless of whether or not you have objects in it.
See also: lcon(), next()
& CONFIG()
config()
config(<option>)
With no arguments, this function returns a list of config option names.
Given a config option name, this function returns its value.
Boolean configuration options will return values of "Yes" or "No".
Ex: config(money_singular) => "Penny"
& CONN()
conn(<player|descriptor>)
This function returns the number of seconds a player has been connected.
<player name> must be the full name of a player, or a player's dbref.
Players who are not connected have a conn value of "-1", as do dark
wizards, when conn() is used on them by a non-priv'ed player.
See also: CONNECTED
& CONTROLS()
controls(<object>,<victim>)
This function returns 1 if <object> controls <victim>, or 0, if
it does not. If one of the objects does not exist, it will return
#-1 ARGN NOT FOUND (where N is the argument which is the invalid
object). You must control <object> or <victim>, or have the See_All
power, to use this function.
See also: CONTROL
& CONVSECS()
& CONVUTCSECS()
convsecs(<seconds>[, <zone>])
convutcsecs(<seconds>)
This function converts seconds to a time string, based on how many
seconds the number is after Jan 1, 1970 UTC. Because it's based on
UTC, but returns local time, convsecs(0) is not going to be
"Thu Jan 1 00:00:00 1970" unless you're in the UTC (GMT) timezone.
convutcsecs() and convsecs() with a second argument of 'utc' return
the time based on UTC time instead of the server's local time.
Example:
> say [secs()]
You say, "709395750"
> say [convsecs(709395750)]
You say, "Wed Jun 24 10:22:54 1992"
> say [convutcsecs(709395750)]
You say, "Wed Jun 24 14:22:30 1992"
See also: convtime(), time()
& CONVTIME()
convtime(<time string>)
This functions converts a time string (in the local time zone) to the
number of seconds since Jan 1, 1970 GMT. A time string is of the
format: Ddd MMM DD HH:MM:SS YYYY where Ddd is the day of the week,
MMM is the month, DD is the day of the month, HH is the hour in
24-hour time, MM is the minutes, SS is the seconds, and YYYY is the
year. If you supply an incorrectly formatted string, it will return
-1.
If the extended convtime() is supported (See @config compile), more
formats for the date are enabled, including ones missing the day
of week and year, and a 'Month Day Year' format.
Example:
> say [time()]
You say, "Wed Jun 24 10:22:54 1992"
> say [convtime(Wed Jun 24 10:22:54 1992)]
You say, "709395774"
See also: convsecs(), time()
& COS()
cos(<angle>[, <angle type>])
Returns the cosine of <angle>. Angle must be in the given angle
type, or radians by default.
Example:
> say cos(90, d)
You say, "0"
> say cos(1.570796)
You say, "0"
See HELP CTU() for more on the angle type.
& COWNER()
cowner(<channel>)
Returns the dbref of the owner of a channel.
& PCREATE()
pcreate(<name>,<password>)
Creates a player with a given name and password. Wizard-only.
See also: @pcreate
& CREATE()
create(<object>, <cost>)
This function creates an object with name <object> for <cost> pennies,
and returns the dbref number of the created object.
This is a side-effect function and may not be enabled on some MUSHes.
& CTIME()
ctime(<object>)
If creation times are enabled, this function will return the
date and time that the object was created, if the player is
able to examine the object.
& CTITLE()
ctitle(<channel>,<object>)
Returns <objects> @chan/title on <channel>. You must either
be able to examine the object, or it must visible be on a channel
which you are allowed to join.
& CTU()
ctu(<angle>, <from>, <to>)
Converts between the different ways to measure angles.
<from> controls what the angle is treated as, and <to> what form
it is turned into. They can be 'd' for degrees, or 'r' for radians.
There is also a third way to measure angle, 'g' for gradians, but it's not
used often and is only included for completeness.
As a refresher, there are 180 degrees in pi radians in 200 gradians.
Example:
> say 90 degrees is [ctu(90, d, r)] radians
You say, "90 degrees is 1.570796 radians"
& CWHO()
cwho(<channel>)
This returns a list of connected dbrefs who are on <channel>.
When used by mortals, hidden/DARK players do not appear on the list.
& DEC()
dec(<integer>)
dec(<string-ending-in-integer>)
Dec returns the integer minus 1. If given a string that ends in an integer,
it decrements only the final integer portion. That is:
> think dec(3)
2
> think dec(hi3)
hi2
> think dec(1.3.3)
1.3.2
> think dec(1.3)
1.2
Note especially the last example, which will trip you up if you use
floating point numbers with dec() and expect it to work like sub().
See also: inc()
& DECRYPT()
decrypt(<string>, <password>)
Decrypts a string encrypted with the encrypt() function, if given
the string and the same password.
& DEFAULT()
Function: default([<obj>/]<attr>,<default case>)
This function returns the value of <obj>/<attr>, as if retrieved via
the get() function, if the attribute exists and is readable by you.
Otherwise, it evaluates the default case, and returns that.
Note that the default case is only evaluated if the attribute does
not exist or cannot be read. Note further than an empty attribute
counts as an existing attribute.
This is useful for code that needs to return the value of an attribute,
or an error message or default case, if that attribute does not exist.
Examples:
> &TEST me=apple orange banana
> say default(me/Test, No fruits!)
You say "apple orange banana"
> &TEST ME
> say default(me/Test, No fruits!)
You say "No fruits!"
See also: get(), eval(), ufun(), edefault(), udefault(), uldefault()
& DELETE()
delete(<string>, <first>, <len>)
Return a modified <string>, with <len> characters starting after the
character at position <first> deleted. In other words, it copies <first>
characters, skips <len> characters>, and then copies the remainder of
the string.
Example:
> say [delete(abcdefgh, 3, 2)]
You say, "abcfgh"
& DIE()
die(<number of times to roll die>, <number of sides on die>[, <show>])
This function simulates rolling dice. It "rolls" a die with a given
number of sides, a certain number of times, and sums the results.
For example, DIE(2, 6) would roll "2d6" - two six-sided dice,
generating a result in the range 2-12. The maximum number of
dice this function will roll in a single call is 20.
If a third argument is given and it's a true value, the result will
be a space-seperated list of the individual rolls rather than their
sum.
Example:
> think die(3, 6)
6
> think die(3, 6, 1)
5 2 1
& DIG()
dig(<name> [, <exit to> [, <exit from>]])
This function digs a room called <name>, and optionally opens and links
<exit to> and <exit from>, like the normal @dig command. It returns
the dbref number of the new room.
This is a side-effect function and may not be enabled on some MUSHes.
& DIGEST()
digest(<algorithm>, <string>)
Returns a checksum (Hash, digest, etc.) of <string> using the given
<algorithm>. If the mush is compiled with SSL support (See @config
compile), <algorithm> can be one of:
md2 md4 md5 sha sha1 dss1 mdc2 ripemd160
Without SSL, only the sha algorithm is enabled. In both cases, sha returns
the same thing as the sha0() function.
See also: sha0()
& DIST2D()
dist2d(x1, y1, x2, y2)
Returns the distance between two points in the Cartesian
plane that have coordinates (x1, y1) and (x2, y2).
& DIST3D()
dist3d(x1, y1, z1, x2, y2, z2)
Returns the distance between two points in space, with
coordinates (x1, y1, z1) and (x2, y2, z2).
& DIV()
& FLOORDIV()
div(<number>,<number>)
floordiv(<number>,<number>)
Div returns the integer part of the quotient of the first number
divided by the second number. Floordiv returns the largest integer
less than or equal to the quotient of the first number divided by
the second. For positive numbers, these are the same thing, but
for negative numbers they may be different:
div(13,4) ==> 3 and floordiv(13,4) ==> 3
div(-13,4) ==> -3 but floordiv(-13,4) ==> -4
div(13,-4) ==> -3 but floordiv(13,-4) ==> -4
div(-13,-4) ==> 3 and floordiv(-13,-4) ==> 3
Note that add(mul(div(%0,%1),%1),remainder(%0,%1)) always yields %0,
and add(mul(floordiv(%0,%1),%1),modulo(%0,%1)) also always yields %0.
See also: MODULO
& DOING()
doing(<player|descriptor>)
Given the name of a connected player, returns that player's @doing
string if they can be seen on the WHO list.
See also: @poll, @doing, poll()
& E()
e()
Returns the value of "e" (2.71828182845904523536, rounded to the
game's float_precision setting).
& EDEFAULT()
Function: edefault([<obj>/]<attr>,<default case>)
This function returns the evaluated value of <obj>/<attr>, as if
retrieved via the get_eval() function, if the attribute exists and
is readable by you. Otherwise, it evaluates the default case, and
returns that. The default case is only evaluated if the attribute
does not exist or cannot be read.
Example:
> &TEST me=You have lost [rand(10)] marbles.
> say edefault(me/Test,You have no marbles.)
You say "You have lost 6 marbles."
> &TEST me
> say edefault(me/Test,You have no marbles.)
You say "You have no marbles."
See also: get(), eval(), ufun(), default(), udefault()
& EDIT()
edit(<string>, <search>, <replace>[, <search2>, <replace2> ...])
This functions in a similar way to the @edit command; instead of
taking an attribute from an object, it takes an arbitrary string.
It searches the string for <search> and replaces with <replace>,
then repeats the process if additional search-replace pairs are
given.
If <search> is a caret (^), <replace> is prepended.
If <search> is a dollar sign ($), <replace> is appended.
If <search> is an empty string, <replace> is inserted between
every character, and before the first and after the last.
If <replace> is an empty string, <search> is deleted from the string.
Example:
> say [edit(this is a test,^,I think%b,$,.,a test,an exam)]
You say "I think this is an exam."
edit() can not replace a literal single ^ or $. Use regedit() for that.
See also: @edit, regedit()
& ELEMENT()
element(<list>,<item>,<single-character separator>)
This returns the position of <item> in <list>, where <list>'s items
are separated by <separator>. A wildcard match is done, so this
function behaves much like MATCH(), except its separator argument
is required, not optional.
Example:
> say [element(this|is|a|test|string,is,|)]
You say, "2"
See also: match(), grab()
& ELEMENTS()
elements(<list of words>,<list of numbers>[,<delim>][, <osep>])
This function returns the words in <list of words> that are in the
positions specified by <list of numbers>. Optionally, a list delimiter
other than a space can be used.
Examples:
> say elements(Foo Ack Beep Moo Zot,2 4)
You say "Ack Moo"
> say elements(Foof|Ack|Beep|Moo,3 1,|)
You say "Beep|Foof"
See also: extract(), index(), grab()
& ELOCK()
elock(<object>[/<locktype>], <victim>)
elock() returns 1 if the <victim> would pass the lock on <object>,
and 0 if it would fail. You must control <object>.
You can also provide a switch after <object> if you wish to check
something other than the basic lock. This can be used to test
user-defined locks. elock() can take as many switches as @lock.
For example:
@lock/drop Dancing Slippers=#0
think elock(Dancing Slippers/drop, Princess)
> 0
See also: @lock, locktypes
& EMIT()
& NSEMIT()
emit(<message>)
nsemit(<message>)
Sends a message to the room, as per @emit.
nsemit() is a wizard-only variation that works like @nsemit.
& ENCRYPT()
encrypt(<string>, <password>)
Returns an encrypted string produced by a simple password-based
encrypted algorithm. Good passwords are long passwords.
This is not high-security encryption. See also decrypt().
& ENTRANCES()
entrances([<object> [,<type> [,<begin> [,<end>]]]])
With no arguments, the entrances() function returns a list of all
exits, things, players, and rooms linked to your location, like
@entrances. You can specify an object other than your current location
with <object>. You can limit the type of objects found by specifying
<type> as follows:
a all (default)
e exits
t things
p players
r rooms
You can also limit the range of the dbrefs searched by giving <begin>
and <end>.
This function is computationally expensive and costs the same as
@find. You must control the object in order to perform entrances()
on it.
& EQ()
eq(<number1>,<number2>)
Takes two numbers, and returns 1 if they are equal, 0 otherwise.
See also: neq()
& ESCAPE()
escape(<string>)
The ESCAPE() function "escapes out" potentially "dangerous" characters,
preventing function evaluation in the next pass of the parser. It
returns <string> after adding the escape character ('\') at the
beginning of the string, and before the following characters:
% ; [ ] { } \ ( ) , ^ $
This function prevents strings entered by players from causing side
effects, such as performing an unintended GET() of an attribute. It
is only needed when the resulting string will be passed through @force
or used as an attribute for an object (like the description of a mail
message object). Since the function preserves the original string,
it is, in most cases, a better choice than SECURE().
& EVAL()
& GET_EVAL()
eval(<object>, <attribute>)
get_eval(<object>/<attribute>)
Eval() works the same way as xget(), except that it performs %-substitutions
and function evaluation on the attribute before returning the value. eval()
does not modify the stack (%0-%9), so the attribute being evaled sees the
same values for them that the calling code does. Unless you need this behavior,
it is better to use u() instead, which hides the caller's stack.
Example:
&TEST me=%B%B%B-[name(me)]
think xget(me,test)
> %B%B%B-[name(me)]
think eval(me,test)
> -Shalott
Get_eval() does the same thing, except it uses the format of get() instead
of xget() -- using a slash rather than a comma to separate the object from
the attribute. It is included for TinyMUSH 2.x compatibility.
See also: get(), u(), xget()
& EXIT()
exit(<object>)
Returns the dbref of the first exit in a room.
You can get the complete exit list of any room you may examine,
regardless of whether or not exits are dark. You can get the partial
exit list (obeying DARK/LIGHT/etc.) of your current location or the
enactor (%#). You CANNOT get the exit list of anything else,
regardless of whether or not you have objects in it.
See also: lexits(), next()
& EXP()
exp(<number>)
Returns e to the power of <number>.
& EXTRACT()
extract(<list>,<first>,<length>[,<delimiter>])
This function returns <length> elements of a list, counting
from the <first> element.
For example:
think extract(This is a test string,3,2)
> a test
See also: index(), elements(), grab()
& FDIV()
fdiv(<numerator>,<denominator>)
Returns the quotient of the two numbers. Note that the DIV() and MOD()
functions cannot be used on floating point numbers.
& FILTER()
& FILTERBOOL()
filter([<obj>/]<attr>, <list>[,<delimiter>][,<osep>])
filterbool([<obj>]/<attr>, <list>[, <delimiter>][,<osep>])
This function returns the elements of <list> for which a user-defined
function evaluates to "1", or to a boolean true value if filterbool()
is used. That function is specified by the first argument (just as
with the ufun() function), and the element of the list being tested is
passed to that user-defined function as %0.
Thus, "filter(obj/attr, x1 x2 x3)" is nearly equivalent to
"iter(x1 x2 x3, switch(ufun(obj/attr, ##),1,##,))"
though the iter version may have extra blank spaces.
Example:
> &IS_ODD test=[mod(%0,2)]
> say [filter(test/is_odd, 1 2 3 4 5 6)]
You say, "1 3 5"
See also: anonymous attributes
& FINDABLE()
findable(<object>,<victim>)
This function returns 1 if <object> can locate <victim>, or 0, if
it cannot. If one of the objects does not exist, it will return
#-1 ARGN NOT FOUND (where N is the argument which is the invalid
object).
& FIRST()
first(<list>[,<delimiter>])
Returns the first element of a list.
See also: rest(), last()
& FIRSTOF()
firstof(<expr1>, <expr2>[, ... ,<exprN>])
Returns the first evaluated expression that is true. If no arguments
are true, then the last argument, <exprN>, is returned as the default
expression, whether it is true or false.
The meaning of true or false is dependent on configuration options
as explained in the 'BOOLEAN VALUES' help topics.
This function does evaluate each argument while testing, including
side-effects, stopping (short-circuits) when the true expression is
found.
> say firstof(0,2)
You say, "2"
> say firstof(10,11,0)
You say, "10"
> say firstof(grab(the cat,mommy),grab(in the hat,daddy),#-1 Error)
You say, "#-1 Error"
> say firstof(get(%#/royal cheese),#-1 This Has No Meaning,0,)
You say, ""
See also: allof(), BOOLEAN VALUES
& FLAGS()
flags(<object>)
flags(<object>/<attribute>)
flags()
Flags returns a string consisting of the flags attached to the
object or the attribute on the object. The string is a single word
made up of all the appropriate flag letters.
Given no arguments, this function returns a string consisting of
all the flag letters of all the flags the server knows. Note that
some flags may not have flag letters, and multiple flags may have
the same letter (and will appear twice).
See also: lflags()
& LFLAGS()
lflags(<object>)
lflags(<object>/<attribute>)
lflags()
Lflags returns a space-separated list consisting of the names of flags
attached to the object or the attribute on the object.
Given no arguments, this function returns a space-separated list
of all flag names known to the server.
See also: flags()
& FLIP()
& REVERSE()
flip(<string>)
reverse(<string>)
This function reverses a string. For example, "flip(foo bar baz)"
returns "zab rab oof".
& FLOOR()
floor(<number>)
Returns the greatest integral value less than or equal to <number>.
See also: ceil(), bound(), round(), trunc()
& FMOD()
fmod(<number>,<divisor>)
Identical to mod() but may take floating point arguments. The return
value is the (possibly floating point) smallest positive remainder
left after subtracting the largest number of multiples of <divisor>
from <number>.
Example:
> think fmod(6.1,2.5)
1.1
& FOLD()
fold([<obj>/]<attr>, <list>[, <base case>][,<delimiter>])
This function "folds" a list through a user-defined function, specified
by the first argument to fold(), which is analogous to ufun()'s first
argument.
If no base case is provided, fold() passes the first element of <list>
as %0, and the second element of <list> as %1, to the user-defined
function. The user-defined function is then called again, with the
result of the first evaluation being %0, and the next (third) element
of the list as %1. This is repeated until all the elements of the
list have been used.
If a base case is provided, it is passed as %0, and the first element
of list is passed as %1, to the user-defined function. The process for
the no-base-case fold() is then used.
See 'help FOLD2' for examples.
& FOLD2
Examples:
> &REP_NUM test=%0[repeat(%1,%1)]
> say [fold(test/rep_num,1 2 3 4 5)]
You say, "122333444455555"
> say [fold(test/rep_num,1 2 3 4 5,List:)]
You say, "List:122333444455555"
> &ADD_NUMS test=add(%0,%1)
> say [fold(test/add_nums,1 2 3 4 5)]
You say, "15"
See also: anonymous attributes
& FOLDERSTATS()
folderstats()
folderstats(folder#)
folderstats(player)
folderstats(player,folder#)
FOLDERSTATS() returns the number of read, unread, and cleared messages
in a specific folder, or, if none is given, the player's current
folder. Only Wizards may use forms which get other players' mail
information.
& FOLLOWERS()
followers(<object>)
Returns the list of things and players following object. You must
control object.
& FOLLOWING()
following(<object>)
Returns the list of things and players that the object is following.
You must control object.
& FOREACH()
foreach([<object>/]<attribute>,<string>[,<start>[,<end>]])
Maps a function onto a string.
Each character in <string> has the user-defined function of the first
argument performed on it; the character is passed to the function as
%0, and its position in the string as %1 (the first character has
position 0). The results are concatenated. If a start character is given,
everything before that character is copied without passing it to the
function, and everything after it until the end of the string or an end
character is passed to the function. Anything left after the end character
is also copied unevaluated. The start and end characters themselves are
not copied.
Continued in HELP FOREACH2
& FOREACH2
Examples:
> &add_one me=[add(%0,1)]
> say [foreach(add_one, 54321)]
You say, "65432"
> say [foreach(add_one, This is #0# number, #, #)]
You say, "This is 1 number"
> &is_alphanum me=[regmatch(%0, \[\[:alnum:\]\])]%b
> say [foreach(is_alphanum,jt1o+)]
You say, "1 1 1 1 0 "
See also: anonymous attributes
& ACCNAME()
accname(<object>)
accname() returns the name of object <object>, applying the object's
@nameaccent, if any.
Related functions: NAME(), FULLNAME(), INAME()
& FRACTION()
fraction(<number>)
This function returns a fraction representing the floating-point <number>.
Since not all numbers can be expressed as a fraction, dividing the
numerator by the denominator of the results will not always return the
original <number>, but something close to it.
Examples:
> think fraction(.75)
3/4
> think fraction(pi())
348987/111086
> think fraction(2)
2
& FULLNAME()
fullname(<object>)
Fullname() returns the name of object <object>. It is identical to
name() except that for exits, fullname() returns the complete
exit name, including all aliases.
>"[fullname(south)]
You say, "South;sout;sou;so;s"
Related functions: NAME(), ACCNAME(), INAME()
& FUNCTIONS()
functions()
Returns a space-separated list of the names of all function.
& GET()
get(<object>/<attribute>)
The get() function returns the string stored in an object's attribute.
You may get the attributes of objects you control, the attributes you
own on other objects, and publicly accessible attributes.
& GRAB()
& REGRAB()
& REGRABI()
grab(<list>, <pattern>[, <delimiter>])
regrab(<list>, <regexp>[, <delimiter>])
regrabi(<list>, <regexp>[, <delimiter>])
This function returns the first word in list which matches the pattern.
For grab(), the pattern is specified as in match(); i.e., it
can contain wildcards. For regrab(), the pattern is a regular expression.
regrabi() is case-insensitive.
Basically, this is a much more efficient way to do:
extract(list, match(list, pattern, delimiter), 1, delimiter) or
the regular expression variation thereof.
See also: match(), extract(), element(), elements(), index(), regmatch(),
graball()
& GRABALL()
& REGRABALL()
& REGRABALLI()
graball(<list>,<pattern>[,<delim>][,<output seperator])
regraball(<list>,<regexp>[,<delim>][,<output seperator])
regraballi(<list>,<regexp>[,<delim>][,<output seperator])
These functions work identically to the grab() and regrab()/regrabi()
functions, save that they return all matches, not just the first: They
return all words in the <list> which match <pattern>.
If none match, an empty string is returned.
Examples:
> say graball(This is a test of a test,test)
You say "test test"
> say graball(This is testing a test,tes*)
You say "testing test"
> say regraball(This is testing a test,s$)
You say "This is"
See also: match(), matchall(), grab(), regmatch()
& GREP()
& REGREP()
grep(<object>,<attrs>,<pattern>)
regrep(<object>,<attrs>,<regexp>)
grepi(<object>,<attrs>,<pattern>)
regrepi(<object>,<attrs>,<regexp>)
These functions return a list of attributes on <object> containing
<pattern> (or matching <regexp>). <attrs> is a wildcard pattern for
attribute names to search.
The list returned is similar to that returned by @grep/list
<object>/<attrs>=<pattern>
Parsing _does_ occur before this function is invoked. Therefore,
"special" characters will need to be escaped out. In grep(),
<pattern> is NOT wildcard matched.
grep()/regrep() are case-sensitive. grepi()/regrepi() are case-insensitive.
& GT()
gt(<num>,<num>)
Takes two numbers, and returns 1 if and only if the first is greater
than the second, and 0 otherwise.
& GTE()
gte(<num>,<num>)
Takes two numbers, and returns 1 if and only if the first is greater
than or equal to the second, and 0 otherwise.
& HASATTR()
& HASATTRP()
& HASATTRVAL()
& HASATTRPVAL()
hasattr(<object>, <attribute name>)
hasattrp(<object>, <attribute name>)
hasattrval(<object>, <attribute name>)
hasattrpval(<object>, <attribute name>)
The hasattr() functions check to see if an object has an attribute.
They return #-1 if the object does not exist or the attribute can't
be examined by the player. Otherwise, they return 1 if the attribute
is present and 0 if it is not.
hasattr() returns 1 if the object has the attribute, 0 if it doesn't.
hasattrp() also checks for attributes inherited from parent objects.
hasattrval() returns 1 if the attribute exists and isn't empty.
hasattrpval() is hasattrval() but checks parents.
& HASFLAG()
hasflag(<object>[/<attrib>], <flag name>)
Returns 1 if the object has the named flag, and 0 if it does not.
If the object does not exist, #-1 will be returned. You do not have
to control the object.
Example: hasflag(me, opaque) will return "1" or "0".
Unlike orflags() and andflags(), hasflag uses the *flag name*, not
the single character abbreviation. Many flag names have shorter
abbreviations which will also work (W for Wizard, roy for royalty).
The "flags" ROOM, EXIT, and PLAYER are actually types. If you want
to check if an object "has" one of these flags, you must use the
HASTYPE() function.
If an attribute is given, checks to see if the attribute has the
given attribute flag. See help attribute flags for attribute flag names.
See also: orlflags(), andlflags(), orflags(), andflags()
& HASPOWER()
haspower(<object>, <power name>)
Returns 1 if the object has the named power, and 0 if it does not.
If the object does not exist, #-1 will be returned.
You may or may not have to be able to examine the object to use this.
& HASTYPE()
hastype(<object>, <type>)
Returns 1 if the object is of the named type, otherwise 0.
Valid types are: ROOM, EXIT, PLAYER, THING, GARBAGE.
If an invalid type is given, #-1 NO SUCH TYPE is returned.
& HIDDEN()
hidden(<player|descriptor>)
Returns 1 if the player is hidden, otherwise 0.
Can only be called by someone privileged to see hidden players.
If you're not, #-1 is returned.
& HOME()
home(<object>)
Returns the object's 'home'. This is the home for a player or thing,
the drop-to of a room, or source of an exit.
& HOST()
& HOSTNAME()
host(<player|descriptor>)
hostname(<player|descriptor>)
Returns the hostname of a player as indicated by WHO. This may
be more reliable that get(<player>/lastsite) if the player has
multple connections from different locations, and the function
is called with a descriptor argument.
The caller can use the function on himself, but using on any other
player requires privileged power such as Wizard, Royalty or SEE_ALL.
See also: Connection Functions, ipaddr(), ports(), lports()
& IDLE()
& IDLESECS()
idle(<player|descriptor>)
idlesecs(<player|descriptor>)
This function returns the number of seconds a player has been idle,
much as WHO does. <player name> must be the full name of a player, or
a player's dbref. Players who are not connected have an idlesecs of "-1",
as do dark wizards, when idle() is used on them by a non-priv'ed player.
& IF()
& IFELSE()
if(<condition>, <true expression>[, <false expression>])
ifelse(<condition>, <true expression>, <false expression>)
These functions evaluate the <condition> and return <true expression>
if the <condition> is true, or <false expression> (if provided) if the
<condition> is false.
See also: BOOLEAN VALUES, switch()
& INAME()
iname(<object>)
iname() returns the name of object <object>, as it would appear if
you were inside it. It is identical to name() except that if the
object has a NAMEFORMAT or NAMEACCENT attribute, it is used.
You must be see_all, control <object>, or be inside it to use this
function.
See also: @nameformat, name(), fullname()
& INC()
inc(<integer>)
inc(<string-ending-in-integer>)
Inc returns the integer plus 1. If given a string that ends in an integer,
it increments only the final integer portion. That is:
> think inc(3)
4
> think inc(hi3)
hi4
> think inc(1.3.3)
1.3.4
> think inc(1.3)
1.4
Note especially the last example, which will trip you up if you use
floating point numbers with inc() and expect it to work like add().
See also: dec()
& INDEX()
index(<list>,<character>,<first>,<length>)
This function is similar to EXTRACT(), except that it requires a
separator argument, while EXTRACT() uses a space if a separator
isn't given. The function returns <length> items starting from
the <first> position. Trailing spaces are trimmed. The comma cannot
be used as the <character> separator unless it's escaped with a \.
Examples:
> say [index(Cup of Tea | Mug of Beer | Glass of Wine, |, 2, 1)]
You say, "Mug of Beer"
> say [index(%rtoy boat^%rblue tribble^%rcute doll^%rred ball,^,2,2)]
You say, "
blue tribble^
cute doll"
See also: extract(), elements(), grab()
& INSERT()
insert(<list>,<position>,<new item>[,<single-character separator>])
If <position> is a positive integer, this inserts <new item> BEFORE
the item at <position> from the left in <list>.
That means that <new item> then becomes the <position>th element of
<list>. If a separator is not given, a space is assumed. Null items are
counted when determining position, as in 'items()'.
If <position> is a negative integer, this inserts <new item> AFTER
the item at the absolute value of <position> from the RIGHT in <list>.
This is the same as reversing the list before inserting <new item>,
and then reversing it again into correct order. For example, when
<position> is -1, <new item> will be the last in the list; when
<position> is -2, <new item> will be the second item from the right,
and so on.
Examples:
> say [insert(This is a string,4,test)]
You say, "This is a test string"
> say [insert(one|three|four,2,two,|)]
You say, "one|two|three|four"
> say [insert(meep bleep gleep,-3,GOOP)]
You say, "meep GOOP bleep gleep"
& ISDAYLIGHT()
isdaylight()
Returns 1 if it's daylight savings time in the MUSH time zone,
otherwise 0.
& ISDBREF()
isdbref(<string>)
This function returns 1 if the string is a valid object dbref, and
0 if the string is not a valid object dbref.
See also: DBREFS
& ISINT()
isint(<string>)
Returns 1 if its argument is an integer, and 0 otherwise. Integers can
begin with a '+' or '-' sign, but the rest of the string must be digits.
See also: isnum()
& ISNUM()
isnum(<string>)
This function returns 1 if <string> is a number, and 0 if it is not.
Numbers can begin with a '-' sign (for negatives), but the rest of
the characters in the string must be digits, and an optional decimal
point.
See also: isint()
& ISWORD()
isword(<string>)
This function returns 1 if every character in <string> is a letter,
or 0, if any character isn't a letter. Case does not matter.
& ITEMS()
items(<list>,<single-character separator>)
items() counts the number of items in a list using an arbitrary
(required) separator. Null items are counted, so:
items(X|X,|) => 2 (2 X items)
items(X||X,|) => 3 (2 X items and 1 null item)
items(X X,%b) => 2 (2 X items)
items(X%b%bX,%b) => 3 (2 X items and 1 null item)
items(,|) => 1 (a single null item)
Another way to think about this is that items() counts the number
of delimiters in the string, and adds 1.
& ITEMIZE()
& ELIST()
itemize(<list>[,<delim>[,<conjunction>[,<punctuation>]]])
elist(<list>[,<conjunction> [,<delim> [,<output delim> [,<punctuation>]]]])
These functions take the elements of <list> (separated by <delim> or
a space by default), and:
If there's just one, return it.
If there's two, return <e1> <conjunction> <e2>
If there's more than two, return <e1><punc> <e2><punc> ... <conj> <en>
The default <conjunction> is "and", default punctuation is ","
Examples:
> say [itemize(eggs)] * [itemize(eggs bacon)]
You say, "eggs * eggs and bacon"
> say [itemize(eggs bacon spam)]
You say, "eggs, bacon, and spam"
> say [itemize(eggs bacon spam, ,&,;)]
You say, "eggs; bacon; & spam"
& ITER()
& PARSE()
iter(<list>,<pattern>[,<delimiter> [,<output separator>]])
parse(<list>,<pattern>[,<delimiter> [,<output separator>]])
This works in a manner very similar to @map, except that it returns
a string directly. <list> is a space-separated list of words, and
<pattern> is what will be "mapped" onto each element of the list,
with the token "##" being replaced successively by the next word in
the list, and the token "#@" being replaced by the word's position
in the list (see also help itext() and help inum()). The result is
concatenated and returned as a space separated list. This is similar
to @dolist, but the results are made into a list rather than executed.
The list may be <delimiter>-separated.
By default, the return list will be space-separated. However,
by including the output separator (which requires explicitly
including the delimiter), you can have it separated by any string.
Continued in HELP ITER2
& ITER2
parse() is a synonym for iter(). If you nest iters, ## and #@ refer
to the first iter(). See 'help ITEXT()' and 'help INUM()' for how to
retrieve their values for any nested iter. See 'help MAP()' for a
similar function.
Note that ## and #@ are replaced before evaluation, so the word will
be evaluated, which can be a problem when iter()ing on an untrusted
list. iter-with-itext or map() should be preferred to iter-with-##
whenever you're iterating over user-provided values.
> say [iter(This is a test string., [strlen(##)])]
You say, "4 2 1 4 7"
> say [iter(lnum(5), mul(add(##,##),2))]
You say, "0 4 8 12 16"
> say [iter(lexits(here), [name(##)] (owned by [name(owner(##))]))]
You say, "South (owned by Claudia) North (owned by Roy)"
> &STRLEN_FN me=[strlen(%0)]
> say [iter(This is a test string., [u(STRLEN_FN, ##)])]
You say, "4 2 1 4 7"
This example could be replaced by the use of map() like so:
> say [map(strlen_fun, This is a test string)]
> say [iter(lnum(3), ##, ,%r)]
You say, "0
1
2"
& ILEV()
& ITEXT()
& INUM()
ilev()
itext(<n>)
inum(<n>)
These functions, when called within an iter(), return the equivalent
of ## (itext) or #@ (inum), with reference to the nth more outermost
iter(), where n=0 refers to the current iter(), n=1 to an iter()
in which the current iter() is nested, etc. ilev() will return the
current nesting depth, or -1 if it is outside an iter(). Thus,
itext(ilev()) will return the ## of the outermost iter().
> say [iter(red blue green,iter(fish shoe, #@:##))]
You say, "1:red 1:red 2:blue 2:blue 3:green 3:green"
> say [iter(red blue green,iter(fish shoe, [inum(ilev())]:[itext(1)]))]
You say, "1:red 1:red 2:blue 2:blue 3:green 3:green"
> say [iter(red blue green,iter(fish shoe, [inum(0)]:[itext(0)]))]
You say, "1:fish 2:shoe 1:fish 2:shoe 1:fish 2:shoe"
> say [iter(red blue green,iter(fish shoe, [itext(1)]:[itext(0)]))]
You say, "red:fish red:shoe blue:fish blue:shoe green:fish green:shoe"
& IPADDR()
ipaddr(<player|descriptor>)
Returns the IP address of the connected player or descriptor. This
may be more reliable that get(<player>/lastip) if the player has
multple connections from different locations, and the function
is called with a descriptor argument.
The caller can use the function on himself, but using on any other
player requires privileged power such as Wizard, Royalty or SEE_ALL.
See also: Connection Functions, hostname(), ports(), lports()
& LAST()
last(<list>[,<delimiter>])
Returns the last element of a list.
See also: first(), rest()
& LATTR()
& LATTRP()
lattr(<object>[/<attribute pattern>])
lattrp(<object>[/<attribute pattern>])
Returns a space-separated list of the attribute names on the object
that you are permitted to examine. To see the complete list,
you must either be a Wizard or Royalty, own the object, have the
See_All power, or have the object set VISUAL in order to use this
function on the object.
If a wildcarded attribute pattern is provided, only attribute names
matching that pattern will be returned. lattr() uses the same
wildcards as examine (?, *, **).
lattrp() also includes attributes inherited from parents.
See also: nattr(), examine
& NATTR()
& NATTRP()
& ATTRCNT()
& ATTRPCNT()
nattr(<object>[/<attribute-pattern>])
nattrp(<object>[/<attribute-pattern>])
attrcnt(<object>[/<attribute-pattern>])
attrpcnt(<object>[/<attribute-pattern>])
This function (known by two names) returns the number of attributes
on the object that you are permitted to examine. This function is
considerably faster than words(lattr()) and doesn't suffer from buffer
length constraints. It's designed primarily for statistical purposes.
nattrp() and attrpcnt() also count matching attributes on the parent.
See also: lattr()
& LCON()
lcon(<object>)
Returns a list of the dbrefs of contents in a container.
You can get the complete contents of any container you may examine,
regardless of whether or not objects are dark. You can get the
partial contents (obeying DARK/LIGHT/etc.) of your current location
or the enactor (%#). You CANNOT get the contents of anything else,
regardless of whether or not you have objects in it.
See also: lexits(), lplayers(), con(), next(), lvcon()
& LCSTR()
lcstr(<string>)
Returns <string> with all letters converted to lowercase.
Example: lcstr(Foo BAR bAz) returns "foo bar baz"
See also: capstr(), ucstr()
& LDELETE()
Ldelete(<list>,<position>[,<single-character separator>])
This deletes the item at <position> in the list. If a separator
character is not given, a space is assumed. Null items are
counted, as in 'items()'.
Examples:
> say [ldelete(This is a long test string,4)]
You say, "This is a test string"
> say [ldelete(lemon|orange|apple,2,|)]
You say, "lemon|apple"
& LEFT()
left(<string>, <length>)
Returns the first <length> characters from string.
& NSLEMIT()
& LEMIT()
lemit(<message>)
nslemit(<message>)
Sends a message to the outermost room, as per @lemit.
nslemit() is a wizard-only variation that works like @nslemit.
& LEXITS()
lexits(<object>)
Returns a list of the dbrefs of exits in a room.
You can get the complete exit list of any room you may examine,
regardless of whether or not exits are dark. You can get the partial
exit list (obeying DARK/LIGHT/etc.) of your current location or the
enactor (%#). You CANNOT get the exit list of anything else,
regardless of whether or not you have objects in it.
See also: lcon(), exit(), next(), lvexits()
& LJUST()
ljust(<string>,<length>[,<fill>])
This function pads a string with trailing characters ("left-justifies")
so it is <length> long. If <string> is longer than <length>, the <string>
is returned; it is not truncated. If <fill> is not specified, a space
is used.
Examples:
> say [ljust(foo,6)]
You say, "foo "
> say %r0[ljust(foo,6,-)]7%r01234567
You say, "
0foo---7
01234567"
& LINK()
link(<name>, <destination>)
This function links object <name> to <destination>. While normally
used on exits, it has all of the other capabilities of @link as well.
It returns nothing.
This is a side-effect function and may not be enabled on some MUSHes.
& LIST()
list(<option>)
This function takes the same arguments as the @list command, and returns
the same things.
& LIT()
lit(<string>)
This function returns the string literally - without even squishing
spaces, and without evaluating *anything*. This can be useful for
writing ASCII maps with spaces or whatever.
It can be a bit tricky to get a literal string with spaces into an
attrib, however, since spaces are usually squished in setting an
attribute. This example illustrates how to make it work:
> @va me=$test: think {[lit(near far)]}
Set.
> ex me/va
VA [#1]: $test: think {[lit(near far)]}
> test
near far
Leaving out the {}'s will not work in the above.
& LMATH()
lmath(<op>, <list>[, <delim>])
This function performs generic math operations on <list>, returning
the result. Each element of the list is treated as one argument to
an operation, so that lmath(<op>, 1 2 3) is equivalent to <op>(1, 2, 3).
Using @function, one can easily write ladd, lsub, etc as per TinyMUSH.
Supported <op>'s are: add and band bor bxor div fdiv max mean
median min modulo mul nand nor or remainder stddev sub xor
Example:
>think lmath(add, 1|2|3, |)
6
>think lmath(max, 1 2 3)
3
>&FUN_FACTORIAL me=[lmath(mul,lnum(1,%0))]
>think u(fun_factorial,5)
120
& LN()
ln(<number>)
Returns the natural log of <number>.
& LNUM()
lnum(<number>)
lnum(<start number>,<end number>[,<output separator>])
With one argument, lnum returns a list of numbers, from 0 to <number - 1>.
For example, lnum(4) returns the list "0 1 2 3". This is useful for
creating loops.
With two arguments, the numbers range from the first to the second
argument. For example, lnum(1,4) => 1 2 3 4
With three arguments, the output is separated by the separator
given in the third argument. lnum(1,4,|) => 1|2|3|4
& LOC()
loc(<object>)
Loc returns the dbref of the location that object is at. The
object has to either be yours or be in the same room as you to
work. The location of an exit is its destination (the source of
an exit is its home). The location of a room is its drop-to
(if one is not set, then the location is #-1).
& LOCALIZE()
localize(<code>)
Localize() saves the q-registers, evaluates its argument, and restores
the registers afterwards. It has much the same relation to s() that
ulocal() does to u(), except localize()'s argument is only evaluated
once, instead of twice like s()'s. Useful in @functions or to wrap around
fragments of code too small to go into another attribute.
Example:
> say [setr(0, Outside)]-[s(\[setr(0, Inside)\])]-%q0
You say, "Outside-Inside-Inside"
> say [setr(0, Outside)]-[localize(setr(0, Inside))]-%q0
You say, "Outside-Inside-Outside"
See also: setq(), setr(), r(), ulocal(), uldefault(), s()
& LOCATE()
locate(<looker>, <name>, <parameters>)
This function attempts to find the number called <name> relative to
<looker>. You must control <looker> or have the See_All power.
This is a bit like the NUM() function, but with a wider, controllable
"range".
You can control the preferred type of the match with:
E - Exits
L - Unlocked exits preferred over locked exits
N - No type (this is the default)
P - Players
R - Rooms
T - Things
F - Return #-1 if what's found is of a different type than the
preferred one.
X - Never return #-2. Use the last dbref found if the match is
ambiguous.
If you specify more than one type, the last one will be preferred. Unless
you specify an F option, if an object of a different type is found and
none of the preferred type are, the found object will be returned.
(Read "help locate2" for more.)
& LOCATE2
You can control where to look with:
a - Absolute match (look for #<object>)
c - Exits carried by <looker>
e - Exits in <looker>'s location
h - "here" (the location of <looker>)
i - Inventory of <looker>
l - Location (container) of <looker>
m - "me" (<looker> itself)
n - Neighbors (other objects in same location as <looker>)
p - Player names prefixed by '*'
y - Player names with or without a '*' prefix
z - English-style matching (my 2nd book) of <name>
* - All of the above (try a complete match)
Just string all the parameters together, without separating them by
spaces, i.e. LOCATE(#100, Test, Tn) would check #100's neighbors
for an object named "Test", preferring a thing over other types.
& LOCK()
lock(<object>[/<locktype>][, <new value>])
lock() returns the text string equivalent of the lock on an object that
you control. You can also provide a locktype (e.g. "enter", "use", etc.)
switch after the object, if you want to check something other than the
regular lock. If a new value is specified, it will attempt to change
the lock before reporting it.
This is a side-effect function and may not be enabled on some MUSHes.
See also: @lock, locktypes, lockflags(), llockflags(), lset(), llocks()
& LLOCKS()
& LOCKS()
llocks(<object>)
locks(<object>)
llocks(), aliased locks(), list locks set on <object>, including
user-defined locks (prefixed with USER:)
> @lock me==me
> @lock/use me==me
> @lock/user:itsme me==me
> th llocks(me)
Basic USER:ITSME Use
See also: lock(), lset(), lockflags(), llockflags()
& LOCKFLAGS()
lockflags(<object>[/<locktype>])
lockflags()
lockflags() returns a string consisting of the flags attached to
the specified lock on the object. The string is a single word
made up of all the appropriate flag letters.
Given no arguments, this function returns a string consisting of
all the flag letters the server knows.
See also: llockflags(), lset(), lock(), llocks()
& LLOCKFLAGS()
llockflags(<object>[/<locktype>])
llockflags()
llockflags returns a space-separated list consisting of the names
of flags attached to the specified lock on the object.
Given no arguments, this function returns a space-separated list
of all flag names known to the server.
See also: llockflags(), lset(), lock(), llocks()
& LSET()
lset(<object>/<lock type>,[!]<flag>)
This functions sets or clears flags on locks.
See 'help @lset' for more information on what flags are available.
& LOG()
log(<number>[, <base>])
Returns the logarithm (base 10, or the given base) of <number>.
& LPARENT()
lparent(<object>)
This function returns a list consisting of the object's db# (as per
num()), the db# of its parent, grandparent, greatgrandparent, etc.
The list will not, however, show parents of objects which the player
is not privileged to examine.
& LPLAYERS()
lplayers(<object>)
This function returns the dbrefs of all players, connected or not, in
<object>. DARK wizards aren't listed to mortals or those without the
see_all power. You must be in <object> or control it to use this
function.
See also: lvplayers(), lcon(), lthings()
& LTHINGS()
lthings(<object>)
This function returns the dbrefs of all things, dark or not, in
<object>. You must be in <object> or control it to use this function.
See also: lvthings(), lcon()
& LPOS()
lpos(<string>, <character>)
This function returns a list of the positions where <character> occupies
in <string>, with the first character of the string being 0. Note that
this differs from the pos() function, but is consistent with other string
functions like mid() and delete().
If <character> is a null argument, space is used.
If <character> is not found anywhere in <string>, an empty list is
returned.
Example:
> say lpos(a-bc-def-g, -)
You say, "1 4 8"
See also: pos()
& LSEARCH()
& SEARCH()
& LSEARCHR()
& CHILDREN()
lsearch(<player>[, <class>[, <restriction>[, <low>[, <high>]]]])
lsearchr(<player>[, <class>[, <restriction>[, <low>[, <high>]]]])
children(<object>)
This function is similar to the @search command, except it returns
just a list of dbref numbers. It is computationally expensive, and
costs 100 pennies to perform. The function must have at least three
arguments. Wizards can specify "all" or <player> for the <player>
field; mortals must use "me". If you do not want to restrict
something, use "none" for <class> and/or <restriction>. <low> and
<high> restrict the search to that range of db#'s and are specified as
dbrefs ("#2") with the #.
The possible <class>es and <restriction>s are the same as those accepted
by @search. See 'help @search' for information about them.
children() is exactly the same as lsearch(<me|all>,parent,<object>),
using "all" for See_All/Search_All players and "me" for others.
See 'help lsearch2' for more details.
& LSEARCH2
& SEARCH2
If <class> is one of the eval ones (EVAL, EEXITS, EROOMS, EOBJECTS or
EPLAYERS), note that any brackets, percent signs, or other special
characters should be escaped, as the code in <restriction> will be
evaluated twice - Once as an argument to lsearch(), and then again for
each object looked at in the search.
<class> can be 'NONE' to make lsearch() act like a @search without a class.
lsearchr() is like an lsearch() run through revwords(). Results are returned
from highest dbref to lowest.
search() is an alias for lsearch().
Examples:
lsearch(all, flags, Wc) <-- lists all connected wizards.
lsearch(me, type, room) <-- lists all rooms owned by me.
lsearch(me, type, room, 100, 200) <-- same, but only w/db# 100-200
lsearch(all, eplayer, \[eq(money(##),100)\]) <-- lists all players with 100
coins.
& LSTATS()
& STATS()
lstats(<player>)
stats(<player>)
This function returns the breakdown of objects in the database, in
a format similar to "@stats". If <player> is "all", a breakdown is
done for the entire database. Otherwise, the breakdown is returned
for that particular player. Only wizards can LSTATS() other players.
The list returned is in the format:
<Total objects> <Rooms> <Exits> <Things> <Players> <Garbage>
stats() is an alias for lstats().
& LT()
lt(<num>,<num>)
Takes two numbers, and returns 1 if and only if the first is less
than the second, and 0 otherwise.
& LTE()
lte(<num>,<num>)
Takes two numbers, and returns 1 if and only if the first is less
than or equal to the second, and 0 otherwise.
& LVCON()
lvcon(<object>)
This function returns the dbrefs of all objects that are inside <object>
and visible (non-dark). You must be in <object> or control it to use this
function.
See also: lcon()
& LVEXITS()
lvexits(<room>)
This function returns the dbrefs of all visible (non-dark) exits from
<room>. You must be in the room or control it to use this function.
See also: lexits()
& LVPLAYERS()
lvplayers(<object>)
This function returns the dbrefs of all connected and non-dark players
in an object. You must be in the object or control it to use this
function.
& LVTHINGS()
lvthings(<object>)
This function returns the dbrefs of all non-dark things inside an
object. You must be in the object or control it to use this function.
& LWHO()
lwho()
lwho(<viewer>)
This returns a list of the dbref numbers for all currently-connected
players. When mortals use this function, the dbref numbers of DARK
wizards or royalty do NOT appear on the dbref list.
If lwho() is given an argument, and used by an object that can see
DARK and Hidden players, lwho() returns the output of lwho() from
<viewer>'s point of view.
See also: mwho(), nwho(), xwho()
& MAIL()
mail()
mail(<player name>)
mail([<folder #>:]<mail message #>)
mail(<player>, [<folder #>:]<mail message #>)
Without arguments, mail() returns the number of messages in
all the player's mail folders. With a player name argument,
mail() returns the number of read, unread, and cleared messages
<player> has in all folders. Only Wizards can use this on other players.
When given numeric arguments, mail() returns the text of the
corresponding message in the current folder. The message number
may also be prefaced by the folder number and a colon, to indicate
a message in a different folder.
Example:
> think mail(3:2)
(text of the second message in the player's third folder)
& MAILFROM()
& MAILTIME()
& MAILSTATUS()
& MAILSUBJECT()
mailfrom([<player>,] [<folder #>:]<mail message #>)
mailtime([<player>,] [<folder #>:]<mail message #>)
mailstatus([<player>,] [<folder #>:]<mail message #>)
mailsubject([<player>,] [<folder #>:]<mail message #>)
mailfrom() returns the dbref number of the sender of a mail message.
mailtime() is similar, but returns the time the mail was sent.
mailsubject() is similar, but returns the subject of the message.
mailstatus() returns the mail's status characters (as per
@mail/list)
& MAILSTATS()
& MAILDSTATS()
& MAILFSTATS()
mailstats([<player>])
maildstats([<player>])
mailfstats([<player>])
mail*stats() functions return data like @mail/*stats does. You
either must use this on yourself, or you must be a wizard. The
information will be joined together as a space separated list of
numbers.
Example:
> think mailstats(One)
<# sent> <# received>
> think mailfstats(One)
<# sent> <# sent unread> <# sent cleared> <# sent bytes> <# received>
<# received unread> <# received cleared> <# received bytes>
& MAILSEND()
mailsend(<player>,[<subject>/]<message>)
This function sends a message to a player, just like @mail/send.
It returns nothing if successful, or an error message.
& MALIAS()
malias([<delimiter>])
malias(<malias name>)
malias(<malias name>[,<delimiter>])
With no arguments, malias() returns the list of all malias names
which are visible to the player. With two arguments, returns the list
of dbrefs that are members of the given malias, delimited by
<delimiter>.
With one argument, the behavior is ambiguous. If the argument
matches a malias, returns the list of dbrefs that are memebrs of
the malias, space-delimited. If not, it's treated as a no-argument
case with a delimiter.
& MAP()
map([<object>/]<attribute>,<list>[,<delim>][, <osep>])
Maps a function onto a list.
This function works much like ITER(). Each element of <list> has
the user-defined function of the first argument performed on it;
the element is passed to the function as %0, and its position
in <list> as %1. <delim> is used as the element delimiter;
if it is not specified, a space is used. The resulting output is
delimited by <osep>, if given, or else by the delimiter
Examples:
> ×_two me=[mul(%0,2)]
> say [map(times_two, 5 4 3 2 1)]
You say, "10 8 6 4 2"
> say [map(times_two,1;2;3;4;5,;)]
You say, "2;4;6;8;10"
See also: anonymous attributes
& MATCH()
match(<list>, <pattern>[, <delimiter>])
This function tests if the pattern matches an element of the list.
The pattern can contain the wildcards * and ?. ? matches to any
one character, while * matches to any number of characters
including none. So s?x would match to sex or six, but not to socx,
but s*x would match to all of them. If no match is found, 0 is
returned. If a match is found, it returns the number of the element
of the list that matched.
This attempts to match to a list element, not to an entire string.
To match an entire string (for example, to match "red blue green"
to "*bl*"), use the strmatch() function.
See also: element(), grab()
& MATCHALL()
Function: matchall(<list>,<pattern>[,<delim>[,<osep>]])
This function works identically to the match() function, save that it
returns all matches, not just the first: It returns the index numbers of
all elements in <list> which match <pattern>. If none match, an empty
string is returned. The resulting output is delimited by <osep>, if
given, or else by the delimiter.
Examples:
> say matchall(This is a test of a test,test)
You say "4 7"
> say matchall(This is testing a test,tes*)
You say "3 5"
See also: match(), strmatch(), graball()
& MAX()
max(<num1>, <num2>, ..., ...)
This function returns the largest number in its list of arguments.
It can take any number of arguments.
& MEAN()
mean(<number>,...)
Returns the mean (arithmetic average) of its arguments.
See also: median(), stddev()
& MEDIAN()
median(<number>,...)
Returns the median (the middlemost numerically) of its arguments.
See also: mean(), stddev()
& MEMBER()
member(<list>,<word>[,<delimiter>])
Takes a list and a word, and returns the position of <word>
if <word> is a word in <list>. A word is defined as a string which
has no interior spaces. So ' hello ' would be one word, while
'hello there' would be two. See LISTS
member() is case-sensitive and requires an exact match. For wild
card patterns, use match().
& MERGE()
merge(<string1>, <string2>, <characters>)
This function merges <string1> and <string2>, depending on <characters>.
If a character in <string1> is the same as one in <characters>, it is
replaced by the character in the corresponding position in <string2>. The
two strings must be of the same length.
Example:
> say [merge(AB--EF,abcdef,-)]
You say, "ABcdEF"
Spaces need to be treated specially. An empty argument is considered to
equal a space, for <characters>.
Example:
> say [merge(AB[space(2)]EF,abcdef,)]
You say, "ABcdEF"
See also: TR()
& MID()
mid(<string>, <first>, <length>)
Mid returns a segment of the string, the <length> characters to the
right of the <first> character. Note that the first character in a
string is numbered zero, and not one.
& MIN()
min(<num1>, <num2>, ..., ...)
This function returns the smallest number in its list of arguments.
It can take any number of arguments.
& MIX()
mix([<object>/]<attribute>,<list 1>,<list 2>[,...,<list n>],[<delim>])
This function is similar to MAP(), except that it takes the elements
of two or more lists, one by one, and passes them to the user-defined
function as %0, %1, up to %9, respectively, for elements of <list 1> to
<list 10>. If the lists are of different sizes, the shorter ones are padded
with empty elements. <delim> is used to separate elements; if it is not
specified, it defaults to a space. If using more than 2 lists, the last
argument must be a delimiter.
See HELP MIX2 for examples
& MIX2
Examples of mix():
> &add_nums me=[add(%0, %1)]
> say [mix(add_nums,1 2 3 4 5, 2 4 6 8 10)]
You say, "3 6 9 12 15"
> &lengths me=[strlen(%0)] and [strlen(%1)].
> say [mix(lengths, some random, words)]
You say, "4 and 5. 6 and 0."
> &add_nums me=[add(%0, %1, %2)]
> say [mix(add_nums, 1:1:1, 2:2:2, 3:3:3, :)]
You say, "6:6:6"
See also: anonymous attributes
& MOD()
& MODULO()
& MODULUS()
& REMAINDER()
mod(<number>,<number>)
modulo(<number>,<number>)
modulus(<number>,<number>)
remainder(<number>,<number>)
Remainder returns the remainder of the integer division of the first
number by the second. Modulo returns the modulo of the two numbers.
For positive numbers, these are the same, but they may be different
for negative numbers:
modulo(13,4) ==> 1 and remainder(13,4) ==> 1
modulo(-13,4) ==> 3 but remainder(-13,4) ==> -1
modulo(13,-4) ==> -3 but remainder(13,-4) ==> 1
modulo(-13,-4) ==> -1 and remainder(-13,-4) ==> -1
Remainder result always has the same sign as the first argument.
Modulo result always has the same sign as the second argument.
Mod and modulus are just aliases for modulo.
See also: DIV
& MONEY()
money(<object>)
money(<integer>)
The first form returns the amount of money <object> has.
The second form returns the name for a given amount
of money, appropriately inflected as singular or plural.
> say [money(Javelin)]
You say, "150"
> say [money(1)]
You say, "Penny"
> say [money(2)]
You say, "Pennies"
> &counter me=$count *: @emit %0 [money(%0)]
> count 2
2 Pennies
& MTIME()
mtime(<object>)
If creation times are enabled, this function will return the
date and time that one of the object's attributes was last
added, deleted, or modified. Only things, rooms, and exits have
modification times.
& MUDNAME()
Function: mudname()
Returns the name of the MUD. This is usually (but not necessarily) the name
that appears in the various mud lists, and is the name that the mud is
listed under in reports from any inter-mush bots like mudnet that it's
connected to.
Example:
> say mudname()
You say "TestMUSH"
& MUL()
mul(<number>,<number>,...)
Returns the product of some numbers.
& MUNGE()
munge([<object>/]<attribute>,<list 1>,<list 2>[,<delimiter>[,<osep>]])
This function takes two lists of equal length. It passes the entirety of
<list 1> to the user-defined function as %0, and the delimiter as %1.
Then, this resulting list is matched with elements in <list 2>, and
the rearranged <list 2> is returned. This is useful for doing things
like sorting a list, and then returning the corresponding elements in
the other list. If a resulting element from the user-defined function
doesn't match an element in the original <list 1>, a corresponding
element from <list 2> does not appear in the final result.
See HELP MUNGE2 for examples.
& MUNGE2
For example: Consider attribute PLACES, which contains "Fort Benden Ista",
and another attribute DBREFS contains the dbrefs of the main JUMP_OK
location of these areas, "#20 #9000 #5000". We want to return a list of
dbrefs, corresponding to the names of the places sorted alphabetically. The
places sorted this way would be "Benden Fort Ista", so we want the final
list to be "#9000 #20 #5000". The functions, using munge(), are simple:
> &sort me=[sort(%0)]
> say [munge(sort,v(places),v(dbrefs))]
You say, "#9000 #20 #5000"
See HELP MUNGE3 for another example
& MUNGE3
Another common task that munge() is well suited for is sorting a list
of dbrefs of players by order of connection. This example reuses the
&sort attribute from the previous one, but unlike the other example,
it builds the list to sort on out of the list to return.
> &faction_members me=#3 #12 #234
> say [munge(sort,iter(v(faction_members),conn(##)),v(faction_members))]
You say, "#12 #234 #3"
See also: anonymous attributes
& MWHO()
mwho()
This returns a list of the dbref numbers for all current-connected,
non-hidden players. It's exactly the same as lwho() used by a
mortal, and is suitable for use on privileged global objects who
need an unprivileged who-list.
& NAME()
name(<object>[,<new name>])
name(<player>[,<new name> <password>])
Name returns the name of object <object>. For exits, name returns
the displayed name of the exit.
If function side effects are allowed, this function, given two arguments,
acts just like @name <object>=<new name>. Consequently, if renaming
a player, you must use the player's password or be God.
name() with no arguments currently returns nothing. This should be an
error, but enough old code has been written that expects this behavior
that it will continue to do this for the time being. Don't rely on it.
Related functions: FULLNAME(), ACCNAME(), INAME()
& NAND()
nand(<boolean>, <boolean>,...)
Returns 1 if at least one of its arguments is false, 0 if all are
true. Equivalent to not(and()), but more efficient.
& NEARBY()
nearby(<object 1>, <object 2>)
Returns 1 if object 1 is "nearby" object 2. "Nearby" is defined as:
object 1 is in the same location as object 2, or,
object 1 is being carried by object 2, or,
object 1 is carrying object 2.
You must control at least one of the objects.
& NEQ()
neq(<num1>,<num2>)
Basically the same as [not(eq(<num1>,<num2>))].
See also: eq(), not()
& NEXT()
next(<object>)
If object is an exit in a room, then next() will return the next
non exit in the list of exits for that room. If object is a
thing or a player, then next will return the next object in the
contents list that the object is in. Otherwise, it returns a
'#-1' string. '#-1' is also used to denote that there are no
more exits/things/players in the container.
You can get the complete contents of any container you may examine,
regardless of whether or not objects are dark. You can get the
partial contents (obeying DARK/LIGHT/etc.) of your current location
or the enactor (%#). You CANNOT get the contents of anything else,
regardless of whether or not you have objects in it. These rules
apply to exits, as well.
See also: lcon(), lexits(), con(), exit()
& NMWHO()
nmwho()
This returns a count of all currently connected, non-hidden players.
It's exactly the same as nwho() used by a mortal, and is suitable
for use on privileged global objects who need an unprivileged count
of who's online.
See also: nwho(), mwho(), xmwho()
& NOR()
nor(<boolean>, <boolean>,...)
Returns 1 if all its arguments are false, 0 if one is true.
Equivalent to not(or()), but more efficient.
See also: and(), or(), xor(), not()
& NOT()
not(<boolean value>)
Takes a boolean value, and returns its inverse.
I.E. if the input is equivalent to true(1), it returns a 0, and if
the input is equivalent to false(0), it returns a 1.
The definition of truth and falsehood depends on configuration settings;
see help BOOLEAN VALUES for details.
See also: and(), or(), nor(), xor()
& NUM()
num(<object>)
Returns the dbref number of the object, which must be in the same
room as the object executing num.
& NVCON()
& NCON()
ncon(<object>)
nvcon(<object>)
These functions return a count of the contents in a container.
ncon(<object>) is identical to words(lcon(<object>))
nvcon(<object>) is identical to words(lvcon(<object>))
See also: nexits(), nplayers(), xcon(), lcon(), lvcon()
& NVEXITS()
& NEXITS()
nexits(<room>)
nvexits(<room>)
These functions return a count of the exits in a room.
nexits(<room>) is identical to words(lexits(<room>))
nvexits(<room>) is identical to words(lvexits(<room>))
See also: ncon(), nplayers(), xexits(), lexits(), lvexits()
& NVPLAYERS()
& NPLAYERS()
nplayers(<object>)
nvplayers(<object>)
These functions return a count of the players in a container.
nplayers(<object>) is identical to words(lplayers(<object>))
nvplayers(<object>) is identical to words(lvplayers(<object>))
See also: ncon(), nexits(), xplayers(), lplayers(), lvplayers()
& NVTHINGS()
& NTHINGS()
nthings(<object>)
nvthings(<object>)
These functions return a count of the things in a container.
nthings(<object>) is identical to words(lthings(<object>))
nvthings(<object>) is identical to words(lvthings(<object>))
See also: ncon(), nexits(), xthings(), lthings(), lvthings()
& NWHO()
nwho()
This returns a count of all currently-connected players. When
mortals use this function, DARK wizards or royalty are NOT counted.
See also: lwho(), nmwho(), xwho()
& OBJ()
obj(<object>)
Returns the objective pronoun - him/her/it - for an object.
& OBJEVAL()
objeval(<object>, <expression>)
Allows you to evaluate <expression> from the viewpoint of <object>.
If side-effect functions are enabled, you must control <object>;
if not, you must either control <object> or have the see_all power.
If <object> does not exist or you don't meet one
of the criterion, the function evaluates with your privileges.
This function is useful for securing objects which need to evaluate
attributes on things owned by others.
& OBJID()
objid(<object>)
This function returns the object id, a value which uniquely identifies
it for the life of the MUSH. The object id is the object's dbref,
a colon character, and the object's creation time, in seconds since
the epoch.
The object id can be used nearly anywhere the dbref can, and ensures
that if an object's dbref is recycled, the new object won't be mistaken
for the old object.
The substitution %: returns the object id of the enacting object.
& OBJMEM()
objmem(<object>)
This function returns the amount of memory, in bytes, being used
by the object. It can only be used by players with Search powers.
See also: playermem()
& OEMIT()
& NSOEMIT()
oemit([<room>/]<object> [<object> ...],<message>)
nsoemit([<room>/]<object> [<object> ...],<message>)
Sends <message> to all objects in <room> (default is the location
of <object>(s)) except <object>(s), as per @oemit.
nsoemit() is a wizard-only variation that works like @nsoemit.
& OPEN()
open(<exit name>, <room>)
This function opens an exit called <exit name> and links it to
<room>, which must be a dbref number. It returns the dbref number
of the new exit.
& OR()
& COR()
or(<boolean value 1>,<boolean value 2>[, ... , <boolean value N>])
cor(<boolean value 1>,<boolean value 2>[, ... , <boolean value N>])
Takes boolean values, and returns a 1 if at least one of the inputs
is equivalent to true(1). or() always evaluates all arguments
(including side effects), while cor() stops evaluation after the
first argument that evaluates to true.
See also: BOOLEAN VALUES, and()
& ORFLAGS()
orflags(<object>,<string of flag characters>)
This function returns 1 if <object> has at least one of the flags in
a specified string, and 0 if it does not. The string is specified with
a single letter standing for each flag, like the output of the FLAGS()
function. A '!' preceding a flag letter means "not flag".
Thus, ORFLAGS(me,Wr) would return 1 if I am set WIZARD or ROYALTY.
ORFLAGS(me,D!c) would return 1 if I am DARK or not CONNECTED.
If a letter does not correspond to any flag, <object> doesn't have it,
so it is simply ignored. There can be an arbitrary number of flags. Do
not put spaces between flag letters.
& ORLFLAGS()
orlflags(<object>,<list of flag names>)
This function returns 1 if <object> has at least one of the flags in
a specified list, and 0 if it does not. The list is a space-separated
list of flag names. A '!' preceding a flag name means "not flag".
Thus, ORLFLAGS(me,wizard royalty) would return 1 if I am set
WIZARD or ROYALTY. ORLFLAGS(me,dark !connected) would return 1 if I am
DARK or not CONNECTED.
If a name does not correspond to any flag, <object> doesn't have it,
so it is simply ignored. There can be an arbitrary number of flags.
& OWNER()
owner(<object>[/<attribute>])
Given just an object, it returns the owner of the object.
Given an object/attribute pair, it returns the owner of that attribute.
& PARENT()
parent(<object>[, <new parent>])
This function returns the dbref number of an object's parent. You
must be able to examine the object to do this.
If you specify a second argument, it tries to re-parent the object.
In this case, you must control the object.
& PEMIT()
& NSPEMIT()
pemit(<object list>,<message>)
nspemit(<object list>,<message>)
This function will send each object on the list a message, as per
the @pemit/list command. It returns nothing. It respects page-locks and
HAVEN flags on players.
nspemit() is a wizard-only variation that works like @nspemit/list.
& PI()
pi()
Returns the value of "pi" (3.14159265358979323846264338327, rounded
to the game's float_precision setting).
& PLAYERMEM()
playermem(<player>)
This function returns the amount of memory, in bytes, being used
by everything owned by the player. It can only be used by players
with Search powers.
See also: objmem()
& PMATCH()
pmatch(<string>)
Given the partial name of a connected player, returns that player's dbref
number. This partial name completion works similarly to the partial
name completion of the "page" command - i.e. it first attempts to match
the full names of all players (connected or not), and if that fails,
it tries to match the partial names of connected players visible to
the enactor. If no player is matched, it returns "#-1". If more than
one match is possible for a partial name, it returns "#-2".
Pmatch() will also accept *<player> or #<db#>. If given a non-player
dbref #, pmatch() will return #-1.
& POLL()
poll()
This function returns the current @poll.
See also: @poll, doing(), @doing
& LPORTS()
& PORTS()
lports()
ports(<player name>)
These function returns the list of descriptors ("ports") that are used by
connected players. lports() returns all ports, in the same order as
lwho() returns dbrefs, and ports() returns those a specific player
is connected to, from most recent to least recent. Only players who
are See_All or privileged may use these functions; in other cases,
lports() returns #-1, and ports() an empty list. As an exception,
players can use ports() on themselves.
These port numbers also appear in the wizard WHO, and can be used
with @boot/port, page/port, and the functions that return information
about a connection to make them use a specific connection rather than the
least-idle one when a player has multiple connections open. Players can
get information about their own connections. See_all is needed to use
them to get information about other people's ports.
& POS()
pos(<string1>,<string2>)
This function returns the position that string1 begins in string2,
with the first position being 1.
If string1 is not in string2, then it returns #-1.
& POSS()
poss(<object>)
Returns the possessive pronoun - his/her/its - for an object.
& POWER()
power(<number>,<exponent>)
Returns <number> to the power of <exponent>.
See also: root()
& POWERS()
powers(<object>)
powers(<object>,<power>)
The first form returns a space-separate list of powers possessed by
the object. If the object does not exist, #-1 will be returned.
The second form attempts to set <power> on <object>, as per @power.
& QUOTA()
quota(<player>)
Returns the player's quota, the maximum number of objects they can
create, if quotas are in effect. Returns 99999 for players with
unlimited quotas, so it's safe to use in numerical comparisons.
& R()
& R-FUNCTION
r(<register>)
The r() function is used to access "local registers", and returns
the contents of the specified register. There are 36 such registers,
numbered 0 through 9, and A through Z.
The '%qN' percent-substitution can also be used to access these local
registers, where N is register <register> needed.
See "help SETQ()" for details about registers.
& RAND()
rand(<num>)
rand(<min>, <max>)
Return a random number.
The first form returns an integer between 0 and <num>-1, inclusive.
The second returns an integer between <min> and <max>, inclusive.
If called with an invalid argument, rand() returns an error message
beginning with #-1.
& RANDWORD()
& PICKRAND()
randword(<list>[, <delim>])
Returns a randomly selected element from <list>. <delim> is the list
delimiter: if not specified, whitespace delimits the list.
pickrand() may be an alias for randword() on some servers.
& REGEDIT()
& REGEDITALL()
& REGEDITI()
& REGEDITALLI()
regedit(<string>, <regexp>, <replacement>[, <regexp2>, <replace2> ...])
regediti(<string>, <regexp>, <replacement>[, <regexp2>, <replace2> ...])
regeditall(<string>, <regexp>, <replacement>[, <regexp2>, <replace2> ...])
regeditalli(<string>, <regexp>, <replacement>[, <regexp2>, <replace2> ...])
These functions are a version of edit() that uses regular expressions.
The part of <string> that matches the <regexp> is replaced by the
evaluated <replacement>, with $<number> in <replacement> expanded to the
corresponding matching sub-expression of <regexp>, with $0 the entire
matched section. regedit() only replaces the first match.
regeditall() replaces all matches. The versions ending in i are
case insensitive. The <replacement> argument is evaluated once for
each match, allowing for more complex transformations than is
possible with straight replacement.
Example:
> say regedit(this test is the best string, (.)est, $1rash)
You say "this trash is the best string"
> say regeditall(this test is the best string, (.)est, [capstr($1)]rash)
You say "this Trash is the Brash string"
See also: edit(), regmatch()
& REGMATCH()
& REGMATCHI()
(Help text from TinyMUSH 2.2.4, with permission)
regmatch(<string>,<regexp>[,<register list>])
regmatchi(<string>,<regexp>[,<register list>])
This function matches the regular expression <regexp> against the
entirety of <string>, returning 1 if it matches and 0 if it does not.
regmatchi() does the same thing, but case-insensitively.
If <register list> is specified, there is a side-effect: any
parenthesized substrings within the regular expression will be set
into the specified local registers, in the order they were specified
in the list. <register list> can be a list of one through nine numbers.
If the specified register is -1, the substring is not copied into a
register. Under regmatchi, case of the substring may be modified.
For example, in regmatch( cookies=30 , (.+)=(\[0-9\]*) )
(note use of escaping for MUSH parser), then the 0th substring
matched is 'cookies=30', the 1st substring is 'cookies', and the 2nd
substring is '30'. If <register list> is '0 3 5', then %q0 will become
"cookies=30", %q3 will become "cookies", and %q5 will become "30".
If <register list> was '0 -1 5', then the "cookies" substring would
simply be discarded.
See 'help regexp syntax' for an explanation of regular expressions.
See also: regrab()
& REMIT()
& NSREMIT()
remit(<object>, <message>)
nsremit(<object>, <message>)
Sends a message to the contents of <object>, as per @remit.
nsremit() is a wizard-only variation that works like @nsremit.
& REMOVE()
remove(<list>,<word>[,<delimiter>])
Remove takes a list and a word, and returns the list, with the
first occurrence of the word deleted from it.
A word is defined as a string which contains no interior spaces (or
<delimiter>'s if <delimiter> is used). If the word is not in the
list, then the list is returned. It is case-sensitive.
To remove all occurrences of a word from a string, consider
using edit().
& REPEAT()
repeat(<string>,<number>)
This function simply repeats <string>, <number> times. No spaces are
inserted between each repetition.
Example:
> say [repeat(Test, 5)]
You say, "TestTestTestTestTest"
& REPLACE()
replace(<list>,<position>,<new item>[,<single-character separator>])
This replaces the item at <position> of <list> with <new item>.
If no separator is given, a space is assumed. Null items are
counted when determining position, as in 'items()'.
Examples:
> say [replace(Turn north at the junction,2,south)]
You say, "Turn south at the junction"
> say [replace(blue|red|green|yellow,3,white,|)]
You say, "blue|red|white|yellow"
& REST()
rest(<list>[,<delimiter>])
Returns a list minus its first element.
See also: first(), last()
& REVWORDS()
revwords(<list of words>[,<delimiter>][, <output seperator>])
This function reverses the order of words in a list.
Example:
> say revwords(foo bar baz eep)
You say, "eep baz bar foo"
& RIGHT()
right(<string>, <length>)
Returns the <length> rightmost characters from string.
& RJUST()
rjust(<string>,<length>[,<fill>])
This function pads a string with leading characters ("right-justifies")
so it is <length> long. If <string> is longer than <length>, the <string>
is returned; it is not truncated. If <fill> is not specified, a space
is used.
Examples:
> say -[rjust(foo,6)]-
You say, "- foo-"
> say %r0[rjust(foo,6,-)]%r01234567
You say, "
0---foo7
01234567"
& RLOC()
rloc(<object>, <levels>)
This function may be used to the get the location of an object's location
(and on through the levels of locations), substituting for repeated nested
loc() calls. <levels> indicates the number of loc()-equivalent calls to
make; i.e., loc(loc(<object>)) is equivalent to rloc(<object>,2).
rloc(<object>,0) is equivalent to num(<object>), and rloc(<object>,1) is
equivalent to loc(<object>).
If rloc() encounters a room, the dbref of that room is returned. If rloc()
encounters an exit, the dbref of that exit's destination is returned.
It can also return the locations of controlled or nearby objects, or of
findable players.
Related functions: LOC(), WHERE(), ROOM()
& RNUM()
rnum(<room number>, <object>)
This function returns the dbref number of an object (player, thing, or
exit). The object must be in the specified room. This function is
essentially identical to NUM(), except it matches things in the
specified room rather than the room that you are in. The RNUM()
function is meant to be used in conjunction with Master Room objects.
& ROOM()
room(<object>)
Returns the "absolute" location of an object. This is always a room;
it is the container of all other containers of the object. The
"absolute" location of an object is the place @lemit messages are
sent to and NO_TEL status determined.
You must control the object, be a wizard or royalty, or be near
the object in order for this function to work. The exception to this
are players; if <object> is a player, the ROOM() function may be
used to find the player's absolute location if the player is not
set UNFINDABLE.
& ROOT()
root(<number>, <n>)
Returns the n-th root of <number>. The 2nd root is the square root,
the 3rd the cube root, and so on.
Example:
> think root(27, 3)
3
> think power(3, 3)
27
See also: sqrt(), power()
& ROUND()
round(<number>,<places>)
Rounds <number> to <places> decimal places. <places> must be between
0 and 6.
See also: ceil(), floor(), bound(), trunc()
& S()
& S-FUNCTION
s(string)
This function performs evaluation on a string and returns that
string. It should be considered extremely dangerous to use on a
string that you don't have complete control over (i.e., on user
input). As usual, %n is the name, %s the subjective pronoun, %o the
objective, and %p the possessive. Functions are evaluated.
It is important to note that the pronoun is that of the triggering object.
So, if the ve of an object were: "[s(This is %n)], and I were to
type @trigger <object>/ve, it would return "This is <myname>", but
if vf were @trigger me/ve, then triggering the vf makes the ve
return "This is <object>"
& SCAN()
scan(<object>, <command>)
scan(<command>)
This function works like @scan, and returns a space-separated list of
dbref/attribute pairs containing $commands that would be triggered if
<command> were run by <object>. You must control <object> or be
See_All to use this function.
If no <object> is specified, this function works like @scan run
by the function's executor.
& SCRAMBLE()
scramble(<string>)
This function scrambles a string, returning a random permutation of its
characters. For example, "[scramble(abcdef)]" might return "cfaedb".
Note that this function does not pay any attention to spaces or other
special characters; it will scramble these characters just like normal
characters.
& SECS()
secs()
This function takes no arguments, and returns the number of elapsed
seconds since midnight, January 1, 1970 UTC. UTC is the base time zone,
formerly GMT. This is a good way of synchronizing things that must
run at a certain time.
& SECURE()
secure(<string>)
This function returns <string> with all "dangerous" characters replaced
by spaces. Dangerous characters are ( ) [ ] { } $ % , ^ and ; This
can make output slightly ugly, but it's a good way of preventing other
people from doing nasty things with your objects.
See also: ESCAPE()
& SET()
set(<object>, <flag>)
set(<object>/<attribute>, <attribute flag>)
set(<object>, <attribute>:<value>)
This function is equivalent to @set, and can be used to switch
flags, set attributes, and many other things. The two arguments
to the function are the same as the arguments that would appear
on either side of the '=' in @set. This function returns nothing.
Note that you can't clear an attribute with set(), though
you can make it an empty attribute. Use wipe() to clear attributes.
& SETDIFF()
setdiff(<list1>, <list2>[, <delimiter>][, <sort type>][, <osep>])
This function returns the difference of two sets -- i.e., the
elements in <list1> that aren't in <list2>. The list that is
returned is sorted. Normally, alphabetic sorting is done. You can
change this with the fourth argument, which is a sort type as defined
in help sorting. If used with exactly four arguments where the fourth
is not a sort type, it's treated instead as the output separator.
Example:
> say setdiff(foo baz gleep bar, bar moof gleep)
You say, "baz foo"
& SETINTER()
setinter(<list1>, <list2>[, <delimiter>][, <sort type>][,<osep>])
This function returns the intersection of two sets -- i.e., the
elements that are in both <list1> and <list2>. The list that is
returned is sorted. Normally, alphabetic sorting is done. You can
change this with the fourth argument, which is a sort type as defined
in help sorting. If used with exactly four arguments where the fourth
is not a sort type, it's treated instead as the output separator.
Example:
> say setinter(foo baz gleep bar, bar moof gleep)
You say, "bar gleep"
& SETQ()
& SETR()
setq(<register>,<string>)
setr(<register>,<string>)
The setq() and setr() functions are used to copy strings into local
registers. setq() returns a null string; it is a purely "side effect"
function. setr() returns the value stored.
There are thirty-six local registers, numbered 0 through 9 and A through Z.
They are cleared at the start of each new queue cycle (i.e. whenever
a new command is evaluated). They are most useful for storing
complex function evaluations which are used repeatedly within a
single command.
Registers set via setq() or setr() can be accessed via the r() function,
or via the %qN percent-substitution.
See "help SETQ2" for examples of its use.
& SETQ2
The setq() function is probably best used at the start of the string
being manipulated, such as in the following example:
&TEST object=[strlen(%0)]
&CMD object=$test *:"[setq(0,u(TEST,%0))]Test. %0 has length [r(0)].
test Foo
> Object says, "Test. Foo has length 3."
In this case, it is a waste to use setq(), since we only use the function
result once, but if TEST was a complex function being used multiple times
within the same command, it would be much more efficient to use the local
register, since TEST would then only be evaluated once.
setq() can thus be used to improve the readability of MUSH code, as well
as to cut down the amount of time needed to do complex evaluations.
See "help SETQ3" for scoping rules of setq().
& SETQ3
The registers set by setq() can be used in later commands in the same
thread. That is, the registers are set to null on all $-commands,
^-commands, A-attribute triggers, etc., but are then retained from
that point forward through the execution of all your code. Code
branches like @wait and @switch retain the register values from the
time of the branch, so the code:
say setr(a,foo); @wait 0=say %qa; say setr(a,bar)
produces the following when executed by an object:
Object says "foo"
Object says "bar"
Object says "foo"
& SETUNION()
setunion(<list1>, <list2>[, <delimiter>][, <sort type>][, <osep>])
This function returns the union of two sets -- i.e., all the
elements of both <list1> and <list2>, minus any duplicate
elements. Think of it as CAT() without words duplicated. The list
returned is sorted. Normally, alphabetic sorting is done. You can
change this with the fourth argument, which is a sort type as defined
in help sorting. If used with exactly four arguments where the fourth
is not a sort type, it's treated instead as the output separator.
Example:
> say setunion(foo baz gleep bar, bar moof gleep)
You say, "bar baz foo gleep moof"
> say setunion(1.1 1.0, 1.000)
You say, "1.0 1.000 1.1"
> say setunion(1.1 1.0, 1.000, %b, f)
You say, "1.0 1.1"
& SHA0()
sha0(<string>)
Returns the SHA cryptographic hash of the string. See RFC 3174
for more information.
& SHL()
shl(<number>,<count>)
Performs a leftwards bit-shift on <number>, shifting it <count> times.
This is equivalent to mul(<number>,power(2,<count>), but much faster.
& SHR()
shr(<number>,<count>)
Performs a rightwards bit-shift on <number>, shifting it <count> times.
This is equivalent to div(<number>,power(2,<count>), but much faster.
& SHUFFLE()
shuffle(<list>>[,<delimiter>][,<osep>])
This function shuffles the order of the items of a list, returning a
random permutation of its elements. "[shuffle(foo bar baz gleep)]"
might evaluate to "baz foo gleep bar".
& SIGN()
sign(<number>)
Essentially returns the sign of a number -- 0 if the number is 0,
1 if the number is positive, and -1 if the number is negative.
Thus, SIGN(-4) is -1, SIGN(2) is 1, and SIGN(0) is 0.
& SIN()
sin(<angle>[, <angle type>)
Returns the sine of <angle>, which should be expressed in the
given angle type, or radians by default.
See HELP CTU() for more on the angle type.
& SORT()
sort(<word1> <word2> ...[,<sort type>][,<delimiter>][,<output sep>])
This sorts a list of words. If no second argument is given, it will
try to detect the type of sort it should do. If all the words are
numbers, it will sort them in order of smallest to largest. If all
the words are dbrefs, it will sort them in order of smallest to
largest. Otherwise, it will perform a lexicographic sort.
The second argument is a sort type. See help sorting.
The optional third argument gives the list's delimiter character.
If not present, <delimiter> defaults to a space.
The optional fourth argument gives a string that will delimit
the resulting list; it defaults to <delimiter>.
& SORTBY()
sortby([<obj>/]<attrib>,<list>[,<delimiter>][, <output seperator>])
This sorts an arbitrary list according to the u-function <obj>/<attrib>.
This u-function should compare two arbitrary elements, %0 and %1, and
return zero (equal), a negative integer (element 1 is less than element 2)
or a positive integer (element 1 is greater than element 2).
A simple example, which imitates a normal alphabetic sort:
> &ALPHASORT test=[comp(%0,%1)]
> say [sortby(test/ALPHASORT,foo bar baz)]
You say, "bar baz foo"
A slightly more complicated sort. #1 is "God", #2 is "Amby", "#3" is "Bob":
> &NAMESORT me=[comp(name(%0),name(%1))]
> say [sortby(NAMESORT,#1 #2 #3)]
You say, "#2 #3 #1"
Warning: the function invocation limit applies to this function. If
this limit is exceeded, the function will fail _silently_. List and
function sizes should be kept reasonable.
See also: anonymous attributes
& SORTING
In functions where you can specify a sorting method, you can provide
one of these sort types:
Type Sorts:
a Sorts lexicographically (Maybe case-sensitive).
i Sorts lexicographically (Always case-insensitive).
d Sorts dbrefs.
n Sorts integer numbers.
f Sorts decimal numbers.
name Sorts dbrefs by their names. (Maybe case-sensitive)
namei Sorts dbrefs by their names. (Always case-insensitive)
conn Sorts dbrefs by their connection time.
idle Sorts dbrefs by their idle time.
owner Sorts dbrefs by their owner dbrefs.
loc Sorts dbrefs by their location dbref.
ctime Sorts dbrefs by their creation time.
The special sort key attr:<aname> or attri:<aname> will sort dbrefs
according to their <aname> attributes. For example: Separating by
&factions or &species attrs. attr is probably case-sensitive, and
attri is case-insensitive.
Whether or not the 'a' sort type is case-sensitive or not depends
on the particular mush and its environment.
See also: sort(), sortby(), setunion(), setinter(), setdiff()
& SOUNDEX()
soundex(<word>)
The soundex function returns the soundex pattern for a word.
A soundex pattern represents the sound of the word, and similar
sounding words should have the same soundex pattern. Soundex patterns
consist of an uppercase letter and 3 digits.
> think soundex(foobar)
F160
For details of how the algorithm works, see help soundex2
See also: soundslike()
& SOUNDEX2
Here's how the soundex algorithm works:
1. The first letter of the soundex code is the first letter of
the word (exception: words starting with PH get a soundex
starting with F)
2. Each remaining letter is converted to a number:
vowels, h, w, y ---------> 0
b, p, f, v --------------> 1
c, g, j, k, q, s, x, z --> 2
d, t --------------------> 3
l -----------------------> 4
m, n --------------------> 5
r -----------------------> 6
At this stage, "foobar" is "F00106"
3. Strings of the same number are condensed. "F0106"
4. All 0's are removed, because vowels are much less important
than consonants in distinguishing words. "F16"
5. The string is padded with 0's or truncated to 4 characters. "F160"
That's it. It's not foolproof (enough = "E520", enuf = "E510") but
it works pretty well. :)
& SOUNDLIKE()
& SOUNDSLIKE()
soundslike(<word>,<word>)
soundlike(<word>,<word>)
The soundslike function returns 1 if the two words have the same
soundex code (see help soundex() for information), which means,
in general, if they sound alike. For example:
> think soundslike(robin,robbyn)
1
> think soundslike(robin,roebuck)
0
& SPACE()
space(<number>)
Prints <number> number of spaces. Useful for times when you want to
be able to use lots of spaces to separate things. For example,
"a[space(5)]b would print, "Amberyl says, "a b"".
& SPELLNUM()
spellnum(<number>)
Given a number, return its written-out representation in words.
& SPLICE()
splice(<list1>, <list2>, <word>[, <delimiter>])
This function splices <list1> and <list2> together. <list1> and <list2>
are space-separated lists of words
If a word in <list1> is the same as <word>, it is replaced by the word
in the corresponding position in <list2>. Both lists must have the
same number of words.
Example:
> say [splice(foo bar baz,eek moof gleep,bar)]
You say, "foo moof baz"
& SQL()
sql(<query string>,[<row delimiter>[,<field delimiter>])
Performs an SQL query if the MUSH is configured to connect to an
SQL database server. This function requires a WIZARD flag or
the Sql_Ok power.
By default, SELECT queries will return their data space-separated.
Usually, it's more useful to specify a character to delimit
rows returned (and sometimes another character to delimit the
fields/columns returned, if they may contain spaces).
<query string> is evaluated, so it's useful to either read it from
another attribute with u() or use lit() to protect commas. If
you will be interpolating user-provided values into the query,
be careful to escape them with sqlescape(), like this:
&SEL_GETID obj = SELECT id FROM mytable WHERE name = '[sqlescape(%0)]'
&DOIT obj = $do *: ... [setq(0,sql(u(SEL_GETID,%0),~,|))] ...
See also: sqlescape(), @sql
& SQLESCAPE()
sqlescape(<string>)
This function performs SQL-server-implemented escaping of strings.
It's important to escape arbitrary data before passing it to the
sql() function or @sql command to prevent SQL injection attacks.
Example:
> think sqlescape(You don't say)
You don\'t say
When used in an SQL query, the results of an sqlescape() function
should be enclosed in single quotes.
You must be a WIZARD or have the Sql_Ok power to use this function.
See also: sql(), @sql
& SQRT()
sqrt(<number>)
Returns the square root of <number>. <number> cannot be negative.
See also: root()
& SQUISH()
squish(<string>[, <character>])
This function removes the leading and trailing <character>s from a string,
and condenses all inter-word <character>s to a single <character>. If no
character is given, uses space.
Example:
> say [squish( foo bar baz blech eek )]
You say, "foo bar baz blech eek"
> say [squish(||a|| b|c|d, |)]
You say, a| b|c|d
& STARTTIME()
Function: starttime()
Returns a string containing the time the MUSH first started up (not
including @shutdown/reboots). The time is in the same format that the
TIME() function returns.
Example:
> say starttime()
You say "Sat Dec 7 00:09:13 1991
See also: convtime(), restarttime(), restarts()
& RESTARTTIME()
restarttime()
Returns a string which is the time the MUSH last rebooted. The time
is in the same format as the TIME() function returns.
See also: convtime(), starttime()
& RESTARTS()
restarts()
Returns the number of times the server has been rebooted with
@shutdown/reboot since the last full startup.
& SSL()
ssl(<player|descriptor>)
This function returns 1 if the player is using an SSL connection,
and 0 otherwise. If SSL is disabled, it always returns 0.
Players can check the SSL status of their own connection.
The See_All power is required to check other connections.
See also: terminfo()
& STEP()
step([<obj>/]<attr>, <list>, <step>[, <delim>, <outsep>])
This function is similar to map(), except you can pass up to
10 elements of the list at a time, in %0 to %9. <step> must
be between 1 and 10, with a step of 1 equivalent to map().
If the elements of the list can't be split up evenly, the last
evaluation pads the missing values with empty values.
If no output separator is given, the delimiter (Default is a
space) is used.
Continued in step2
& STEP2
Example:
> &foo me=%0 - %1 - %2%r
> think step(foo, 1 2 3 4 5, 3)
1 - 2 - 3
4 - 5 -
See also: map(), iter(), anonymous attributes
& STDDEV()
stddev(<number>,...)
Returns the sample standard deviation of its arguments.
See also: mean(), median()
& STRCAT()
strcat(<string1>, <string2>)
Concatenates two strings together, with no space between them.
For example, strcat(foo bar,baz blech) will return the string
"foo barbaz blech".
& STRINSERT()
strinsert(<string>, <position>, <insert>)
This function returns <string>, with <insert> added before <position>
in <string>. Note that the first character in a string is numbered 0,
not 1.
Example:
> think strinsert(barbaz, 0, foo)
foobarbaz
> think strinsert(Myname, 2, %b)
My name
& STRIPACCENTS()
stripaccents(<string>)
Returns the string with accented characters converted to non-accented.
As with the accent() function, this assumes the ISO 8859-1 character set.
& STRIPANSI()
stripansi(<string>)
Returns the string with all ansi and HTML codes removed.
& STRLEN()
strlen(<string>)
Returns the length of the string (The number of characters in it).
& STRMATCH()
strmatch(<string>, <pattern>)
This function is matches <pattern> against the entire <string>.
It returns 1 if it matches and 0 if it doesn't. It is not
case-sensitive, and <pattern> may contain wildcards.
strmatch(Foo bar baz,*Baz) will return 1.
strmatch(Foo bar baz,*Foo) will return 0.
strmatch(Foo bar baz,*o*a*) will return 1.
& STRREPLACE()
strreplace(<string>, <start>, <length>, <text>)
Returns string with the <length> characters starting at <start> replaced
by <text>. As with other string functions, the first character is at
position 0.
Example:
> think strreplace(Fix teh typo, 4, 3, the)
Fix the typo
& SUB()
sub(<num>, <num>)
Sub() subtracts the second number from the first.
& SUBJ()
subj(<object>)
Returns the subjective pronoun - he/she/it - for an object.
& RESWITCH()
& RESWITCHI()
& RESWITCHALL()
& RESWITCHALLI()
reswitch(<string>, <re1>, <list1>, [<reN>, <listN>], ... [<default>])
reswitchall(<string>, <re1>, <list1>, [<reN>, <listN>], ... [<default>])
reswitchi(<string>, <re1>, <list1>, [<reN>, <listN>], ... [<default>])
reswitchalli(<string>, <re1>, <list1>, [<reN>, <listN>], ... [<default>])
These functions are just like switch() except they compare <string>
against a series of regular expressions, not wildcard patterns. reswitch()
is case-sensitive, reswitchi() is case-insensitive. The reswitchall versions
evaluate every corresponding <list>, not just the first that matches a regexp.
See also: switch()
& SWITCH()
& SWITCHALL()
& CASE()
& CASEALL()
switch(<string>, <expr1>, <list1>, [<exprN>, <listN>], ...[<default>])
switchall(<string>, <expr1>, <list1>, [<exprN>, <listN>], ...[<default>])
case(<string>, <expr1>, <list1>, [<exprN>, <listN>], ...[<default>])
caseall(<string>, <expr1>, <list1>, [<exprN>, <listN>], ...[<default>])
These functions match <string> against the <expr>essions, returning the
corresponding <list>. If nothing is matched, the <default> is returned.
Only the first matching expression counts (like @switch/first), and
<list>s that are not returned are not evaluated.
Wildcard patterns are allowed in switch() and switchall(). case() and
caseall() do a case-sensitive exact match, like member() or comp().
If the string "#$" appears in the <list> to be evaluated, it will be
replaced with the evaluated value of <string> /before/ evaluation of
<list>. This is not done in case() and caseall(), for TinyMUSH 3
compatibility.
switchall() and caseall() will return all the <lists> with matching
<expr>ssions, without spaces between them, so they match similarly to
@switch, while switch() and case() match more like @switch/first.
See HELP SWITCH WILDCARDS for more, and HELP SWITCH2 for examples
& SWITCH2
Examples of switch() and related functions:
> say switch(test, *a*, foo, *b*, bar, *t*, neat, baz)
You say, "neat"
> say switchall(ack, *a*, foo, *b*, bar, *c*, neat, baz)
You say, "fooneat"
> say switch(moof, *a*, foo, *b*, bar, *t*, neat, baz)
You say, "baz"
> say switch(moof, *a*, foo, *b*, bar, *t*, neat, #$)
You say, "moof"
> say case(moof, *f, foo, moof, bar, baz)
You say, "bar"
& SWITCH WILDCARDS
@switch, @select, switch() and switchall() normally do wildcard
matching between their first argument and the <expr>ession
arguments, with the normal * and ? special characters. However, if
one of the <expr>essions starts with < or >, a less than or greater
than check is done instead of wildcard matching for that pair.
switch(X, >Y, A, B) returns A if X is greater than Y,
and B if X is less than or equal to Y.
switch(X, <Y, A, B) returns A if X is less than Y,
and B if X is greater than or equal to Y.
If X and Y are numbers, the test is like using gt() or lt(). gte()
and lte() can be simulated by using Y'=Y-1 and Y'=Y+1.
If X and Y are non-numeric strings, the result of comp(X,Y) is used
to determine which string is alphabetically before (Less than) the other.
If you need to have a leading < or > that's treated like a normal
character in a wildcard match, use \\< or \\> (The \\ will turn into
\ when the argument is evaluated, and then that single \ will stop
the greater/less than check).
See also: HELP WILDCARDS
& T()
t(<expression>)
Returns a 0 if the expression is false, and 1 otherwise.
The definition of truth and falsehood depends on configuration settings;
see help BOOLEAN VALUES for details.
& TABLE()
table(<list>,<field width>,<line length>,<delimiter>,<output separator>)
This function returns the elements of <list> in a tabular format.
All other parameters are optional.
<field width> specifies how wide each table entry is allowed to be.
It defaults to 10 characters
<line length> is how wide a table row can be. Default is 78 chars.
<delimiter> is the delimiter used in <list>. Default is white space.
<output separator> is a single character to be used between entries
in the table. Default is a single space.
Examples:
> think table(a b areallylongone d)
a b areallylon d
> think table(the quick brown fox,10,25, ,|)
the |quick
brown |fox
& TAN()
tan(<angle>[, <angle type>])
Returns the tangent of <angle>, which should be expressed in the
given angle type, or radians by default.
See HELP CTU() for more on the angle type.
& TEL()
tel(<object>,<destination>[,<silent>[,<inside>]])
This function will teleport <object> to <destination>, exactly as
@tel <object>=<destination>. <silent> is an optional boolean that,
if true, makes the function act like @tel/silent. <inside>
is an optional boolean that, if true, makes the function act like
@tel/inside (some value for <silent> must also be specified).
See also: @tel
& TERMINFO()
terminfo(<player|descriptor>)
Returns a list with at least one element - the type of client used
by the player, or "unknown" if the client being used doesn't support
being asked to identify itself using RFC 1091.
Other elements in the list describe client capabilities, and
currently include:
pueblo present if the client is in Pueblo mode.
telnet present if the client understands the telnet protocol.
ssl present if the client is using an SSL/TLS connection.
Other fields may be added in the future, if, for example, MXP support
is ever added.
Players can use terminfo() on their own connections. Using it on
other players is restricted to see_all objects.
& TEXTFILE()
& dynhelp()
textfile(<type>,<entry>)
textfile() returns the text of entries from cached text files (such as
"help", "news", "events", etc.) All whitespace and newlines are included,
so you may want to edit %r's and squish the result if you plan to use
the text as a list of words rather than a display.
Examples:
> say textfile(help,tel\()
You say, " tel(<object>,<destination>)
This function will teleport <object> to <destination>, exactly as
@tel <object>=<destination>.
See also: @tel
"
& TIME()
& UTCTIME()
time([utc])
utctime()
time(<timezone>)
time(<object>)
time() gives you the current time on the MUSH.
WARNING! This is the time on the machine that the mush is running
on, and not where you are.
utctime() and time(utc) give the same time in UTC (Aka GMT), not the
server's local timezone.
If a timezone (-24 to +24) is given, it adds that many hours to UTC
to return the correct timezone. Timezone may contain decimals (-1.5)
If <object> is given, and is a valid object containing an attribute
TZ, it modifies the resulting time according to said timezone. time()
on a player will always return a time, and if TZ is not a number between
-24 and +24 inclusive, the time returned is UTC.
See also: timefmt(), timestring(), convsecs(), convtime()
& ETIMEFMT()
etimefmt(<format>[, <secs>])
This function is similar to timestring() - it formats an elapsed time
into days, hours, minutes and seconds. However, its formatting is
much more versatile than timestring(), as well as being more complex.
Escape codes in <format> are replaced by the proper values, and other
characters are left unchanged.
A list of all codes is in HELP ETIMEFMT2
Examples:
> say etimefmt(I have been connected for $2H:$2M., conn(%#))
You say, "I have been connected for 01:32."
> think etimefmt($2mm $2ss, 500) - [timestring(500)]
8m 20s - 8m 20s
See also: timestring(), timefmt()
& ETIMEFMT2
etimefmt()'s escape codes are similar to timefmt()'s.
The time is broken up into days, hours, minutes, and seconds, and
each value replaces the matching code.
$s - The number of seconds. $h - The number of hours.
$S - The number of seconds, $H - The number of hours,
left-padded with 0. left-padded with 0.
$m - The number of minutes. $d - The number of days.
$M - The number of minutes, $D - The number of days,
left-padded with 0. left-padded with 0.
$$ - A literal $.
You can also put a number between the $ and letter to specify
a minimum width for the expanded code. The capital letter codes
are the same as the lower case codes if you don't provide a width.
An 'x' before the code (But after any number) will automatically add
a d, h, m, or s suffix to the time, and a 'z' will not display anything
if the field's value is 0. x and z can be combined.
Continued in HELP ETIMEFMT3
& ETIMEFMT3
Some examples:
> think etimefmt($2h:$2M, 3700)
1:01
> think etimefmt(You have $m minutes and $s seconds to go, 78)
You have 1 minutes and 18 seconds to go
> think squish(etimefmt(Connected for $zxd $xzh $zxm $xzs, conn(me)))
Connected for 5h 24m 45s
& TIMEFMT()
timefmt(<format>[, <secs>])
This function takes a format and a time in seconds (Or the current time)
and returns the format with escape sequences in it expanded to the
proper values based on the time, relative to the host the server is
on.
A list of all codes is in HELP TIMEFMT2
Example:
> think timefmt($A\, the $dth day of $B.)
Monday, the 17th day of July.
& TIMEFMT2
All escape codes start with a $. To get a literal $, use $$.
Invalid codes will return #-1 INVALID ESCAPE CODE. Other text will be
passed through unchanged.
$a - Abbreviated weekday name $p - AM/PM ($P may also work)
$A - Full weekday name $S - Seconds after the minute
$b - Abbreviated month name $U - Week of the year from 1rst Sunday
$B - Full month name $w - Day of the week. 0 = Sunday
$c - Date and time $W - Week of the year from 1rst Monday
$d - Day of the month $x - Date
$H - Hour of the 24-hour day $X - Time
$I - Hour of the 12-hour day $y - Two-digit year
$j - Day of the year $Y - Four-digit year
$m - Month of the year $Z - Time zone
$M - Minutes after the hour $$ - $ character.
& TIMESTRING()
timestring(<seconds>[,<pad flag>])
The timestring function takes a number of seconds as input and
returns the amount of time formatted into days, hours, minutes, and
seconds. If <pad flag> is 1, all time periods will be used even
if the number of seconds is less than a day, hour, or minute.
If <pad flag> is 2, all numbers will be 2 digits long.
Example:
> say [timestring(301)]
You say, " 5m 1s"
> say [timestring(301,1)]
You say, "0d 0h 5m 1s"
> say [timestring(301,2)]
You say, "00d 00h 05m 01s"
& TR()
tr(<string>,<find>,<replace>)
This function translates every character in <string> that exists in
<find> to the character at an identical position in <replace>. Ranges of
characters seperated by -'s are accepted. <find> and <replace> must be the
same length after expansion of ranges. If a character exists more than
once in <find>, only the last instance will be counted. The example
below is the common ROT-13 algorithm for lower case strings, demonstrated
with every letter explicitly listed, and with the equivalent but briefer
character ranges. Literal -'s can be in <find> and <replace> if they are the
first or last characters in the arguments.
Examples:
> say tr(hello,abcdefghijklmnopqrstuvwxyz,nopqrstuvwxyzabcdefghijklm)
You say, "uryyb"
> say tr(uryyb, a-z, n-za-m)
You say, "hello"
See also: MERGE()
& TRIM()
trim(<string>[,<character to trim>][,<trim style>])
trimpenn(<string>[,<character to trim>][,<trim style>])
trimtiny(<string>[,<trim style>][,<character to trim>])
This function trims leading and trailing characters from a string.
The character trimmed is normally a space; if a second argument is
provided, however, that character will be used instead.
If no trim style is specified, characters are trimmed from both the
left and right sides of the string. If the 'l' trim style is specified,
characters are only trimmed from the left side. If the 'r' trim style
is specified, characters are only trimmed from the right side. If you
specify a trim style, you must also explicitly specify the character
to trim, since the trim style must be the third argument to the function.
If the tiny_trim_fun config option is "yes", the character and style
arguments are reversed. Use trimpenn() or trimtiny() if you want to
specify a particular argument sequence no matter how the option is set.
Examples:
> say [trim( foo bar baz eek )]
You say, "foo bar baz eek"
> say [trim(***BLAM***,*)]
You say, "BLAM"
> say [trim(-----> WOW---,-,r)]
You say, "-----> WOW"
& TRUNC()
& VAL()
trunc(<string>)
val(<string>)
This function truncates floating point numbers to integers. It can
also be used to return the leading numeric prefix of a string, or
"0" if there isn't one. For example, "val(101Dalmations)" => 101.
See also: ceil(), floor(), bound(), round()
& TYPE()
type(<object>)
This function returns the type of an object - PLAYER, THING, EXIT,
or ROOM. See "help types of objects" for more.
& U()
& UFUN()
u([<object>/]<user function name>, <arg 0>, <arg 1>, ...)
ufun([<object>/]<user function name>, <arg 0>, <arg1>, ...)
This allows you to create your own functions and evaluate them.
<user function name> is the attribute that contains the desired
user-defined function. Supplying <object> is optional; if you
do not, the attribute will be read off the object that is
evaluating the UFUN().
<arg 0>, <arg 1>, ... are the arguments that get passed to the
user function as v(0), v(1), etc. (as in @trigger). You can pass
up to 10 arguments (v(0) through v(9)); extra arguments will be
evaluated but not accessible (since v(10) refers to an attribute,
not another argument).
This function is also known as U() (alias for TinyMUSH compatibility).
See "help UFUN2" for more.
& U2
& UFUN2
Example:
> @va Object=$test *:"[ufun(testfun, v(0))]; @emit [v(0)]
> &testfun object=[strlen(v(0))] [ucstr(v(0))]
> test string
Object says, "6 STRING"
string
A user-defined function may be as complex as you want it to be,
subject to limits on recursion depth, number of function invocations,
or cpu time that may be configured in the MUSH.
If the evaluation order doesn't quite seem right, adding escapes
or breaking up the expression will probably help.
& UCSTR()
ucstr(<string>)
Returns <string> with all letters converted to uppercase.
Example: ucstr(Foo BAR baz) returns "FOO BAR BAZ"
See also: lcstr(), capstr()
& UDEFAULT()
Function: udefault([<obj>/]<attr>,<default case>[,<arg>]...)
This function returns the value of the user-defined function
as defined by <attr> (or <obj>/<attr>), as if retrieved via
the u() function, with <args>, if the attribute exists and is
readable by you.
Otherwise, it evaluates the default case, and returns that. The
default case is only evaluated if the attribute does not exist
or cannot be read.
Examples:
> &TEST me=[center(%0,5,*)]
> say udefault(Test,-- BOOM --,ACK)
You say "*ACK*"
> &TEST me
> say udefault(me/Test,-- BOOM --,ACK)
You say "-- BOOM --"
See also: get(), eval(), ufun(), uldefault(), default(), edefault()
& ULDEFAULT()
uldefault([<obj>/]<attr>,<default case>[,<arg>]...)
Just like UDEFAULT(), but it preserves registers like ULOCAL().
See also: u(), udefault(), ulocal(), setq()
& ULOCAL()
Function: ulocal([<obj>/]<attr>[,<arg>]...)
The ulocal() function is almost identical to u() in function: it
evaluates an attribute, either from the object performing the function,
or another object that you control or has the same owner as you, passing
in arguments and returning the result. When evaluating the fetched
attribute, %# refers to the original enactor and not the 'calling' object;
'me' refers to the object that supplied the attribute.
However, unlike the u() function, the evaluated attribute receives
only a temporary copy of the global registers r(0)-r(9) and
r(A)-r(Z) (%q0-%q9, %qa-%qz). This means that functions "below" the
level of the ulocal() can reset global registers for temporary
calculations, without needing to worry about "clobbering" the original
values (which are restored when ulocal() returns).
This makes ulocal() particularly useful for global or shared code which
calls arbitrary u() functions, where global register values need to be
preserved from accidental user clobbering.
See "help ulocal2" for examples.
& ULOCAL2
Example of ulocal():
> &FRUIT me=apples bananas oranges pears
> &SUB-FUNCTION me=[setq(0,v(FRUIT))][extract(%q0,match(%q0,%0),1)]
> &TOP-FUNCTION me=[setq(0,are delicious!)][ulocal(SUB-FUNCTION,%0)] %q0
> say u(TOP-FUNCTION,b*)
You say "bananas are delicious!"
If SUB-FUNCTION had been called with u() instead of ulocal():
> &TOP-FUNCTION me=[setq(0,are delicious!)][u(SUB-FUNCTION,%0)] %q0
> say u(TOP-FUNCTION,b*)
You say "bananas apples bananas oranges pears"
In this second example, in SUB-FUNCTION, %q0 was set to "apples bananas
oranges pears", so that when the u() "returned" and TOP-FUNCTION evaluated
%q0, this is what was printed. In the first example, ulocal() reset the
value of %q0 to its original "are delicious!"
See also: u(), setq(), r()
& V()
& V-FUNCTION
V(<name of attribute>)
V(<variable name>)
The first form of this function works just like get(me/<attribute name>).
It is faster and more efficient than get(), however, and so it's better
to use v() when you are getting attributes off an object or its parents.
The second form of this function provides a different way of getting the
results of %-substitutions like %#, %N, %0, etc. Simply take the variable
name (whatever follows the % symbol) and put it inside the v() function:
v(N) is equivalent to %N
v(!) is equivalent to %!
v(3) is equivalent to %3
See also: SUBSTITUTIONS, get(), ATTRIBUTES
& VADD()
vadd(<vector>,<vector>[,<delimiter>])
Returns the sum of two vectors. A vector is a list of numbers
separated by spaces or a delimiter.
> think vadd(1 2 3,4 5 6)
5 7 9
> think vadd(0|0|0,1|2|3,|)
1|2|3
& VALID()
valid(<category>,<string>)
The valid() function checks to see if <string> is a valid member of
<category>, and returns 1 if it is, 0 if not, and #-1 if an
invalid category is used.
The categories are:
name Test for a valid object name.
attrname Test for a valid attribute name.
playername Test for a valid player name that can be set with
@name or @alias.
password Test for a valid password.
command Test for a valid command name for @command/add
function Test for a valid function name for @function
> think valid(name,Foobar)
1
> think valid(attrname,Foo bar)
0
& VCROSS()
vcross(<vector>, <vector>[, <delimiter>])
Returns the 3-dimensional vector that is the cross product of its
3-dimensional argument vectors. The cross product is defined as:
x = Ay * Bz - By * Az
y = Az * Bx - Bz * Ax
z = Ax * By - Bx * Ay
> think vcross(4 5 6, 7 8 9)
-3 6 -3
& VDIM()
vdim(<vector>[,<delimiter>])
Returns the dimensionality of a vector.
> think vdim(1 2 3 4)
4
& VDOT()
vdot(<vector>,<vector>[,<delimiter>])
Returns the dot product of two vectors. A dot product is the sum
of the products of the corresponding elements of the two
vectors, e.g. vdot(a b c,d e f) = ad + be + cf.
The vectors must be of the same length.
> think vdot(1 2 3,2 3 4)
20
& VMIN()
vmin(<vector>, <vector>[, <delimiter>])
Returns a new vector made out of the minimums of each
corresponding pair of numbers from the two vectors.
The vectors must be of the same length.
> think vmin(1 2 3, 4 1 2)
1 1 2
& VMAX()
vmax(<vector>, <vector>[, <delimiter>])
Returns a new vector made out of the maximums of each
corresponding pair of numbers from the two vectors.
The vectors must be of the same length.
> think vmax(1 2 3, 4 1 2)
4 2 3
& VERSION()
Function: version()
Returns a string which contains various version information for the MUSH
you're on.
Example:
> say version()
You say "PennMUSH version 1.6.0 patchlevel 0 [1/10/96]"
& VISIBLE()
visible(<object>,<victim>[/<attribute>])
If no attribute name is provided, this function returns 1 if
<object> can examine <victim>, or 0, if it cannot. If an
attribute name is given, the function returns 1 if <object>
can see the attribute <attribute> on <victim>, or 0, if it
cannot.
If <object>, <victim>, or <attribute> is invalid, the function
returns 0.
& VMAG()
vmag(<vector>[,<delimiter>]
Returns the magnitude of a vector, using a Euclidean distance metric.
That is, for vector a b c d, returns sqrt(a^2+b^2+c^2+d^2).
> think vmag(3 4)
5
& VMUL()
vmul(<vector|number>,<vector|number>[,<delimiter>])
Returns the result of either multiplying a vector by a number,
or the element-wise product of two vectors. The element-wise product
of a b c by w x z is aw bx cz
> think vmul(1 2 3,2)
2 4 6
> think vmul(1 2 3,2 3 4)
2 6 12
& VSUB()
vsub(<vector>,<vector>[,<delimiter>])
Returns the difference between two vectors.
> think vsub(3 4 5,3 2 1)
0 2 4
& VUNIT()
vunit(<vector>[,<delimiter>]
Returns the unit vector (a vector of magnitude 1), which points
in the same direction as the given vector.
> think vunit(2 0 0)
1 0 0
> think vmul(vunit(5 6 7),vmag(5 6 7))
5 6 7
& WIDTH()
& HEIGHT()
& SCREENWIDTH
& SCREENHEIGHT
width(<player|descriptor>)
height(<player|descriptor>)
These two functions return the screen width and height for a connected
player. If the player's client is capable of doing so, it will let the
mush know what the correct sizes are on connection and when the client
is resized. The defaults are 78 for width, and 24 for height, the
normal minimal values. These can be changed with the special
SCREENWIDTH and SCREENHEIGHT commands, both of which take a number as
their sole argument, and set the appropriate field.
If used on something that's not a player, the functions return the
default values.
The intent of these functions is allow softcode that does formatting
to be able to produce a display that can make full use of any given
screen size.
& WHERE()
where(<object>)
This function returns the "true" location of an object. This is
the standard location (i.e. where the object is) for things and
players, the source room for exits, and #-1 for rooms.
In other words, the "true" location of an object is where it is
linked into the database. For example, an exit appears in the
room of its "home", not its "location" (the LOC() function on an
exit will return the latter). A room's "real" location is always
Nothing (the LOC() function will return its drop-to).
& WIPE()
wipe(<obj>/<attribute-pattern>)
This function is equivalent to @wipe. It returns nothing.
& WORDPOS()
wordpos(<list>, <number>[, <delimiter>])
Returns the number of the word within <list> where the <number>th
character falls. Characters and words are numbered starting with 1,
and spaces between words are treated as belonging to the word that
follows them. If <number> is not within the string, #-1 is returned.
Example: wordpos(foo bar baz, 5) returns "2"
& WORDS()
words(<list>[,<delimiter>])
words() returns the number of elements in <list>.
& WRAP()
wrap(<string>, <width>[, <first line width>[, <line separator>])
This function takes <string> and splits it into lines containing
no more than <width> characters each. If <first line width> is
given, the first line may have a different width. If <line separator>
is given, it is inserted between each line; by default the
separator is a newline.
Examples:
@desc here=[wrap(Wrapped paragraph,72)]
@desc here=[wrap([space(4)]Indented paragraph,72)]
@desc here=[iter(wrap(Hanging indent,72,76,|),
[switch(#@,>1,space(4))]##,|,%r)]
& XATTR()
& XATTRP()
xattr(<object>[/<attribute pattern>],start,count)
xattrp(<object>[/<attribute pattern>],start,count)
xattr() fetches <count> or fewer attribute names from <object>
starting at position <start>. It is useful when the number of attributes
on an object causes lattr() to exceed the buffer limit.
It is equivalent to extract(lattr(<object>[/<pattern>]),<start>,<count>)
xattrp() will include attributes from parents. Do note that parent
attributes are listed _after_ child attributes, not sorted
alphabetically.
See also: nattr(), lattr()
& XGET()
xget(<object>, <attribute>)
This function is identical to get() in purpose, but a comma instead of
a slash separates object and attribute. There is no real advantage to
using this instead of get(). Please see "help get()" for more details
on the use of this function.
& XOR()
xor(<boolean value>,<boolean value>)
Takes two booleans, and returns a 1 if one, and only one of the two
inputs is equivalent to true(1). See BOOLEAN VALUES.
See also: and(), or(), not(), nor()
& XVCON()
& XCON()
xcon(<object>,<start>,<count>)
xvcon(<object>,<start>,<count>)
xcon() fetches <count> or fewer item dbrefs from <object>'s contents
starting at position <start>. It is useful when the number of objects
in a container causes lcon() to exceed the buffer limit.
It is equivalent to extract(lcon(<object>),<start>,<count>)
xvcon() is identical, except it follows the restrictions of
lvcon()
See also: ncon(), lcon(), lvcon()
& XVEXITS()
& XEXITS()
xexits(<room>,<start>,<count>)
xvexits(<room>,<start>,<count>)
xexits() fetches <count> or fewer exit dbrefs from <room>
starting at position <start>. It is useful when the number
of exits in a container causes lexits() to exceed the buffer
limit.
It is equivalent to extract(lexits(<room>),<start>,<count>)
xvexits() is identical, except it follows the restrictions of
lvexits()
See also: nexits(), lexits(), lvexits()
& XVPLAYERS()
& XPLAYERS()
xplayers(<object>,<start>,<count>)
xvplayers(<object>,<start>,<count>)
xplayers() fetches <count> or fewer player dbrefs from <object>
starting at position <start>. It is useful when the number of
players in a container causes lplayers() to exceed the buffer limit.
It is equivalent to extract(lplayers(<object>),<start>,<count>)
xvplayers() is identical, except it follows the restrictions of
lvplayers()
See also: nplayers(), lplayers(), lvplayers()
& XVTHINGS()
& XTHINGS()
xthings(<object>,<start>,<count>)
xvthings(<object>,<start>,<count>)
xthings() fetches <count> or fewer non-player dbrefs from <object>'s
contents starting at position <start>. It is useful when the number of
players in a container causes lthings() to exceed the buffer limit.
It is equivalent to extract(lthings(<object>),<start>,<count>)
xvthings() is identical, except it follows the restrictions of
lvthings()
See also: nthings(), lthings(), lvthings()
& XWHO()
& XMWHO()
xwho(start,count)
xmwho(start,count)
xwho() fetches <count> or fewer player dbrefs from the list of connected
players. It is useful when the number of players connected causes lwho()
or pemits in +who $-commands to exceed buffer limits.
It is equivalent to extract(lwho(),<start>,<count>).
xmwho() is identical, except it is limited to non-DARK and non-HIDE
players.
See also: lwho(), mwho(), nwho()
& ZMWHO()
zmwho(<object>)
This returns a list of the dbref numbers for all current-connected,
non-hidden players within a location belonging to the specified zone.
It's exactly the same as zwho() used by a mortal, and is suitable for
use on privileged global objects who need an unprivileged zwho-list.
See also: zwho()
& ZWHO()
zwho(<object>[,<viewer>])
This returns a list of the dbref numbers for all currently-connected
players within a location belonging to the specified zone. When mortals
use this function, the dbref numbers of DARK wizards or hidden royalty
do NOT appear on the dbref list.
If <viewer> is given by a privileged user, zwho() returns a dbref list
using <viewer>'s privileges.
See also: zmwho()
& ZEMIT()
& NSZEMIT()
zemit(<zone>, <message>)
nszemit(<zone>, <message>)
Sends a message to everything zoned to <zone>, as per @zemit.
Costs apply.
nszemit() is a wizard-only variation that works like @nszemit.
& ZFUN()
zfun(<user function name>, <arg 0>, <arg1>, ... <arg8>)
This is essentially identical to UFUN(), but the attribute corresponding
to the user function name is read from the ZMO of the object instead
of from the object itself. In order to read the attribute from the ZMO,
one of the following criteria must be met:
1. The object is set WIZARD or ROYALTY.
2. The object controls the ZMO.
3. The object's owner owns the attribute on the ZMO.
4. The ZMO is set VISUAL.
5. The attribute being checked is set VISUAL.
See the help for UFUN() for more details on user-defined functions.
& ZONE()
zone(<object>[, <new zone>])
Returns the object's 'zone'. This is the dbref of the master object
which defines the zone. If the second argument is specified, the
function tries to change the zone on the object before reporting it.
See also: ZONES