From the NannyMUD documentation

LAST CHANGE

2004-05-12

NAME

        basic - Basic functionality for _all_ objects.

FUNCTIONS

SETUP FUNCTIONS

	set_short
	set_long
	add_item
	remove_item
	add_property
	remove_property
	add_command
	remove_command
	add_item_cmd
	remove_item_cmd

QUERY FUNCTIONS

	short
	id
	query_long
	long
	query_item_map
	query_property

OTHER FUNCTIONS

	eval
	reset

PROPERTIES

EXTERNAL PROPERTIES

PROPERTY NAME
        __remote - 


DESCRIPTION
	See eval.


PROPERTY NAME
        simplemore - 


DESCRIPTION
	 If this property is set, the long description of the object
	 will be fed through simplemore instead of simply being
	 written.


PROPERTY NAME
        temp_ - 


DESCRIPTION
        Any property beginning with temp_ will be removed
        automatically at the next reset.


PROPERTY NAME
        no_wrap - Do not wrap descriptions by default.


DESCRIPTION
        Descriptions will, if the contain no new-lines, be wrapped
	at 77 characters per line. Setting this  property will
	disable that feature.



NOTE
	Please do not redefine long(), redefine query_long() instead.




FUNCTION

NAME
        eval - Internal function converting a string to a function call.


SYNTAX
	mixed eval(mixed value, mixed optional_argument)

DESCRIPTION
        This is an internal function called from various standard lib query
        functions, such as short(), query_long(), etc. It lets the query
        function return a variable result rather than assigning it a
        constant string description.

        You do not need to call this function yourself, but you need to know
        the format of its arguments to be able to use its functionality.

        The format allows the following four function calls:
          1) "@function_name()";
          2) "@function_name(argument)";
          3) "@object_name->function_name()" and
          4) "@object_name->function_name(argument)" ,
        where you specify the object_name, function_name and argument.

        If you set a description to either of these formats, the given
        function will be called and the returned value will be used.
        
        The given function will be called with these three arguments:
          1) the string given as 'argument' above;
          2) the optional argument to eval();
          3) this_object()

        If no object_name is given, the function will be called in
        this_object(), or in the remote object if it is set through
        the "__remote" property.

        The second optional argument, passed along to your function, depends 
        on the function that uses eval(), for example with add_command() it
        may contain the words typed by the player. This is mentioned in the
        individual manual pages for the functions that use it.


NOTE
        This is not a man page for the wizard command eval.


NOTE
        If a string that doesn't match the given formats is sent through eval,
        eval will simply return the string.


NOTE
        The object_name goes through expand_file_name(), allowing objects
        such as "../description_daemon".


EXAMPLE
	set_short("@/std/foo->get_short()");

        The short description of the object at any time will be whatever 
        "/std/foo"->get_short() returns at the moment.




FUNCTION

NAME
        set_short - Set the short description.


SYNTAX
	void set_short(string short_desc)

DESCRIPTION
	This function sets the short description of the object. The
	short description is used when showing the object as part of
	an inventory, a list, etc. In the case of a room, the short
	description is shown if you are walking around in brief mode.

	The lib will apply 'eval()' on this value.




FUNCTION

NAME
        set_long - Set the long description.


SYNTAX
	void set_long(string long_desc);

DESCRIPTION
	THis function sets the long description of the object. The
	long description is presented when you look at the object.

	The system will line-break this description for you, if and
	only if you use no line-breaks, \n, in it. The system will
	assume a width of 78 characters per line.

	If the property "simplemore" has been set on the object, the
	long description will be presented using simplemore instaed of
	a simple write.




FUNCTION

NAME
        add_item - Add or change a virtual item.


SYNTAX
	void add_item(mixed item, string description)

SYNTAX
	void add_item(mapping items)

DESCRIPTION
	This function adds a virtual 'item' so you can look at it. A
	virtual item is something that only exists as a description,
	without having an object of it's own. Consider the description
	of a room, where you mention that there is a tree here. The
	tree exists only as part of the description, but a description
	has been added for it using add_item(). Then, the tree is a
	virtual item.

	If the item in question already exists it will be
	redefined. If the first argument is an array, an item will be
	added for each string in that array with the same
	description. The description is passed to eval, when someone
	looks at it, with the name of the item as optional_argument.

	The second syntax (giving a mapping as argument) removes all
	previous items and then sets the items to the new argument.

	Note that add_item() does the same formatting as set_long().


NOTE
	Items MUST be lower case, because the 'look at' forces all characters
	to lower case.


EXAMPLE
	add_item("snow","It is white.");


EXAMPLE
	add_item(({"snowman","man"}),"He looks cold.");




FUNCTION

NAME
        remove_item - Remove one or several items.


SYNTAX
	void remove_item(mixed item);

DESCRIPTION
	This function removes an item (if it exists). Just as with
	add_item, the first argument can be an array, in which case 
	all the items in that array will be removed.




FUNCTION

NAME
        query_item_map - List the added items.


SYNTAX
	mixed query_item_map()

DESCRIPTION
	This function returns the mapping holding all added items.




FUNCTION

NAME
        add_property - Add or change properties.


SYNTAX
	void add_property(string property [, mixed value])

SYNTAX
	void add_property(mapping properties)

DESCRIPTION
	The first syntax adds or changes one property to have the
	given value. (Default is 1) The property deamon will be asked
	to add linked properties.

	The second syntax first removes all properties and then sets
	the properties that are present in the mapping.


NOTE
	Any property starting with temp_ will be removed in the next
	call to reset.


EXAMPLE
	add_property("metal");


EXAMPLE
	add_property((["metal":1]));




FUNCTION

NAME
        remove_property - Remove one or several properties.


SYNTAX
	void remove_property(mixed property)

DESCRIPTION
	The argument is a property or an array of properties to be
	removed, any linked properties will also be removed.




FUNCTION

NAME
        add_command - Add a command definition to an object.


SYNTAX
	void add_command(mixed command, string action)

DESCRIPTION
        This function adds a command or commands to an object.  This
        means that the object will catch whatever a player types, if
        it matches any command defined by the object.

        The argument 'command' can be one of the following:
           1.  A string that matches exactly what the player should type.
           2.  A single word + " %s", that matches anything typed by the
               player that starts with that single word.
           3.  An array containing elements of type 1 and/or 2.

        The argument 'action' is a string value that can be one of the
        following:
           1.  A message that will be sent immediately through
               /std/msg->msg().
           2.  A string that matches any of the eval() formats, which
               allows a function to be tied to the command.
  
        If the command tied to the function is of type 2, the words that
        come after the single word is passed as the second argument to 
        your function. The first argument is either 0, or a value you may
        have specified in your eval() format.

        If the command is tied to a function, the returned value of the 
        function is handled as follows:
           1. If it is a string, it will be sent to /std/msg->msg().
           2. If it is an integer other than zero, nothing will be written.
              This is useful when you want to control the written message
              yourself through your function.
           3. If it is zero, the command will be considered unsuccessful,
              which allows another command to catch what the player typed
              or triggers a notify_fail().


EXAMPLE
        These examples use simple string messages:

        add_command(({ "climb tree", "climb up"}),
                    "You can't climb the tree.");

        add_command("say %s", "No, you may not talk here.");

        add_command("pick nose",
                    "\bPRON pick\b$ \bposs nose and eat\b$ \bposs findings!");


EXAMPLE
        This example is passed through a function:

        add_command("intone %s", "@intone_cmd()");
 
        intone_cmd(string useless, string arg) {
           if (!stringp(arg)) return 0;
           if (arg == "the password")
              return "\bPRON intone\b$ the password.";
           return "\bPRON intone\b$ some nonsense.";
        }


SEE ALSO
        add_item_cmd in std/basic/basic


SEE ALSO
        remove_command in std/basic/basic


SEE ALSO
        eval in std/basic/basic
        eval in wizcommands/debug/eval


SEE ALSO
        msg in std/text/msg
        msg in std/text/msg




FUNCTION

NAME
        remove_command - The opposite of add_command.


SYNTAX
	void remove_command(string command)

DESCRIPTION
	This function removes a command previously added with
	add_command. Note that if you do
	add_command( ({"foo","bar"}), "action"); 
	and then
	remove_command("foo")
	the command 'bar' will still be available.


SEE ALSO
        add_command in std/basic/basic




FUNCTION

NAME
        add_item_cmd - Add a command bound to an item.


SYNTAX
	void add_item_cmd(mixed verb, mixed item, string action)

DESCRIPTION
	This function works similarly to add_command, except it binds
	to a previously added item, with some smart defaults.

	'verb'   is a string or an array of strings which will be used
	         as acceptable verb(s).
	'item'   is a name of a previously added item, or an array of such
	         names. If the item has several aliases, you need give only 
	         one per item (the description of the item is used for
                 matching).
	'action' works exactly as the action argument for add_command.

	If this funcion is used in something that inherits stationary.c
	"item" can also be the name of the object in which case the name
	or any of the aliases of the object will match is used with the
	verb.


NOTE
	You can't have an add_item_cmd and an add_command on the same verb.


NOTE
	This function uses the _description_ of the item as an
	identification. That means that if you have several items with
	the same description in the room, add_item_cmd might not work
	as it should on those items.


NOTE
	The code implementing this feature is a horrible kludge.


EXAMPLE
	add_item(({"tree","oak tree","large oak"}),"Looks climbable.");


EXAMPLE
	add_item_cmd("climb","tree","@climb_tree()");


EXAMPLE
	add_item( ({ "a", "b", "c" }), "Here're a, b and c.");


EXAMPLE
	add_item( ({ "e", "f", "g" }), "Here're e, f and g.");


EXAMPLE
	add_item("d", "Here's d.");


EXAMPLE
	add_item_cmd( ({ "read", "study" }), ({ "a", "d", "e" }), "You study hard.\n"); 


SEE ALSO
        add_command in std/basic/basic


SEE ALSO
        remove_item_cmd in std/basic/basic




FUNCTION

NAME
        remove_item_cmd - The opposite of add_item_cmd


SYNTAX
	void remove_item_cmd(mixed verb, string item)

DESCRIPTION
	This function removes a previously added item command, the
	arguments have the same function as the first two arguments to
	add_item_cmd.


SEE ALSO
        add_item_cmd in std/basic/basic




FUNCTION

NAME
        query_property - Ask if a property is set


SYNTAX
	mixed query_property(string prop, int truth)

DESCRIPTION
	If called with no arguments, the function returns an array with the
	names of all properties that are set in the object.
	
	If called with one argument, the function returns the value of the
	property after running that value through eval().

	If called with two arguments, the function returns the value of the
	property without running that through eval().




FUNCTION

NAME
        _change_property_callback - Notification of property changes.


SYNTAX
	int _change_property_callback(string type,
				      string property,
				      mixed property_value)

DESCRIPTION
	This function is called when a property is added and removed. 
	It can be used to block the change of the property, for example
	the __remote property. Thus it works much like a block-hook,
	but this implementation is more secure than a hook.

	The argument 'type' will be either "add" or "remove".

	The argument 'property' will be the name of the property that is
	being added/removed.

	The argument 'property_value' will be the value of the property.
	In the case of a "remove", the value will be the current value
	of the property.  In the case of a "add", the value you will be
	the new value of the property.  This value is not passed through
	eval(), for security reasons.




FUNCTION

NAME
        call_remote - Central point for using the __remote property.


SYNTAX
	varargs mixed call_remote(string function,
				   mixed a,
				   mixed b,
				   mixed c,
				   mixed d)

DESCRIPTION
	This function is a central point to use the __remote property
	through. If you are coding in the lib, please use this for the
	remote calls.