CONCEPT
	properties

UPDATE
	Mateese, 15-Oct-93 - 14:45 MET

DESCRIPTION
	Properties are a means of describing an object with
	properties, which can be read and sometimes changed
	by other objects. They are also useful for adding new
	functionality to objects later and they help to prevent
	the object cluttering up with new set_xx and query_xx
	functions. The /sys/properties.h file helps to publicly
	show which properties are available.

	A property is a pair consisting of the property name and the
	property value. Some standard property names are declared in
	the include file <properties.h>. The value can be any type.
	This provides the flexibility to add new properties of any
	kind later, even to completely alien objects.

	Two functions allow the access to properties:

	mixed Set(string property_name, mixed value, void|int sc)
	  Sets or changes the property <property_name> to
	  <value>. Returns the actually set property value
	  (see also the discussion below). If it is a
	  standard property as defined in <properties.h>,
	  you should use the P_<NAME> notation instead of
	  the property name string.
	  If <sc> is true, the function doesn't look for a
	  Set<Name>(), but instead treats it as true soft property.

	mixed Query(string property_name, void|mixed sc)
	  Returns the value of property <property_name>.
	  If <sc> is true, the function doesn't look for a
	  Query<Name>(), but instead treats it as true soft property.

	Where such freedom of type or range of values is not
	wished or a stricter control of change of properties
	is wanted the property can be made a "built in"
	property. This is done by defining two functions,
	which control read and write access to the property.
	If the property has the name "Foo", the following functions
	must be defined to provide a controlled access:

	mixed SetFoo (mixed value)
	  This function is called, when someone wants to change
	  or set the property, with a Set("Foo",value) call.
	  The function should return the actually set value.

	mixed QueryFoo (void|int flag)
	  This function returns the value of the property "Foo"
	  to the caller. It is automatically called by
	  Query("Foo") if defined.
	  If 'flag' is '1', QueryFoo() has to return that value 
	  which was actually _set_ with SetFoo() (if the QueryFoo()
	  already returns the true value set, it is free to ignore the
	  flat).

	You should understand that the property name (in this
	example "Foo") is an actual part of the function name.
	The functions Set() and Query() use the efun
	function_exist("Set"+propname) to check wheter the
	special functions exist and if they should be called
	instead of using the standard method, to store and
	retrieve the property/value pair in the property alist.

        By convention, every property listen in <properties.h>
        has to be implemented as builtin property!!
	The exceptions are clearly marked in <properties.h>.

        If you overlay a builtin-property with an own one, don't
	assume that the object uses QueryFoo() to query the prop.
	Instead, adjust the underlaying prop in a way that it's at
	all times perfectly valid.
	Also be aware that the object needn't change the prop using
	SetFoo().

	Inventing new properties is no easy task, and you should
	at least talk to some other wizards before presenting
	the idea to the public. "Official" properties are always
	listed in the include file <properties.h>, where the
	name string is defined as (mostly) P_<NAME>.


IMPORTANT
	Refer to perception(C).

SEE ALSO
	perception(C), object(S), room(S), thing(S)