Building Info

Property List Documentation

By eVil

1. Overview
2. The list editor
   • Overview
   • Commands
3. List support commands
   • lcat
   • lcopy
   • lremove
   • lmove
4. List support macros
   • list-cat ( L s -- L' )
   • list-delete ( L i -- L' )
   • list-deleterange ( L i1 i2 -- L' )
   • list-english ( L -- s )
   • list-filter ( L a -- L' )
   • list-getitem ( L i -- s )
   • list-insert ( L i s -- L' )
   • list-load ( d s -- L )
   • list-notify ( L d -- )
   • list-pop ( L -- )
   • list-prune ( L a -- L' )
   • list-random ( L -- s )
   • list-recite ( L d1 d2 d3 -- )
   • list-remove ( d s -- )
   • list-reverse ( L -- L' )
   • list-save ( L d s -- )
   • list-setitem ( L i s -- L' )
5. Appendices
   • List storage
   • Applications that use list

Overview

A property list (proplist) is a series of string properties stored on an object that represent ordered lines of text. With the commands, macros, and programs outlined in this document they are easily created, modified, and used.

The usual way to create proplist is by running the list editor on an object. The list editor allows the user to insert and delete lines from a property list in a manner similiar to the MUCK program editor.

Once a list has been created, there are a number of support commands. These commands treat proplists much like files, by allowing the user to view a list, or move them from object to object.

The Pegasus macro library includes quite an assortment of proplist-specific macros. These make it very easy to deal with large amounts of text in any MUF program. They provide all the basic functions a MUCKER would want to perform on a file in an easy-to-use manner.

Many of the global programs on Pegasus make use of proplists as their primary datastorage. A list of some of these programs can be found in Appendix B.

The list editor

Overview

The list editor command (ledit) allows any user to create and modify proplists on any object they control. The editor functions in a very similiar manner to the program editor; all the commands are postfix notation, and it is a line-based editor.

The usage for the list editor is as follows: "ledit <object> = <proplist>"
If the specified list does not exist, the list editor will create it.

Each command in the list editor uses post-fix notation. The normal form for commands is: "{<line#>} <command>" All commands are one letter in length.

Commands

[<start> [<end>]] L	Lists all lines between start and end, if both are provided, otherwise it lists only the start line. If no arguments are provided, all lines are printed.
<start> [<end>] D	Deletes the specified line or lines from the buffer.
[<start>] I	Inserts new lines into the buffer before the start line. If no arguments are provided, the lines are inserted at the end of the buffer.
H	Displays help text.
<find> <replace> <start> [<end>] R	Searches all lines between start and end (or only the start line if no end is provided) for the find string, and replaces each instance with the replace string. Currently only search/replace strings that include no spaces are supported.
Q	Save proplist and exit.
X	Exit without saving proplist.

Notes:

• Where line numbers are used, the numbers start at the first line with 0 and go to the last line at n-1. (Where n is the size of the list.)

List support commands

Command	Usage	Explanation
lcat	lcat <object>=<proplist>	This command displays the contents of a proplist to the user.
lcopy	lcopy<source> <destination>=<proplist>	Copies the proplist from the source object to the destination object.
lmove	lmove<source> <destination>=<proplist>	Moves the proplist from the source object to the destination object. The source list is removed.
lremove	lremove <object>=<proplist>	Removes the list from the object.

List support macros

Name	Arguments	Explanation
list-cat	L s1 -- s2	The elements of the list are concatenated together into one string with the provided string places between each list element.
list-delete	L i -- L'	The numbered element is removed from the list.
list-deleterange	L i1 i2 -- L'	The elements i1 and i2, as well as any element between them, are removed from the list.
list-english	L s1 -- s2	The elements of the list are concatenated together with a comma and a space between all but the last elements, and ", and " between the last two elements. ( "one" "two" "three" --> "one, two, and three")
list-filter	L a -- L'	Each of the list elements is passed in turn to the word that the address points to. That word should replace the string with the one that should be placed in the list at the position of the original string.
list-getitem	L i -- s	The requested list element is returned.
list-insert	L i s -- L'	The string inserted into the list before the specified element.
list-load	d s -- L	The named proplist is read from the object and placed on the stack.
list-notify	L d --	Each element in the list is displayed to the object.
list-pop	L --	Removes the list from the stack.
list-prune	L a -- L'	Each of the list elements is passed in turn to the word that the address points to. That word should return false for elements that should be removed and a true for elements that should be kept.
list-random	L -- s	One list element is selected at random and placed on the stack.
list-recite	L d1 d2 d3 --	If d1 is a valid dbref, the list is recited to each player in d1 except d2. If d1 is invalid, but d2 is valid, the list is recited to d2. If neither d1 nor d2 is valid, the list is recited to d3's current location. In any case, the list is recited from d3's perspective. (See recite for more information.)
list-remove	d s --	The list specified is removed from the object specified.
list-reverse	L -- L'	The elements of the list are exactly reversed so that the first element becomes the last element, and so forth.
list-save	L d s --	The list is written out to properties on the object under a list named s.
list-setitem	L i s -- L'	Element i in the list is replaced by the string.

Notes:

• Where element numbers are used, the numbers start at the first element with 0 and go to the last element at n-1. (Where n is the size of the list.)
• These macros may or may not exit cleanly if they are passed invalid parameters.

---

Appendix A -- List Storage

Property Lists are stored in a series of string properties stored on an object. The line count is stored in a prop named "<listname>#" and the elements themselves are stored in a prop named "<listname>#/<i>" where i is the element number plus one.

Thus, a list named "list" that contains "one", "two" and "three" in that order would be stored as:

  list#:3
  list#/1:one
  list#/2:two
  list#/3:three

Appendix B -- Applications that use lists

Here are some of the programs on Pegasus that use property lists:

• The long description program (#3700) uses proplists to store the descriptions.
• The "ask" command uses lists to store NPC responses to questions.
• The recite command uses lists to store the scripts that it recites.
• The global typelist for the LOCK-ObjectType(#3000) program uses lists to store the registered types.
• The global weather program uses lists for its state descriptions.