case   ( -- )

cmd-look   ( s -- )

contents-filter   ( a d -- d' ... d'' i )

Takes the address of a `filter' function and a dbref, and returns the objects from d's contents for which the filter function returns true (1) as a range on the stack. The first item found (the `top' of a Contents or Carrying list) will be at the start of the range. Example:

    : PlayerCheck   ( d -- i )  
        player? if 1 else 0 then
    ;
    : GetPlayers   ( -- d' ... d'' i )
        `PlayerCheck me @ location contents-filter
    ;

.controls   ( d1 d2 -- i )

db-desc   ( d -- )

dbstr-desc   ( d s -- )

default   ( x -- )

EDITcenter   ( range ... offset i1 i2 i3 -- range' )

EDITcopy   ( {rng} ... offset dest start end -- {rng'} ... )

EDITdisplay   ( range -- )

EDITformat   ( range ... c i1 i2 -- range' )

EDITfmt_rng   ( range ... offset i position1 position2 -- range' )

EDITindent   ( range ... offset i position1 position2 -- range' )

EDITjoin   ( range -- s )

EDITjoin_rng   ( range ... offset position1 position2 -- range' )

EDITleft   ( range ... offset position1 position2 -- range' )

EDITlist   ( range ... offset i1 i2 i3 -- range )

EDITOR   ( range -- range' s )

EDITORheader   ( -- )

Prints the standard header informing the user that he is entering the list editor and giving succinct help. Called automatically by EDITOR.

EDITORloop   ( range s1 i1 -- range' s1 i2 s2 i3 i4 s3 )

EDITORparse   ( range s1 i1 s2 -- range' s1 i1 i2 )

Parses range with the editor command s2, returning the modified range, the original paramaters s1 and i1, and the last line handled as i2.

  "mink" "otter" "linsang" 3   "quit" 1 ".indent 1 3 = 5" EDITORparse

This would enter and exit the editor, indenting each string in the range by 5 spaces, with the last line handled on top of the stack as i2. The standard editor output would be shown to the user:

  < Indented 3 lines starting at line 1, 5 columns. >

EDITreplace   ( range ... offset s1 s2 position1 position2 -- range' )

EDITright   ( range ... offset i position1 position2 -- range' )

EDITsearch   ( range ... offset s position -- range ... i2 )

EDITshuffle   ( range -- range' )

EDITsort   ( range i1 i2 -- range' )

EDITsplit   ( s c i1 i2 -- range )

end   ( -- )

endcase   ( -- )

envprop   ( d s -- s' )

envsearch   ( d s -- d' )

get-contents   ( d -- d' ... d'' i )

index-add   ( d s1 s2 s3 -- i )

index-add-sort   ( d s1 s2 s3 -- i )

index-delete   ( d s1 s2 -- )

index-first   ( d s1 -- s2 )

index-envmatch   ( d s1 s2 -- d2 s3 i )

index-match   ( d s1 s2 -- s2' i )

index-matchrange   ( d s1 s2 -- string_range )

index-next   ( d s1 s2 -- s3 )

index-prev   ( d s1 s2 -- s3 )

index-set   ( d s1 s2 s3 -- i )

index-value   ( d s1 s2 -- s3 )

index-write   ( d s1 s2 s3 -- i )

Indexes

"In theory, there's no difference between theory and practice. But in practice, there is." Keep this firmly in mind when working with Lib-Index functions. The following is a brief discussion of how Lib-Index functions are supposed to work. However, several do not behave as advertised. Such cases are noted in the entries for specific Lib-Index functions.

An index is a set of name/value pairs. The index as a whole is stored as a set of associated properties, in a single propdir, consisting of a list of all elements (stored as a single string) and a property for each `name', which holds a `value' associated with the name.

Most routines are also available in `std-' form (the routine name is prefaced with std-, such as .index-add to .std-index-add). Routines which store information (add members to the index) have the following stack effect:

  ( d s1 s2 s3 -- d s1 s2 s3 i )

where d is the object the index is stored on, s1 is the name of the index, s2 is the `name' value, and s3 is the `value' value. All four items are left on the stack unchanged, and an integer error code is returned: 1 for `no error: item successfully added', and 0 for `error: s2 is already a member of the index; index unchanged'.

Routines that retrieve information (perform matches) have the following stack effect:

  ( d s1 s2 s3 -- d s1 s2' s4 i )

where d is the object the index is stored on, s1 is the name of the index, s2 is the name to be matched, and s3 is a string holding 1 - 3 characters specifying matching criteria:

    x: exact match only, ignores the index itself
    e: exit-style match: exact match of ;-separated value, and select the
       first match found if there are more than one
    w: normal operation: match the beginning of a space separated word, 
       and fail if more than one matched. So, `mat' matches `mattress' 
       and `lit match', but not `rematch'.

Arguments d and s1 are left on the stack unchanged. The name to be matched is, if found, returned as s2'. If the match was unsuccessful, s2' will be a null string. If s2 were a partial match, s2' would be returned as the full name. The match criteria paramters, s3, are returned as null string s4. Finally, an error code is returned (1 is no error, match successful; 0 is error, match unsuccessful).

instring   ( s1 s2 -- i )

list-contents   ( s d -- )

LMGR-ClearElem   ( i s d -- )

LMGR-ClearRange   ( i1 i2 s d -- )

LMGR-DeleteList   ( s d -- )

LMGR-DeleteRange   ( i1 i2 s d -- )

LMGR-FullRange   ( s d -- i 1 s d )

LMGR-GetBRange   ( i1 i2 s d -- range )

LMGR-GetCount   ( s d -- i )

LMGR-GetElem   ( i s d -- )

LMGR-Getlist   ( s1 d -- s s' ... s'' i )

LMGR-GetRange   ( i1 i2 s d -- range )

LMGR-InsertRange   ( sx sx' ... sx'' i1 i2 s d -- )

LMGR-MoveRange   ( i1 i2 i3 s d -- )

LMGR-PutBRange   ( sx sx' ... sx'' i1 i2 s d -- )

LMGR-PutElem   ( s1 i s2 d -- )

LMGR-PutRange   ( sx sx' ... sx'' i1 i2 s d -- )

LMGR-SetCount   ( i s d -- )

locate-prop   ( d s -- d' )

long-display   ( d' ... d'' i -- )

Prints the string form of a range of dbrefs to the user's screen, using unparse to determine the strings' format. The start of the range is printed first. Example:

    me @ location get-contents long-display

.match_controlled   ( s -- d )

MBOX-append   ( range s1 s2 d -- i )

MBOX-badref?   ( i s d -- i' )

MBOX-count   ( s d -- i )

MBOX-create   ( s d -- )

MBOX-delmesg   ( refnum base dbref -- )

MBOX-destroy   ( s d -- )

MBOX-insmesg   ( range s1 i1 s2 d -- i2 )

MBOX-message   ( refnum base dbref -- {strrange} )

MBOX-msginfo   ( refnum base dbref -- infostr )

MBOX-ref2num   ( i s d -- i' )

MBOX-ref2prop   ( i s d -- s' d )

MBOX-num2ref   ( i s d -- i' )

MBOX-setinfo   ( refnum base dbref -- )

Messages

A message is a set of associated list properties consisting of a `base' (the list name), one or more `items' (lines in the list), `item strings' (the strings stored in the list, usually holding players' dbrefs or names), and an `information' string (the content of the message). Some Lib-Mesg functions handle `string ranges': sets of strings adjacent on the stack, followed by their count. Multiple, related messages are stored in a propdir that constitutes a `message box'. Example:

  str /msgs/1#/1:2
  str /msgs/1#/2:3
  str /msgs/1#/3:13
  str /msgs/1#/i:This is the content of a message for players
                 with dbrefs #2, #3, and #13.

MBOX-setmesg   ( {strrange} infostr refnum base dbref -- )

MSG-append   ( s1 s2 d -- )

MSG-count   ( s d -- i )

MSG-create   ( range s1 s2 d -- )

Creates a new message with the items in a stringe range and the information string s1, stored as list properties with base s2 on object d.

Example: The following code reads list _staff from the trigger action onto the stack as a range, and creates a message with the contents of lvar ourString for each staff member.

    "_staff" trig LMGR-Getlist        (*read list onto stack as range*)
    ourString @                       (*put message on stack *)
    "st-msgs/" dup trig LMGR-Getcount (*get next available line number*)
    1 + intostr strcat                (*use count to create message base*)
    trig MSG-create                   (*create message, stored on trig*)
    
                                      (*note: this same effect could be
                                        achieved more efficiently with
                                        MSG-append or MBOX-append*)

Assume that a staff memeber uses the stnews command (#555) with the message "Please check `+read 17'"; that list _staff contains 5 lines, each holding a staff member's dbref in string form (2, 3, 13, 99, and 244); and that there are currently two other staff messages. In this case, the code would put the following values on the stack:

    "2", "3", "13", "99", "244", 5, "Please check `+read 17'",
    "st-msgs/3", #555

Then, MSG-create would be called, creating propdir st-msgs/3#/, which other functions could use to relay the message to staff members online, at log-in, or when they check staff news. Ex #555 = st-news/3#/ would show the following values:

    str /st-msgs/3#/1:2
    str /st-msgs/3#/2:3
    str /st-msgs/3#/3:13
    str /st-msgs/3#/4:99
    str /st-msgs/3#/5:244
    str /st-msgs/3#/i:Please check `news staff'

MSG-delitem   ( i s d -- )

MSG-destroy   ( s d -- )

MSG-info   ( s d -- s2 )

MSG-insitem   ( s1 i s2 d -- )

MSG-item   ( i s d -- s2 )

MSG-message   ( s d -- range )

MSG-setinfo   ( s1 s2 d -- )

MSG-setitem   ( s1 i s2 d -- )

.multi_rmatch   ( d s -- d' ... d'' i )

.noisy_match   ( s -- d )

.noisy_pmatch   ( s -- d )

Ranges

A number of library functions handle `ranges': sets of related items adjacent to each other on the stack. The documentation for these functions uses the following terms:

range:

A set of related items on the stack, and their count. Example: "mink" "otter" "linsang" 3

count:

The number of items in a range. The count of the range in the above example is 3.

offset:

The number of stack items between the range and the parameters such as `offset', `position', & `number'. That is, how `deep' in the stack the specified range lies. Example: "mink" "otter" "linsang" 3 "wolf" The range of three items has an offset of 1.

position:

The position of the first item in a subrange within a range. The first item in a range is at position 1. Example: "wolf" "mink" "otter" "linsang" 3 Within this range, "mink" is at position 1, "linsang" is at position 3, and "wolf" is at position 0.

number:

The number of items within a to handle (e.g., to copy or delete).

start:

The first item in a range, farthest from the top of the stack.

end:

The last item in a range, closest to the top of the stack.

REF-add   ( d1 s d2 -- )

REF-allrefs   ( d s -- d' ... d'' i )

REF-delete   ( d1 s d2 -- )

REF-editlist   ( i d s -- )

Puts the user in an interactive editor that allows dbrefs to be added and removed from reflist s on object d. If i is true, only player dbrefs may be added. If i is false, objects of any type may be entered. In either case, the editor rejects invalid dbrefs. The reflist must exists, and all dbrefs contained in it must be valid. REF-editlist displays the following header when the user enters the editor:

   To add an object, enter its name or dbref.  To remove an object, 
   enter its name or dbref with a ! in front of it.  ie: `!button'.  
   To display the list, enter `*' on a line by itself.  To clear the 
   list, enter'#clear'.  To finish editing and exit, enter `.' on a 
   line by itself.Enter `#help' to see these instructions again.

REF-filter   ( a d s -- d' ... d'' i )

Tests each dbref in reflist s on object d in the filter function at address a, returning the those for which the function returns true as a range of dbrefs. The filter function (supplied by your code) should return 1 for true or 0 for false.

Example: the following code tests the dbrefs in reflist _members, stored on the trigger action, filtering out garbage dbrefs and returning the others as a range.

   : CheckRefs
       ok? if 1 else 0 then
   ;

   : GetMembers
       `CheckRefs
       trig "_members"
       REF-Filter
   ;

REF-inlist?   ( d1 s d2 -- i )

REF-list   ( d s -- s' )

REF-next   ( d1 s d2 -- )

Reflists

rinstring   ( s1 s2 -- i )

safecall   ( x d -- )

setpropstr   ( d s1 s2 -- )

short-display   ( d' ... d'' i -- )

short-list   ( d' ... d'' i -- s )

Returns a range of dbrefs as a space- and comma-separated string, punctuated and formatted intellegently. For example, the contents of a room might be returned as

    "Kenya, Passiflora, PowerMac 7100, and Sign"

sr-catrng   ( range1 range2 -- range )

sr-copyrng   ( range ... offset number position -- range ... range2 )

Copies a subrange of number items out of a range in the stack, beginning with the item at position. For example,

   "a" "b" "c" "d" 4 0 3 2 sr-copyrng

would make take the 4-item stack "a" "b" "c" "d", and copy from it, making a new, 3-item range, beginning with the second item in the 4-item range.

   "a" "b" "c" "d" 4 "b" "c" "d" 3

sr-deleterng   ( range ... offset number position -- range' )

Deletes a subrange of number items from a range on the stack, beginning with the item at position. For example,

   "a" "b" "c" 3 "d" 1 2 1 sr-deleterng

would delete 2 items, beginning with the first item in the range, from the 3-item range. The range has an offset of 1: that is, there is 1 item ("d") between the range and the parameters for sr-deleterng. This would leave

   "c" 1

sr-extractrng   ( range ... offset number position -- range' ... subrange )

Extracts a subrange of number items from a range in the stack, beginning with the item at position. The subrange is removed from the original range, and placed on top of the stack as a new range. For example,

   "a" "b" "c" "d" 4 0 2 2 sr-extractrng

would remove 2 items from the 4-item range, beginning with the second item, leaving

   "a" "d" 2 "b" "c" 2

sr-filterrng   ( range function_address -- range' filtered_range )

Passes each item in a range to the function at function_address. If this function returns a non-zero value, sr-filterrng removes that item from range and puts it in filtered_range. The items in range may be of any type. To determine the address of a function, preceed the function name with an ` apostrophe. For example, the following code extracts the items of type string from all items on the stack.

   : StringTest
   string? if 1 else 0 then
   ;

   : PullStrings
   depth `StringTest sr-filterrng
   ;

Calling PullStrings with

   #123 "a" "b" 666 "c"

should leave

   #123 666 2 "a" "b" "c" 3

on the stack. Unfortunately, this potentially useful function does not work as advertised. The code above will actually leave

   #123 "a" 666 3 "c" "b"

sr-insertrng   ( range1 ... range2 offset position -- range )

sr-poprng   ( range1 -- )

sr-swaprng   ( range1 range2 -- i range2 range1 )

Swaps two ranges on the stack, inserting a 0-length range before the two ranges. There must be x items on the stack below range1, where x is equal to the larger of range1's count or range2's count. That is,

   "" "a" "b" 2 "c" "d" "e" 3 sr-swaprng

would crash due to stack underflow, but

   "" "null" "null" "null" "a" "b" 2 "c" "d" "e" 3 sr-swaprng

would put

   "" "null" "null" "null" 0 "c" "d" "e" 3 "a "b" 2

std-index-add   ( d s1 s2 s3 -- d s1 s2 s3 i )

std-index-add-sort   ( d s1 s2 s3 -- d s1 s2 s3 i )

std-index-delete   ( d s1 s2 -- d s1 s2 )

std-index-envmatch   ( d s1 s2 s3 -- d s1 s2' s4 i )

std-index-first   ( d s1 s2 s3 -- d s1 s2' s4 )

std-index-last   ( d s1 s2 s3 -- d s1 s2' s4 )

std-index-match   ( d s1 s2 s3 -- d s1 s2' s4 i )

std-index-next   ( d s1 s2 s3 -- d s1 s2' s3 )

std-index-prev   ( d s1 s2 s3 -- d s1 s2' s3 )

std-index-remove   ( d s1 s2 s3 -- d s1 s2 s3 i )

std-index-set   ( d s1 s2 s3 -- d s1 s2 s3 )

std-index-value   ( d s1 s2 s3 -- d s1 s2' s4 )

std-index-write   ( d s1 s2 s3 -- d s1 s2 s3 i )

.std_table_match   ( x1 x2 sn pn ... s1 p2 i sm -- sx px | x1 | x2 )

str-desc   ( s -- )

STRasc   ( s -- i )

STRblank?   ( s -- i )

STRcenter   ( s i -- s )

Centers s in a field i characters wide.

    "Welcome to " "muckname" sysparm 78 STRcenter .tell

STRchr   ( i -- s )

STRfillfield   ( s1 s2 i -- s3 ]

Returns a string consisting of as many characters s2 as would be needed to concattenate with s1 to create a string i characters long. Useful for aligning columns of output.

        me @ name " " 20 STRfillfield strcat

...would return...

    "Jessy               "

STRleft   ( s i -- s )

STRright   ( s i -- s )

STRrsplit   ( s1 s2 -- s3 s4 )

Splits s1 on last occurence of delimiter string s2.

"#add here=detail=chair" "=" STRrsplit

...would put...

"#add here=detail", "chair"

STRsts   ( s -- s' )

STRsls   ( s -- s' )

STRsms   ( s -- s' )

Strips multiple internal spaces from s.

  "It's a long way to Tipperary" STRsms

...would return...

  "It's a long way to Tipperary"

STRstrip   ( s -- s' )

STRsplit   ( s1 s2 -- s3 s4 ]

Splits s1 at the first occurence of delimiter string s2.

  "mink otter linsang" "otter" STRsplit

...would put...

  "mink ", " linsang"

.table_match   ( x1 x2 cn pn ... c1 p1 i x3 address -- cx px )

This function tests successive pairs of `comparator' and `data' elements with a separate function (that you create), returning the pair that (according to your function's criteria) `matches'. Although .table_match is supplied as a matching function, it can have other applications: the comparator/data pairs in effect constitute a hash table, and the `matching' function can perform whatever operations you require.

.Table_match takes parameters x1 — the item to be returned if no match is found — and x2 — the item to be returned if more than one pair matches. x1 and x2 can be of any type. Example: #-1 and #-2 are the conventional items used to indicate negative or ambiguous match results for objects of type dbref. These parameters are followed by comparator/data pairs: the comparator is the item to be tested for a match; the data item is a stack item associated with the comparator. An integer specifying the number of such pairs to be tested is then supplied, followed by the value x3 — which will be used to test the match — and the address of the testing function. The testing function should return 1 for true results and 0 for false results. .Table_match returns the comparator/data pair that matches (cx px), or the paramters for negative or ambiguous results (x1 or x2)

Example: Suppose you want a function supplementing .pmatch and .noisy_pmatch that can find players by `nicknames', which are often set as a player's %n property. One way (among many possibilities) to create such a function would be to supply comparator/data pairs of players' %n properties and their dbrefs, and calling .table_match. The nickname to be matched is stored in lvar ourString. Function GetPairs puts the prop/dbref pairs and their count on the stack. Function CheckNick performs a SMATCH, returning 1 if a comparator matches ourString, and 0 if it does not. Code for calling .table_match might then look like this:

  #-1 #-2 GetPairs ourString @ `CheckNick .table_match

If a player calls the program with a search for "Dr. Cat", and GetPairs returns three players who have %n nicknames (and thus are candidates for possible matches) the stack created by this code might have values such as the following immediately before .table_match is called:

  #-1, #-2, "the Scamper Gal", #2, "the terribly velvet-furred linsang",
  #13, "Dr. Cat" #244, "Dr. Cat", `CheckNick

#-1 and #-2 are the codes .table_match is to return for negative and ambiguous matches. The next six items on the stack are three comparator/data pairs: The dbrefs of players #2, #13, and #244, paired with their nicknames. The next item (the second occurance of string "Dr. Cat") is the string to be matched, which was fetched from lvar ourString. `CheckNick — a function name preceded by an ` apostrophe — is a pointer to the address for the CheckNick function.

In this case, the results are not negative or ambiguous: one of the players does have the nickname to be matched: player #244 is Dr. Cat. .Table_match would clear all the above data from the stack, and return...

  "Dr. Cat", #244

unparse   ( d -- s )

when   ( x -- )