david - added documentation to phpgats

1 files changed, 226 insertions, 5 deletions

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 ) );