From the NannyMUD documentation

LAST CHANGE

2001-11-01

NAME

        finder - An object finder.

LOCATION

/obj/finder

FUNCTIONS

OTHER FUNCTIONS

        get_object
        get_multiple_object

DESCRIPTION

        The finder is a tool that, given a string describing an
        object, and implicitly its whereabouts, finds that object if
        possible and returns it. This is mainly of interest when
        building wiztools. There is also a function for finding
        several objects at once.

FUNCTION

NAME
        get_object - Get an object from somewhere in the MUD.


SYNTAX
        varargs object get_object(string ob_desc, int no_load)

DESCRIPTION
        The string 'ob_desc' describes an object and where it is
        supposed to be found. Normally, finder loads objects in
        certain circumstances; this can be prevented by giving the
        flag 'no_load'.

        The string 'ob_desc' is a list of one or more identifiers,
        separated by dots:

        < identifier > [ . identifier ]...

        The finder splits the list into identifiers, and processes
        every part. Initially, the investigated object, IO for short,
        is set to this_player() (i.e. you). Then the finder looks for
        an object whose description matches the identifier in the
        'vicinity' (see below) of the IO. If not found, a zero is
        returned, but if found, the IO is set to the found object, and
        the next identifier is parsed. When the finder runs out of
        identifiers, the last IO is returned.

        Several identifiers are handled specially:
        me      The player itself, i.e you. Also triggers the use of
                restricted object finding: the search is limited to
		the IO's inventory.
        env     The IOs environment.
        shadow  The object shadowing IOs, if any.
	master  The master object for the IO.
        Other identifiers are assumed to describe an object in the
        'vicinity' of the IO is. This is, in order of where the object
        is looked for:
        + IOs inventory
        + IOs environment
        + player with name equal to the identifier.
        + clones:
          If the identifier starts with '#', a clone with the given
          clone number is searched for in the inventory and
          environment of the IO.
        + number:
          If the identifier is a number, nr, the 'nr+1':th object of
          the IOs inventory is assumed. If there are less than nr+1
          items in the IOs inventory, this number is treated as a clone
          number. There is a risk that inventory numbers and clone
          numbers are confused, but in reality that risk is very small,
          as clonenumbers usually are quite large.
  
          Things now depends on if the no-load flag is set. If it is,
          'load_object()' is used, otherwise 'find_object()'.
        + load/find on 'identifier', assuming absolute path.
        + load/find on expand_file_name('identifier'). This takes care
          of expansion of '~/foo' and '~foo/bar'.
        + load/find on 'identifier', assuming path relatively your
          current directory. 



EXAMPLE
        me              You, i.e. this_player().
        env             Your environment.
        me.env          Your environment, again.
        obj/player      The masterobject for /obj/player.
        obj/player#12   The player object with clone number 12.
        foobar          An object with id "foobar".
        env.foobar      An object with id "foobar" in your
                        environment. 
        urgle.key       An object with id "key" in an object with id
                        "urgle".
        me.#47          An object in your inventory with clone number
	                47.
        me.47           An object in your inventory with clone number
	                47, but if you don't have that, the 48:th
                        object in your inventory (since it's numbered
                        from zero and up). 




FUNCTION

NAME
        get_multiple_object - Get objects from somewhere in the MUD.


SYNTAX
        varargs object *get_multiple_object(mixed strs, int no_load)

DESCRIPTION
        Given an array of strings describing some objects and their
        whereabouts, an array of those objects is returned. This works
        much like the function get_object(), but allows for some extra
        identifiers in the definition:
        all     The inventory of the IO.
        inv     Ditto.
        deepinv The deep inventory of the IO.
        users   All active players logged on.
        clones  All clones of the IO.
        players/mami/*
	        All objects loaded from this directory.
        players/mami/*.clones
	        All clones of all objects loaded from this directory.



SEE ALSO
        get_object in obj/finder