prev | toc | next
 

[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

3.2.4 MUF Library Reference

The standard database and package of programs includes the following programming libraries:

lib-case            lib-edit          lib-editor           lib-index            lib-lmgr
lib-look lib-match lib-mesg lib-mesgbox lib-props
lib-reflist lib-strings lib-stackrng

Note: Since the libararies were written, many of the functions they provide have been defined as MUF primitives. The libraries are retained in their current form for compatibility with existing programs. If a primitive providing the functionality you want is available, it will be more efficient than a library call. For more information on using libraries, see Section 3.2.2.

Functions by Library:

Lib-Case
An ingenious library that uses a few simple $defines to give MUF `case' or `switch' handling like you would find in other programming languages. See the program's header comment for a good, terse explanation.
case default end endcase default
         
Lib-Edit
This library includes string-editing routines, with capabilities for handling ranges of strings such as would be present by reading a list or range from a list onto the stack.
EDITcenter EDITcopy EDITdisplay EDITformat EDITfmt_rng
EDITjoin EDITjoin_rng EDITindent EDITleft EDITlist
EDITmove EDITreplace EDITright EDITsearch EDITshuffle
EDITsort EDITsplit instring STRasc STRchr
STRright rinstring
                                                                         
Lib-Editor
A set of functions providing an interface with the list editor. Note: this library is in the public domain, but its terms of use state that the author of the library, Foxen, must be credited in the header comment of any program that makes use of it.
EDITOR EDITORloop EDITORparse EDITORheader
         
Lib-Index
This library provides a set of routines for handling `indexes'. See Indexes. Note: There are two versions of this library in circulation. Currently, basedb.db and fbmuf provide the older version. The second version — which may or may not be available on your MUCK — provides the additional public routines index-setmatchstr,, index-getmatchstr, and index-propname. Use @view $lib/index to determine which version you have. The standard version is discussed here. Also, the standard version as implemented by basedb.db and the upload script in fbmuf only set _def/ props in the .period-prefix form: routine names must be joined with a leading period in your code, unless the wizards on your MUCK have added the no-period form. Example: to use the routine index-add, put .index-add in your code. (The newer version may or may not require the .format). There are some problems with the implementation of several functions in this library, as discussed in individual entries below.
index-add index-add-sort index-delete index-envmatch index-match
index-matchrange index-remove index-set index-value index-write
         
Lib-Match
A library of matching functions.
.noisy_match .noisy_pmatch .controls .match_controlled .multi_rmatch
.table_match .std_table_match
         
Lib-LMGR
Lib-Lmgr is one of several libraries holding functions used by lsedit. These functions are also useful for other programs that need to manipulate lists without going through the list editor, or to create their own list editors. Note: The documentation provided in the program's header comment, and listed with @view, is inaccurate. The function LMGR-CopyRange (listed in the header) does not exist, but the following undocumented public functions do: LMGR-PutBRange, LMGR-GetCount, and LMGR-SetCount. The public function LMGR-ExtractRange (undocumented, but included as a _def/) does not work. Despite the inaccuracies of documentation, the functions provided by Lib-Lmgr are useful and efficient, and provide a number of capabilities not duplicated by primitives.
LMGR-ClearElem LMGR-ClearRange LMGR-DeleteList LMGR-DeleteRange LMGR-FullRange
LMGR-GetBRange LMGR-GetCount LMGR-GetElem LMGR-Getlist LMGR-GetRange
LMGR-InsertRange LMGR-MoveRange LMGR-PutBRange LMGR-PutElem LMGR-PutRange
LMGR-SetCount
         
Lib-Look
A set of routines adapted to `look' functions. Note: the standard version of lib-look as implemented by basedb.db and the upload script in fbmuf only set _def/ props in the .period-prefix form: routine names must be joined with a leading period in your code, unless the wizards on your MUCK have added the no-period form. Example: to use the routine `safecall', put `.safecall' in your code.
contents-filter cmd-look db-desc dbstr-desc get-contents
list-contents long-display safecall short-display short-list
str-desc unparse
         
Lib-Mesg
This library provides functions for handling `messages'. See Messages.
MSG-append MSG-count MSG-create MSG-destroy MSG-info
MSG-insitem MSG-item MSG-message MSG-setinfo MSG-setitem
MSG-delitem
         
Lib-Mesgbox
A library of message and message-box handling routines. See Messages.
MBOX-append MBOX-badref? MBOX-count MBOX-create MBOX-delmesg
MBOX-destroy MBOX-insmesg MBOX-message MBOX-msginfo MBOX-num2ref
MBOX-ref2num MBOX-ref2prop MBOX-setinfo MBOX-setmesg
         
Lib-Props
This library contains several useful property-handling functions.
setpropstr envprop envsearch locate-prop
         
Lib-Reflist
A library of reflist-handling routines. See Reflists.
REF-add REF-delete REF-first REF-next REF-inlist?
REF-list REF-allrefs REF-filter REF-editlist
         
Lib-Strings
This library provides a number of routines for formating strings.
instring rinstring STRasc STRblank? STRchar
STRcenter STRfillfield STRleft STRrsplit STRright
STRsls STRsms STRsplit STRstrip STRsts
         
Lib-Stackrng
This library provides routines for handling items within a specified range of the stack. See Ranges
sr-catrng sr-copyrng sr-deleterng sr-extractrng sr-filterrng
sr-insertrng sr-poprng sr-swaprng
         


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

case   ( -- )

Begins a case statement. See header for lib-case. (Lib-Case)  [top]


cmd-look   ( s -- )

Does a match function on s, then calls db-desc with the results, simulating the server look command. (Lib-Look)  [top]


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
    ;

This code puts all the players in the room on the stack as a range of dbrefs, filtering out objects of other types. `PlayerCheck (a function name joined with an ` apostrophe) puts the address of the the filter function PlayerCheck function on the stack. (Lib-Look)  [top]


.controls   ( d1 d2 -- i )

Returns true if player d1 controls object d2. The same capability is provided by the CONTROLS primitive. (Lib-Match)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

db-desc   ( d -- )

Prints a description of d, including the name and triggering succ and fail if d is a room. The desc is not parsed for MPI. Programs run with d stored in the variable trigger. (Lib-Look)  [top]


dbstr-desc   ( d s -- )

Prints s as a description, like str-desc, using d as the effective trigger value. The string is not parsed for MPI. (Lib-Look)  [top]


default   ( x -- )

Declares default action to take if no cases in a case statement test true. See header for lib-case. (Lib-Case)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

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

Center justifies all strings between position1 and position2 for a screen i1 characters wide. That is, the strings are padded to a length of i1 characters with leading and trailing spaces. (Lib-Edit)  [top]


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

Copies text within a string range from one line to another, inserting it in the new location. (Lib-Edit)  [top]


EDITdisplay   ( range -- )

Displays the range of strings on the stack to the user. See also
EDITlist. (Lib-Edit)  [top]


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

Formats the strings in range to strings between right margin i1 and wrap margin i2 in length. Short strings are joined to fill this field width; long strings are split at the last occurance of split character c found between i1 and i2. See aslo EDITfmt_rng. (Lib-Edit)  [top]


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

Formats the strings of the range between position1 and position2 to strings i characters wide, splitting long strings and joining short strings. A string that consists only of spaces is considered a paragraph delimiter and is not joined. i must be equal to or greater then 20. The string at position1 must 2 or more characters long. See also EDITformat. (Lib-Edit)  [top]


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

Indents all strings between position1 and position2 by i spaces. That is, the strings are padded with i space characters. If i is a negative number, it reduces indentation by i characters, but will not unindent past the left margin. (Lib-Edit)  [top]


EDITjoin   ( range -- s )

Joins a range of strings on the stack into one string. (Lib-Edit)  [top]


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

Joins the lines of the subrange between position1 and position2 into a single string, returning the string range that results. Leading and trailing spaces are stripped from the strings to be joined, and a single space is inserted in the combined string at points where strings were joined. See also EDITjoin. (Lib-Edit)  [top]


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

Left justifies all strings between position1 and position2. That is, leading spaces are stripped from these strings. (Lib-Edit)  [top]


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

Prints the strings i2 to i3 from range to the user's screen. If i1 is true, the lines will be prepended with line numbers. See also EDITdisplay. (Lib-Edit)  [top]


EDITOR   ( range -- range' s )

Puts the user in the list editor, using range as the values for the list. The list can be interactively edited as with command lsedit. Exits with the modified range and the editor's exit string (end or abort) on the stack. See also EDITORloop. (Lib-Editor)  [top]


EDITORheader   ( -- )

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

< Entering editor. Type `.h' on a line by itself for help. >
< `.end' will exit the editor. `.abort' aborts the edit. >
< Poses and says will pose and say as usual. To start a >
< line with : or " just preceed it with a period (`.') >

(Lib-Editor)  [
top]


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

Puts the user in the list editor, using range as the values for the lines of the list. The list can be interactively edited as with command lsedit. The EDITOR function provides similar functionality; EDITORloop gives greater control over data passed to and from the editor.

EDITORloop takes a range, a space-separated string s1 containing any commands that can be used to return from the editor in addition to end and abort, cursor position i1, and the first editor command to be executed.

EDITORloop returns the modified range, the string s1, the cursor postion at time-of-exit, exit arguments s2, i3, and i4, and the command string used to exit the editor on the stack. Exit arguments are parameters returned to the program when EDITORloop exits. They follow the syntax of other editor commands:

  command start_line end_line = argument_string

start_line is i3. end_line is i4. argument_string is s2.

Example: Suppose you create a program that allows players included in a list holding their dbrefs to update documents in a news reader program. The program includes and #admin function that puts the user into the editor to modify this list. You want to include, in your version of the editor, a command that shows the names of the players who are currently in the list, optionally followed by information such as the last time they logged on or their position/title in the MUCK news staff. The user could then display the names (and other information) for players whose dbrefs are in the list, or a range from the list, by entering .names or .names <range> or .names [<range>] = <field>. You could do this by reading the list onto the stack and supplying names as a command string that would cause EDITORloop to return, with code such as the following:

   "_staff" trig LMGR-Getlist       (*read list onto stack as a range*)
   "names" over 1 + ".i" EDITORloop (*put user in editor, ready to insert
                                      text, at the next free line, with
                                      `names' defined as a .command that
                                      will cause EDITORloop to return*)

If the user typed .names while at line 6 of a 12-line list of dbrefs, the following would be put on the stack:

  ... #123, 12, "names", 6, "", 0, 0, "names"

Using comparison primitives such as SMATCH or STRINGCMP, you could check the top value on the stack and, if it is the string "names" (as it is here), execute a ShowNames function in your program, then return to the editor with another instance of EDITORloop.

If the user had typed .names 1 8, the following would be put on the stack:

  ... #123, 12, "names", 6, "", 1, 8, "names"

Your ShowNames function would need to use the values 1 and 8 to show only names for the dbrefs in lines 1 - 8.

If the user had typed .names 1 - 8 = title, the following would be put on the stack:

  ... #123, 12, "names", 6, "title", 1, 8, "names"

ShowNames would use this information to show the names of players listed in lines 1 - 8 of the list, concattenated with their title... perhaps a value stored in their _news/title property. See also EDITOR. (Lib-Editor)  [top]


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.

Example:

  "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. >

(Lib-Editor)  [top]


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

Moves text within a string range from one line to another location, deleting the original. (Lib-Edit)  [top]


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

Performs a case-sensitive seach of the range items from position1 to position1, inclusive, for all occurances of string s1, replacing each with string s2. (Lib-Edit)  [top]


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

Right justifies all strings between position1 and position2 for a screen width of i characters. That is, these strings are padded with trailing spaces to a string length of i characters. (Lib-Edit)  [top]


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

Perfroms a case-sensitive search of the strings in range for an occurance of string s. The search begins with the item at position. i2 is the position of the first item that includes an occurance of string s. (Lib-Edit)  [top]


EDITshuffle   ( range -- range' )

Randomizes the order items in a range. (Lib-Edit)  [top]


EDITsort   ( range i1 i2 -- range' )

Alphabetically sorts range. If i1 is true, the sort will be in descending order: "aardvark" would be near the top of the stack and "zebra" would be near the bottom. If i2 is true, the sort will be case-sensitive: "Leviathon" would be come before "lapidary", since "L" and "l" are two different characters in a case-sensitive comparison, with "L" preceding "l". (Lib-Edit)  [top]


EDITsplit   ( s c i1 i2 -- range )

Splits string s on the last split character c found between right margin i1 and wrap margin i2. If no split character is found in this range, the string is split at right margin i1. (Lib-Edit)  [top]


end   ( -- )

Declares the end of an action block in a case statement. See header for lib-case. (Lib-Case)  [top]


endcase   ( -- )

Ends a case statement. See header for lib-case. (Lib-Case)  [top]


envprop   ( d s -- s' )

Searches up the environment tree from object d, looking for a property with the name s. Envprop returns the value stored in the first occurance of prop s found, or a null string if it wasn't found. (Lib-Props)  [top]


envsearch   ( d s -- d' )

Searches up the environment tree from object d for an occurance of property s. Envsearch returns the dbref of the first object the property is found on, or #-1 if the propety is not found. (Lib-Props)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

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

Passes the contents of object d through a standard filter that emulates a server contents list: dark rooms do not have contents lists, unless you control the objects or the room; dark objects you don't control do not show; you do not show. Those objects which would show in a Contents/Carrying list by these criteria are returned as a range of dbrefs. The first contained object (the `top' of a Contents or Carrying list) is at the start of the range. (Lib-Look)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

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

Adds name s2, associated with value s3, to index s1 on object d. Returns error code i. If s2 is already a member of the index (matching exactly), index-add returns error code 0, and no changes are made to the index. Otherwise, the name and value are added to the index and error code 1 is returned (operation successful). See also Indexes and std-index-add. (Lib-Index)   [top]


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

Like index-add, index-add-sort adds name s2 and value s3 to index s1, stored on object d. index-add always adds a name to the end of the index; Index-add-sort, in theory, inserts the new name in alphabetical order, immediately before the element it would precede alphabetically. In theory, if names are always added to the index with this routine, the index will remain in alphabetical order. However, this function does not behave as advertised: like index-add, it always puts new names at the end of the index. Returns error code i: 1 is `no error: item added', 0 is `error: name already a member of index; index unchanged'. See also Indexes and std-index-add. (Lib-Index)  [top]


index-delete   ( d s1 s2 -- )

Removes name s2, and its associated value, from index s1 on object d, with no error checking. See also Indexes and std-index-delete. (Lib-Index)   [top]


index-first   ( d s1 -- s2 )

Returns the first name in index s1 on object d as s2. See also Indexes and std-index-first. (Lib-Index)  [top]


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

Returns name s2 from index s1 on object d as s3, the object on which the name was found as d2, and error code i (1 if no error; 0 if no match). If no match is found on d, continues searching up the environment tree, checking indexes called s2 on these objects as well. If index s1 is was created with index-add, or with index-setmatchstr with the `w' name parameter, index-envmatch will return the first match found. That is, there is no check for ambiguity. See also Indexes and std-index-envmatch. (Lib-Index)  [top]


index-last ( d s1 -- s2 )

In theory, returns the last name in index s1 on object d as s2. In practice, returns a null string. See also Indexes and std-index-last. (Lib-Index)  [top]


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

Returns name s2 from index s1 on object d and error code 1 (no error) if s2 is a member of index s1. If s2 is not a member of s1, index-match returns a null string and error code 0 (error: no match). If index s1 was created with index-add, or with index-setmatchstr with the `w' name parameter, index-match will return the first match found. That is, there is no check for ambiguity. If the index was created with index-setmatchstr without the `w' parameter, only complete, explicit matches will be returned, in which case ambiguity is impossible. See also Indexes and std-index-match. (Lib-Index)  [top]


index-matchrange   ( d s1 s2 -- string_range )

Performs a partial-word match search on all members of index s1 on object d, returning those which match true as a string range (see Ranges). Ignores match-type parameters: any full or partial matches will be returned. Not available in `std-' form. See also Indexes. (Lib-Index)  [top]


index-next   ( d s1 s2 -- s3 )

Returns the name immediately following name s2 from index s1 on object d. See also Indexes and std-index-next.(Lib-Index)  [top]


index-prev   ( d s1 s2 -- s3 )

Returns the name immediately preceding name s2 from index s1 on object d. See also Indexes and std-index-prev.(Lib-Index)

index-remove   ( dbref index name -- error )

Removes name s2 and its associated value from index s1 on object d, and returns an error code: 1 if the name existed in the index and was successfully removed, and 0 otherwise. See also Indexes and std-index-remove. (Lib-Index)  [top]


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

Adds name s2, associated with value s3, to index s1 on object d, and returns error code i. Unlike index-add and index-write, this routine does not check for and return errors: if the name is not presently a member of the index, it will be added; if the name is already a member, its value will be edited. See also Indexes and std-index-set. (Lib-Index)  [top]


index-value   ( d s1 s2 -- s3 )

Returns the value associated with name s2 in index s1 on object d. If the index does not include name s1, s3 will be a null string.See also Indexes and std-index-value. (Lib-Index)  [top]


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

In index s1 on object d, sets the value of existing index member with name s2 to value s3. Returns error code i: 1 is `no error: value changed', 0 is `error: name not a member of this index; index unchanged'. See also Indexes and std-index-write. (Lib-Index)  [top]


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).

The default matching criteria (employed with routines called without the std- prefix) is xew: all three criteria are used, and the first match made by any of the criteria will be returned.  [top]


instring   ( s1 s2 -- i )

Returns the position of the first occurance of s2 in s1, case-insensitive. The same capability is provided by the INSTRING primitive. (Lib-Strings)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

list-contents   ( s d -- )

Calls get-contents followed by long-display to print out all of the contents of the given dbref. If there are any contents listed, then the string on the stack is printed out, for "Contents:" or the like. If the contents list is empty, the string is ignored. The triggering player's name is omitted from the contents list of a room (that is, you don't see yourself listed). (Lib-Look)  [top]


LMGR-ClearElem   ( i s d -- )

Clears the content of line i from list s on object d. The size of the list (number of lines) remains unchanged.  [top]


LMGR-ClearRange   ( i1 i2 s d -- )

Clears i1 lines from list s on object d, beginning with line i2. The number of lines in the list does not change. See also LMGR-DeleteRange  [top]


LMGR-DeleteList   ( s d -- )

Deletes list s from object d.  [top]


LMGR-DeleteRange   ( i1 i2 s d -- )

Deletes i1 lines from list s on object d, beginning with line i2. Lines in the orginal list positioned after line i2 are shifted to earlier positions. See also LMGR-ClearRange.  [top]


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

Returns the count of lines in list s, an index value of 1, and string s and dbref d unchanged. These are the parameters that would be needed to put a complete list on the stack using LMGR-GetRange.  [top]


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

Returns puts i1 lines from list s on object d, followed by their count, on the stack, beginning with line i2. The first line of the list will be closest to the top of the stack. See also LMGR-GetRange.  [top]


LMGR-GetCount   ( s d -- i )

Returns the count of lines in list s on object d.  [top]


LMGR-GetElem   ( i s d -- )

Returns the content of line i from list s on object d.  [
top]


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

Puts the contents of list s1 on object d and the total number of lines on the stack.  [top]


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

Puts i1 lines from list s on object d, followed by their count, on the stack, beginning with line i2. The last line of the list will be closest to the top of the stack. See also LMGR-GetBRange.  [top]


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

Inserts i1 strings (range sx sx' ... sx'') in list s on object d, beginning with line i1. Lines in the original list positioned after i2 are shifted to later positions. See also LMGR-PutRange  [top]


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

Moves the contents of the i2 lines of list s on object d, beginning at line i3, to the lines beginning at line i1. The contents of lines i1 to i1+i2 are over-written.  [top]


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

Stores i1 strings (range sx sx' ... sx'') in list s on object d, beginning with line i2. The string at the top of the range is stored at line i2, and the remaining strings are stored on successive lines (in other words, strings are stored in descending order). on The previous contents of the lines are over-written. See also LMGR-PutRange and LMGR-InsertRange.  [top]


LMGR-PutElem   ( s1 i s2 d -- )

Stores string s1 in line i of list s2 on object d. The previous contents of the line are over-written.  [top]


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

Stores i1 strings (range sx sx' ... sx'') in list s on object d, beginning with line i2. The string at the bottom of the range is stored at line i2, and the remaining strings are stored on successive lines (in other words, strings are stored in ascending order). on The previous contents of the lines are over-written. See also LMGR-PutBRange and LMGR-InsertRange.  [top]


LMGR-SetCount   ( i s d -- )

Sets the count of lines for list s on object d to i.  [top]


locate-prop   ( d s -- d' )

Given a property name and dbref, locate-prop finds the property, whether on the dbref itself, an environment of the dbref, or a proploc of the dbref. If no matching property is found, returns #-1. (Lib-Props)  [top]


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

This code duplicates the Contents portion of a server look in a room (note: the same effect could be achieved with a single library call to `list-contents'). (Lib-Look)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

.match_controlled   ( s -- d )

Searches the vacinity for objects with names matching s, like .noisy_match and with similar messages for negative or ambiguous results, but returns #-1 and prints "Permission denied." if the user does not control the found object. (Lib-Match)  [top]


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

Creates a new message with base s2 on object d, with items range, on object d, appending it to existing messages in the box. The newly-created message's number is returned. (Lib-Mesgbox)  [top]


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

Returns true if message item i in the message with base s on object d does not exist. (Lib-Mesgbox)  [top]


MBOX-count   ( s d -- i )

Returns the number of messages contained in message box is on object d. (Lib-Mesgbox)  [top]


MBOX-create   ( s d -- )

Creates a new message box with base s on object d with no messages in it. This consists of a property `<base>#/i' with the string 0 stored in it. (Lib-Mesgbox)  [top]


MBOX-delmesg   ( refnum base dbref -- )

Delete the given message number in the message box. It moves the rest of the messages after it up in the message box.  [top]


MBOX-destroy   ( s d -- )

Destroys message box s on object d and all of its contents. (Lib-Mesgbox)  [top]


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

Creates a new message with the given message items and info string and inserts it before the given message number in the message box. Returns the message's number.  [top]


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

Returns the contents of the given message number in the message box as a range of strings.  [top]


MBOX-msginfo   ( refnum base dbref -- infostr )

Returns the info string of the goven message number in the message box.  [top]


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

Returns the absolute message number (the number assigned when the message was created) for the message with base s on object d with reference number i (the reference number of a message is its current position in the message list). Note: the first message created has absolute message number 0. This is also the value that will be returned if no message at postion i exists. Code that uses MBOX-ref2num should include error checking to deal with this contingency. See also MBOX-num2ref and MBOX-ref2prop. (Lib-Mesgbox)  [top]


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

Returns the propterty name of message number i in the message box with base s on object d. Note: The first message created for a box, number 1, is stored in property <base>#/0 (example:   "1" "+news" trig MBOX-ref2prop   would return   "+news/0#" #123). This is also the the data that will be returned if message i does not exist. Code that uses MBOX-ref2prop should include error checking to deal with this contingency. See also MBOX-ref2num and MBOX-num2ref. (Lib-Mesgbox)  [top]


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

Returns the reference number (the current position in the message list) for the message with base s on object d that has the absolute number i (the number assigned when the message was created). If no such message exits, 0 is returned. See also MBOX-ref2num and MBOX-ref2prop. (Lib-Mesgbox)  [top]


MBOX-setinfo   ( refnum base dbref -- )

Sets the info string for the given message number in the message box.  [top]


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.
This message has three items (1, 2, and 3) holding the item strings "2", "3", and "13" respecitively. Its base is msgs/1. Its information string is "This is the content of a message for players with dbrefs #2, #3, and #13." The message is stored in message box msgs.  [
top]


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

Sets the given message number in the given message box to contain the given message items and info string.  [top]


MSG-append   ( s1 s2 d -- )

Appends message item s1 to the message with base s2 on object d. (Lib-Mesg)  [top]


MSG-count   ( s d -- i )

Returns the number of items in message with base s on object d. (Lib-Mesg)  [top]


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'

The data passed to MSG-create would be cleared from the stack. (Lib-Mesg)  [top]


MSG-delitem   ( i s d -- )

Deletes message item i from the message with base s on object d. (Lib-Mesg)  [top]


MSG-destroy   ( s d -- )

Clears and removes the message with base s from object d. (Lib-Mesg)  [top]


MSG-info   ( s d -- s2 )

Returns the information string for the message with base s on object d. (Lib-Mesg)  [top]


MSG-insitem   ( s1 i s2 d -- )

Inserts a new message item with string value s1 at position i into the message with base s2 on object d. (Lib-Mesg)  [top]


MSG-item   ( i s d -- s2 )

Returns item number i from message with base s on object d. (Lib-Mesg)  [top]


MSG-message   ( s d -- range )

Reads the items for the message with base s on object d onto the stack as a string range. (Lib-Mesg)  [top]


MSG-setinfo   ( s1 s2 d -- )

Sets the s1 as the information string for message with base s2 on object d. (Lib-Mesg)  [top]


MSG-setitem   ( s1 i s2 d -- )

Sets the value of item i in message s2 on object do the the string value 1. (Lib-Mesg)  [top]


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

returns all objects contained by object d whose name matches string s, with the total number of successful matches. the search string can include wildcard and grouping operators such as those used by the smatch primitive. See also SMATCH. (lib-match)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

.noisy_match   ( s -- d )

Checks the room, objects in the room, the player, objects carried by the player, and exits that the player may use for objects whose name matches s, returning the dbref. Partial name strings will work, provided that enough characters are specified to distinguish the object from other similarly named objects. The function is `noisy' in that it supplies explanatory messages for negative or ambiguous results. If no matching object is found, #-1 will be returned, and the string "I don't see that here!" will be printed to the user's screen. If the match is ambiguous, #-2 will be returned, and the string "I don't know which one you mean!" will be printed. (Lib-Match)  [top]


.noisy_pmatch   ( s -- d )

returns the dbref of the player with name s. the player need not be in the vacinity of the user, but the name must be supplied completely (not case-sensitive). the function is `noisy' in that it supplies explanatory messages for negative or ambiguous results. if no matching player is found, #-1 will be returned, and the string "i don't recognize anyone by that name." will be printed to the user's screen. (lib-match)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

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 -- )

Adds dbref d2 to reflist s on object d1. If d1 is already a member of the list, it is moved to the final position in the list. REF-add does not check to ensure that d1 is a valid dbref. (Lib-Reflist)  [top]


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

Returns the contents of reflist s on object d as a range of dbrefs (Lib-Reflist)  [top]


REF-delete   ( d1 s d2 -- )

Removes dbref d2 from reflist s on object d1. (Lib-Reflist)  [top]


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.

(Lib-Reflist)  [top]


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
   ;

In function GetMembers, `CheckRefs (a function named joined with an apostrophe) puts a pointer to the CheckRefs function on the stack. The next line reads the reflist onto the stack. REF-Filter then tests each dbref in the list, using the test provided in CheckRefs: those dbrefs which are currently valid will be returned as a range.

REF-first   ( d s -- d' )

Returns the first dbref in reflist s on object d. (Lib-Reflist)  [top]


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

Returns true (1) if dbref d2 is a member of reflist s on object d1, or false (0) if it is not. (Lib-Reflist)  [top]


REF-list   ( d s -- s' )

Returns a string containing a comma-separated list of the names of all objects with dbrefs in reflist s on object d. (Lib-Reflist)  [top]


REF-next   ( d1 s d2 -- )

Returns the next dbref after d2 from reflist s on object d1. If there are no dbrefs after d1, #-1 is returned. (Lib-Reflist)  [top]


Reflists

A `reflist' is string, stored in a property, containing space- and # octothorpe-delimited dbrefs, such as "#2 #3 #13 #3175 #244". A reflist will contain only one instance of any one dbref. Like all strings stored in properties, a reflist is limited to 4096 characters (about 500 dbrefs).  [
top]


rinstring   ( s1 s2 -- i )

Returns the position of the last occurance of s2 in s1, case-insensitive. The same capability is provided by the RINSTRING primitive. (Lib-Strings)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

safecall   ( x d -- )

Calls program d, passing x (usually a string) as an argument. This routine ensures no garbage is left on the stack by the program called, and that the variables `me', `loc', `trigger', or `command' are unchanged: even if they are modified by program d, they will have their original values after the program call. (Lib-Look)  [top]


setpropstr   ( d s1 s2 -- )

Sets d's property s1 to the string value s2, or removes prop s1 if s2 is a null string. Similar capability is provided by the SETPROP primitive. (Lib-Props)  [top]


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

Calls short-list for the range of dbrefs on the stack, then prints "You see <contents string>" to the user. Note: Contrary to documentation provided with @view, short-display will crash if not passed a range of valid dbrefs containing at least one member. (Lib-Look)  [top]


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"

(Lib-Look)  [
top]


sr-catrng   ( range1 range2 -- range )

Concatenates two ranges into one range. (Lib-Stackrng)  [top]


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

would be left on the stack. (Lib-Stackrng)  [top]


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

on the stack. (Lib-Stackrng)  [top]


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

on the stack. (Lib-Stackrng)  [top]


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"

on the stack. (Lib-Stackrng)  [top]


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

Inserts a subrange into a range on the stack, between the items at position and position + 1. (Lib-Stackrng)  [top]


sr-poprng   ( range1 -- )

Removes a range from the stack. Also defined as popn in lib-stackrng. The same capability is provided by the POPN primitive. (Lib-Stackrng)  [top]


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

on the stack. For this reason, it will often be necessary to copy a `work space' range with sr-copyrng before using sr-swaprng. (Lib-Stackrng)  [top]


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

Like index-add, this routine adds name s2 and value s3 to index s1, stored on object d. All four items are left on the stack unchanged, and error code i is returned: 1 is `no error: item added', 0 is `error: name already a member of index; index unchanged'. See also Indexes and index-add. (Lib-Index)  [top]


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

Alphabetically adds a name/value pair to an index, like index-add-sort, but leaves all four items on the stack, returning error code i: 1 is `no error: item added', 0 is `error: name already a member of index; index unchanged'. In theory, it should add the name to the index in alphabetical order, but in practice and like index-add, it simply adds the name to the end of the index. See also Indexes and index-add-sort. (Lib-Index)  [top]


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

Removes name s2, and its associated value, from index s1 on object d, with no error checking. All three items are left on the stack unchanged. See also Indexes and index-delete. (Lib-Index)  [top]


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

Performs an environment match like index-envmatch, using the match criteria specified in paramater string s3. Arguments d and s1 are left on the stack; parameter string s3 is returned as null string s4. See also Indexes and index-envmatch. (Lib-Index)  [top]


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

Takes object to holding index (d), an index name (s1), and two null strings (s2 and s3). Returns four items, with s2 being replaced by s2', the first name in the index. See also Indexes and index-first. (Lib-Index)  [top]


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

In theory, takes object to holding index (d), an index name (s1), and two null strings (s2 and s3), returning four items, with s2 being replaced by s2', the last name in the index. In practice, s2' will still be a null string. See also Indexes and index-last. (Lib-Index)  [top]


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

Performs a name match like index-match, using the match criteria specified in parameter string s3. Arguments d and s1 are left on the stack; parameter string s3 is returned as null string s4. See also Indexes and index-match.(Lib-Index)  [top]


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

Takes object holding index (d), an index name (s1), a name (s2), and a null string (s3), returning the four items with s2 modified to s2', the name in the index immediately following s2. See also Indexes and index-next.(Lib-Index)  [top]


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

Takes object holding index (d), an index name (s1), a name (s2), and a null string (s3), returning the four items with s2 modified to s2', the name in the index immediately preceding s2. See also
Indexes and index-prev.(Lib-Index)  [top]


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

Takes object holding index (d), an index name (s1), a name (s2), and a null string (s3), and removes name s2 and its associated value from the list. The four initial arguments and an error code are left on the stack. See also Indexes and index-remove.(Lib-Index)  [top]


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

Adds a name/value pair to an index, with no error checking, like index-set. All four items are left on the stack unchanged. See also Indexes and index-set.(Lib-Index)  [top]


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

Performs a match for name s2 in index s1 on object d, using matching criteria specified in parameter string s3. The dbref and index name are left on the stack unchanged. Name s2 is returned in complete form (partial matches are expanded). Returns the value associated with name s3 as string s4. If the match was unsuccessful, s4 will be a null string. See also Indexes and index-value.(Lib-Index)  [top]


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

Sets a value for an existing index member, like index-write, but leaves all four items on the stack and returns an error code. See also Indexes and index-write.(Lib-Index)  [top]


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

The standard table match takes i comparator/data pairs in the same manner as .table_match, and performs a SMATCH on each comparator, matching against string sm. Comparators must be strings; it is not necessary to supply a matching functin and its address. .Std_table_match returns the comparator/data pair that matchs sm, or x1 if no match was found, or x2 if more than one match was found. See also .table_match and SMATCH. (Lib-Match)  [top]


str-desc   ( s -- )

Prints s as a description, matching the `@###' and `@$prog' values properly, and uses them with the present trigger value. If neither of these exist, or if they are invalid, the string is simply printed. The string is not parsed for MPI. (Lib-Look)  [top]


STRasc   ( s -- i )

Converts character s to its ASCII number equivalent. The same capability is provided by the CTOI primitive. (Lib-Strings)  [top]


STRblank?   ( s -- i )

Returns true if s null string or only spaces. (Lib-Strings)  [top]


STRcenter   ( s i -- s )

Centers s in a field i characters wide.

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

...would display a welcome line including the name of the MUCK centered for a standard screen. (Lib-Strings)  [top]


STRchr   ( i -- s )

Converts ASCII code number i to its character equivalent. The same capability is provided by the ITOC primitive. (Note: the header document for Lib-Strings lists the name of this funtions as STRchar, but this is incorrect: use STRchr.)   [top]


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               "

(Lib-Strings)  [top]


STRleft   ( s i -- s )

Returns s, padded with trailing spaces to a string length of i characters. (Lib-Strings)  [top]


STRright   ( s i -- s )

Returns s, padded with leading spaces to a string length of i characters. (Lib-Strings)  [top]


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"

...on the stack. If s1 does not include s2, s3 will be identical to s1 and s4 will be a null string. The same capability is provided by the RSPLIT primitive. See also STRsplit. (Lib-Strings)  [top]


STRsts   ( s -- s' )

Strips leading spaces from s. The same capability is provided by the STRIPLEAD primitive. (Lib-Strings)  [top]


STRsls   ( s -- s' )

Strip trailing spaces from s. The same capability is provided by the STRIPTAIL primitive. (Lib-Strings)  [top]


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"

(Lib-Strings)  [top]


STRstrip   ( s -- s' )

Strips leading and trailing spaces from s. The same capability is provided by the STRIP primitive. (Lib-Strings)  [top]


STRsplit   ( s1 s2 -- s3 s4 ]

Splits s1 at the first occurence of delimiter string s2.

  "mink otter linsang" "otter" STRsplit

...would put...

  "mink ", " linsang"

...on the stack. If s1 does not include s2, s3 will be identical to s1 and s4 will be a null string. The same capability is provided by the SPLIT primitive. See also STRrsplit. (Lib-Strings)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

.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

See also .std_table_match. (Lib-Match)   [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

unparse   ( d -- s )

Returns the name of object d, concattenated with its dbref and flags (such as "Bulletin Board(#177S)") if the user controls object d. If the user does not control d, or if the user is set Silent, only its name is returned ("Bulletin Board"). (Lib-Look)  [top]


[A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]

when   ( x -- )

Performs a TRUE|FALSE condition test within a case statement. See header for lib-case. (Lib-Case)  [top]


prev | toc | top | next