Guide to PropDirs

Properties and PropDirs

Properties are stored in AVL trees, and organized into directories of properties. This speeds things up, and keeps you from being spammed on examines. To examine the properties on an object, use 'ex obj=propdir'. where to examine the base properties in an object, propdir would be '/'. You can see the value of a single property with 'ex object=propname'.

Propdirs are a method of storing and organizing properties to speed access and to provide a sort of built-in organization. The basic idea is to make something similar to a 'filesystem' for properties. In this analogy, each person would be a filesystem, with a root directory and (theoretically) an infinite number of properties beneath that.

A property has been expanded with the idea that each property may now contain a new property list -- the 'propdir'. properties can both have a value (either integer or string as before) _and_ contain other properties.

The actual directory entries may ALSO contain data. Propdirs' only real 'visible' changes are in the names of properties -- '/' is used as the property directory separator, and so will not appear in the names of the properties when listed through 'examine' or MUF programs.

Property protections have also been expanded -- the . and _ may appear either at the beginning of the property name or immediately following a '/', and that property will have the appropriate protections. For example, the property '/mail/.inbox/mesg/#' would have the same protections as '.mesg#' would now.

There are two ways to remove a property list:

First, and most straight forward, is to remove the property that contains it. so, in the previous example, removing the property '/mail/.inbox' would (recursively) remove all properties under .inbox before removing .inbox itself.
The second way is to remove all properties within the property list yourself. When the last property is removed, the parent property (the one that contained the property list) is examined to see if contains data. If it does, then the property list only is removed. If the property doesn't contain data then it is removed also.

Because of the first method of removing propdirs, the ability to have a property list and value in the same property should be used sparingly.

If you try to access a property ending in '/', in MUF, it will give a programmer error, except in NEXTPROP, in which it will give the name of the first property in that propdir.

The last visible, non-MUF change that propdirs bring is that 'examine' will no longer show properties _directly_. Instead, where the properties would normally be shown, it will say: "[ Use 'examine object=/' to list root properties. ]"

Examine now can take an argument which is the property or propdir to view. If the property name given ends with a '/', all properties in property directory will be listed, otherwise the single property named will be shown.

Internally, a few things changed. property lists are now stored as AVL trees instead of straight lists, so there is a speed increase even if propdirs are not directly used. This also means properties are kept in sorted order and will be displayed that way. 'addprop' will no longer allow a ":" in the property name. To clear a propdir's value without deleting the proptree below it, from MUF do a '"" 0 addprop' to it.

A property can *not* have both a string and integer stored at the same time anymore. The old property.c was lax and allowed this, even though the integer value would be lost on dbload.

Property and Propdir Usage Examples

Lines indented only 2 spaces are what the user is typing. Lines indented 6 spaces are what the MUCK is returning to the user. Lines in justified paragraphs, like this one, are comments on what's going on. First, lets set up a bunch of properties.

  @set me=first:a property.
  @set me=second:another property.
  @set me=first/one:A property in a propdir
  @set me=first/two:Another property in a propdir
  @set me=third/prime:three

Okay, now lets see what properties we have. We use the examine command to do that, with a second argument, to tell it what we want to list in the way of properties. In this case, since we want to list the base level properties, we use '/'.

  ex me=/
      first/: (string) a property.
      second: (string) another property.
      third/: (no value)

Okay, it has a few properties with the first part of the names of the properties that we set. The /'s at the end of some of the property names means that there are sub-properties that we can list. When we set a property like 'first/one', it's actually creating a sub-property named 'one' beneath a property named 'first'. If 'first' doesn't already exist, then it will create that property. Let's list what sub-properties we created under 'first'.

  ex me=first/
      first/one: (string) A property in a propdir.
      first/two: (string) Another property in a propdir.

Here we see the properties that we set as sub-properties under 'first'. We examined for 'first/' to list the sub-properties. The / at the end of the name tells the game that we want it to list the sub-properties of that property, and not that property's value itself. Lets see what value the property 'first' has, itself. To do this we leave off the '/'

  ex me=first
      first/: (string) a property.

Okay, lets say that we just want to see the value of the sub-property named 'one', under the property 'first'. We can list it as follows:

  ex me=first/one
      first/one: (string) A property in a propdir.

If the property or sub-property that you specify does not exist, it will complain about it.

  ex me=first/three
      No property found.

If a property was created to contain a sub-property, but was never given a value itself, it is listed as having no value. It has sub-properties, however.

  ex me=third
      third/: (no value)

Let's list those sub-properties.

  ex me=third/
      third/prime: (string) three

Okay, let's delete the sub-property 'prime', from under the property 'third'. To do this, we act like we are setting the variable again, except that we are giving it no value this time.

  @set me=third/prime:
  ex me=third/
      No properties listed.

There. It's gone. Now let's list the bottom level properties again.

  ex me=/
      first/: (string) a property.
      second: (string) another property.

Whoops! The property 'third' is gone too! This is because properties with no values are automatically deleted when their last sub-property is deleted. Let's delete a subproperty from 'first', now.

  @set me=first/one:
  ex me=/
      first/: (string) a property.
      second: (string) another property.

The property 'first' still exists, with it's string value, and it still has sub-properties. Lets list those.

  ex me=first/
      first/two: (string) Another property in a propdir.

[Here we see that the sub-property 'one' is gone, as we expected. Let's see what happens when you erase a property that has sub-properties.

  @set me=first:
  ex me=/
      second: (string) another property.

The property 'first' is gone.

  ex me=first/
      No properties listed.

And the subproperty it had is gone too! Let's remake the 'first' prop.

  @set me=first:again, a property.
  ex me=/
      first: (string) again, a property.
      second: (string) another property.

We have two properties again, and no sub-properties. It should be noted that sub-properties can have sub-sub-properties, and they can contain even subbier properties, and so on and so forth.

  @set me=first/one:uno
  @set me=first/one/example:dos
  @set me=first/two/example:tres
  @set me=first/one/example/cat:meow
  ex me=first/
      first/one/: (string) uno
      first/two/: (no value)
  ex me=first/one/
      first/one/example/: (string) dos
  ex me=first/one/example/
      first/one/example/cat: (string) meow

There is a special case in examine to let us list ALL the properties and sub-properties of a prop. To use it, we just specify '**' as a propdir. For example, to list all sub-properties and sub-sub-properties, etc., under 'first', you would do the following:

  ex me=first/**
      first/one/: (string) uno
      first/one/example/: (string) dos
      first/one/example/cat: (string) meow
      first/two/: (no value)
      first/two/example/: (string) tres

Let's delete all the properties on the object, now. To do that, we specify no property name or value when we use @set. Nothing but a colon.

  @set me=:
  ex me=/
      No properties listed.

All gone!

Return to the TinyMUCK Page

Page created by Telzey, and maintained by Tugrik d'Itichi.
Comments/Questions/Flames to: FMPages@furry.com