Source for file Tree.class.php

Documentation is available at Tree.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 Composite
  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.  * Abstract Tree Class for Composite Interface
  22.  * 
  23.  * The abstract Tree class provides general implementation to common methods
  24.  * of Composite classes.  Typically, Composite classes should extend an
  25.  * abstract class (such as this one).  This assists in eliminating having to
  26.  * implement all the methods of the Composite Interface.
  27.  * 
  28.  * The full Composite structure will consist of a Branch and a Leaf (both
  29.  * extending the abstract Tree).  Some Composite definitions will consist
  30.  * of Components and other language.  The use of Tree-Branch-Leaf keeps the
  31.  * idea of a tree structure more direct (especially those new to Design Patterns).
  32.  * Tree-Branch-Leaf is the same as Component-Composite-Leaf, just smaller names.
  33.  * 
  34.  * Branch
  35.  * The Branch will hold the other Tree objects.  Every Composite will start
  36.  * with a Branch object (trunk).  Additional Tree elements can be added to
  37.  * populate the Tree.
  38.  * 
  39.  * Leaf
  40.  * The Leaf is a single name=>value element.  It is the lowest form of data
  41.  * that can be held by a Composite.  A Leaf cannot hold other Tree elements.
  42.  * 
  43.  * To create a Composite structure, start with the first Branch (trunk), and
  44.  * add the necessary elements as required.  If a Branch is added with the same
  45.  * name as another Branch, a numerical reference will be applied.  Think of
  46.  * an XML file with multiple tags of the same name.  To access a numerical
  47.  * reference, simply place the number inside curly braces.
  48.  * <pre>
  49.  * // access second Leaf element value
  50.  * $branch->{1}->value;
  51.  * </pre>
  52.  * 
  53.  * @category Gumbo
  54.  * @package Composite
  55.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  56.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  57.  * @author Michael Luster <mluster79@yahoo.com>
  58.  * @link http://sourceforge.net/projects/phpgumbo
  59.  * @desc Abstract Tree Class for Composite Interface
  60.  * @version 0.0.1
  61.  */
  62.  
  63. gumbo_load ("Interface_Composite");
  64.  
  65. abstract class Gumbo_Tree implements Gumbo_Interface_Composite {
  66.     
  67.     /** @var int|string$_name Composite name */
  68.     private $_name;
  69.     /** @var mixed $_value Composite value */
  70.     private $_value;
  71.     
  72.     /** @var array $_attr list of Attributes */
  73.     private $_attr = array ();
  74.     /** @var array $_comments list of Comments */
  75.     private $_comments = array ();
  76.     
  77.     
  78.     
  79.     /** ACTION METHODS **/
  80.     /**
  81.      * Adds an attribute description to the Composite object
  82.      * @postcondition remove non-alphanumeric characters (excluding underscores) from $name
  83.      * @param string $name attribute name
  84.      * @param string|num|bool$val attribute value
  85.      * @param bool $replace replaces duplicate attribute
  86.      * @throws Gumbo_Exception
  87.      */
  88.     public function addAttribute ($name, $val, $replace=false) {
  89.         try {
  90.             // verify precondition
  91.             if (!is_string ($name)) {
  92.                 throw new Gumbo_Exception ("Invalid Argument 'name:str' => {$name}:" . gettype ($name));
  93.             }
  94.             if (!is_string ($val) && !is_numeric ($val) && !is_bool ($val)) {
  95.                 throw new Gumbo_Exception ("Invalid Argument 'val:str|num|bool' => {$val}:" . gettype ($name));
  96.             }
  97.             try {
  98.                 if (!is_bool ($replace)) {
  99.                     throw new Gumbo_Exception ("Invalid Argument 'replace:bool' => {$replace}:" . gettype ($replace));
  100.                     $replace = false;
  101.                 }
  102.             } catch (Gumbo_Exception $e) {
  103.                 $e->setFunction (__METHOD__);
  104.                 gumbo_trigger ($e);
  105.                 $replace = false;
  106.             }
  107.             
  108.             // verify postcondition
  109.             $name = ereg_replace ("[^0-9A-Za-z_]", "", $name);
  110.                 
  111.             if ($replace) {
  112.                 $this->_attr [$name] = $val;
  113.             } else {
  114.                 if (!isset ($this->_attr [$name])) {
  115.                     $this->_attr [$name] = $val;
  116.                 }
  117.             }
  118.         } catch (Gumbo_Exception $e) {
  119.             $e->setFunction (__METHOD__);
  120.             gumbo_trigger ($e);
  121.         }
  122.     }
  123.  
  124.     /**
  125.      * Removes an attribute
  126.      * @param string $name 
  127.      * @throws Gumbo_Exception
  128.      */
  129.     public function removeAttribute ($name) {
  130.         try {
  131.             // verify precondition
  132.             if (!is_string ($name)) {
  133.                 throw new Gumbo_Exception ("Invalid Argument 'name:str' => {$name}:" . gettype ($name));
  134.             }
  135.             if (!isset ($this->_attr [$name])) {
  136.                 throw new Gumbo_Exception ("Attribute Not Found: {$name}");
  137.             }
  138.                 
  139.             unset ($this->_attr [$name]);
  140.         } catch (Gumbo_Exception $e) {
  141.             $e->setFunction (__METHOD__);
  142.             gumbo_trigger ($e);
  143.         }
  144.     }
  145.  
  146.     /**
  147.      * Adds a comment to the Composite (A null comment will add a blank line)
  148.      * @param string $comment 
  149.      * @throws Gumbo_Exception
  150.      */
  151.     public function addComment ($comment=null) {
  152.         try {
  153.             // verify precondition
  154.             if (!is_string ($comment) && !is_null ($comment)) {
  155.                 throw new Gumbo_Exception ("Invalid Argument 'comment:str|null' => {$comment}:" . gettype ($comment));
  156.             }
  157.             
  158.             $this->_comments [] = $comment;
  159.         } catch (Gumbo_Exception $e) {
  160.             $e->setFunction (__METHOD__);
  161.             gumbo_trigger ($e);
  162.         }
  163.     }
  164.  
  165.     /**
  166.      * Resets all comments
  167.      * @postcondition !getComments()
  168.      */
  169.     final public function resetComments () {
  170.         $this->_comments = array ();
  171.     }
  172.     
  173.     
  174.     
  175.     /** MUTATOR METHODS **/
  176.     /**
  177.      * Sets the Tree name
  178.      * @postcondition removes all non-alphanumeric characters (excluding underscores)
  179.      * @param int|string$name 
  180.      * @throws Gumbo_Exception
  181.      */
  182.     protected function setName ($name=null) {
  183.         if (is_null ($name)) { return; }
  184.         try {
  185.             // verify precondition
  186.             if (!is_int ($name) && !is_string ($name)) {
  187.                 throw new Gumbo_Exception ("Invalid Argument 'name:str|int' => {$name}:" . gettype ($name));
  188.             }
  189.             
  190.             $this->_name = ereg_replace ("[^0-9A-Za-z_]", "", $name);
  191.         } catch (Gumbo_Exception $e) {
  192.             $e->setFunction (__METHOD__);
  193.             gumbo_trigger ($e);
  194.         }
  195.     }
  196.     
  197.     /**
  198.      * Sets the Composite value (for Leaf use only)
  199.      * @param mixed $val (primitive types only)
  200.      * @throws Gumbo_Exception
  201.      */
  202.     public function setValue ($val) {
  203.         try {
  204.             // verify precondition
  205.             if (!is_string ($val) && !is_numeric ($val) && !is_bool ($val) && !is_null ($val)) {
  206.                 throw new Gumbo_Exception ("Invalid Argument 'val:str|num|bool|null' => {$val}:" . gettype ($val));
  207.             }
  208.             
  209.             $this->_value = $val;
  210.         } catch (Gumbo_Exception $e) {
  211.             $e->setFunction (__METHOD__);
  212.             gumbo_trigger ($e);
  213.         }
  214.     }
  215.     
  216.     
  217.     
  218.     /** ACCESSOR METHODS **/
  219.     /**
  220.      * Returns the Name
  221.      * @return int|string
  222.      */
  223.     public function getName () {
  224.         return $this->_name;
  225.     }
  226.     
  227.     /**
  228.      * Returns the Value
  229.      * @return mixed (primitive type)
  230.      */
  231.     public function getValue () {
  232.         return $this->_value;
  233.     }
  234.     
  235.     /**
  236.      * Returns an attribute value
  237.      * @param string $name 
  238.      * @return mixed (primitive values only)
  239.      * @throws Gumbo_Exception
  240.      */
  241.     final public function getAttribute ($name) {
  242.         try {
  243.             // verify precondition
  244.             if (!is_string ($name)) {
  245.                 throw new Gumbo_Exception ("Invalid Argument 'name:str' => {$name}:" . gettype ($name));
  246.             }
  247.             if (!isset ($this->_attr [$name])) {
  248.                 throw new Gumbo_Exception ("Attribute Not Found: {$name}");
  249.             }
  250.             
  251.             return $this->_attr [$name];
  252.         } catch (Gumbo_Exception $e) {
  253.             $e->setFunction (__METHOD__);
  254.             gumbo_trigger ($e);
  255.         }
  256.         return null;
  257.     }
  258.     
  259.     /**
  260.      * Returns all attributes of the Composite
  261.      * @return array 
  262.      */
  263.     final public function getAttributes () {
  264.         return $this->_attr;
  265.     }
  266.     
  267.     /**
  268.      * Returns the comments
  269.      * @return array 
  270.      */
  271.     final public function getComments () {
  272.         return $this->_comments;
  273.     }
  274.     
  275. }
  276.  
  277. ?>