Updated code comments for PHPDocumentor - XmlQueryParser, QueryParser, DBParser

git-svn-id: http://xe-core.googlecode.com/svn/branches/luminous@12417 201d5d3c-b55e-5fd7-737f-ddc643e51545

classes/xml/XmlQueryParser.150.class.php

@@ -43,7 +43,7 @@ if(!defined('__XE_LOADED_XML_CLASS__')){
  * Parses XE XML query files
  *
  * @author Corina Udrescu (corina.udrescu@arnia.ro)
- * @package dbclasses
+ * @package /classes/xml
  */
 class XmlQueryParser extends XmlParser {
 

classes/xml/xmlquery/DBParser.class.php

@@ -1,35 +1,62 @@
 <?php
 /**
-	 * DBParser class
+ * File containing the DBParser class
-	 * @author NHN (developers@xpressengine.com)
-	 * @package /classes/xml/xmlquery
-	 * @version 0.1
  */
-	class DBParser {
+/**
+ * Escapes query statements:
+ *  - column names: member.member_srl => "member"."member_srl"
+ *  - expressions: SUM(member.member_srl) => SUM("member"."member_srl")
+ *
+ * @author Corina Udrescu (corina.udrescu@arnia.ro)
+ * @package /classes/xml/xmlquery
+ */
+class DBParser
+{
 	/**
 	 * Character for escape target value on the left
+	 *
+	 * For example, in CUBRID left and right escape
+	 * chars are the same, the double quote - "
+	 * But for SQL Server, the escape is made with
+	 * [double brackets], so the left and right char differ
+	 *
+	 *
 	 * @var string
 	 */
 	var $escape_char_left;
+
 	/**
 	 * Character for escape target value on the right
+	 *
+	 * For example, in CUBRID left and right escape
+	 * chars are the same, the double quote - "
+	 * But for SQL Server, the escape is made with
+	 * [double brackets], so the left and right char differ
+	 *
 	 * @var string
 	 */
 	var $escape_char_right;
+
 	/**
 	 * Table prefix string
+	 *
+	 * Default is "xe_"
+	 *
 	 * @var string
 	 */
 	var $table_prefix;
 
 	/**
-		 * constructor
+	 * Constructor
+	 *
 	 * @param string $escape_char_left
 	 * @param string $escape_char_right
 	 * @param string $table_prefix
+	 *
 	 * @return void
 	 */
-		function DBParser($escape_char_left,  $escape_char_right = "", $table_prefix = "xe_"){
+	function DBParser($escape_char_left,  $escape_char_right = "", $table_prefix = "xe_")
+	{
 		$this->escape_char_left = $escape_char_left;
 		if ($escape_char_right !== "")$this->escape_char_right = $escape_char_right;
 		else $this->escape_char_right = $escape_char_left;
@@ -41,35 +68,39 @@
 	 * @param string $leftOrRight left or right
 	 * @return string
 	 */
-		function getEscapeChar($leftOrRight){
+	function getEscapeChar($leftOrRight)
+	{
 		if ($leftOrRight === 'left')return $this->escape_char_left;
 		else return $this->escape_char_right;
 	}
 
 	/**
-		 * escape the value
+	 * Escape the value
 	 * @param mixed $name
 	 * @return string
 	 */
-		function escape($name){
+	function escape($name)
+	{
 		return $this->escape_char_left . $name . $this->escape_char_right;
 	}
 
 	/**
-		 * escape the string value
+	 * Escape the string value
 	 * @param string $name
 	 * @return string
 	 */
-		function escapeString($name){
+	function escapeString($name)
+	{
 		return "'".$this->escapeStringValue($name)."'";
 	}
 
 	/**
-		 * escape the string value
+	 * Escape the string value
 	 * @param string $value
 	 * @return string
 	 */
-		function escapeStringValue($value){
+	function escapeStringValue($value)
+	{
 		if($value == "*")	return $value;
 		if (is_string($value))	return $value = str_replace("'","''",$value);
 		return $value;
@@ -77,28 +108,36 @@
 
 	/**
 	 * Return table full name
+	 *
 	 * @param string $name table name without table prefix
+	 *
 	 * @return string table full name with table prefix
 	 */
-		function parseTableName($name){
+	function parseTableName($name)
+	{
 		return $this->table_prefix . $name;
 	}
 
 	/**
-		 * Return colmun name after escape
+	 * Return column name after escape
+	 *
 	 * @param string $name column name before escape
+	 *
 	 * @return string column name after escape
 	 */
-		function parseColumnName($name){
+	function parseColumnName($name)
+	{
 		return $this->escapeColumn($name);
 	}
 
 	/**
-		 * Escape column
+	 * Escape column name
+	 *
 	 * @param string $column_name
 	 * @return string column name with db name
 	 */
-		function escapeColumn($column_name){
+	function escapeColumn($column_name)
+	{
 		if($this->isUnqualifiedColumnName($column_name))
 			return $this->escape($column_name);
 		if($this->isQualifiedColumnName($column_name)){
@@ -110,26 +149,50 @@
 	}
 
 	/**
-		 * Column name is suitable for use in checking
+	 * Checks to see if a given column name is unqualified
+	 *
+	 * Ex: "member_srl"           -> unqualified
+	 *     "member"."member_srl"  -> qualified
+	 *
 	 * @param string $column_name
 	 * @return bool
 	 */
-		function isUnqualifiedColumnName($column_name){
+	function isUnqualifiedColumnName($column_name)
-			if(strpos($column_name,'.')===false && strpos($column_name,'(')===false) return true;
+	{
-			return false;	
+		if(strpos($column_name,'.')===FALSE && strpos($column_name,'(')===FALSE) return TRUE;
+		return FALSE;
 	}
 
 	/**
-		 * Column name is suitable for use in checking
+	 * Checks to see if a given column name is qualified
+	 *
+	 * Ex: "member_srl"           -> unqualified
+	 *     "member"."member_srl"  -> qualified
+	 *
 	 * @param string $column_name
 	 * @return bool
 	 */
-		function isQualifiedColumnName($column_name){
+	function isQualifiedColumnName($column_name)
-			if(strpos($column_name,'.')!==false && strpos($column_name,'(')===false) return true;
+	{
-			return false;		
+		if(strpos($column_name,'.')!==FALSE && strpos($column_name,'(')===FALSE) return TRUE;
+		return FALSE;
 	}
 
-		function parseExpression($column_name){
+	/**
+	 * Escapes a query expression
+	 *
+	 * This can be:
+	 *  - a column name: "member_srl" or "xe_member"."member_srl"
+	 *  - an expression:
+	 *        - LEFT(UPPER("content"))
+	 *        - readed_count + voted_count
+	 *        - CAST(regdate as DATE)
+	 *
+	 * @param $column_name
+	 * @return string
+	 */
+	function parseExpression($column_name)
+	{
 		$functions = preg_split('/([\+\-\*\/\ ])/', $column_name, -1, PREG_SPLIT_DELIM_CAPTURE|PREG_SPLIT_NO_EMPTY);
 		foreach($functions as $k => $v){
 			$function = &$functions[$k];
@@ -141,7 +204,7 @@
 			foreach($matches as $i => $j){
 				$match = &$matches[$i];
 				if($match == '(') {$brackets++; continue;}
-					if(strpos($match,')') !== false) continue;
+				if(strpos($match,')') !== FALSE) continue;
 				if(in_array($match, array(',', '.'))) continue;
 				if($brackets == $total_brackets){
 					if(!is_numeric($match) && !in_array(strtoupper($match), array('UNSIGNED', 'INTEGER', 'AS'))) {
@@ -154,38 +217,44 @@
 		return implode('', $functions);
 	}
 
-		/*
+	/**
-		 * Checks argument is asterisk
+	 * Checks if a given argument is an asterisk
+	 *
 	 * @param string $column_name
 	 * @return bool
 	 */
-		function isStar($column_name){
+	function isStar($column_name)
-			if(substr($column_name,-1) == '*') return true;
+	{
-			return false;
+		if(substr($column_name,-1) == '*') return TRUE;
+		return FALSE;
 	}
 
-		/*
+	/**
 	 * Checks to see if expression is an aggregate star function
 	 * like count(*)
+	 *
 	 * @param string $column_name
 	 * @return bool
 	 */
-		function isStarFunction($column_name){
+	function isStarFunction($column_name)
-			if(strpos($column_name, "(*)")!==false) return true;
+	{
-			return false;
+		if(strpos($column_name, "(*)")!==FALSE) return TRUE;
+		return FALSE;
 	}
 
-		/*
+	/**
 	 * Return column name after escape
 	 * @param string $column_name
 	 * @return string
 	 */
-		function escapeColumnExpression($column_name){
+	function escapeColumnExpression($column_name)
+	{
 		if($this->isStar($column_name)) return $column_name;
-			if($this->isStarFunction($column_name)){
+		if($this->isStarFunction($column_name))
+		{
 			return $column_name;
 		}
-			if(strpos(strtolower($column_name), 'distinct') !== false) return $column_name;
+		if(strpos(strtolower($column_name), 'distinct') !== FALSE) return $column_name;
 		return $this->escapeColumn($column_name);
 	}
 }

classes/xml/xmlquery/QueryParser.class.php

@@ -1,30 +1,43 @@
 <?php
 /**
-	 * QueryParser class
+ * File containing the QueryParser class
-	 * @author NHN (developers@xpressengine.com)
+ */
+/**
+ * Parses an XML Object and returns a string used for generating the PHP cache file
+ * The XML Object structure must be the one defined in the XmlParser class
+ *
+ * @author Corina Udrescu (corina.udrescu@arnia.ro)
  * @package /classes/xml/xmlquery
-	 * @version 0.1
  */
 class QueryParser {
+
 	/**
-		 * QueryTag object
+	 * Property containing the associated QueryTag object
 	 * @var QueryTag object
 	 */
 	var $queryTag;
 
 	/**
-		 * constructor
+	 * Constructor
-		 * @param object $query
+	 *
+	 * @param object $query XML object obtained after reading the XML Query file
 	 * @param bool $isSubQuery
 	 * @return void
 	 */
-        function QueryParser($query = NULL, $isSubQuery = false) {
+	function QueryParser($query = NULL, $isSubQuery = FALSE)
+	{
 		if ($query)
+		{
 			$this->queryTag = new QueryTag($query, $isSubQuery);
 		}
+	}
 
 	/**
 	 * Return table information
+	 * Used for finding column type info (string/numeric)
+	 *
+	 * Obtains the table info from XE's XML schema files
+	 *
 	 * @param object $query_id
 	 * @param bool $table_name
 	 * @return array
@@ -78,7 +91,8 @@
 	}
 
 	/**
-		 * Change code string from queryTag object
+	 * Returns the contents for the query cache file
+	 *
 	 * @return string
 	 */
 	function toString() {