diff options
author | Marcus Boerger <helly@php.net> | 2004-05-08 12:24:15 +0000 |
---|---|---|
committer | Marcus Boerger <helly@php.net> | 2004-05-08 12:24:15 +0000 |
commit | a6feb3f405f76f068c6a89058f3382b4ebe4d4f2 (patch) | |
tree | 418a89436f73fe362163428419c45fa573c99a44 | |
parent | 26fea0bd809a06b505d9af69e606ded18e565692 (diff) | |
download | php-git-a6feb3f405f76f068c6a89058f3382b4ebe4d4f2.tar.gz |
- Update examples
- Update documentation
- Move classes/interfaces already implemented in c to new subdir internal
27 files changed, 330 insertions, 205 deletions
diff --git a/ext/spl/examples/KeyFilter.inc b/ext/spl/examples/KeyFilter.inc deleted file mode 100755 index ba73435955..0000000000 --- a/ext/spl/examples/KeyFilter.inc +++ /dev/null @@ -1,106 +0,0 @@ -<?php - -/** - * @brief Regular expression filter for string iterators - * @author Marcus Boerger - * @version 1.0 - * - * Instances of this class act as a filter around iterators whose elements - * are strings. In other words you can put an iterator into the constructor - * and the instance will only return elements which match the given regular - * expression. - */ -class KeyFilter implements Iterator -{ - protected $it; - protected $regex; - protected $key; - protected $curr; - - /** - * Constructs a filter around an iterator whose elemnts are strings. - * If the given iterator is of type spl_sequence then its rewind() - * method is called. - * - * @param it Object that implements at least spl_forward - * @param regex Regular expression used as a filter. - */ - function __construct(Iterator $it, $regex) { - $this->it = $it; - $this->regex = $regex; - $this->fetch(); - } - - /** - * Rewind input iterator - */ - function rewind() { - $this->it->rewind(); - } - - /** - * Destruct the iterator. - */ - function __destruct() { - unset($this->it); - } - - /** - * Fetch next element and store it. - * - * @return void - */ - protected function fetch() { - $this->key = false; - $this->curr = false; - while ($this->it->valid()) { - $key = $this->it->key(); - if (ereg($this->regex, $key)) { - $this->key = $key; - $this->curr = $this->it->current(); - return; - } - $this->it->next(); - }; - } - - /** - * Move to next element - * - * @return void - */ - function next() { - $this->it->next(); - $this->fetch(); - } - - /** - * @return Whether more elements are available - */ - function valid() { - return $this->key !== false; - } - - /** - * @return The current key - */ - function key() { - return $this->key; - } - - /** - * @return The current value - */ - function current() { - return $this->curr; - } - - /** - * hidden __clone - */ - protected function __clone() { - // disallow clone - } -} - -?>
\ No newline at end of file diff --git a/ext/spl/examples/autoload.inc b/ext/spl/examples/autoload.inc index 430680645a..c2c4222f85 100755 --- a/ext/spl/examples/autoload.inc +++ b/ext/spl/examples/autoload.inc @@ -1,5 +1,8 @@ <?php +/** \internal + * Tries to load class $classname from directory $dir. + */ function __load_class($classname, $dir) { $file = $dir . '/' . $classname . '.inc'; @@ -11,6 +14,14 @@ function __load_class($classname, $dir) return false; } +/** + * @brief Class loader for SPL example classes + * @author Marcus Boerger + * @version 1.0 + * + * Loads classes automatically from include_path as given by ini or from + * current directory of script or include file. + */ function __autoload($classname) { $classname = strtolower($classname); foreach(split(':', ini_get('include_path')) as $dir) diff --git a/ext/spl/examples/dba_array.php b/ext/spl/examples/dba_array.php index 931e3cfb92..7d7a3816df 100755 --- a/ext/spl/examples/dba_array.php +++ b/ext/spl/examples/dba_array.php @@ -9,7 +9,7 @@ * * Note: configure with --enable-dba * - * (c) Marcus Boerger, 2003 + * (c) Marcus Boerger, 2003 - 2004 */ if ($argc < 4) { @@ -24,55 +24,7 @@ EOF; exit(1); } -class DbaArray implements ArrayAccess { - private $db; - - function __construct($file, $handler) - { - $this->db = dba_popen($file, "c", $handler); - if (!$this->db) { - throw new exception("Databse could not be opened"); - } - } - - function __destruct() - { - dba_close($this->db); - } - - function get($name) - { - $data = dba_fetch($name, $this->db); - if($data) { - if (ini_get('magic_quotes_runtime')) { - $data = stripslashes($data); - } - //return unserialize($data); - return $data; - } - else - { - return NULL; - } - } - - function set($name, $value) - { - //dba_replace($name, serialize($value), $this->db); - dba_replace($name, $value, $this->db); - return $value; - } - - function exists($name) - { - return dba_exists($name, $this->db); - } - - function del($name) - { - return dba_delete($name, $this->db); - } -} +if (!class_exists("DbaReader", false)) require_once("dbareader.inc"); try { if ($argc > 2) { diff --git a/ext/spl/examples/dba_dump.php b/ext/spl/examples/dba_dump.php index cdee831b0a..613674fef8 100755 --- a/ext/spl/examples/dba_dump.php +++ b/ext/spl/examples/dba_dump.php @@ -9,7 +9,7 @@ * * Note: configure with --enable-dba * - * (c) Marcus Boerger, 2003 + * (c) Marcus Boerger, 2003 - 2004 */ if ($argc < 3) { @@ -24,13 +24,13 @@ EOF; exit(1); } -require_once("dba_reader.inc"); -require_once("KeyFilter.inc"); +if (!class_exists("DbaReader")) require_once("dbareader.inc"); +if (!class_exists("KeyFilter")) require_once("keyfilter.inc"); $db = new DbaReader($argv[1], $argv[2]); if ($argc>3) { - $db = new keyFilter($db, $argv[3]); + $db = new KeyFilter($db, $argv[3]); } foreach($db as $key => $val) { diff --git a/ext/spl/examples/dbaarray.inc b/ext/spl/examples/dbaarray.inc new file mode 100755 index 0000000000..51cd38fadf --- /dev/null +++ b/ext/spl/examples/dbaarray.inc @@ -0,0 +1,89 @@ +<?php + +if (!class_exists("DbaReader")) require_once("dbareader.inc"); + +/** \ingroup Examples + * @brief This implements a DBA Array + * @author Marcus Boerger + * @version 1.0 + */ +class DbaArray extends DbaReader implements ArrayAccess +{ + + /** + * Open database $file with $handler in read only mode. + * + * @param file Database file to open. + * @param handler Handler to use for database access. + */ + function __construct($file, $handler) + { + $this->db = dba_popen($file, "c", $handler); + if (!$this->db) { + throw new exception("Databse could not be opened"); + } + } + + /** + * Close database. + */ + function __destruct() + { + parent::__destruct(); + } + + /** + * Read an entry. + * + * @param $name key to read from + * @return value associated with $name + */ + function offsetGet($name) + { + $data = dba_fetch($name, $this->db); + if($data) { + if (ini_get('magic_quotes_runtime')) { + $data = stripslashes($data); + } + //return unserialize($data); + return $data; + } + else + { + return NULL; + } + } + + /** + * Set an entry. + * + * @param $name key to write to + * @param $value value to write + */ + function offsetSet($name, $value) + { + //dba_replace($name, serialize($value), $this->db); + dba_replace($name, $value, $this->db); + return $value; + } + + /** + * @return whether key $name exists. + */ + function offsetExists($name) + { + return dba_exists($name, $this->db); + } + + /** + * Delete a key/value pair. + * + * @param $name key to delete. + */ + function offsetUnset($name) + { + return dba_delete($name, $this->db); + } +} + +?>
\ No newline at end of file diff --git a/ext/spl/examples/dba_reader.inc b/ext/spl/examples/dbareader.inc index fa8fd3d854..add4df9b1f 100755 --- a/ext/spl/examples/dba_reader.inc +++ b/ext/spl/examples/dbareader.inc @@ -1,14 +1,14 @@ <?php -/** - * @brief This implements a Dba Iterator. +/** \ingroup Examples + * @brief This implements a DBA Iterator. * @author Marcus Boerger * @version 1.0 */ class DbaReader implements Iterator { - private $db = NULL; + protected $db = NULL; private $key = false; private $val = false; diff --git a/ext/spl/examples/directoryfilterdots.inc b/ext/spl/examples/directoryfilterdots.inc index 3ca0e6a2f8..f03b4290f1 100755 --- a/ext/spl/examples/directoryfilterdots.inc +++ b/ext/spl/examples/directoryfilterdots.inc @@ -1,24 +1,48 @@ <?php +/** \ingroup Examples + * @brief A filtered DirectoryIterator + * @author Marcus Boerger + * @version 1.0 + * + * This Iteraotr takes a pathname from which it creates a DirectoryIterator + * and makes it recursive. Further more it filters the entries '.' and '..'. + */ class DirectoryFilterDots extends FilterIterator implements RecursiveIterator { - function __construct($path) { + /** Construct from a path. + * @param $path directory to iterate + */ + function __construct($path) + { parent::__construct(new DirectoryIterator($path)); } - - function accept() { + + /** @return whether the current entry is neither '.' nor '..' + */ + function accept() + { return !$this->it->isDot(); } - function hasChildren() { + /** @return whether the current entry is a directory + */ + function hasChildren() + { return $this->it->hasChildren(); } - function getChildren() { + /** @return the current subdirectory as a new DirectoryFilterDots instance. + */ + function getChildren() + { return new DirectoryFilterDots($this->it->getPathname()); } - function key() { + /** @return the current entries path name + */ + function key() + { return $this->it->getPathname(); } } diff --git a/ext/spl/examples/directorygraphiterator.inc b/ext/spl/examples/directorygraphiterator.inc deleted file mode 100644 index a8382e2baa..0000000000 --- a/ext/spl/examples/directorygraphiterator.inc +++ /dev/null @@ -1,11 +0,0 @@ -<?php - -class DirectoryGraphIterator extends DirectoryTreeIterator -{ - function __construct($path) - { - RecursiveIteratorIterator::__construct(new CachingRecursiveIterator(new ParentIterator(new RecursiveDirectoryIterator($path)), CIT_CALL_TOSTRING|CIT_CATCH_GET_CHILD), 1); - } -} - -?>
\ No newline at end of file diff --git a/ext/spl/examples/directorytree.inc b/ext/spl/examples/directorytree.inc index 218ca513d9..31c84b4af8 100755 --- a/ext/spl/examples/directorytree.inc +++ b/ext/spl/examples/directorytree.inc @@ -1,7 +1,15 @@ <?php +/** \ingroup Examples + * @brief A directory iterator that does not show '.' and '..'. + * @author Marcus Boerger + * @version 1.0 + */ class DirectoryTree extends RecursiveIteratorIterator { + /** Construct from a path. + * @param $path directory to iterate + */ function __construct($path) { parent::__construct(new DirectoryFilterDots($path)); } diff --git a/ext/spl/examples/directorytreeiterator.inc b/ext/spl/examples/directorytreeiterator.inc index 13253d9a52..4fadd6f71b 100644 --- a/ext/spl/examples/directorytreeiterator.inc +++ b/ext/spl/examples/directorytreeiterator.inc @@ -1,12 +1,22 @@ <?php +/** \ingroup Examples + * @brief DirectoryIterator to generate ASCII graphic directory trees + * @author Marcus Boerger + * @version 1.0 + */ class DirectoryTreeIterator extends RecursiveIteratorIterator { + /** Construct from a path. + * @param $path directory to iterate + */ function __construct($path) { parent::__construct(new CachingRecursiveIterator(new RecursiveDirectoryIterator($path), CIT_CALL_TOSTRING|CIT_CATCH_GET_CHILD), 1); } - + + /** @return the current element prefixed with ASCII graphics + */ function current() { $tree = ''; @@ -16,7 +26,9 @@ class DirectoryTreeIterator extends RecursiveIteratorIterator return $tree . ($this->getSubIterator($l)->hasNext() ? '|-' : '\-') . $this->getSubIterator($l)->__toString(); } - + + /** Aggregates the inner iterator + */ function __call($func, $params) { return call_user_func_array(array($this->getSubIterator(), $func), $params); diff --git a/ext/spl/examples/emptyiterator.inc b/ext/spl/examples/emptyiterator.inc index 34b5118e74..1a79173938 100755 --- a/ext/spl/examples/emptyiterator.inc +++ b/ext/spl/examples/emptyiterator.inc @@ -1,6 +1,6 @@ <?php -/** +/** \ingroup Examples * @brief An empty Iterator * @author Marcus Boerger * @version 1.0 @@ -8,26 +8,42 @@ */ class EmptyIterator implements Iterator { + /** No operation. + * @return void + */ function rewind() { // nothing to do } + /** @return \c false + */ function valid() { return false; } + /** This function must not be called. It throws an exception upon access. + * @throw Exception + * @return void + */ function current() { throw new Exception('Accessing the value of an EmptyIterator'); } + /** This function must not be called. It throws an exception upon access. + * @throw Exception + * @return void + */ function key() { throw new Exception('Accessing the key of an EmptyIterator'); } + /** No operation. + * @return void + */ function next() { // nothing to do diff --git a/ext/spl/examples/findfile.inc b/ext/spl/examples/findfile.inc index c4bce73a30..147a69b34f 100755 --- a/ext/spl/examples/findfile.inc +++ b/ext/spl/examples/findfile.inc @@ -1,15 +1,26 @@ <?php +if (!class_exists("FindFile")) require_once("findfile.inc"); +if (!class_exists("AppendIterator")) require_once("appenditerator.inc"); + /** * @brief Base class to find files * @author Marcus Boerger - * @version 1.0 + * @version 1.1 * */ class FindFile extends FilterIterator { - protected $file; + /** @internal filename to find */ + private $file; + /** Construct from path and filename + * + * @param $path the directory to search in + * If path contains ';' then this parameter is split and every + * part of it is used as separate directory. + * @param $file the name of the files to search fro + */ function __construct($path, $file) { $this->file = $file; @@ -25,10 +36,21 @@ class FindFile extends FilterIterator } } + /** @return whether the current file matches the given filename + */ function accept() { return !strcmp($this->current(), $this->file); } + + /** @return the filename to search for. + * @note This may be overloaded and contain a regular expression for an + * extended class that uses regular expressions to search. + */ + function getSearch() + { + return $this->file; + } } ?>
\ No newline at end of file diff --git a/ext/spl/examples/findregex.php b/ext/spl/examples/findregex.php index faed6a8ee0..55431c0e38 100755 --- a/ext/spl/examples/findregex.php +++ b/ext/spl/examples/findregex.php @@ -24,15 +24,10 @@ EOF; exit(1); } -class RegexFindFile extends FindFile -{ - function accept() - { - return preg_match($this->file, $this->current()); - } -} +if (!class_exists("RegexFindFile")) require_once("regexfindfile.inc"); -foreach(new RegexFindFile($argv[1], $argv[2]) as $file) { +foreach(new RegexFindFile($argv[1], $argv[2]) as $file) +{ echo $file->getPathname()."\n"; } diff --git a/ext/spl/examples/infiniteiterator.inc b/ext/spl/examples/infiniteiterator.inc index d6488750b6..ea83edb76e 100755 --- a/ext/spl/examples/infiniteiterator.inc +++ b/ext/spl/examples/infiniteiterator.inc @@ -1,6 +1,6 @@ <?php -/** +/** \ingroup Examples * @brief An infinite Iterator * @author Marcus Boerger * @version 1.0 @@ -22,38 +22,57 @@ */ class InfiniteIterator implements Iterator { + /** @internal + * The inner Iterator. */ private $it; + /** Construct from another Iterator. + * @param $it the inner Iterator. + */ function __construct(Iterator $it) { $this->it = $it; } + /** @return the inner iterator + */ function getInnerIterator() { return $this->it; } + /** Rewind the inner iterator. + * @return void + */ function rewind() { $this->it->rewind(); } + /** @return whether the current element is valid + */ function valid() { return $this->it->valid(); } + /** @return the current value + */ function current() { return $this->it->current(); } + /** @return the current key + */ function key() { return $this->it->key(); } + /** Move the inner Iterator forward to its next element or rewind it. + * @return void + */ function next() { $this->it->next(); @@ -62,6 +81,13 @@ class InfiniteIterator implements Iterator $this->it->rewind(); } } + + /** Aggregates the inner iterator + */ + function __call($func, $params) + { + return call_user_func_array(array($this->getSubIterator(), $func), $params); + } } ?>
\ No newline at end of file diff --git a/ext/spl/examples/ini_groups.php b/ext/spl/examples/ini_groups.php index 2e76752e23..81cd4012b0 100755 --- a/ext/spl/examples/ini_groups.php +++ b/ext/spl/examples/ini_groups.php @@ -24,8 +24,8 @@ EOF; exit(1); } -require_once("dba_reader.inc"); -require_once("IniGroups.inc"); +if (!class_exists("KeyFilter")) require_once("keyfilter.inc"); +if (!class_exists("IniGroups")) require_once("inigroups.inc"); $it = new IniGroups($argv[1]); if ($argc>2) { diff --git a/ext/spl/examples/IniGroups.inc b/ext/spl/examples/inigroups.inc index bb596c2717..745930643b 100755 --- a/ext/spl/examples/IniGroups.inc +++ b/ext/spl/examples/inigroups.inc @@ -1,11 +1,12 @@ <?php -require_once("KeyFilter.inc"); +if (!class_exists("KeyFilter")) require_once("keyfilter.inc"); +if (!class_exists("DbaReader")) require_once("dbareader.inc"); -/** +/** \ingroup Examples * @brief Class to iterate all groups within an ini file. * @author Marcus Boerger - * @version 1.0 + * @version 1.1 * * Using this class you can iterator over all groups of a ini file. * @@ -23,7 +24,7 @@ class IniGroups extends KeyFilter * @param file Ini file to open. */ function __construct($file) { - parent::__construct(new dba_reader($file, 'inifile'), '^\[.*\]$'); + parent::__construct(new DbaReader($file, 'inifile'), '^\[.*\]$'); } /** diff --git a/ext/spl/examples/keyfilter.inc b/ext/spl/examples/keyfilter.inc new file mode 100755 index 0000000000..0a61783817 --- /dev/null +++ b/ext/spl/examples/keyfilter.inc @@ -0,0 +1,55 @@ +<?php + +/** \ingroup Examples + * @brief Regular expression filter for string iterators + * @author Marcus Boerger + * @version 1.1 + * + * Instances of this class act as a filter around iterators whose elements + * are strings. In other words you can put an iterator into the constructor + * and the instance will only return elements which match the given regular + * expression. + */ +class KeyFilter extends FilterIterator +{ + /** @internal regular exoression used as filter */ + private $regex; + + /** + * Constructs a filter around an iterator whose elemnts are strings. + * If the given iterator is of type spl_sequence then its rewind() + * method is called. + * + * @param it Object that implements at least spl_forward + * @param regex Regular expression used as a filter. + */ + function __construct(Iterator $it, $regex) + { + parent::__construct($it); + $this->regex = $regex; + } + + /** \return whether the current key mathes the regular expression + */ + function accept() + { + return ereg($this->regex, $this->getInnerIterator()->key()); + } + + /** @return regular expression used as filter + */ + function getRegex() + { + return $this->regex; + } + + /** + * hidden __clone + */ + protected function __clone() + { + // disallow clone + } +} + +?>
\ No newline at end of file diff --git a/ext/spl/examples/searchiterator.inc b/ext/spl/examples/searchiterator.inc index a9ba9df171..c2bbbe6dea 100755 --- a/ext/spl/examples/searchiterator.inc +++ b/ext/spl/examples/searchiterator.inc @@ -1,21 +1,49 @@ <?php +/** @ingroup Examples + * @brief Iterator to search for a specific element + * @author Marcus Boerger + * @version 1.0 + * + * This extended FilterIterator stops after finding the first acceptable + * value. + */ abstract class SearchIterator extends FilterIterator { + /** @internal whether an entry was found already */ private $done = false; - function rewind() { + /** Rewind and reset so that it once again searches. + * @return void + */ + function rewind() + { parent::rewind(); $this->done = false; } - function valid() { + /** @return whether the current element is valid + * which can only happen once per iteration. + */ + function valid() + { return !$this->done && parent::valid(); } - function next() { + /** Do not move forward but instead mark as finished. + * @return void + */ + function next() + { $this->done = true; } + + /** Aggregates the inner iterator + */ + function __call($func, $params) + { + return call_user_func_array(array($this->getSubIterator(), $func), $params); + } } ?>
\ No newline at end of file diff --git a/ext/spl/examples/tree.php b/ext/spl/examples/tree.php index 9a61acf942..ce989a2c34 100755 --- a/ext/spl/examples/tree.php +++ b/ext/spl/examples/tree.php @@ -6,7 +6,7 @@ * * Simply specify the path to tree with parameter <path>. * - * (c) Marcus Boerger, 2003 + * (c) Marcus Boerger, 2003 - 2004 */ // The following line only operates on classes which are converted to c already. @@ -26,8 +26,11 @@ EOF; exit(1); } +if (!class_exists("DirectoryTreeIterator")) require_once("directorytreeiterator.inc"); + echo $argv[1]."\n"; -foreach(new DirectoryGraphIterator($argv[1]) as $file) { +foreach(new DirectoryTreeIterator($argv[1]) as $file) +{ echo $file . "\n"; } diff --git a/ext/spl/examples/cachingiterator.inc b/ext/spl/internal/cachingiterator.inc index ac2476f1f8..ac2476f1f8 100644..100755 --- a/ext/spl/examples/cachingiterator.inc +++ b/ext/spl/internal/cachingiterator.inc diff --git a/ext/spl/examples/cachingrecursiveiterator.inc b/ext/spl/internal/cachingrecursiveiterator.inc index fc7d9a7220..fc7d9a7220 100644..100755 --- a/ext/spl/examples/cachingrecursiveiterator.inc +++ b/ext/spl/internal/cachingrecursiveiterator.inc diff --git a/ext/spl/examples/filteriterator.inc b/ext/spl/internal/filteriterator.inc index 7040c4bef9..7040c4bef9 100755 --- a/ext/spl/examples/filteriterator.inc +++ b/ext/spl/internal/filteriterator.inc diff --git a/ext/spl/examples/limititerator.inc b/ext/spl/internal/limititerator.inc index 9a87f6874f..9a87f6874f 100755 --- a/ext/spl/examples/limititerator.inc +++ b/ext/spl/internal/limititerator.inc diff --git a/ext/spl/examples/parentiterator.inc b/ext/spl/internal/parentiterator.inc index 4b758132ac..4b758132ac 100644..100755 --- a/ext/spl/examples/parentiterator.inc +++ b/ext/spl/internal/parentiterator.inc diff --git a/ext/spl/examples/recursiveiterator.inc b/ext/spl/internal/recursiveiterator.inc index 63523ffad9..63523ffad9 100644..100755 --- a/ext/spl/examples/recursiveiterator.inc +++ b/ext/spl/internal/recursiveiterator.inc diff --git a/ext/spl/examples/recursiveiteratoriterator.inc b/ext/spl/internal/recursiveiteratoriterator.inc index 05e31df464..05e31df464 100755 --- a/ext/spl/examples/recursiveiteratoriterator.inc +++ b/ext/spl/internal/recursiveiteratoriterator.inc diff --git a/ext/spl/examples/seekableiterator.inc b/ext/spl/internal/seekableiterator.inc index 3012155771..3012155771 100755 --- a/ext/spl/examples/seekableiterator.inc +++ b/ext/spl/internal/seekableiterator.inc |