/*
//      get_object() and get_objects()
//      Created by Pallando@Ephemeral Dale   (92-06)
//      Created by Watcher@TMI  (92-09-27)
//      Revised by Watcher and Pallando (92-12-11)
//      Re-written by Pallando (92-12-18)
//      get_objects() added by Pallando@Tabor (93-03-02)
//      changed to use get_path() by Pallando@Nightmare (93-05-28)
//
//      Use all possible methods to locate an object by the inputed 
//      name and return the object pointer if located.
// Ideas for future expansion (please, anyone feel free to add them if they
//                             have the time)
//   "wizards" - the subset of "users" who are wizards.
//   check the capitalized and lower_case version of str
//   check wizard's home directories.
//   :c - suffix indicating the children() of the previous object's base name.
//   :s - shadow of an object
//   :>func - the object returned by the base object->func() (useful for things
//            like referencing the monster attacking someone.
*/

varargs object get_object( string str, object player )
{
  object what;
  mixed tmp;

  // Prevent wizards finding things they shouldn't.

  if( !str ) return 0;
  if( !player || !living( player ) ) player = this_player();
  if( sscanf( str, "@%s", tmp )         &&
    ( tmp = get_object( tmp, player ) ) &&
    ( what = environment( tmp )       )    )
    return what;
  if( player )    //  Check existance of this_player()
  {
    if( str == "me" ) return player;
    if( what = present( str, player ) ) return what; // Inventory check
    if( what = environment( player ) )               // Environment check
    {
      if (str == "here" || str == "env" || str == "environment")
        return what;
      if( what = present( str, what ) ) return what;
    }
  }
 
  // Call might be made by a room so make a previous_object() check
  // first just to be sure
 
  if( what = present( str, previous_object() ) )  return what;
 
  //  Check to see if a living object matches the name

  if( what = find_player( str ) ) return what;
  if( what = find_living( str ) ) return what;
 
  //  Search for a matching file_name, completing path with 
  //  user's present path

  if( player )
  {
//  this option removed because Nightmare doesn't support cwf
//  if( str == "cwf" ) str = (string)player-> query( "cwf" );
    str = absolute_path( (string)player-> get_path(), str );
  }
 
  //  Make sure the object is loaded into memory, if it exists

  catch( call_other( str, "???" ) );
 
  //  Finally return any object found matching the requested name

  return find_object( str );
}

// Created by Pallando@Tabor (93-03-02)
// player - as per get_object()
// no_arr - if specified, only 0 or an object will be returned,
//          otherwise an array of objects may also be returned.
// str - eg
//   "pallando" - returns the object, /lib/user#123
//   "pallando:i" - returns pallando's inventory
//   "pallando:e" - returns pallando's environment
//   "pallando:e:d:12" - returns the 12th object in the deep inventory of
//                       the room that pallando is in.
//   "caractacus:e:lady" - finds a lady of the court of King Caractacus 8-)
//   "users:rod" - searches the inventories of all users for a rod.
//   "users:e:guard" - searches the environments of all users for a guard.
varargs mixed get_objects( string str, object player, int no_arr )
{
  mixed base, tmp, ret;
  object what;
  int i, s;
// Hmm.  i and s do several jobs here.  It would be clearer to use different
// variables (with longer names) for each job.
// Is it worth slowing the function (using more memory) to do this?


  if( !str ) return 0;
  s = strlen( str );
  i = s;
  while( i-- && ( str[i..i] != ":" ) ); // a reverse sscanf
  if( ( i > 0 ) && ( i < ( s - 1 ) ) ) // of form "%s:%s"
  {
    base = get_objects( str[0..(i-1)], player );
    str = str[(i+1)..s];
    if( !base ) return 0;
    if( !pointerp( base ) ) base = ({ base });
    s = sizeof( base );
    ret = ({ });
    if( str == "e" )
    {
      while( s-- )
        if( tmp = environment( base[s] ) )
          ret += ({ tmp });
    } else if( str == "i" ) {
      while( s-- )
        if( tmp = all_inventory( base[s] ) )
          ret += ( pointerp( tmp ) ? tmp : ({ tmp }) );
    } else if( str == "d" ) {
      while( s-- )
        if( tmp = deep_inventory( base[s] ) )
          ret += ( pointerp( tmp ) ? tmp : ({ tmp }) );
    } else if( sscanf( str, "%d", i ) ) {
      if( ( i > -1 ) && ( i < s ) ) return base[i];
      else return 0;
    } else {
    // This is the location to add more syntax options if wanted such as
    // ith item in jth base object, all such items in all base objects, etc
      while( s-- )
        if( what = present( str, base[s] ) )
          return what;
      return 0;
    }
    switch( sizeof( ret ) )
    {
      case 0: return 0;
      case 1: return ret[0];
    }
    return( no_arr ? ret[0] : ret );
  }
  if( str == "users" )
  {
    ret = users();
    if( !no_arr ) return ret;
    if( sizeof( ret ) ) return ret[0];
    return 0;
  }
  return get_object( str, player );
}

/*
  NB

  It would be fairly simple to combine these two functions into one
varargs object get_object( string str, object player, int arr_poss )
  which will only return a single object unless the array_possible flag
  is passed.

  I have chosen not to do this however, since some muds may not wish to
  use the more complicated search routines and keeping get_objects() as
  a seperate simul_efun makes it easier to disable.
*/