Merge pull request #944 from dawnbreak/docu

Correcting reported Doxygen syntax warnings.

1 files changed, 271 insertions, 269 deletions

diff --git a/include/template_processor.php b/include/template_processor.php
index 74acc9c67..d2bf283e3 100755
--- a/include/template_processor.php
+++ b/include/template_processor.php
@@ -1,305 +1,307 @@
 <?php
-	require_once 'include/ITemplateEngine.php';
-
-	define ("KEY_NOT_EXISTS", '^R_key_not_Exists^');
-
-	class Template implements ITemplateEngine {
-		static $name ="internal";
-	
-		var $r;
-		var $search;
-		var $replace;
-		var $stack = array();
-		var $nodes = array();
-		var $done = false;
-		var $d = false;
-		var $lang = null;
-		var $debug=false;
-		
-		private function _preg_error(){
-			
-			switch(preg_last_error()){
-			    case PREG_INTERNAL_ERROR: echo('PREG_INTERNAL_ERROR'); break;
-			    case PREG_BACKTRACK_LIMIT_ERROR: echo('PREG_BACKTRACK_LIMIT_ERROR'); break;
-			    case PREG_RECURSION_LIMIT_ERROR: echo('PREG_RECURSION_LIMIT_ERROR'); break;
-			    case PREG_BAD_UTF8_ERROR: echo('PREG_BAD_UTF8_ERROR'); break;
+require_once 'include/ITemplateEngine.php';
+
+define ("KEY_NOT_EXISTS", '^R_key_not_Exists^');
+
+class Template implements ITemplateEngine {
+	static $name ="internal";
+
+	var $r;
+	var $search;
+	var $replace;
+	var $stack = array();
+	var $nodes = array();
+	var $done = false;
+	var $d = false;
+	var $lang = null;
+	var $debug=false;
+
+	private function _preg_error() {
+		switch(preg_last_error()) {
+			case PREG_INTERNAL_ERROR: echo('PREG_INTERNAL_ERROR'); break;
+			case PREG_BACKTRACK_LIMIT_ERROR: echo('PREG_BACKTRACK_LIMIT_ERROR'); break;
+			case PREG_RECURSION_LIMIT_ERROR: echo('PREG_RECURSION_LIMIT_ERROR'); break;
+			case PREG_BAD_UTF8_ERROR: echo('PREG_BAD_UTF8_ERROR'); break;
 // This is only valid for php > 5.3, not certain how to code around it for unit tests
-//			    case PREG_BAD_UTF8_OFFSET_ERROR: echo('PREG_BAD_UTF8_OFFSET_ERROR'); break;
-			    default:
-					//die("Unknown preg error.");
-					return;
-			}
-			echo "<hr><pre>";
-			debug_print_backtrace();
-			die();
+//			case PREG_BAD_UTF8_OFFSET_ERROR: echo('PREG_BAD_UTF8_OFFSET_ERROR'); break;
+			default:
+				//die("Unknown preg error.");
+				return;
 		}
-		
-		
-		private function _push_stack(){
-			$this->stack[] = array($this->r, $this->nodes);
-		}
-		private function _pop_stack(){
-			list($this->r, $this->nodes) = array_pop($this->stack);
-			
-		}
-		
-		private function _get_var($name, $retNoKey=false){
-			$keys = array_map('trim',explode(".",$name));
-			if ($retNoKey && !array_key_exists($keys[0], $this->r)) return KEY_NOT_EXISTS;
-			$val = $this->r;
-			foreach($keys as $k) {
-				$val = (isset($val[$k]) ? $val[$k] : null);
-			}
-			return template_escape($val);
+		echo "<hr><pre>";
+		debug_print_backtrace();
+		die();
+	}
+
+	private function _push_stack() {
+		$this->stack[] = array($this->r, $this->nodes);
+	}
+
+	private function _pop_stack(){
+		list($this->r, $this->nodes) = array_pop($this->stack);
+	}
+
+	private function _get_var($name, $retNoKey=false) {
+		$keys = array_map('trim',explode(".",$name));
+		if ($retNoKey && !array_key_exists($keys[0], $this->r))
+			return KEY_NOT_EXISTS;
+
+		$val = $this->r;
+		foreach($keys as $k) {
+			$val = (isset($val[$k]) ? $val[$k] : null);
 		}
-		
-		/**
-		 * IF node
-		 * 
-		 * {{ if <$var> }}...[{{ else }} ...] {{ endif }}
-		 * {{ if <$var>==<val|$var> }}...[{{ else }} ...]{{ endif }}
-		 * {{ if <$var>!=<val|$var> }}...[{{ else }} ...]{{ endif }}
-		 */
-		private function _replcb_if($args){
-			if (strpos($args[2],"==")>0){
-				list($a,$b) = array_map("trim",explode("==",$args[2]));
-				$a = $this->_get_var($a);
-				if ($b[0]=="$") $b =  $this->_get_var($b);
-				$val = ($a == $b);
-			} else if (strpos($args[2],"!=")>0){
-				list($a,$b) = array_map("trim", explode("!=",$args[2]));
-				$a = $this->_get_var($a);
-				if ($b[0]=="$") $b =  $this->_get_var($b);
-				$val = ($a != $b);
-			} else {
-				$val = $this->_get_var($args[2]);
-			}
-			$x = preg_split("|{{ *else *}}|", $args[3]);
-			return ( ($val) ? $x[0] : (isset($x[1]) ? $x[1] : ""));
+
+		return template_escape($val);
+	}
+
+	/**
+	 * IF node
+	 * \code
+	 * {{ if <$var> }}...[{{ else }} ...] {{ endif }}
+	 * {{ if <$var>==<val|$var> }}...[{{ else }} ...]{{ endif }}
+	 * {{ if <$var>!=<val|$var> }}...[{{ else }} ...]{{ endif }}
+	 * \endcode
+	 */
+	private function _replcb_if($args) {
+		if (strpos($args[2],"==")>0){
+			list($a,$b) = array_map("trim",explode("==",$args[2]));
+			$a = $this->_get_var($a);
+			if ($b[0]=="$") $b =  $this->_get_var($b);
+			$val = ($a == $b);
+		} else if (strpos($args[2],"!=")>0){
+			list($a,$b) = array_map("trim", explode("!=",$args[2]));
+			$a = $this->_get_var($a);
+			if ($b[0]=="$") $b =  $this->_get_var($b);
+			$val = ($a != $b);
+		} else {
+			$val = $this->_get_var($args[2]);
 		}
-		
-		/**
-		 * FOR node
-		 * 
-		 * {{ for <$var> as $name }}...{{ endfor }}
-		 * {{ for <$var> as $key=>$name }}...{{ endfor }}
-		 */
-		private function _replcb_for($args){
-			$m = array_map('trim', explode(" as ", $args[2]));
-			$x = explode("=>",$m[1]);
-			if (count($x) == 1) {
-				$varname = $x[0];
-				$keyname = "";
-			} else {
-				list($keyname, $varname) = $x;
-			}
-			if ($m[0]=="" || $varname=="" || is_null($varname)) die("template error: 'for ".$m[0]." as ".$varname."'") ;
-			//$vals = $this->r[$m[0]];
-			$vals = $this->_get_var($m[0]);
-			$ret="";
-			if (!is_array($vals)) return $ret; 
-			foreach ($vals as $k=>$v){
-				$this->_push_stack();
-				$r = $this->r;
-				$r[$varname] = $v;
-				if ($keyname!='') $r[$keyname] = (($k === 0) ? '0' : $k);
-				$ret .=  $this->replace($args[3], $r);
-				$this->_pop_stack();
-			}
-			return $ret;
+		$x = preg_split("|{{ *else *}}|", $args[3]);
+
+		return ( ($val) ? $x[0] : (isset($x[1]) ? $x[1] : ""));
+	}
+
+	/**
+	 * FOR node
+	 * \code
+	 * {{ for <$var> as $name }}...{{ endfor }}
+	 * {{ for <$var> as $key=>$name }}...{{ endfor }}
+	 * \endcode
+	 */
+	private function _replcb_for($args) {
+		$m = array_map('trim', explode(" as ", $args[2]));
+		$x = explode("=>",$m[1]);
+		if (count($x) == 1) {
+			$varname = $x[0];
+			$keyname = "";
+		} else {
+			list($keyname, $varname) = $x;
 		}
+		if ($m[0]=="" || $varname=="" || is_null($varname)) die("template error: 'for ".$m[0]." as ".$varname."'") ;
+		//$vals = $this->r[$m[0]];
+		$vals = $this->_get_var($m[0]);
+		$ret="";
+		if (!is_array($vals)) return $ret;
 
-		/**
-		 * INC node
-		 * 
-		 * {{ inc <templatefile> [with $var1=$var2] }}{{ endinc }}
-		 */
-		private function _replcb_inc($args){
-			if (strpos($args[2],"with")) {
-				list($tplfile, $newctx) = array_map('trim', explode("with",$args[2]));
-			} else {
-				$tplfile = trim($args[2]);
-				$newctx = null;
-			}
-			
-			if ($tplfile[0]=="$") $tplfile = $this->_get_var($tplfile);
-			
+		foreach ($vals as $k=>$v){
 			$this->_push_stack();
 			$r = $this->r;
-			if (!is_null($newctx)) {
-				list($a,$b) = array_map('trim', explode("=",$newctx));
-				$r[$a] = $this->_get_var($b); 
-			}
-			$this->nodes = Array();
-			$tpl = get_markup_template($tplfile);
-			$ret = $this->replace($tpl, $r);
+			$r[$varname] = $v;
+			if ($keyname!='') $r[$keyname] = (($k === 0) ? '0' : $k);
+			$ret .=  $this->replace($args[3], $r);
 			$this->_pop_stack();
-			return $ret;
-			
 		}
-		
-		/**
-		 * DEBUG node
-		 * 
-		 * {{ debug $var [$var [$var [...]]] }}{{ enddebug }}
-		 * 
-		 * replace node with <pre>var_dump($var, $var, ...);</pre>
-		 */
-		private function _replcb_debug($args){
-			$vars = array_map('trim', explode(" ",$args[2]));
-			$vars[] = $args[1];
-
-			$ret = "<pre>";
-			foreach ($vars as $var){
-				$ret .= htmlspecialchars(var_export( $this->_get_var($var), true ));
-				$ret .= "\n";
-			}
-			$ret .= "</pre>";
-			return $ret;
+
+		return $ret;
+	}
+
+	/**
+	 * INC node
+	 * \code
+	 * {{ inc <templatefile> [with $var1=$var2] }}{{ endinc }}
+	 * \endcode
+	 */
+	private function _replcb_inc($args) {
+		if (strpos($args[2],"with")) {
+			list($tplfile, $newctx) = array_map('trim', explode("with",$args[2]));
+		} else {
+			$tplfile = trim($args[2]);
+			$newctx = null;
 		}
 
-		private function _replcb_node($m) {
-			$node = $this->nodes[$m[1]];
-			if (method_exists($this, "_replcb_".$node[1])){
-				$s = call_user_func(array($this, "_replcb_".$node[1]),  $node);
-			} else {
-				$s = "";
-			}
-			$s = preg_replace_callback('/\|\|([0-9]+)\|\|/', array($this, "_replcb_node"), $s);
-			return $s;
+		if ($tplfile[0]=="$") $tplfile = $this->_get_var($tplfile);
+
+		$this->_push_stack();
+		$r = $this->r;
+		if (!is_null($newctx)) {
+			list($a,$b) = array_map('trim', explode("=",$newctx));
+			$r[$a] = $this->_get_var($b); 
+		}
+		$this->nodes = Array();
+		$tpl = get_markup_template($tplfile);
+		$ret = $this->replace($tpl, $r);
+		$this->_pop_stack();
+
+		return $ret;
+	}
+
+	/**
+	 * DEBUG node
+	 * \code
+	 * {{ debug $var [$var [$var [...]]] }}{{ enddebug }}
+	 * \endcode
+	 * replace node with <pre>var_dump($var, $var, ...);</pre>
+	 */
+	private function _replcb_debug($args) {
+		$vars = array_map('trim', explode(" ",$args[2]));
+		$vars[] = $args[1];
+
+		$ret = "<pre>";
+		foreach ($vars as $var){
+			$ret .= htmlspecialchars(var_export( $this->_get_var($var), true ));
+			$ret .= "\n";
 		}
-						
-		private function _replcb($m){
-			//var_dump(array_map('htmlspecialchars', $m));
-			$this->done = false;	
-			$this->nodes[] = (array) $m;
-			return "||". (count($this->nodes)-1) ."||";
+		$ret .= "</pre>";
+
+		return $ret;
+	}
+
+	private function _replcb_node($m) {
+		$node = $this->nodes[$m[1]];
+		if (method_exists($this, "_replcb_".$node[1])){
+			$s = call_user_func(array($this, "_replcb_".$node[1]),  $node);
+		} else {
+			$s = "";
 		}
-		
-		private function _build_nodes($s){
-			$this->done = false;
-			while (!$this->done){
-				$this->done=true;
-				$s = preg_replace_callback('|{{ *([a-z]*) *([^}]*)}}([^{]*({{ *else *}}[^{]*)?){{ *end\1 *}}|', array($this, "_replcb"), $s);
-				if ($s==Null) $this->_preg_error();
-			}
-			//({{ *else *}}[^{]*)?
-			krsort($this->nodes);
-			return $s;
+		$s = preg_replace_callback('/\|\|([0-9]+)\|\|/', array($this, "_replcb_node"), $s);
+
+		return $s;
+	}
+
+	private function _replcb($m) {
+		//var_dump(array_map('htmlspecialchars', $m));
+		$this->done = false;
+		$this->nodes[] = (array) $m;
+
+		return "||". (count($this->nodes)-1) ."||";
+	}
+
+	private function _build_nodes($s) {
+		$this->done = false;
+		while (!$this->done) {
+			$this->done=true;
+			$s = preg_replace_callback('|{{ *([a-z]*) *([^}]*)}}([^{]*({{ *else *}}[^{]*)?){{ *end\1 *}}|', array($this, "_replcb"), $s);
+			if ($s==Null) $this->_preg_error();
 		}
-		
-
-		private function var_replace($s){
-			$m = array();
-			/** regexp:
-			 * \$ 						literal $
-			 * (\[)?					optional open square bracket
-			 * ([a-zA-Z0-9-_]+\.?)+		var name, followed by optional
-			 * 							dot, repeated at least 1 time
-			 * (?(1)\])					if there was opened square bracket
-			 * 							(subgrup 1), match close bracket
-			 */
-			if (preg_match_all('/\$(\[)?([a-zA-Z0-9-_]+\.?)+(?(1)\])/', $s,$m)){
-					foreach($m[0] as $var){
-
-              $exp = str_replace(array("[", "]"), array("", ""), $var);
-                $exptks = explode("|", $exp);
-
-                $varn = $exptks[0];
-                unset($exptks[0]);
-                $val = $this->_get_var($varn, true);
-                if ($val != KEY_NOT_EXISTS) {
-                    /* run filters */
-                    /*
-                     * Filter are in form of:
-                     * filtername:arg:arg:arg
-                     *
-                     * "filtername" is function name
-                     * "arg"s are optional, var value is appended to the end
-                     *          if one "arg"==='x' , is replaced with var value
-                     *
-                     * examples:
-                     * $item.body|htmlspecialchars              // escape html chars
-                     * $item.body|htmlspecialchars|strtoupper   // escape html and uppercase result
-                     * $item.created|date:%Y %M %j              // format date (created is a timestamp)
-                     * $item.body|str_replace:cat:dog           // replace all "cat" with "dog"
-                     * $item.body|str_replace:cat:dog:x:1       // replace one "cat" with "dog"
-
-                     */
-                    foreach ($exptks as $filterstr) {
-                        $filter = explode(":", $filterstr);
-                        $filtername = $filter[0];
-                        unset($filter[0]);
-                        $valkey = array_search("x", $filter);
-                        if ($valkey === false) {
-                            $filter[] = $val;
-                        } else {
-                            $filter[$valkey] = $val;
-                        }
-                        if (function_exists($filtername)) {
-                            $val = call_user_func_array($filtername, $filter);
-                        }
-                    }
-                    $s = str_replace($var, $val, $s);
+		//({{ *else *}}[^{]*)?
+		krsort($this->nodes);
+
+		return $s;
+	}
 
+	private function var_replace($s) {
+		$m = array();
+		/** regexp:
+		 * \$ 						literal $
+		 * (\[)?					optional open square bracket
+		 * ([a-zA-Z0-9-_]+\.?)+		var name, followed by optional
+		 * 							dot, repeated at least 1 time
+		 * (?(1)\])					if there was opened square bracket
+		 * 							(subgrup 1), match close bracket
+		 */
+		if (preg_match_all('/\$(\[)?([a-zA-Z0-9-_]+\.?)+(?(1)\])/', $s,$m)) {
+			foreach ($m[0] as $var) {
+				$exp = str_replace(array("[", "]"), array("", ""), $var);
+				$exptks = explode("|", $exp);
+
+				$varn = $exptks[0];
+				unset($exptks[0]);
+				$val = $this->_get_var($varn, true);
+				if ($val != KEY_NOT_EXISTS) {
+					/* run filters */
+					/*
+					 * Filter are in form of:
+					 * filtername:arg:arg:arg
+					 *
+					 * "filtername" is function name
+					 * "arg"s are optional, var value is appended to the end
+					 *          if one "arg"==='x' , is replaced with var value
+					 *
+					 * examples:
+					 * $item.body|htmlspecialchars              // escape html chars
+					 * $item.body|htmlspecialchars|strtoupper   // escape html and uppercase result
+					 * $item.created|date:%Y %M %j              // format date (created is a timestamp)
+					 * $item.body|str_replace:cat:dog           // replace all "cat" with "dog"
+					 * $item.body|str_replace:cat:dog:x:1       // replace one "cat" with "dog"
+					 */
+					foreach ($exptks as $filterstr) {
+						$filter = explode(":", $filterstr);
+						$filtername = $filter[0];
+						unset($filter[0]);
+						$valkey = array_search("x", $filter);
+						if ($valkey === false) {
+							$filter[] = $val;
+						} else {
+							$filter[$valkey] = $val;
+						}
+						if (function_exists($filtername)) {
+							$val = call_user_func_array($filtername, $filter);
+						}
 					}
+					$s = str_replace($var, $val, $s);
 				}
 			}
-			
-			return $s;
-		}
-		
-		private function replace($s,$r) {
-			$this->replace_macros($s, $r);
-		}
-		
-		// TemplateEngine interface
-		public function replace_macros($s, $r) {
-			$this->r = $r;
-			
-			$s = $this->_build_nodes($s);
-
-			$s = preg_replace_callback('/\|\|([0-9]+)\|\|/', array($this, "_replcb_node"), $s);
-			if ($s==Null) $this->_preg_error();
-			
-			// remove comments block
-			$s = preg_replace('/{#[^#]*#}/', "" , $s);
-			
-			$t2 = dba_timer();
-
-			// replace strings recursively (limit to 10 loops)
-			$os = ""; $count=0;
-			while(($os !== $s) && $count<10){
-				$os=$s; $count++;
-				$s = $this->var_replace($s);
-			}
-			return $s;
 		}
 
-		public function get_markup_template($file, $root='') {
-			$template_file = theme_include($file, $root);
-			if ($template_file) {
-				$content = file_get_contents($template_file);
-			}
-			return $content;		
-		}			
+		return $s;
 	}
-	
 
+	private function replace($s, $r) {
+		$this->replace_macros($s, $r);
+	}
 
+	// TemplateEngine interface
+	public function replace_macros($s, $r) {
+		$this->r = $r;
 
+		$s = $this->_build_nodes($s);
 
-function template_escape($s) {
+		$s = preg_replace_callback('/\|\|([0-9]+)\|\|/', array($this, "_replcb_node"), $s);
+		if ($s == Null)
+			$this->_preg_error();
 
-	return str_replace(array('$','{{'),array('!_Doll^Ars1Az_!','!_DoubLe^BraceS4Rw_!'),$s);
+		// remove comments block
+		$s = preg_replace('/{#[^#]*#}/', "" , $s);
 
+		//$t2 = dba_timer();
 
-}
+		// replace strings recursively (limit to 10 loops)
+		$os = "";
+		$count=0;
+		while (($os !== $s) && $count<10) {
+			$os=$s;
+			$count++;
+			$s = $this->var_replace($s);
+		}
 
-function template_unescape($s) {
+		return $s;
+	}
 
-	return str_replace(array('!_Doll^Ars1Az_!','!_DoubLe^BraceS4Rw_!'),array('$','{{'),$s);
+	public function get_markup_template($file, $root='') {
+		$template_file = theme_include($file, $root);
+		if ($template_file) {
+			$content = file_get_contents($template_file);
+		}
 
+		return $content;
+	}
+}
 
 
+function template_escape($s) {
+	return str_replace(array('$','{{'),array('!_Doll^Ars1Az_!','!_DoubLe^BraceS4Rw_!'),$s);
+}
+
+function template_unescape($s) {
+	return str_replace(array('!_Doll^Ars1Az_!','!_DoubLe^BraceS4Rw_!'),array('$','{{'),$s);
 }