Source for file Setting.class.php

Documentation is available at Setting.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package Load
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Load Setting Interface
  22.  * 
  23.  * This is a special Setting Interface for the Load Interface.  A Load Setting
  24.  * holds rules on how to Load a particular file into memory.  A series of
  25.  * Settings can be created for a variety of file types.  Each Load Setting
  26.  * element refers to a parameter in one of the Load methods.  By defining a
  27.  * Load Setting, the programmer would not have to memorize the entire list
  28.  * arguments required by certain Gumbo_Interface_Load methods, just a key
  29.  * reference.
  30.  * <pre>
  31.  * $load->load ("File_Name", "my_key");
  32.  * </pre>
  33.  * 
  34.  * 'dirs'
  35.  * This provides a list of directories to search for the possible existence
  36.  * of the file.  The list will be searched in the order they are added.  The
  37.  * list will be appended to the type of path chosen (see below).  This is where
  38.  * the use of a custom directory is important.  Place the custom directory ahead
  39.  * of the source path.
  40.  * 
  41.  * 'class'
  42.  * This simply indicates that the file name passed is the class name.  There are
  43.  * special rules when loading a Class file and a regular file.  There can only be
  44.  * one definition of a Class or Interface.
  45.  * 
  46.  * 'ext' (file extension)
  47.  * This will define the file extension of the file being passed.  The file name
  48.  * passed does not need to include the file extension.  If the extension argument
  49.  * is set, then it will replace the extension in the file name (file_name.*.ext).
  50.  * It will only replace the last part of the extension.  So, if passing
  51.  * "file_name.class.php" with an extension "inc.php", the search will be for
  52.  * "file_name.class.inc.php".  If the extension is not set, the default value
  53.  * will be used.
  54.  * 
  55.  * 'once'
  56.  * This will load the file only once.  This is useful for files that hold a series
  57.  * of functions or multiple class definitions.
  58.  * 
  59.  * 'include'
  60.  * This setting will tell the Loader to use the include[_once] functions instead of
  61.  * the require[_once] functions.  The default is require.
  62.  * 
  63.  * 'stretch'
  64.  * This setting will expand the file name into additional directory paths.  For example,
  65.  * the Gumbo Library is organized using the stretch feature.  To find the Gumbo_Valid_Address
  66.  * class, simply go into <gumbo_home[custom]_path>/valid/Address.class.php.  The last element
  67.  * of the file name should be the actual file name.  The stretch feature will use the
  68.  * separator string (see below) for searching.
  69.  * 
  70.  * 'separator'
  71.  * This is a character of string of characters to use to separate the file name into
  72.  * directory paths.  The default is an underscore "_" (see example above).
  73.  * 
  74.  * 'path'
  75.  * This indicates the starting path of the search.  The directories list will be
  76.  * appended to this location, followed by any stretch definitions, then the file
  77.  * name and extension.  The path is separated into three areas.
  78.  * - include (default), uses the include path
  79.  * - home, indicates the path to the Gumbo Library
  80.  * - absolute, indicates the directories are from the home path
  81.  * 
  82.  * 'remove'
  83.  * This is a character or string of characters to remove from the file name prior to
  84.  * searching.  For example, when searching for Library files, I would want the
  85.  * library path (home or custom) to be the starting point, followed by the stretch
  86.  * of the file name "Gumbo_Valid_Address".  Without remove, the path would be created
  87.  * as '<home>/gumbo/valid/address.class.php'.  With remove set to "Gumbo_" (default),
  88.  * the string will be removed prior to setting the file path. Now, the path will be
  89.  * '<home>/valid/address.class.php'.  This feature can be used to create a Load Setting
  90.  * for the Zend Framework, using remove as 'Zend_'.
  91.  *
  92.  * @category Gumbo
  93.  * @package Load
  94.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  95.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  96.  * @author Michael Luster <mluster79@yahoo.com>
  97.  * @link http://sourceforge.net/projects/phpgumbo
  98.  * @desc Load Setting Interface
  99.  * @version 0.0.1
  100.  */
  101.  
  102. interface Gumbo_Interface_Load_Setting {
  103.     
  104.     /** ACTION METHODS **/
  105.     /**
  106.      * Adds a single directory path to the list
  107.      * @param string $dir 
  108.      */
  109.     public function addDir ($dir);
  110.     
  111.     
  112.     
  113.     /** MUTATOR METHODS **/
  114.     /**
  115.      * Sets the setting to load a class file
  116.      * @param bool $val 
  117.      */
  118.     public function setClass ($val);
  119.     
  120.     /**
  121.      * Adds a list of directories to the list
  122.      * 
  123.      * There are three ways to set the Directory paths.  The first method passes
  124.      * a string, with either a single directory or list of directories separated
  125.      * by the PATH_SEPARATOR constant.  The second passes an array, with each
  126.      * element value a different directory.  The third involves either of the first
  127.      * two methods, but multiple arguments.
  128.      * 
  129.      * 1. $this->setDirs ("path1:path2:path3/path4");
  130.      * 2. $this->setDirs (array ("path1", "path2", "path3/path4"));
  131.      * 3. $this->setDirs ("path1", array ("path2"), "path3/path4:path5");
  132.      * 
  133.      * @param array|string$dirs ...[]
  134.      */
  135.     public function setDirs ($dirs);
  136.     
  137.     /**
  138.      * Sets the file extension (leading "." not necessary)
  139.      * @param string $ext 
  140.      */
  141.     public function setExtension ($ext);
  142.     
  143.     /**
  144.      * Sets the load only once setting
  145.      * @param bool $once 
  146.      */
  147.     public function setOnce ($once);
  148.     
  149.     /**
  150.      * Sets to use include instead of require
  151.      * @param bool $include 
  152.      */
  153.     public function setInclude ($include);
  154.     
  155.     /**
  156.      * Sets to stretch the file name as additional directory paths
  157.      * @param bool $stretch 
  158.      */
  159.     public function setStretch ($stretch);
  160.     
  161.     /**
  162.      * Sets the stretch separator character
  163.      * @param string $sep 
  164.      */
  165.     public function setSeparator ($sep);
  166.     
  167.     /**
  168.      * Sets the path to start searching from.
  169.      * Possible values:
  170.      * - include: search the include path (default)
  171.      * - home: start from Gumbo home directory
  172.      * - absolute: ignores starting point and uses dirs as absolute paths
  173.      * 
  174.      * @param string $path 
  175.      */
  176.     public function setPath ($path);
  177.     
  178.     /**
  179.      * Sets a string pattern to remove from the file name before search
  180.      * @param string $remove 
  181.      */
  182.     public function setRemove ($remove);
  183.     
  184.     
  185.     
  186.     /** ACCESSOR METHODS **/
  187.     /**
  188.      * Returns if the setting is for a class load
  189.      * @return bool 
  190.      */
  191.     public function getClass ();
  192.     
  193.     /**
  194.      * Returns the list of directory paths
  195.      * @return array 
  196.      */
  197.     public function getDirs ();
  198.     
  199.     /**
  200.      * Returns the file extension
  201.      * @return string 
  202.      */
  203.     public function getExtension ();
  204.     
  205.     /**
  206.      * Returns if the file should be loaded once
  207.      * @return bool 
  208.      */
  209.     public function getOnce ();
  210.     
  211.     /**
  212.      * Returns if the include function should be used instead of require
  213.      * @return bool 
  214.      */
  215.     public function getInclude ();
  216.     
  217.     /**
  218.      * Returns if the file name should stretch
  219.      * @return bool 
  220.      */
  221.     public function getStretch ();
  222.     
  223.     /**
  224.      * Returns the stretch separator character
  225.      * @return string 
  226.      */
  227.     public function getSeparator ();
  228.     
  229.     /**
  230.      * Returns the path to start searching from
  231.      * @return string 
  232.      */
  233.     public function getPath ();
  234.     
  235.     /**
  236.      * Returns the remove string pattern
  237.      * @return string 
  238.      */
  239.     public function getRemove ();
  240.     
  241. }
  242.  
  243. ?>