Source for file Composite.class.php

Documentation is available at Composite.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.  * Composite Pattern Interface
  22.  * 
  23.  * The Composite Pattern is responsible for holding multi-tiered data into an
  24.  * easily accessible interface.  This would be similar to accessing the elements
  25.  * of a multi-dimensional array.  A Composite can hold other Composite objects.
  26.  * 
  27.  * Attributes
  28.  * An Attribute is simply a key=>val pair of data used to provide more details
  29.  * about a particular Composite.  The best example is an attribute inside an
  30.  * XML element.
  31.  * <pre>
  32.  * <xml id="value">data</xml>
  33.  * </pre>
  34.  * 
  35.  * Comments
  36.  * This feature is useless, unless the Composite is being used to read/write
  37.  * files with comments.  This feature will allow the object to hold comments
  38.  * for a particular Composite, which can be used by a file writer to include
  39.  * in particular parts of the file.
  40.  * 
  41.  * Look at the Tree-Branch-Leaf classes for more details on implementing a
  42.  * Composite.
  43.  *
  44.  * @category Gumbo
  45.  * @package Composite
  46.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  47.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  48.  * @author Michael Luster <mluster79@yahoo.com>
  49.  * @link http://sourceforge.net/projects/phpgumbo
  50.  * @desc Composite Pattern Interface
  51.  * @version 0.0.1
  52.  * @see Gumbo_Tree
  53.  */
  54.  
  55. interface Gumbo_Interface_Composite {
  56.     
  57.     /** OVERLOAD METHODS **/
  58.     /**
  59.      * Sets a Value, or adds a new Composite to a Branch
  60.      * @param int|string$name (for 'int', wrap in curly braces $comp->{0} = value)
  61.      * @param mixed $val 
  62.      */
  63.     public function __set ($name, $val);
  64.     
  65.     /**
  66.      * Returns the Value or a Composite referenced by the 'name'
  67.      * @param int|string$name (for 'int', wrap in curly braces $comp->{0})
  68.      * @return mixed 
  69.      */
  70.     public function __get ($name);
  71.     
  72.     
  73.     
  74.     /** ABSTRACT METHODS **/
  75.     /**
  76.      * Adds a Composite object to the Composite (for Branch use only)
  77.      * @param Gumbo_Interface_Composite $tree 
  78.      * @param bool $replace replaces the original Composite object
  79.      */
  80.     public function add (Gumbo_Interface_Composite $tree, $replace=false);
  81.     
  82.     /**
  83.      * Removes a Composite object based on the Composite name (for Branch use only)
  84.      * @param int|string$name 
  85.      */
  86.     public function remove ($name);
  87.     
  88.     
  89.     
  90.     /** ACTION METHODS **/
  91.     /**
  92.      * Adds an attribute description to the Composite object
  93.      * @postcondition remove non-alphanumeric characters (excluding underscores) from $name
  94.      * @param string $name attribute name
  95.      * @param string|num|bool$val attribute value
  96.      * @param bool $replace replaces existing attribute
  97.      */
  98.     public function addAttribute ($name, $val, $replace=false);
  99.  
  100.     /**
  101.      * Removes an attribute
  102.      * @param string $name 
  103.      */
  104.     public function removeAttribute ($name);
  105.  
  106.     /**
  107.      * Adds a comment to the Composite (A null comment will add a blank line)
  108.      * @param string $comment 
  109.      */
  110.     public function addComment ($comment=null);
  111.  
  112.     /**
  113.      * Resets all comments
  114.      * @postcondition !getComments()
  115.      */
  116.     public function resetComments ();
  117.     
  118.     
  119.     
  120.     /** MUTATOR METHODS **/
  121.     /**
  122.      * Sets the Composite value (for Leaf use only)
  123.      * @param mixed $val (primitive types only)
  124.      */
  125.     public function setValue ($val);
  126.     
  127.     
  128.     
  129.     /** ACCESSOR METHODS **/
  130.     /**
  131.      * Returns the corresponding Composite object or Value
  132.      * @param int|string$name 
  133.      * @return mixed 
  134.      */
  135.     public function get ($name=null);
  136.     
  137.     /**
  138.      * Returns the Name
  139.      * @return int|string
  140.      */
  141.     public function getName ();
  142.     
  143.     /**
  144.      * Returns the Value
  145.      * @return mixed 
  146.      */
  147.     public function getValue ();
  148.     
  149.     /**
  150.      * Returns an attribute value
  151.      * @param string $name 
  152.      * @return mixed (primitive values only)
  153.      */
  154.     public function getAttribute ($name);
  155.     
  156.     /**
  157.      * Returns all attributes of the Composite
  158.      * @return array 
  159.      */
  160.     public function getAttributes ();
  161.     
  162.     /**
  163.      * Returns all comments
  164.      * @return array 
  165.      */
  166.     public function getComments ();
  167.     
  168. }
  169.  
  170. ?>