diff --git a/lib/html2text.php b/lib/html2text.php index dbf0943d54f8e..ca8017182218d 100644 --- a/lib/html2text.php +++ b/lib/html2text.php @@ -1,35 +1,22 @@ * - * All rights reserved. * - * * - * This script is free software; you can redistribute it and/or modify * - * it under the terms of the GNU General Public License as published by * - * the Free Software Foundation; either version 2 of the License, or * - * (at your option) any later version. * - * * - * The GNU General Public License can be found at * - * http://www.gnu.org/copyleft/gpl.html. * - * * - * This script is distributed in the hope that it will be useful, * - * but WITHOUT ANY WARRANTY; without even the implied warranty of * - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * - * GNU General Public License for more details. * - * * - * Author(s): Jon Abernathy * - * * - * Last modified: 08/08/07 * - * * - *************************************************************************/ - +// This file is part of Moodle - http://moodle.org/ +// +// Moodle is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// Moodle is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with Moodle. If not, see . +// +// Author(s): Jon Abernathy +// Copyright (c) 2005-2007 Jon Abernathy /** * Takes HTML and converts it to formatted, plain text. @@ -100,9 +87,15 @@ * * *** End of the housecleaning updates. Updated 08/08/07. * - * @author Jon Abernathy - * @version 1.0.0 - * @since PHP 4.0.2 + * @package moodlecore + * @copyright Jon Abernathy + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +/** + * @package moodlecore + * @copyright Jon Abernathy + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class html2text { @@ -218,7 +211,7 @@ class html2text '-', '*', '£', - 'EUR', // Euro sign. € ? + 'EUR', // Euro sign. � ? ' ' // Runs of spaces, post-handling ); @@ -542,7 +535,7 @@ function _build_link_list( $link, $display ) /** * Helper function for PRE body conversion. * - * @param string HTML content + * @param string $text HTML content * @access private */ function _convert_pre(&$text) @@ -556,7 +549,7 @@ function _convert_pre(&$text) /** * Callback function for preg_replace_callback use. * - * @param array PREG matches + * @param array $matches PREG matches * @return string * @access private */ @@ -578,7 +571,7 @@ function _preg_callback($matches) /** * Strtoupper multibyte wrapper function * - * @param string + * @param string $str * @return string * @access private */ diff --git a/lib/installlib.php b/lib/installlib.php index 1e4952940002a..7187bf02e1325 100644 --- a/lib/installlib.php +++ b/lib/installlib.php @@ -24,16 +24,23 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ +/** INSTALL_WELCOME = 0 */ define('INSTALL_WELCOME', 0); +/** INSTALL_ENVIRONMENT = 1 */ define('INSTALL_ENVIRONMENT', 1); +/** INSTALL_PATHS = 2 */ define('INSTALL_PATHS', 2); +/** INSTALL_DOWNLOADLANG = 3 */ define('INSTALL_DOWNLOADLANG', 3); +/** INSTALL_DATABASETYPE = 4 */ define('INSTALL_DATABASETYPE', 4); +/** INSTALL_DATABASE = 5 */ define('INSTALL_DATABASE', 5); +/** INSTALL_SAVE = 6 */ define('INSTALL_SAVE', 6); /** - *Tries to detect the right www root setting. + * Tries to detect the right www root setting. * @return string detected www root */ function install_guess_wwwroot() { @@ -88,6 +95,15 @@ function install_helpbutton($url, $title='') { /** * This is in function because we want the /install.php to parse in PHP4 + * + * @param object $database + * @param string $dbhsot + * @param string $dbuser + * @param string $dbpass + * @param string $dbname + * @param string $prefix + * @param mixed $dboptions + * @return string */ function install_db_validate($database, $dbhost, $dbuser, $dbpass, $dbname, $prefix, $dboptions) { try { @@ -111,6 +127,8 @@ function install_db_validate($database, $dbhost, $dbuser, $dbpass, $dbname, $pre * This function returns a list of languages and their full names. The * list of available languages is fetched from install/lang/xx/installer.php * and it's used exclusively by the installation process + * + * @global object * @return array An associative array with contents in the form of LanguageCode => LanguageName */ function install_get_list_of_languages() { @@ -195,6 +213,8 @@ function install_generate_configphp($database, $cfg, $userealpath=false) { /** * Prints complete help page used during installation. * Does not return. + * + * @global object * @param string $help */ function install_print_help_page($help) { @@ -235,6 +255,8 @@ function install_print_help_page($help) { /** * Prints installation page header, we can no use weblib yet in isntaller. + * + * @global object * @param array $config * @param string $stagename * @param string $heading @@ -303,6 +325,8 @@ function install_print_header($config, $stagename, $heading, $stagetext) { /** * Prints installation page header, we can no use weblib yet in isntaller. + * + * @global object * @param array $config * @param bool $reload print reload button instead of next * @return void @@ -344,6 +368,8 @@ function install_print_footer($config, $reload=false) { /** * Prints css needed on installation page, tries to look like the rest of installation. * Does not return. + * + * @global object */ function install_css_styles() { global $CFG; diff --git a/lib/javascript-mod.php b/lib/javascript-mod.php index b48e39d75237c..4a6956193bdbb 100644 --- a/lib/javascript-mod.php +++ b/lib/javascript-mod.php @@ -1,9 +1,32 @@ -. +/** + * Searches modules, filters and blocks for any Javascript files + * that should be called on every page + * + * @package moodlecore + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +/** NO_MOODLE_COOKIES = true */ define('NO_MOODLE_COOKIES', true); + /** NO_UPGRADE_CHECK = true */ define('NO_UPGRADE_CHECK', true); include('../config.php'); diff --git a/lib/javascript.php b/lib/javascript.php index eaa53685ceab6..b106cd50b720b 100644 --- a/lib/javascript.php +++ b/lib/javascript.php @@ -1,5 +1,27 @@ -. + +/** + * Load up any required Javascript libraries + * + * @package moodlecore + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ if (!defined('MOODLE_INTERNAL')) { die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page diff --git a/lib/kses.php b/lib/kses.php index 204a56a802ad0..5825823980530 100644 --- a/lib/kses.php +++ b/lib/kses.php @@ -1,35 +1,50 @@ " characters. + * + * @param string $string + * @param string $allowed_html + * @param array $allowed_protocols + * @return string + */ function kses_split($string, $allowed_html, $allowed_protocols) ############################################################################### # This function searches for HTML tags, no matter how malformed. It also @@ -82,7 +116,17 @@ function kses_split($string, $allowed_html, $allowed_protocols) $string); } # function kses_split - +/** + * This function does a lot of work. It rejects some very malformed things + * like <:::>. It returns an empty string, if the element isn't allowed (look + * ma, no strip_tags()!). Otherwise it splits the tag into an element and an + * attribute list. + * + * @param string $string + * @param string $allowed_html + * @param array $allowed_protocols + * @return string + */ function kses_split2($string, $allowed_html, $allowed_protocols) ############################################################################### # This function does a lot of work. It rejects some very malformed things @@ -117,7 +161,20 @@ function kses_split2($string, $allowed_html, $allowed_protocols) $allowed_protocols); } # function kses_split2 - +/** + * This function removes all attributes, if none are allowed for this element. + * If some are allowed it calls kses_hair() to split them further, and then it + * builds up new HTML code from the data that kses_hair() returns. It also + * removes "<" and ">" characters, if there are any left. One more thing it + * does is to check if the tag has a closing XHTML slash, and if it does, + * it puts one in the returned code as well. + * + * @param string $element + * @param string $attr + * @param string $allowed_html + * @param array $allowed_protocols + * @return string + */ function kses_attr($element, $attr, $allowed_html, $allowed_protocols) ############################################################################### # This function removes all attributes, if none are allowed for this element. @@ -182,7 +239,18 @@ function kses_attr($element, $attr, $allowed_html, $allowed_protocols) return "<$element$attr2$xhtml_slash>"; } # function kses_attr - +/** + * This function does a lot of work. It parses an attribute list into an array + * with attribute data, and tries to do the right thing even if it gets weird + * input. It will add quotes around attribute values that don't have any quotes + * or apostrophes around them, to make it easier to produce HTML code that will + * conform to W3C's HTML specification. It will also remove bad URL protocols + * from attribute values. + * + * @param string $attr + * @param array $allowed_protocols + * @return array + */ function kses_hair($attr, $allowed_protocols) ############################################################################### # This function does a lot of work. It parses an attribute list into an array @@ -307,7 +375,17 @@ function kses_hair($attr, $allowed_protocols) return $attrarr; } # function kses_hair - +/** + * This function performs different checks for attribute values. The currently + * implemented checks are "maxlen", "minlen", "maxval", "minval" and "valueless" + * with even more checks to come soon. + * + * @param string $value + * @param string $vless + * @param string $checkname + * @param string $checkvalue + * @return bool + */ function kses_check_attr_val($value, $vless, $checkname, $checkvalue) ############################################################################### # This function performs different checks for attribute values. The currently @@ -373,7 +451,16 @@ function kses_check_attr_val($value, $vless, $checkname, $checkvalue) return $ok; } # function kses_check_attr_val - +/** + * This function removes all non-allowed protocols from the beginning of + * $string. It ignores whitespace and the case of the letters, and it does + * understand HTML entities. It does its work in a while loop, so it won't be + * fooled by a string like "javascript:javascript:alert(57)". + * + * @param string $string + * @param array $$allowed_protocols + * @return string + */ function kses_bad_protocol($string, $allowed_protocols) ############################################################################### # This function removes all non-allowed protocols from the beginning of @@ -395,7 +482,12 @@ function kses_bad_protocol($string, $allowed_protocols) return $string; } # function kses_bad_protocol - +/** + * This function removes any NULL characters in $string. + * + * @param string $string + * @return string + */ function kses_no_null($string) ############################################################################### # This function removes any NULL characters in $string. @@ -408,6 +500,14 @@ function kses_no_null($string) } # function kses_no_null +/** + * This function changes the character sequence \" to just " + * It leaves all other slashes alone. It's really weird, but the quoting from + * preg_replace(//e) seems to require this. + * + * @param string $string + * @return string + */ function kses_stripslashes($string) ############################################################################### # This function changes the character sequence \" to just " @@ -419,6 +519,12 @@ function kses_stripslashes($string) } # function kses_stripslashes +/** + * This function goes through an array, and changes the keys to all lower case. + * + * @param array $inarray + * @return array + */ function kses_array_lc($inarray) ############################################################################### # This function goes through an array, and changes the keys to all lower case. @@ -441,7 +547,12 @@ function kses_array_lc($inarray) return $outarray; } # function kses_array_lc - +/** + * This function removes the HTML JavaScript entities found in early versions of + * Netscape 4. + * + * @param string $string + */ function kses_js_entities($string) ############################################################################### # This function removes the HTML JavaScript entities found in early versions of @@ -451,7 +562,14 @@ function kses_js_entities($string) return preg_replace('%&\s*\{[^}]*(\}\s*;?|$)%', '', $string); } # function kses_js_entities - +/** + * This function deals with parsing errors in kses_hair(). The general plan is + * to remove everything to and including some whitespace, but it deals with + * quotes and apostrophes as well. + * + * @param string $string + * @return string + */ function kses_html_error($string) ############################################################################### # This function deals with parsing errors in kses_hair(). The general plan is @@ -462,7 +580,14 @@ function kses_html_error($string) return preg_replace('/^("[^"]*("|$)|\'[^\']*(\'|$)|\S)*\s*/', '', $string); } # function kses_html_error - +/** + * This function searches for URL protocols at the beginning of $string, while + * handling whitespace and HTML entities. + * + * @param string $string + * @param string $allowed_protocols + * @return string + */ function kses_bad_protocol_once($string, $allowed_protocols) ############################################################################### # This function searches for URL protocols at the beginning of $string, while @@ -477,7 +602,14 @@ function kses_bad_protocol_once($string, $allowed_protocols) return $string; } # function kses_bad_protocol_once - +/** + * This function processes URL protocols, checks to see if they're in the white- + * list or not, and returns different data depending on the answer. + * + * @param string $string + * @param string $allowed_protocols + * @return string + */ function kses_bad_protocol_once2($string, $allowed_protocols) ############################################################################### # This function processes URL protocols, checks to see if they're in the white- @@ -505,7 +637,13 @@ function kses_bad_protocol_once2($string, $allowed_protocols) return ''; } # function kses_bad_protocol_once2 - +/** + * This function normalizes HTML entities. It will convert "AT&T" to the correct + * "AT&T", ":" to ":", "&#XYZZY;" to "&#XYZZY;" and so on. + * + * @param string $string + * @return string + */ function kses_normalize_entities($string) ############################################################################### # This function normalizes HTML entities. It will convert "AT&T" to the correct @@ -528,7 +666,13 @@ function kses_normalize_entities($string) return $string; } # function kses_normalize_entities - +/** + * This function helps kses_normalize_entities() to only accept 16 bit values + * and nothing more for &#number; entities. + * + * @param int $i + * @return string + */ function kses_normalize_entities2($i) ############################################################################### # This function helps kses_normalize_entities() to only accept 16 bit values @@ -538,7 +682,14 @@ function kses_normalize_entities2($i) return (($i > 65535) ? "&#$i;" : "&#$i;"); } # function kses_normalize_entities2 - +/** + * This function decodes numeric HTML entities (A and A). It doesn't + * do anything with other entities like ä, but we don't need them in the + * URL protocol whitelisting system anyway. + * + * @param string $string + * @return string + */ function kses_decode_entities($string) ############################################################################### # This function decodes numeric HTML entities (A and A). It doesn't diff --git a/lib/languages.php b/lib/languages.php index 21da37968ac54..83b09676413e7 100644 --- a/lib/languages.php +++ b/lib/languages.php @@ -1,7 +1,30 @@ -. + +/** + * @package moodlecore + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +/** + * @global array $LANGUAGES + * @name $$LANGUAGES + */ $LANGUAGES = array ( "aa" => "Afar", diff --git a/lib/lexer.php b/lib/lexer.php index fe01255157d21..ca53509fcef0b 100644 --- a/lib/lexer.php +++ b/lib/lexer.php @@ -1,23 +1,36 @@ -_case = $case; @@ -40,11 +53,11 @@ function ParallelRegex($case) { /** * Adds a pattern with an optional label. - * @param $pattern Perl style regex, but ( and ) + * @param string $pattern Perl style regex, but ( and ) * lose the usual meaning. - * @param $label Label of regex to be returned + * @param string $label Label of regex to be returned * on a match. - * @public + * @access public */ function addPattern($pattern, $label = true) { $count = count($this->_patterns); @@ -56,11 +69,11 @@ function addPattern($pattern, $label = true) { /** * Attempts to match all patterns at once against * a string. - * @param $subject String to match against. - * @param $match First matched portion of + * @param string $subject String to match against. + * @param string $match First matched portion of * subject. - * @return True on success. - * @public + * @return bool True on success. + * @access public */ function match($subject, &$match) { if (count($this->_patterns) == 0) { @@ -84,8 +97,7 @@ function match($subject, &$match) { * regular expression separated with the * "or" operator. Caches the regex. * Will automatically escape (, ) and / tokens. - * @param $patterns List of patterns in order. - * @private + * @access private */ function _getCompoundedRegex() { if ($this->_regex == null) { @@ -102,8 +114,8 @@ function _getCompoundedRegex() { /** * Accessor for perl regex mode flags to use. - * @return Flags as string. - * @private + * @return string Flags as string. + * @access private */ function _getPerlMatchingFlags() { return ($this->_case ? "msS" : "msSi"); @@ -111,15 +123,19 @@ function _getPerlMatchingFlags() { } /** - * States for a stack machine. + * States for a stack machine. + * + * @package moodlecore + * @copyright Markus Baker, Harry Fuecks and Matt Mitchell + * @license Public Domain {@link http://sourceforge.net/projects/lamplib} */ class StateStack { var $_stack; /** * Constructor. Starts in named state. - * @param $start Starting state name. - * @public + * @param string $start Starting state name. + * @access public */ function StateStack($start) { $this->_stack = array($start); @@ -127,8 +143,8 @@ function StateStack($start) { /** * Accessor for current state. - * @return State as string. - * @public + * @return string State as string. + * @access public */ function getCurrent() { return $this->_stack[count($this->_stack) - 1]; @@ -137,8 +153,8 @@ function getCurrent() { /** * Adds a state to the stack and sets it * to be the current state. - * @param $state New state. - * @public + * @param string $state New state. + * @access public */ function enter($state) { array_push($this->_stack, $state); @@ -147,9 +163,9 @@ function enter($state) { /** * Leaves the current state and reverts * to the previous one. - * @return False if we drop off + * @return bool False if we drop off * the bottom of the list. - * @public + * @access public */ function leave() { if (count($this->_stack) == 1) { @@ -161,11 +177,15 @@ function leave() { } /** - * Accepts text and breaks it into tokens. - * Some optimisation to make the sure the - * content is only scanned by the PHP regex - * parser once. Lexer modes must not start - * with leading underscores. + * Accepts text and breaks it into tokens. + * Some optimisation to make the sure the + * content is only scanned by the PHP regex + * parser once. Lexer modes must not start + * with leading underscores. + * + * @package moodlecore + * @copyright Markus Baker, Harry Fuecks and Matt Mitchell + * @license Public Domain {@link http://sourceforge.net/projects/lamplib} */ class Lexer { var $_regexes; @@ -177,11 +197,11 @@ class Lexer { /** * Sets up the lexer in case insensitive matching * by default. - * @param $parser Handling strategy by + * @param object $parser Handling strategy by * reference. - * @param $start Starting handler. - * @param $case True for case sensitive. - * @public + * @param string $start Starting handler. + * @param bool $case True for case sensitive. + * @access public */ function Lexer(&$parser, $start = "accept", $case = false) { $this->_case = $case; @@ -195,12 +215,12 @@ function Lexer(&$parser, $start = "accept", $case = false) { * Adds a token search pattern for a particular * parsing mode. The pattern does not change the * current mode. - * @param $pattern Perl style regex, but ( and ) + * @param string $pattern Perl style regex, but ( and ) * lose the usual meaning. - * @param $mode Should only apply this + * @param string $mode Should only apply this * pattern when dealing with * this type of input. - * @public + * @access public */ function addPattern($pattern, $mode = "accept") { if (!isset($this->_regexes[$mode])) { @@ -213,14 +233,14 @@ function addPattern($pattern, $mode = "accept") { * Adds a pattern that will enter a new parsing * mode. Useful for entering parenthesis, strings, * tags, etc. - * @param $pattern Perl style regex, but ( and ) + * @param string $pattern Perl style regex, but ( and ) * lose the usual meaning. - * @param $mode Should only apply this + * @param string $mode Should only apply this * pattern when dealing with * this type of input. - * @param $new_mode Change parsing to this new + * @param string $new_mode Change parsing to this new * nested mode. - * @public + * @access public */ function addEntryPattern($pattern, $mode, $new_mode) { if (!isset($this->_regexes[$mode])) { @@ -232,10 +252,10 @@ function addEntryPattern($pattern, $mode, $new_mode) { /** * Adds a pattern that will exit the current mode * and re-enter the previous one. - * @param $pattern Perl style regex, but ( and ) + * @param string $pattern Perl style regex, but ( and ) * lose the usual meaning. - * @param $mode Mode to leave. - * @public + * @param string $mode Mode to leave. + * @access public */ function addExitPattern($pattern, $mode) { if (!isset($this->_regexes[$mode])) { @@ -247,13 +267,13 @@ function addExitPattern($pattern, $mode) { /** * Adds a pattern that has a special mode. * Acts as an entry and exit pattern in one go. - * @param $pattern Perl style regex, but ( and ) + * @param string $pattern Perl style regex, but ( and ) * lose the usual meaning. - * @param $mode Should only apply this + * @param string $mode Should only apply this * pattern when dealing with * this type of input. - * @param $special Use this mode for this one token. - * @public + * @param string $special Use this mode for this one token. + * @access public */ function addSpecialPattern($pattern, $mode, $special) { if (!isset($this->_regexes[$mode])) { @@ -264,9 +284,9 @@ function addSpecialPattern($pattern, $mode, $special) { /** * Adds a mapping from a mode to another handler. - * @param $mode Mode to be remapped. - * @param $handler New target handler. - * @public + * @param string $mode Mode to be remapped. + * @param string $handler New target handler. + * @access public */ function mapHandler($mode, $handler) { $this->_mode_handlers[$mode] = $handler; @@ -278,9 +298,9 @@ function mapHandler($mode, $handler) { * content is consumed. If successful then each * unparsed and parsed token invokes a call to the * held listener. - * @param $raw Raw HTML text. - * @return True on success, else false. - * @public + * @param string $raw Raw HTML text. + * @return bool True on success, else false. + * @access public */ function parse($raw) { if (!isset($this->_parser)) { @@ -307,14 +327,14 @@ function parse($raw) { * Sends the matched token and any leading unmatched * text to the parser changing the lexer to a new * mode if one is listed. - * @param $unmatched Unmatched leading portion. - * @param $matched Actual token match. - * @param $mode Mode after match. The "_exit" + * @param string $unmatched Unmatched leading portion. + * @param string $matched Actual token match. + * @param string $mode Mode after match. The "_exit" * mode causes a stack pop. An * false mode causes no change. - * @return False if there was any error + * @return bool False if there was any error * from the parser. - * @private + * @access private */ function _dispatchTokens($unmatched, $matched, $mode = false) { if (!$this->_invokeParser($unmatched, LEXER_UNMATCHED)) { @@ -344,10 +364,10 @@ function _dispatchTokens($unmatched, $matched, $mode = false) { /** * Calls the parser method named after the current * mode. Empty content will be ignored. - * @param $content Text parsed. - * @param $is_match Token is recognised rather + * @param string $content Text parsed. + * @param string $is_match Token is recognised rather * than unparsed data. - * @private + * @access private */ function _invokeParser($content, $is_match) { if (($content === "") || ($content === false)) { @@ -364,15 +384,15 @@ function _invokeParser($content, $is_match) { * Tries to match a chunk of text and if successful * removes the recognised chunk and any leading * unparsed data. Empty strings will not be matched. - * @param $raw The subject to parse. This is the + * @param string $raw The subject to parse. This is the * content that will be eaten. - * @return Three item list of unparsed + * @return bool|array Three item list of unparsed * content followed by the * recognised token and finally the * action the parser is to take. * True if no match, false if there * is a parsing error. - * @private + * @access private */ function _reduce(&$raw) { if (!isset($this->_regexes[$this->_mode->getCurrent()])) {