From 4fddcdf30f88a639eb286a9d5eed609d1620b8dc Mon Sep 17 00:00:00 2001
From: David <david@xagasoft.com>
Date: Mon, 23 May 2011 21:08:08 +0000
Subject: david - added documentation to phpgats

---
 php/phpgats.php | 231 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 226 insertions(+), 5 deletions(-)

(limited to 'php/phpgats.php')

diff --git a/php/phpgats.php b/php/phpgats.php
index 188dbc0..68ab82b 100644
--- a/php/phpgats.php
+++ b/php/phpgats.php
@@ -1,29 +1,67 @@
 <?php
 
-/*
- * @function phpgats_parseGats( $str_data (string) );
- * @returns gats element
+/** @mainpage phpgats.php PHP Gats Library
+ * @section Notes
+ *
+ * This library requires that php be built with the The GNU Multiple Precision Arithmetic Library (GMP)
+ *
+ * @section Usage
+ *
+ * function phpgats_parseGats( $str_data (string) );
+ * returns phpgats_Element
  *
- * @function phpgats_writeGats( $elem (phpgats_Element subclass) );
- * @returns binary encoded gats string
+ * function phpgats_writeGats( $elem (phpgats_Element) );
+ * returns binary encoded gats string
+ *
+ * @section Types
+ *
+ * phpgats_Element - Base Class for all phpgats types\n
+ * phpgats_Boolean\n
+ * phpgats_Dictionary\n
+ * phpgats_Float\n
+ * phpgats_Integer\n
+ * phpgats_List\n
+ * phpgats_String\n
  */
 
+/**
+ * The base class for all phpgats types
+ */
 class phpgats_Element
 {
+	/**
+	 * Get the binary representation of the gats type
+	 * @returns (string) binary gats data
+	 */
 	function encode()
 	{
 		return "";
 	}
+
+	/**
+	 * Get a string representation of this type
+	 * @returns (string)
+	 */
 	function getStr()
 	{
 		return "";
 	}
+
+	/**
+	 * Get the gats type of the current element
+	 * @returns (string) one of: ("boolean"|"dictionary"|"float"|"integer"|"list"|"string")
+	 */
 	function getGatsType()
 	{
 		return "";
 	}
 }
 
+/**
+ * Write a gats packed integer
+ * @param $iIn (either a string representing a number, a gmp_int, or an int) The integer to be converted
+ * @returns (string) packed int binary data
+ */
 function phpgats_writeInt( $iIn )
 {
 	$ret = "";
@@ -58,6 +96,12 @@ function phpgats_writeInt( $iIn )
 	return $ret;
 }
 
+/**
+ * Read a gats packed integer into a gmp_int
+ * @param $sIn (string) the input stream
+ * @param &$pos (integer) the current position in the input stream (will be modified)
+ * @returns (gmp_int) the integer
+ */
 function phpgats_readInt( $sIn, &$pos )
 {
 	$neg = false;
@@ -79,20 +123,35 @@ function phpgats_readInt( $sIn, &$pos )
 	return $iOut;
 }
 
+/**
+ * Boolean Gats type (true or false)
+ */
 class phpgats_Boolean extends phpgats_Element
 {
 	public $elem = false;
 
+	/**
+	 * Creates a phpgats_Boolean out of a php type
+	 * @param $_elem (mixed) the php type to convert to a gats boolean
+	 */
 	function __construct( $_elem )
 	{
 		$this->elem = ($_elem==true)?true:false;
 	}
 
+	/**
+	 * Sets this phpgats_Boolean type based on php type $_elem
+	 * @param $_elem (mixed) the php type to convert to a gats boolean
+	 */
 	function set( $_elem )
 	{
 		$this->elem = ($_elem==true)?true:false;
 	}
 
+	/**
+	 * Get the php type of this element
+	 * @returns (bool)
+	 */
 	function get()
 	{
 		return $this->elem;
@@ -108,26 +167,45 @@ class phpgats_Boolean extends phpgats_Element
 		return ($this->elem==true)?"true":"false";
 	}
 
+	/**
+	 * Get the gats type of the current element
+	 * @returns "boolean"
+	 */
 	function getGatsType()
 	{
 		return "boolean";
 	}
 }
 
+/**
+ * String Gats type
+ */
 class phpgats_String extends phpgats_Element
 {
 	public $elem = "";
 
+	/**
+	 * Creates a phpgats_String out of a php type
+	 * @param $_elem (mixed) the php type to convert to a gats string
+	 */
 	function __construct( $_elem )
 	{
 		$this->elem = $_elem . "";
 	}
 
+	/**
+	 * Sets this phpgats_String type based on php type $_elem
+	 * @param $_elem (mixed) the php type to convert to a gats string
+	 */
 	function set( $_elem )
 	{
 		$this->elem = $_elem . "";
 	}
 
+	/**
+	 * Get the php type of this element
+	 * @returns (string)
+	 */
 	function get()
 	{
 		return $this->elem;
@@ -143,16 +221,27 @@ class phpgats_String extends phpgats_Element
 		return $this->get();
 	}
 
+	/**
+	 * Get the gats type of the current element
+	 * @returns "string"
+	 */
 	function getGatsType()
 	{
 		return "string";
 	}
 }
 
+/**
+ * Integer Gats type (gmp_int)
+ */
 class phpgats_Integer extends phpgats_Element
 {
 	public $elem = 0;
 
+	/**
+	 * Creates a phpgats_Integer out of a php type
+	 * @param $_elem (mixed) the php type to convert to a gats integer
+	 */
 	function __construct( $_elem )
 	{
 		if( $_elem === '' )
@@ -170,16 +259,28 @@ class phpgats_Integer extends phpgats_Element
 				getType($_elem) . "'.");
 	}
 
+	/**
+	 * Sets this phpgats_Integer type based on php type $_elem
+	 * @param $_elem (mixed) the php type to convert to a gats integer
+	 */
 	function set( $_elem )
 	{
 		$this->elem = gmp_init($_elem);
 	}
 
+	/**
+	 * Get the php type of this element
+	 * @returns (int)
+	 */
 	function get()
 	{
 		return gmp_intval($this->elem);
 	}
 
+	/**
+	 * Get the php type of this element
+	 * @returns (gmp_int)
+	 */
 	function get64()
 	{
 		return $this->elem;
@@ -195,26 +296,45 @@ class phpgats_Integer extends phpgats_Element
 		return gmp_strval($this->elem);
 	}
 
+	/**
+	 * Get the gats type of the current element
+	 * @returns "integer"
+	 */
 	function getGatsType()
 	{
 		return "integer";
 	}
 }
 
+/**
+ * Float Gats type
+ */
 class phpgats_Float extends phpgats_Element
 {
 	public $elem = 0;
 
+	/**
+	 * Creates a phpgats_Float out of a php type
+	 * @param $_elem (mixed) the php type to convert to a gats float
+	 */
 	function __construct( $_elem )
 	{
 		$this->elem = $_elem+0.0;
 	}
 
+	/**
+	 * Sets this phpgats_Float type based on php type $_elem
+	 * @param $_elem (mixed) the php type to convert to a gats float
+	 */
 	function set( $_elem )
 	{
 		$this->elem = $_elem+0.0;
 	}
 
+	/**
+	 * Get the php type of this element
+	 * @returns (float)
+	 */
 	function get()
 	{
 		return $this->elem;
@@ -268,16 +388,27 @@ class phpgats_Float extends phpgats_Element
 		return $this->elem+"";
 	}
 
+	/**
+	 * Get the gats type of the current element
+	 * @returns "float"
+	 */
 	function getGatsType()
 	{
 		return "float";
 	}
 }
 
+/**
+ * List Gats type
+ */
 class phpgats_List extends phpgats_Element
 {
 	public $elems = array();
 
+	/**
+	 * Append an element to this phpgats_List
+	 * @param $_elem (phpgats_Element) the element to append
+	 */
 	function append( $_elem )
 	{
 		if( !is_subclass_of( $_elem, "phpgats_Element" ) )
@@ -286,11 +417,19 @@ class phpgats_List extends phpgats_Element
 		array_push( $this->elems, $_elem );
 	}
 
+	/**
+	 * Returns the php array that is the core of this element
+	 * @returns (array)
+	 */
 	function get()
 	{
 		return $this->elems;
 	}
 
+	/**
+	 * Returns the current size of this list
+	 * @returns (int) the number of elements
+	 */
 	function size()
 	{
 		return count($this->elems);
@@ -307,16 +446,28 @@ class phpgats_List extends phpgats_Element
 		return $s_out;
 	}
 
+	/**
+	 * Get the gats type of the current element
+	 * @returns "list"
+	 */
 	function getGatsType()
 	{
 		return "list";
 	}
 }
 
+/**
+ * Dictionary Gats type
+ */
 class phpgats_Dictionary extends phpgats_Element
 {
 	public $elems = array();
 
+	/**
+	 * Append an element to the phpgats_Dictionary
+	 * @param $_name (string) the key under which to place this element
+	 * @param $_val (phpgats_Element) the phpgats_Element to place in the dictionary
+	 */
 	function append( $_name, $_val )
 	{
 		if( !is_subclass_of( $_val, "phpgats_Element" ) || 
@@ -326,11 +477,19 @@ class phpgats_Dictionary extends phpgats_Element
 		$this->elems[$_name] = $_val;
 	}
 
+	/**
+	 * Returns the php associative array that is the core of this element
+	 * @returns (array)
+	 */
 	function get()
 	{
 		return $this->elems;
 	}
 
+	/**
+	 * Returns the current size of the dictionary
+	 * @returns (int)
+	 */
 	function size()
 	{
 		return count($this->elems);
@@ -349,18 +508,34 @@ class phpgats_Dictionary extends phpgats_Element
 		return $s_out;
 	}
 
+	/**
+	 * Get the gats type of the current element
+	 * @returns "dictionary"
+	 */
 	function getGatsType()
 	{
 		return "dictionary";
 	}
 }
 
+/**
+ * Make sure we can read a character off the input stream
+ * @param $str_data (string) the input stream
+ * @param $offset (integer) the current position in the input stream
+ */
 function phpgats_pC( $str_data, $offset )
 {
 	if($offset>strlen($str_data))
 		throw new Exception("Not enough data");
 }
 
+/**
+ * Parse a string element out of the input stream
+ * @param $str_data (string) the input stream
+ * @param &$offset (integer) the current position in the input stream (will be updated)
+ * @param $dbg (integer) the current depth (for pretty printing)
+ * @returns (phpgats_String) the element read
+ */
 function phpgats_pS( $str_data, &$offset, $dbg )
 {
 	$str_tmp = "";
@@ -382,11 +557,25 @@ function phpgats_pS( $str_data, &$offset, $dbg )
 	return new phpgats_String($str_tmp);
 }
 
+/**
+ * Parse an integer element out of the input stream
+ * @param $str_data (string) the input stream
+ * @param &$offset (integer) the current position in the input stream (will be updated)
+ * @param $dbg (integer) the current depth (for pretty printing)
+ * @returns (phpgats_Integer) the element read
+ */
 function phpgats_pI( $str_data, &$offset, $dbg )
 {
 	return new phpgats_Integer(phpgats_readInt($str_data, $offset));
 }
 
+/**
+ * Parse a float element out of the input stream
+ * @param $str_data (string) the input stream
+ * @param &$offset (integer) the current position in the input stream (will be updated)
+ * @param $dbg (integer) the current depth (for pretty printing)
+ * @returns (phpgats_Float) the element read
+ */
 function phpgats_pF( $str_data, &$offset, $dbg )
 {
 	$str_tmp = "";
@@ -416,6 +605,13 @@ function phpgats_pF( $str_data, &$offset, $dbg )
 	return new phpgats_Float( $e );
 }
 
+/**
+ * Parse a list element out of the input stream
+ * @param $str_data (string) the input stream
+ * @param &$offset (integer) the current position in the input stream (will be updated)
+ * @param $dbg (integer) the current depth (for pretty printing)
+ * @returns (phpgats_List) the element read
+ */
 function phpgats_pL( $str_data, &$offset, $dbg )
 {
 	phpgats_pC( $str_data, $offset );
@@ -432,6 +628,13 @@ function phpgats_pL( $str_data, &$offset, $dbg )
 	return $l_out;
 }
 
+/**
+ * Parse a dictionary element out of the input stream
+ * @param $str_data (string) the input stream
+ * @param &$offset (integer) the current position in the input stream (will be updated)
+ * @param $dbg (integer) the current depth (for pretty printing)
+ * @returns (phpgats_Dictionary) the element read
+ */
 function phpgats_pD( $str_data, &$offset, $dbg )
 {
 	phpgats_pC( $str_data, $offset );
@@ -449,6 +652,13 @@ function phpgats_pD( $str_data, &$offset, $dbg )
 	return $d_out;
 }
 
+/**
+ * The internal master recursive parse function
+ * @param $str_data (string) the input stream
+ * @param &$offset (integer) the current position in the input stream (will be updated)
+ * @param $dbg (integer) the current depth (for pretty printing)
+ * @returns (phpgats_Element) the element read
+ */
 function phpgats_pM( $str_data, &$offset, $dbg=0 )
 {
 	phpgats_pC( $str_data, $offset );
@@ -507,6 +717,11 @@ function phpgats_pM( $str_data, &$offset, $dbg=0 )
 	}
 }
 
+/**
+ * Call this function to parse a gats binary string into a phpgats_Element object
+ * @param $str_data (string) the binary gats data to be parsed
+ * @returns (phpgats_Element)
+ */
 function phpgats_parseGats( $str_data )
 {
 	//print "parsing\n";
@@ -534,12 +749,18 @@ function phpgats_parseGats( $str_data )
 	return phpgats_pM( $str_data, $offset );
 }
 
+/**
+ * Call this function to generate a binary gats stream from the given phpgats_Element object
+ * @param $elem (phpgats_Element) the gats element object from which to generate a binary blob
+ * @returns (string) binary gats data
+ */
 function phpgats_writeGats( $elem )
 {
 	$str_out = $elem->encode();
 	$str_out = "\x01" . pack( "N", strlen($str_out)+5 ) . $str_out;
 	return $str_out;
 }
+
 /*
 $l = new phpgats_List();
 $l->append( new phpgats_Float( 123000000000.0 ) );
-- 
cgit v1.2.3