[Phpslash-commit] CVS: phpslash-ft/class lib.resources.php,NONE,1.1

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/phpslash/phpslash-ft/class
In directory sc8-pr-cvs1:/tmp/cvs-serv23527

Added Files:
	lib.resources.php 
Log Message:
New functions to register classes and libraries, their requirements and
their replacements.  A pslNew function checks to make sure the class is
loaded before instantiating, as well as allows user overrides.

--- NEW FILE: lib.resources.php ---
<?php 
/**
 * PHPSlash Resource Library
 *
 * Definition: A "resource" is anything that can be loaded.  Currently
 * used resources are classes and libraries.  By library we mean
 * basically any PHP application that provides functionality without
 * producing output.
 *
 * The resources library provides functions for declaring what classes
 * or libraries require which, and a loader which includes the necessary
 * files to make instantiation succeed.  This way only the class files
 * which are necessary get loaded.  PHPSlash users can even replace
 * classes with their own via the AddClassReplacement function.
 *
 * @author sympleko (lei...@ma...)
 * 
 * $Id: lib.resources.php,v 1.1 2002/12/11 19:39:15 sympleko Exp $ 
 **/

/**
 * Instantiate a new object.
 *
 * Internally calls loadClass to make sure the object is ready to be
 * constructed (I.e., that the class file has been loaded).
 *
 * By calling addClassReplacement($class,$whatever) you can replace this
 * class with a derived or compatible one.
 *
 * Cribbed from phpgroupware's CreateObject function.  I'm leaving their names
 * on as authors.
 * @link http://savannah.gnu.org/cgi-bin/viewcvs/phpgroupware/phpgwapi/inc/common_functions.inc.php?rev=1.13&content-type=text/vnd.viewcvs-markup
 * 
 * @author mdean
 * @author milosch
 * @author (thanks to jengo and ralf)
 * @syntax CreateObject('class', 'constructor_params');
 * @param string name of class
 * @param string class parameters (all optional) 
 **/
function pslNew($class,
		$p1='_UNDEF_',$p2='_UNDEF_',$p3='_UNDEF_',$p4='_UNDEF_',
		$p5='_UNDEF_',$p6='_UNDEF_',$p7='_UNDEF_',$p8='_UNDEF_',
		$p9='_UNDEF_',$p10='_UNDEF_',$p11='_UNDEF_',$p12='_UNDEF_',
		$p13='_UNDEF_',$p14='_UNDEF_',$p15='_UNDEF_',$p16='_UNDEF_')
{ 
   $fs = "pslNew(\"$class\")";
   // debug($fs,"begin");

   /* override if desired */
   $class = pslGetClass($class);

   /* then we load all necessary classes. */
   loadClass($class);

   if (class_exists($class)) {
      /* Now, we generate the code:
       * "$obj = new($class,$arg1,$arg2,...) 
       */
      if ($p1 == '_UNDEF_' && $p1 != 1)
	 {
	    eval('$obj = new ' . $class . ';');
	 }
      else
	 {
	    $input = array($p1,$p2,$p3,$p4,$p5,$p6,$p7,$p8,$p9,$p10,$p11,$p12,$p13,$p14,$p15,$p16);
	    $i = 1;
	    $code = '$obj = new ' . $class . '(';
	    while (list($x,$test) = each($input))
	       {
		  if (($test == '_UNDEF_' && $test != 1 ) || $i == 17)
		     {
			break;
		     }
		  else
		     {
			$code .= '$p' . $i . ',';
		     }
		  $i++;
	       }
	    $code = substr($code,0,-1) . ');';
	    eval($code);
	 }
      /* error_reporting(E_ERROR | E_WARNING | E_PARSE); */
      // debug($fs,"end");
      return $obj;
   } /* end if class_exists($class) */
   else {
      error("No such class: $class");
      return false;
   }
}

/**
 * loads the files necessary to make a successful instantiation of a class
 *
 * @access public
 * @param string class
 * @return bool success
 */
function loadClass($class) {
   $fn = "loadClass";
   $fc = "$fn(\"$class\")";
   // debug($fc,"begin");
   $urn = classUrn($class);
   return load_resource($urn);
}

/**
 * loads a library that has been registered in the resources area
 * 
 * @access public
 * @param string library name
 * @return bool success
 */
function loadLibrary($lib) {
   return load_resource(libUrn($lib));
}

/**
 * returns the class specified, which may have been overridden by
 * configuration 
 * 
 * @access public
 * @param string class name
 * @return string overidden class name, or original
 */
function pslGetClass($class) {
   $fn = "pslGetClass";
   $fc = "$fn(\"$class\")";
   // debug($fc,"begin");
   $urn = classUrn($class);
   $rep = resource_replacement($urn);
   list($nid,$nss) = parse_urn($urn);
   if ('class' == $nid) {
      $answer = $nss;
   }
   else {
      $answer = $class;
   }
   // debug("$fn:answer",$answer);
   return $answer;
}

/**
 * add a class requirement
 *
 * loadClass will make sure the required class or library is loaded before this
 * Resources will be loaded in the order they are specified, so take care.
 *
 * @access public
 * @param string class, URN, or URI
 * @param string required class
 * @return true
 */
function addClassRequirement($class,$reqClass) {
   // debug("addClassRequirement($class, $reqClass)","begin");
   $urn = classUrn($class);
   if (is_urn($reqClass)) 
      {
	 return add_resource_requirement($reqClass);
      } 
   elseif ($FILE = @fopen($reqClass,'r')) 
      {
	 fclose($FILE);
	 // not a required class, but a required file
	 return add_resource_requirement($urn,$reqClass);
      }
   else 
      {
	 $reqUrn = classUrn($reqClass);
	 return add_resource_requirement($urn,$reqUrn);
      }
}

/** 
 * add a library requirement
 * 
 * "Library" is just a collection of one or more php files which are expected
 * to have function definitions and other non-output-producing code in them.
 *
 * @access public
 * @param string library name
 * @param requirement libarary, URI, or URN
 */
function addLibraryRequirement($lib,$reqLib) {
   // debug("addClassRequirement($lib, $reqLib)","begin");
   $urn = libUrn($lib);
   if (is_urn($reqLib)) 
      {
	 return add_resource_requirement($urn,$reqLib);
      }
   elseif ($FILE = @fopen($reqLib,'r')) 
      {
	 // not a required class, but a required file
	 fclose($FILE);
	 return add_resource_requirement($urn,$reqLib);
      }
   else 
      {
	 $reqUrn = libUrn($reqLib);
	 return add_resource_requirement($urn,$reqUrn);
      }
}

/**
 * add a class replacement
 *
 * pslGetClass will return this class instead of the standard one
 *
 * @access public
 * @param string class
 * @param string replacement class
 * @return true
 */
function addClassReplacement($class,$repClass) {
   $urn = classUrn($class);
   $repUrn = classUrn($repClass);
   return add_resource_replacement($urn,$repUrn);
}

function classUrn($class) {
   return "urn:class:" . strtolower($class);
}

function libUrn($lib) {
   return "urn:lib:" . strtolower($lib);
}

/**
 * URN/RDF functions for specific tags and loading
 */

/**
 * return the resources required for successful loading of this one
 *
 * @access private
 * @param string URN
 * @return array required resources, or false if URN is not valid.
 */
function resource_requirements($urn) {
   return resource_data($urn,"requires");
}

/**
 * returns the resource specified to replace this one through customization
 *
 * @access private
 * @param string URN
 * @return string replacement URN
 */
function resource_replacement($urn) {   
   return resource_data($urn,"isReplacedBy");
}

/**
 * add a requirement to the specified resources
 *
 * @access private
 * @param string URN
 * @param string required URN
 * @return true
 */
function add_resource_requirement($urn,$reqUrn) {
   // debug("add_resource_requirement($urn,$reqUrn)","begin");
   return add_resource_data_multiple($urn,"requires",$reqUrn);
}

/**
 * add a replacement to the specified resources
 *
 * @param string URN
 * @param string replacement URN
 * @return true
 */
function add_resource_replacement($urn,$repUrn) {
   return add_resource_data_single($urn,"isReplacedBy",$repUrn);
}

/**
 * loads a resource (URN) and all resources it requires
 * 
 * @access private
 * @param string urn
 * @return success
 **/
function load_resource($urn) {
   $fs = "load_resource(\"$urn\")";
   // debug($fs,"begin");
   $success = true;
   if (!is_valid_urn($urn)) {
      error("Resource $urn is not known.");
      $success = false;
   }
   else {
      $requirements = resource_requirements($urn);
      // debug("requirements",$requirements);
      foreach($requirements as $req) {
	 if (is_urn($req)) {
	    load_resource($req);
	 }
	 else { 
	    $includedFiles = get_included_files();
	    if (!in_array($req,$includedFiles)) {
	       if (!include_once($req)) {
		  error("Include failed: $req.");
		  $success = false;
	       }
	       else {
		  // debug($fs,"$req successfully loaded");
	       }
	    }
	    else {
	       // debug($fs,"$req already loaded");
	    }
	 }
      }
   }
   // debug($fs,"end");
   return $success;       
}

/**
 * URN string functions
 **/

/**
 * parse a URN into NID and NSS
 *
 * URNs look like "urn:<NID>:<NSS>".  <NID> (Namespace Identifier) can
 * have letters, numbers, or hyphens, but can't start with a hyphen.
 * <NSS> (Namespace Specific String) can have letters, numbers, any of
 * the punctuation marks "()+,-.:=@;$_!*'", or any other character
 * encoded by a hex byte "%xx".
 *
 * @link http://www.ietf.org/rfc/rfc2141.txt
 * @param string urn
 * @return array hash with keys "NID" and "NSS", or empty if no match
 **/
function parse_urn($urn) {
   $nidRE = "[A-Za-z0-9][A-Za-z0-9-]{1,31}";
   $nssRE = "([A-Za-z0-9()+,.:=@;\$_!*'-]|%[0-9A-Fa-f]{2})+";
   preg_match("/^urn:($nidRE):($nssRE)\$/",$urn,$matches);
   if ($matches) {
      $ans = array('NID'=>$matches[1],
		   'NSS'=>$matches[2]);
   }
   else {
      $ans = array();
   }
   return $ans;
}

/** 
 * check if string is a well-formed URN
 * 
 * @param string prospective URN
 * @return bool success
 */
function is_urn($string) {
   return parse_urn($string) ? true : false;
}

/**
 * URN/RDF low-level functions
 */

/**
 * check if information is known about a URN
 *
 * @access private
 * @param string URN
 * @return bool if valid
 */
function is_valid_urn($urn) {
   return $GLOBALS['_PSL']['resources'][$urn] ? true : false;
}

/**
 * return specific RDF tag about a resource
 *
 * @param string URN
 * @param string key (tagname)
 * @return string data if exists
 */
function resource_data($urn,$key) {
   $fn = "resource_data";
   $fc = "$fn(\"$urn\",\"$key\")";
   // debug($fc,"begin");
   $answer = $GLOBALS['_PSL']['resources'][$urn][$key];
   // debug("$fc:answer",$answer);
   return $answer;
}

function add_resource_data_single($urn,$key,$value) {
   $GLOBALS['_PSL']['resources'][$urn][$key] = $value;
   return true;
}

function add_resource_data_multiple($urn,$key,$value) {
   // debug("add_resource_data_multiple($urn, $key, $value)","begin");
   $arr =& $GLOBALS['_PSL']['resources'][$urn][$key];
   if (!is_array($arr) || !in_array($value,$arr)) {
      $arr[] = $value;
   }
   return true;
}

?>