Mercurial > SimpleWebPresenter

changeset 94:2370f4450983

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Document functions and move a few functions to more appropriate places.
author Tom Fredrik Blenning Klaussen <bfg@blenning.no>
date Thu, 18 Oct 2012 17:33:34 +0200
parents 8aadd7a23b68
children 8a9bfbe220ca
files Http.inc OnlineBufferValidator.inc OnlineURIValidator.inc OnlineValidator.inc Page.inc Validator.inc common-functions.inc
diffstat 7 files changed, 140 insertions(+), 37 deletions(-) [+]
line wrap: on
line diff
--- a/Http.inc	Thu Oct 18 16:44:48 2012 +0200
+++ b/Http.inc	Thu Oct 18 17:33:34 2012 +0200
@@ -3,12 +3,74 @@
 
 /// @cond
 $baseDir = dirname(__FILE__);
-
 $cache = ScriptIncludeCache::instance(__FILE__);
 /// @endcond
 
+/**
+ * Thrown if a request has gone bad
+ */
+class RequestException extends RuntimeException
+{
+  private $_info;
+
+  /**
+   * Constructs a RequestException
+   *
+   * @param $info an info array as defined in http_get, if a key with
+   * name error exist, this will be the error text for the
+   * RuntimeException
+   */
+  function __construct($info)
+  {
+    $this->_info = $info;
+    if (array_key_exists('error', $info)) {
+      parent::__construct($info['error']);
+    }
+  }
+
+  /**
+   * Get the info object associated with this RequestException
+   *
+   * @return $info an info array as defined in http_get
+   */
+  function info()
+  {
+    return $this->_info;
+  }
+}
+
+/**
+ * Http contains a set of functions for retrieving http information
+ */
 class Http
 {
+  /**
+   * Gets the content of a page
+   *
+   * This mimics the file_content with a uri parameter which is often
+   * disabled due to security reasons
+   *
+   * @param $uri The uri to fetch
+   */
+  static function get_uri_contents($uri)
+  {
+    $crl = curl_init();
+    $timeout = 5;
+
+    curl_setopt ($crl, CURLOPT_URL, $uri);
+    curl_setopt ($crl, CURLOPT_RETURNTRANSFER, 1);
+    curl_setopt ($crl, CURLOPT_CONNECTTIMEOUT, $timeout);
+    $ret = curl_exec($crl);
+    curl_close($crl);
+    return $ret;
+  }
+
+  /**
+   * Splits an http header response into an associative array
+   *
+   * @param $response The headers to parse
+   * @return an Associative array, the key '' refers to the HTTP status header
+   */
   static function headersToArray($response)
   {
     $headers = array();
@@ -30,6 +92,7 @@
    * Queries a URL for headers
    *
    * @param $url the url to query
+   * @param $timeout float number of seconds to wait before timeout
    * @return an associative array of all headers returned
    */
   static function getHeaders($url, $timeout = 1)
@@ -43,7 +106,15 @@
     return self::headersToArray($response);
   }
 
-  static function postHeaders($url, $params, $timeout = 1)
+  /**
+   * Performs a post to an URI for headers
+   *
+   * @param $uri the uri to query
+   * @param $params an associative array of params to post
+   * @param $timeout float number of seconds to wait before timeout
+   * @return an associative array of all headers returned
+   */
+  static function postHeaders($uri, $params, $timeout = 1)
   {
     $crl = curl_init();
 
@@ -57,7 +128,7 @@
     //being reordered.
     $process = proc_open('tac | tac', $descriptorspec, $pipes);
 
-    curl_setopt ($crl, CURLOPT_URL, $url);
+    curl_setopt ($crl, CURLOPT_URL, $uri);
     curl_setopt ($crl, CURLOPT_WRITEHEADER, $pipes[0]);
     curl_setopt ($crl, CURLOPT_NOBODY, true);
     curl_setopt ($crl, CURLOPT_POST, true);
--- a/OnlineBufferValidator.inc	Thu Oct 18 16:44:48 2012 +0200
+++ b/OnlineBufferValidator.inc	Thu Oct 18 17:33:34 2012 +0200
@@ -9,11 +9,20 @@
 /// @endcond
 
 
+/**
+ * Defines a validator which uses an online validator and a buffer
+ * with the content
+ */
 class OnlineBufferValidator extends OnlineValidator
 {
 
   private $buffer;
 
+  /**
+   * Constructs an OnlineURIValidator
+   *
+   * @param $buffer The buffer to validate
+   */
   function __construct($buffer)
   {
     $this->buffer = $buffer;
--- a/OnlineURIValidator.inc	Thu Oct 18 16:44:48 2012 +0200
+++ b/OnlineURIValidator.inc	Thu Oct 18 17:33:34 2012 +0200
@@ -8,24 +8,19 @@
 $cache->includeOnce('OnlineValidator.inc', $baseDir);
 /// @endcond
 
-
+/**
+ * Defines a validator which uses an online validator and a URI to the
+ * content
+ */
 class OnlineURIValidator extends OnlineValidator
 {
   private $uri;
 
-  static function get_url_contents($url)
-  {
-    $crl = curl_init();
-    $timeout = 5;
-
-    curl_setopt ($crl, CURLOPT_URL, $url);
-    curl_setopt ($crl, CURLOPT_RETURNTRANSFER, 1);
-    curl_setopt ($crl, CURLOPT_CONNECTTIMEOUT, $timeout);
-    $ret = curl_exec($crl);
-    curl_close($crl);
-    return $ret;
-  }
-
+  /**
+   * Constructs an OnlineURIValidator
+   *
+   * @param $uri The uri to validate
+   */
   function __construct($uri)
   {
     $this->uri = $uri;
@@ -40,6 +35,11 @@
     return $headers['X-W3C-Validator-Status'] === "Valid";
   }
 
+  /**
+   * Gets the URI for this validator
+   *
+   * @return string with the URI
+   */
   function getUri()
   {
     return $this->uri;
--- a/OnlineValidator.inc	Thu Oct 18 16:44:48 2012 +0200
+++ b/OnlineValidator.inc	Thu Oct 18 17:33:34 2012 +0200
@@ -8,8 +8,14 @@
 /// @endcond
 
 
+/**
+ * Defines a validator which uses an online validator
+ */
 abstract class OnlineValidator extends Validator
 {
+  /**
+   * The url where the validator is located
+   */
   protected $validator_url = 'http://validator.w3.org/check';
 }
 ?>
\ No newline at end of file
--- a/Page.inc	Thu Oct 18 16:44:48 2012 +0200
+++ b/Page.inc	Thu Oct 18 17:33:34 2012 +0200
@@ -8,21 +8,43 @@
 $cache->includeOnce('Options.inc', $baseDir);
 /// @endcond
 
+/**
+ * Container for headers and content, used for compounding these
+ */
 class PageContent
 {
+  /// The headers for the page
   public $headers = array();
+  /// The content of the page
   public $content;
 
+  /**
+   * Constructs a PageContent object containing only content
+   *
+   * @param $content The content of this page
+   */
   function __construct($content = "")
   {
     $this->content = $content;
   }
 
+  /**
+   * Sets a header
+   *
+   * @param $headername Name of the header
+   * @param $value Value for the header
+   */
   function setHeader($headername, $value)
   {
     $this->headers[$headername] = $value;
   }
 
+  /**
+   * Returns a string representation of this object, containing only
+   * the content
+   *
+   * @return the content of the page
+   */
   function __toString()
   {
     return $this->content;
@@ -160,6 +182,11 @@
     return $res;
   }
 
+  /**
+   * Displays the result from genPage.
+   *
+   * Printing headers and content.
+   */
   function display()
   {
     $res = $this->genPage();
--- a/Validator.inc	Thu Oct 18 16:44:48 2012 +0200
+++ b/Validator.inc	Thu Oct 18 17:33:34 2012 +0200
@@ -6,8 +6,16 @@
 $cache = ScriptIncludeCache::instance(__FILE__);
 /// @endcond
 
-
-abstract class Validator {
+/**
+ * This is the base class for all validators
+ */
+abstract class Validator
+{
+  /**
+   * Performs the check if input is valid
+   *
+   * @return bool if the check went through
+   */
   abstract function check();
 }
 ?>
\ No newline at end of file
--- a/common-functions.inc	Thu Oct 18 16:44:48 2012 +0200
+++ b/common-functions.inc	Thu Oct 18 17:33:34 2012 +0200
@@ -12,24 +12,6 @@
 $cache->includeOnce('StatusCodes.inc', $baseDir);
 /// @endcond
 
-class RequestException extends RuntimeException
-{
-  private $_info;
-
-  function __construct($info)
-  {
-    $this->_info = $info;
-    if (array_key_exists('error', $info)) {
-      parent::__construct($info['error']);
-    }
-  }
-
-  function info()
-  {
-    return $this->_info;
-  }
-}
-
 /**
  * Generates a representation for an array of key => value pairs
  *