The Gen-Desc (@6800) Program

On FurryMUCK, this file may be viewed by typing:  @view $desc
-------------------------------------------------------------

Quick Usage Summary of $desc (gen-desc v2.0)
August 2, 1992 by Conrad Wong

How to use:

    $desc is a program that you can use to make more complex messages on
descriptions, success, fail, and drop messages.  To do so, do this:

    @desc object = @$desc (description here)
  (or @succ, @fail, @drop)

    The description is a normal text message, but may include special
'tokens' which are translated by the $desc program to normal text.  For
example, you might write this:

    @desc me = @$desc A cute little fox with %sub[color] eyes.
    @set me = color:green

    Then when someone looked at you, they would see:

    A cute little fox with green eyes.

    All tokens are of the form %token-name[parameters] and you may nest
tokens, so that you may have descriptions which look like this:

    @desc me = @$desc %sub[%sub[morph]  %sub[clothes]

    Which would take the property name that you had stored in the property
'morph' and substitute the contents of that property.  It would also take
whatever you had in 'clothes' and add that into the description.

    You should also bear in mind that lists, when mentioned below, are
created by doing this:

    lsedit object = listname
    (first line of the list)
    (second line of the list)
        ....
    (last line of the list)
    .end

    The lsedit program is very useful for editing lists.

Tokens:

%sub[<match,>property]
Example: %sub[color]
         %sub[me,species]
         %sub[here,night]
         %sub[#321,small]

    %sub[] is used to take the contents of a property.  It normally takes
the property from the object that is looked at (or which has the @succ or
@fail message) but can be set to use properties from other objects as shown
above.

%rand[<match,>listname]
Example: %rand[buttons]
         %rand[here,songs]

    %rand[] takes one of the lines in a list at random.  As with %sub[], it
normally takes this from the object that is looked at, but can take
properties from other objects.  %rand[] differs in that it expects the name
given to be the name of a list created with lsedit, not a property name.

%time[<match,>listname]
  Table: one item in list -- full day
         two items in list -- midnight to noon, noon to midnight
         three items -- midnight to 8 AM, 8 AM to 4 PM, 4 PM to midnight
         four items -- midnight to 6 AM, 6 AM to noon, noon to 6 PM,
                       6 PM to midnight
         six items -- midnight to 4 AM, 4 AM to 8 AM, 8 AM to noon,
                      noon to 4 PM, 4 PM to 8 PM, 8 PM to midnight
%date[<match,>listname]
  Table: one item in list -- full year
         two items in list -- January to July, August to December
         three items in list -- Jan. to Apr., May to Aug., Sept. to Dec.
         four items in list -- winter, spring, summer, fall
         twelve items in list -- monthly

    %time[] selects one of the lines in a list, based on the time of the
day.  That is, the first line corresponds to just after midnight, the last
line is before midnight, and all the lines in between are mapped over the
day.  %date[] is similar, but it does this over the year so that you can
have descriptions which vary with the season.

%concat[<match,>listname]

    Rather than taking one item, %concat[] takes each of the items in the
list and strings them together into your description.  However no spaces are
inserted between elements so you must include that, or commas, if you want
something to be put in between list elements.

%select[<match,>listname,value]
Example: %select[here,weather,%sub[me,climate]]

    This selects one item in a list, given the value.  This can be useful in
such cases as where you have a number on some object and want to give a
description keyed to it.  Also, if there is no entry in the list that
corresponds, it will take the closest entry less than or equal to that
number given.  (for instance, you could set only some entries in a list)
    %select[] was written to allow people to write descriptions that would
vary with the size of the people looking.  This is generally defined as an
implementation-specific macro such as %+size[listname]

%if[condition,true<,false>]
Example: %if[%sub[me,fly],You fly up into the air,You can't fly!]
         %if[%sub[light],In the flickering glow you see a trapdoor.]

    If the condition given (i.e. a substituted property) is not a null
string (blank), or FALSE, then it will return the "true" message.
Otherwise, it will return either a blank or a "false" message if one is
provided.
    Note that you may combine substitution of properties with %yes[] and
%no[] which are described below.

%yes[parameter]
%no[parameter]
Example: %yes[%sub[me,fly]]

    If the parameter given is either 'Yes' or 'No' for %yes[] and %no[]
respectively, then it will return YES.  Otherwise, it will return a blank
string.  These are non-case-sensitive so you may use 'yes', 'Yes', or 'YES',
or even 'y'.
    These may be useful with %if[] where you may require that a property be
set specifically to 'yes' or 'no'.

%@progname[<arguments>]
%#prognum[<arguments>]
Example: %@$foo[bar]
         %#321[baz]

    These allow you to call programs, which must take one string parameter
(whatever is given as <arguments>) and will return one string.  This will
then be inserted into your description like any other token would.

%+<macroname>[<arguments>]
Example: %+size[listname]

    This looks for a macro on the object, the current room, or environments
thereof up to #0.  A macro is set as a property named _macros/macroname so
for instance, you might do this:

    @set #0 = _macros/size:%select[%0,%sub[me,size]]

    In a macro definition (which is simply inserted like another token) %0,
%1, %2, and so on may be used for arguments, which are separated with
commas.  So %0 here refers to the first argument given, and all other
arguments would be ignored.

%prog#num[arg1,arg2,arg3,...]
%prog$name[arg1,arg2,arg3,...]
Example: %prog#321[foo,bar]
         %prog$baz[gum]

    These are like %$prog[] and %#prog[] but they split the arguments so you
can call programs that need several different arguments.

%char[num]
Example: \\[
         \\,
         %%token[parameter]

    Escaped characters such as \c (i.e. any character prefaced with \) and
%% (which is translated to %) will be translated into %char[num] which
should not be used directly.  This allows you to substitute special
characters which would otherwise be interpreted by $desc.

%otell[<room,>message]
Example: %otell[stares out the window at the passing fishes.]

    This sends a message to everyone else which can be useful if you want to
simulate a randomly changing osucc or ofail.  You would leave the @osucc
blank and instead, use $desc to create the @osucc message.  The message will
be preceded by the name of the person looking.  You may use this to display
a message in some other room as long as the owner of the object also owns
that room.
    Note: you cannot use %otell[] on a message that is on a player, so you
cannot make %otell[] to simulate @odescs on players.  Please do not abuse
%otell[].

%prand[listname<,mins>]
Example: %prand[fishtype]

    This chooses one of the elements at random, based on both the trigger's
dbref (object number) and the current time, within a period.  So you may
have it cycle through all the objects in the number of minutes you want, and
it will be like a random message that will not change if you look at it
immediately.
    %prand[] defaults to a cycle time of 1 minute through each element in
the list.

%list[listname]
Example: %list[desc]

    This prints out the first part of the description before the %list[],
then prints each element of the list on its own line, then resumes printing
the rest of the description.  This can be useful when you want to print
pictures or lists of items.
    Note that %list[] cannot be used as an argument so something like
%sub[%list[]] will simply look for a property named "%list[]"

%call[prognum<,arguments>]
Example: %call[#321,foobarbaz]

    This prints out the first part of the description before the %call[],
then calls the program, which may do whatever it wishes including printing
out messages and taking input from the user.  (programs that need to take
input cannot be called from descriptions) It then resumes with the rest of
the description.
    Like %list[], you may not use %call[] as an argument to another token.

%nl[]

    This simply prints whatever comes before this and starts the rest of the
description on a new line.
    Like %list[], you may not use %nl[] as an argument to another token.

Proplocs and Property Searches:

    Normally a property is looked for on the trigger object, i.e. where the
@description, @succ, or @fail is set.  With many commands you can specify
another object such as the looker or the current room.

    The program can normally only read properties on the looker, or anything
that the owner of the trigger object owns.

    The program will automatically search environments for properties where
appropiate.  So you may set a list on a parent room and each of the rooms
inside will be able to use that list.

    You may set a _proploc:(object number without the #) property on objects
and the $desc program will look on the 'property location' given for the
property asked for _after_ it checks the environment.  You may even create
chains of _proploc properties so that several proplocs can inherit from
one.

    However you can only use a proploc owned by someone else if it is set
_proploc_ok?:yes