Update examples

ext/spl/examples/dba_dump.php

@@ -2,63 +2,25 @@
 
 /* dba dump utility
  *
- * Usage php dba_dump <file> <handler>
+ * Usage: php dba_dump <file> <handler> [<regex>]
+ *
+ * Show all groups in the ini file specified by <file>.
+ * The regular expression <regex> is used to filter the by setting name.
  *
  * Note: configure with --enable-dba 
  *
  * (c) Marcus Boerger
  */
 
-class dba_reader implements spl_sequence_assoc
-{
-
-	private $db = NULL;
-	private $key = false;
-	private $val = false;
-
-	function __construct($file, $handler) {
-		$this->db = dba_open($file, 'r', $handler);
-	}
-	
-	function __destruct() {
-		if ($this->db) {
-			dba_close($this->db);
-		}
-	}
-
-	function rewind() {
-		if ($this->db) {
-			$this->key = dba_firstkey($this->db);
-		}
-	}
-
-	function current() {
-		return $this->val;
-	}
-
-	function next() {
-		if ($this->db) {
-			$this->key = dba_nextkey($this->db);
-			if ($this->key !== false) {
-				$this->val = dba_fetch($this->key, $this->db);
-			}
-		}
-	}
-
-	function has_more() {
-		if ($this->db && $this->key !== false) {
-			return true;
-		} else {
-			return false;
-		}
-	}
-
-	function key() {
-		return $this->key;
-	}
-}
+require_once("dba_reader.inc");
+require_once("key_filter.inc");
 
 $db = new dba_reader($argv[1], $argv[2]);
+
+if ($argc>3) {
+	$db = new key_filter($db, $argv[3]);
+}
+
 foreach($db as $key => $val) {
 	echo "'$key' => '$val'\n";
 }

ext/spl/examples/dba_reader.inc

@@ -0,0 +1,83 @@
+<?php
+
+/**
+ * @brief   This implements an dba iterator.
+ * @author  Marcus Boerger
+ * @version 1.0
+ */
+class dba_reader implements spl_sequence_assoc
+{
+
+	private $db = NULL;
+	private $key = false;
+	private $val = false;
+
+	/**
+	 * 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_open($file, 'r', $handler);
+	}
+	
+	/**
+	 * Close database.
+	 */
+	function __destruct() {
+		if ($this->db) {
+			dba_close($this->db);
+		}
+	}
+
+	/**
+	 * Rewind to first element.
+	 */
+	function rewind() {
+		if ($this->db) {
+			$this->key = dba_firstkey($this->db);
+		}
+	}
+
+	/**
+	 * @return Current data.
+	 */
+	function current() {
+		return $this->val;
+	}
+
+	/**
+	 * Move to next element.
+	 *
+	 * @return void
+	 */
+	function next() {
+		if ($this->db) {
+			$this->key = dba_nextkey($this->db);
+			if ($this->key !== false) {
+				$this->val = dba_fetch($this->key, $this->db);
+			}
+		}
+	}
+
+	/**
+	 * @return Whether more elements are available.
+	 */
+	function has_more() {
+		if ($this->db && $this->key !== false) {
+			return true;
+		} else {
+			return false;
+		}
+	}
+
+	/**
+	 * @return Current key.
+	 */
+	function key() {
+		return $this->key;
+	}
+}
+
+?>

ext/spl/examples/filter.inc

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @brief Regular expression filter for string iterators
- * @author Marcus Boerger
+ * @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

ext/spl/examples/ini_groups.php

@@ -0,0 +1,65 @@
+<?php
+
+/* List groups within an ini file
+ *
+ * Usage: php dba_dump <file> [<regex>]
+ *
+ * Show all groups in the ini file specified by <file>.
+ * The regular expression <regex> is used to filter the result.
+ *
+ * Note: configure with --enable-dba 
+ *
+ * (c) Marcus Boerger
+ */
+
+require_once("dba_reader.inc");
+require_once("key_filter.inc");
+
+/**
+ * @brief   Class to iterate all groups within an ini file.
+ * @author  Marcus Boerger
+ * @version 1.0
+ *
+ * Using this class you can iterator over all groups of a ini file.
+ * 
+ * This class uses a 'is-a' relation to key_filter in contrast to a 'has-a'
+ * relation. Doing so both current() and key() methods must be overwritten. 
+ * If it would use a 'has-a' relation there would be much more to type...
+ * but for puritists that would allow correctness in so far as then no 
+ * key() would be needed.
+ */
+class ini_groups extends key_filter
+{
+	/**
+	 * Construct an ini file group iterator from a filename.
+	 *
+	 * @param file Ini file to open.
+	 */
+	function __construct($file) {
+		parent::__construct(new dba_reader($file, 'inifile'), '^\[.*\]$');
+	}
+
+	/**
+	 * @return The current group.
+	 */
+	function current() {
+		return substr(parent::key(),1,-1);
+	}
+
+	/**
+	 * @return The current group.
+	 */
+	function key() {
+		return substr(parent::key(),1,-1);
+	}
+}
+
+$it = new ini_groups($argv[1]);
+if ($argc>2) {
+	$it = new key_filter($it, $argv[2]);
+}
+foreach($it as $group) {
+	echo "$group\n";
+}
+
+?>

ext/spl/examples/key_filter.inc

@@ -0,0 +1,102 @@
+<?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 key_filter implements spl_forward_assoc
+{
+	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
+	 * @patam regex  Regular expression used as a filter.
+	 */
+	function __construct(spl_forward $it, $regex) {
+		if ($it instanceof spl_sequence) {
+			$it->rewind();
+		}
+		$this->it = $it;
+		$this->regex = $regex;
+		$this->fetch();
+	}
+	
+	/**
+	 * 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->has_more()) {
+			$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 has_more() {
+		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 
+	}
+}
+
+?>

ext/spl/examples/sub_dir.inc

@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @brief Subdirectory aware directory iterator.
- * @author Marcus Boerger
+ * @brief   Subdirectory aware directory iterator.
+ * @author  Marcus Boerger
  * @version 1.0
  *
  * This directory iterator recursively returns all files and directories