Mercurial > SimpleWebPresenter
changeset 66:74f7b64bdb78
Lots of documentation fixes, and removal of unused function getXmlContent
| author | Tom Fredrik Blenning Klaussen <bfg@blenning.no> |
|---|---|
| date | Thu, 11 Oct 2012 22:11:33 +0200 |
| parents | 7b87ec8b0842 |
| children | 37dee99c1f8c |
| files | InputParser.inc Language.inc Logger.inc Options.inc common-functions.inc doc/Doxyfile filters.inc |
| diffstat | 7 files changed, 172 insertions(+), 32 deletions(-) [+] |
line wrap: on
line diff
--- a/InputParser.inc Thu Oct 11 20:36:24 2012 +0200 +++ b/InputParser.inc Thu Oct 11 22:11:33 2012 +0200 @@ -1,12 +1,20 @@ <?php /** - * @file - * Functionality for translating an XML document into a webpage + * Functionality for translating an XML configuration document into a webpage */ class InputParser { private $options; private $master; + /** + * Constructs a new InputParser object + * + * @param $name name of file to read configuration from + * @param $masterCache CacheTimeCheck cache object to use as parent for this inputParsercache + * + * @todo masterCache is currently used as is, fix so linked caches + * may be used. + */ function __construct($name, $masterCache) { $this->master = new DOMDocument(); $cache = $masterCache; @@ -49,6 +57,10 @@ } + /** + * Generate an appropriate response for this page, eg. 302 NOT + * MODIFIED or the actual page + */ function genPage() { if (CACHING && $this->options->getCacheable()) @@ -58,17 +70,24 @@ //print_r($cache->cacheSet(1)); } - + /** + * Extracts data from a @<param@> tag. + * + * @param $param the param tag + * + * @return if the type is array, return an array, otherwise return a + * scalar + */ function getParam($param) { - $param_type=$param->getAttribute("type"); + $param_type = $param->getAttribute("type"); $param_value; - if (!$param_type) - $param_type="scalar"; + if (! $param_type) + $param_type = "scalar"; if($param_type == "scalar") { - $param_subst=$param->getAttribute("subst"); - $param_value=$param->getAttribute("value"); + $param_subst = $param->getAttribute("subst"); + $param_value = $param->getAttribute("value"); if ($param_subst) { /* $param_value=preg_replace("/name/", $name, $param_subst); @@ -77,19 +96,26 @@ } } elseif($param_type == "array") { - $params=$param->getElementsByTagName("param"); - $param_value=array(); + $params = $param->getElementsByTagName("param"); + $param_value = array(); foreach ($param->childNodes as $param) { - if ($param->nodeType == XML_ELEMENT_NODE) - { - array_push($param_value, self::getParam($param)); - } + if ($param->nodeType == XML_ELEMENT_NODE) { + array_push($param_value, self::getParam($param)); + } } } return $param_value; } - function getFiles($doc, $options) { + /** + * This is the last processing stage for generating a file. + * + * @param $doc the document to be worked upon + * @param $options an Options object for this file. + * + * @return This is the same as the input document, fully processed + */ + static function getFiles($doc, $options) { $lang = $options->getLang(); $conf = $options->getName(); @@ -228,6 +254,17 @@ return $doc; } + /** + * Follows all include directives recursively for the specified + * $param an generates an xml file. + * + * This function may be used to generate a file which has all the + * necessary information to determine wether or not we may cache. + * + * @param $master The master document to be processed + * @param $param the input tag to resolve + * @param $options the options object for this file + */ function getInput($master, $param, $options) { $lang = $options->getLang();
--- a/Language.inc Thu Oct 11 20:36:24 2012 +0200 +++ b/Language.inc Thu Oct 11 22:11:33 2012 +0200 @@ -1,6 +1,5 @@ <?php /** - * @file * Functionality for determining language use */ class Language { @@ -10,7 +9,7 @@ * * @return associative array of language codes with q value */ - function accepted() { + static function accepted() { $langs = array(); if (isset($_SERVER['HTTP_ACCEPT_LANGUAGE'])) {
--- a/Logger.inc Thu Oct 11 20:36:24 2012 +0200 +++ b/Logger.inc Thu Oct 11 22:11:33 2012 +0200 @@ -1,9 +1,14 @@ <?php /** - * @file * Common access point for logging */ class Logger { + /** + * All logging goes through this function + * + * @param $level the severity level of this message + * @param $msg message to be logged + */ static function msg($level, $msg) { if (DEBUG_LEVEL >= $level) { @@ -13,6 +18,11 @@ } } + /** + * Convenience function, logs a message with level VERBOSITY_WARNING + * + * @param $msg message to be logged + */ static function warn($msg) { self::msg(VERBOSITY_WARNING, $msg);
--- a/Options.inc Thu Oct 11 20:36:24 2012 +0200 +++ b/Options.inc Thu Oct 11 22:11:33 2012 +0200 @@ -16,7 +16,7 @@ private $basePath; private $flagUrl; private $baseUrl; - private $cacheable; + private $cacheable = True; /** * Gets the default language @@ -38,11 +38,21 @@ return $this->lang; } + /** + * Sets wether or not this page may be cached + * + * @param $cacheable bool + */ function setCacheable($cacheable) { $this->cacheable = $cacheable; } + /** + * Gets wether or not this page may be cached + * + * @return bool, default is True + */ function getCacheable() { return $this->cacheable;
--- a/common-functions.inc Thu Oct 11 20:36:24 2012 +0200 +++ b/common-functions.inc Thu Oct 11 22:11:33 2012 +0200 @@ -5,11 +5,21 @@ */ include_once 'CacheTimeCheck.inc'; +/// @cond $baseDir = dirname(__FILE__); $cache = CacheTimeCheck::instance(__FILE__); $cache->includeOnce('StatusCodes.inc', $baseDir); +/// @endcond +/** + * Generates a representation for an array of key => value pairs + * + * @note Behaviour is undefined if value is a composite structure. + * + * @param $map the input array + * @return a string representation that may be eval'ed + */ function repMapString($map) { $opt = 'array('; @@ -28,12 +38,29 @@ return $opt; } +/** + * Get the location on the server where the top level script is + * located + * + * @return directory + */ function basePath() { $l = strrpos($_SERVER['SCRIPT_FILENAME'], $_SERVER['SCRIPT_NAME']); return substr($_SERVER['SCRIPT_FILENAME'], 0, $l); } +/** + * Loads a file + * + * @param $sFilename name of the file to load + * @param $sCharset the character encoding of the file + * + * @todo make this function throw instead of returning codes + * + * @return the contents of the file, or a status code (-3 if file does + * not exists, if file could not be opened -2) + */ function loadFile($sFilename, $sCharset = 'UTF-8') { if (floatval(phpversion()) >= 4.3) { @@ -61,6 +88,12 @@ return $sData; } +/** + * Generate a status page and exit + * + * @param $errorText the text to be displayed in the body + * @param $errorCode the status code to be served + */ function errorPage($errorText, $errorCode = 403) { header(StatusCodes::httpHeaderFor($errorCode)); @@ -68,6 +101,16 @@ exit; } +/** + * Generates an URL for the specified parameters + * + * @param $urlParams an associative array of the values already set + * @param $keys a set of values to override $urlParams + * + * @param $nonQueryParams a list of keys, where values should be in + * the URL, rather than the query part, note that the order is + * important + */ function genUrl($urlParams, $keys = array(), $nonQueryParams = array()) { $out = ''; $first = 1; @@ -100,6 +143,15 @@ return $out; } +/** + * Retrieves a single subelement + * @throw Exception if number of elements are different from 1 + * + * @todo Throw more specific exception + * + * @param $obj the xml element to search in + * @param $name the name of the element to search for + */ function getElementByTagName($obj, $name) { $elems = $obj->getElementsByTagName($name); if ($elems->length != 1) { @@ -109,31 +161,42 @@ return $elem; } -function getXmlContent($node) -{ - $text = $node->ownerDocument->saveXml($node); - $pattern = "/^<" . $node->tagName."[^>]*>/is"; - $text = preg_replace($pattern, '' , $text); - $pattern = '/<\/' . $node->tagName . '[^>]*>$/is'; - $text = preg_replace($pattern, '' , $text); - - return $text; -} - +/** + * Checks if one string start with another string + * + * @param $haystack the string to search + * @param $needle the string to search for + * + * @return bool if match + */ function startswith($haystack, $needle) { return strpos($haystack, $needle) === 0; } +/** + * Checks if one string ends with another string + * + * @param $haystack the string to search + * @param $needle the string to search for + * + * @return bool if match + */ function endsWith($haystack, $needle) { $l = strlen($haystack) - strlen($needle); return strrpos($haystack, $needle) === $l; } +/** + * Queries a URL for headers + * + * @param $url the url to query + * @return an associative array of all headers returned + */ function getHeaders($url) { - $response = http_head($url, array("timeout"=>1), $info); + $response = http_head($url, array("timeout" => 1), $info); $headers = array(); $str = explode("\n", $response); foreach($str as $kv) { @@ -147,6 +210,12 @@ return $headers; } +/** + * Generates the query part of an URI + * + * @param $opts an associative array of options + * @return a string that can be used for the query part of an URI + */ function opttostring($opts) { $str = '';
--- a/doc/Doxyfile Thu Oct 11 20:36:24 2012 +0200 +++ b/doc/Doxyfile Thu Oct 11 22:11:33 2012 +0200 @@ -38,7 +38,7 @@ # for a project that appears at the top of each page and should give viewer # a quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "An extremely simple CMS" +PROJECT_BRIEF = "An extremely basic CMS" # With the PROJECT_LOGO tag one can specify an logo or icon that is # included in the documentation. The maximum height of the logo should not
--- a/filters.inc Thu Oct 11 20:36:24 2012 +0200 +++ b/filters.inc Thu Oct 11 22:11:33 2012 +0200 @@ -3,6 +3,14 @@ * @file * Filters which may be used from xml */ + +/** + * A configuration function for generating an active status in a list + * item corresponding to the currently active 'name' + * + * @param $input the string to be processed + * @param $options Options for this file + */ function activeNav($input, $options) { $name = $options->getName(); @@ -28,6 +36,13 @@ return $output; } +/** + * A configuration function for generating a language bar. + * + * @param $input the string to be processed + * @param $options Options for this file + * @param $languages array of alternative languages + */ function addLangBar($input, $options, $languages) { $name = $options->getName();