X-Git-Url: https://git.heureux-cyclage.org/?a=blobdiff_plain;f=includes%2FMagicWord.php;h=131ae1ddea198ef436fa3c3d7d968558ca8fe7a3;hb=af28c6f55abdf3d00b18cc44af8ca41e22955491;hp=bc05e92a3af1858f3495a8a8ed873babda500dd8;hpb=a4296effc728c7bc117325d974cb5647fe02a18d;p=lhc%2Fweb%2Fwiklou.git diff --git a/includes/MagicWord.php b/includes/MagicWord.php index bc05e92a3a..131ae1ddea 100644 --- a/includes/MagicWord.php +++ b/includes/MagicWord.php @@ -10,8 +10,13 @@ /** * This class encapsulates "magic words" such as #redirect, __NOTOC__, etc. - * Usage: - * if (MagicWord::get( 'redirect' )->match( $text ) ) + * + * @par Usage: + * @code + * if (MagicWord::get( 'redirect' )->match( $text ) ) { + * // some code + * } + * @endcode * * Possible future improvements: * * Simultaneous searching for a number of magic words @@ -20,8 +25,20 @@ * Please avoid reading the data out of one of these objects and then writing * special case code. If possible, add another match()-like function here. * - * To add magic words in an extension, use the LanguageGetMagic hook. For - * magic words which are also Parser variables, add a MagicWordwgVariableIDs + * To add magic words in an extension, use $magicWords in a file listed in + * $wgExtensionMessagesFiles[]. + * + * @par Example: + * @code + * $magicWords = array(); + * + * $magicWords['en'] = array( + * 'magicwordkey' => array( 0, 'case_insensitive_magic_word' ), + * 'magicwordkey2' => array( 1, 'CASE_sensitive_magic_word2' ), + * ); + * @endcode + * + * For magic words which are also Parser variables, add a MagicWordwgVariableIDs * hook. Use string keys. * * @ingroup Parser @@ -78,6 +95,7 @@ class MagicWord { 'fullpagenamee', 'namespace', 'namespacee', + 'namespacenumber', 'currentweek', 'currentdow', 'localweek', @@ -191,31 +209,27 @@ class MagicWord { /** * Factory: creates an object representing an ID + * + * @param $id + * * @return MagicWord */ static function &get( $id ) { - wfProfileIn( __METHOD__ ); if ( !isset( self::$mObjects[$id] ) ) { $mw = new MagicWord(); $mw->load( $id ); self::$mObjects[$id] = $mw; } - wfProfileOut( __METHOD__ ); return self::$mObjects[$id]; } /** * Get an array of parser variable IDs + * + * @return array */ static function getVariableIDs() { if ( !self::$mVariableIDsInitialised ) { - # Deprecated constant definition hook, available for extensions that need it - $magicWords = array(); - wfRunHooks( 'MagicWordMagicWords', array( &$magicWords ) ); - foreach ( $magicWords as $word ) { - define( $word, $word ); - } - # Get variable IDs wfRunHooks( 'MagicWordwgVariableIDs', array( &self::$mVariableIDs ) ); self::$mVariableIDsInitialised = true; @@ -225,21 +239,31 @@ class MagicWord { /** * Get an array of parser substitution modifier IDs + * @return array */ static function getSubstIDs() { - return self::$mSubstIDs; + return self::$mSubstIDs; } - /* Allow external reads of TTL array */ - static function getCacheTTL($id) { - if (array_key_exists($id,self::$mCacheTTLs)) { + /** + * Allow external reads of TTL array + * + * @param $id int + * @return array + */ + static function getCacheTTL( $id ) { + if ( array_key_exists( $id, self::$mCacheTTLs ) ) { return self::$mCacheTTLs[$id]; } else { return -1; } } - /** Get a MagicWordArray of double-underscore entities */ + /** + * Get a MagicWordArray of double-underscore entities + * + * @return MagicWordArray + */ static function getDoubleUnderscoreArray() { if ( is_null( self::$mDoubleUnderscoreArray ) ) { self::$mDoubleUnderscoreArray = new MagicWordArray( self::$mDoubleUnderscoreIDs ); @@ -255,9 +279,14 @@ class MagicWord { self::$mObjects = array(); } - # Initialises this object with an ID + /** + * Initialises this object with an ID + * + * @param $id + */ function load( $id ) { global $wgContLang; + wfProfileIn( __METHOD__ ); $this->mId = $id; $wgContLang->getMagic( $this ); if ( !$this->mSynonyms ) { @@ -265,6 +294,7 @@ class MagicWord { #throw new MWException( "Error: invalid magic word '$id'" ); wfDebugLog( 'exception', "Error: invalid magic word '$id'\n" ); } + wfProfileOut( __METHOD__ ); } /** @@ -292,9 +322,14 @@ class MagicWord { } /** - * A comparison function that returns -1, 0 or 1 depending on whether the - * first string is longer, the same length or shorter than the second + * A comparison function that returns -1, 0 or 1 depending on whether the + * first string is longer, the same length or shorter than the second * string. + * + * @param $s1 string + * @param $s2 string + * + * @return int */ function compareStringLength( $s1, $s2 ) { $l1 = strlen( $s1 ); @@ -310,6 +345,8 @@ class MagicWord { /** * Gets a regex representing matching the word + * + * @return string */ function getRegex() { if ($this->mRegex == '' ) { @@ -322,6 +359,8 @@ class MagicWord { * Gets the regexp case modifier to use, i.e. i or nothing, to be used if * one is using MagicWord::getBaseRegex(), otherwise it'll be included in * the complete expression + * + * @return string */ function getRegexCase() { if ( $this->mRegex === '' ) @@ -332,6 +371,8 @@ class MagicWord { /** * Gets a regex matching the word, if it is at the string start + * + * @return string */ function getRegexStart() { if ($this->mRegex == '' ) { @@ -342,6 +383,8 @@ class MagicWord { /** * regex without the slashes and what not + * + * @return string */ function getBaseRegex() { if ($this->mRegex == '') { @@ -352,6 +395,9 @@ class MagicWord { /** * Returns true if the text contains the word + * + * @param $text string + * * @return bool */ function match( $text ) { @@ -360,6 +406,9 @@ class MagicWord { /** * Returns true if the text starts with the word + * + * @param $text string + * * @return bool */ function matchStart( $text ) { @@ -371,6 +420,10 @@ class MagicWord { * The return code is the matched string, if there's no variable * part in the regex and the matched variable part ($1) if there * is one. + * + * @param $text string + * + * @return string */ function matchVariableStartToEnd( $text ) { $matches = array(); @@ -385,8 +438,11 @@ class MagicWord { $matches = array_values(array_filter($matches)); - if ( count($matches) == 1 ) { return $matches[0]; } - else { return $matches[1]; } + if ( count($matches) == 1 ) { + return $matches[0]; + } else { + return $matches[1]; + } } } @@ -394,6 +450,10 @@ class MagicWord { /** * Returns true if the text matches the word, and alters the * input string, removing all instances of the word + * + * @param $text string + * + * @return bool */ function matchAndRemove( &$text ) { $this->mFound = false; @@ -401,6 +461,10 @@ class MagicWord { return $this->mFound; } + /** + * @param $text + * @return bool + */ function matchStartAndRemove( &$text ) { $this->mFound = false; $text = preg_replace_callback( $this->getRegexStart(), array( &$this, 'pregRemoveAndRecord' ), $text ); @@ -409,17 +473,24 @@ class MagicWord { /** * Used in matchAndRemove() - * @private - **/ - function pregRemoveAndRecord( ) { + * + * @return string + */ + function pregRemoveAndRecord() { $this->mFound = true; return ''; } /** * Replaces the word with something else - */ - function replace( $replacement, $subject, $limit=-1 ) { + * + * @param $replacement + * @param $subject + * @param $limit int + * + * @return string + */ + function replace( $replacement, $subject, $limit = -1 ) { $res = preg_replace( $this->getRegex(), StringUtils::escapeRegexReplacement( $replacement ), $subject, $limit ); $this->mModified = !($res === $subject); return $res; @@ -429,6 +500,11 @@ class MagicWord { * Variable handling: {{SUBST:xxx}} style words * Calls back a function to determine what to replace xxx with * Input word must contain $1 + * + * @param $text string + * @param $callback + * + * @return string */ function substituteCallback( $text, $callback ) { $res = preg_replace_callback( $this->getVariableRegex(), $callback, $text ); @@ -438,6 +514,8 @@ class MagicWord { /** * Matches the word, where $1 is a wildcard + * + * @return string */ function getVariableRegex() { if ( $this->mVariableRegex == '' ) { @@ -448,6 +526,8 @@ class MagicWord { /** * Matches the entire string, where $1 is a wildcard + * + * @return string */ function getVariableStartToEndRegex() { if ( $this->mVariableStartToEndRegex == '' ) { @@ -458,11 +538,18 @@ class MagicWord { /** * Accesses the synonym list directly + * + * @param $i int + * + * @return string */ function getSynonym( $i ) { return $this->mSynonyms[$i]; } + /** + * @return array + */ function getSynonyms() { return $this->mSynonyms; } @@ -470,6 +557,8 @@ class MagicWord { /** * Returns true if the last call to replace() or substituteCallback() * returned a modified text, otherwise false. + * + * @return bool */ function getWasModified(){ return $this->mModified; @@ -480,9 +569,14 @@ class MagicWord { * This method uses the php feature to do several replacements at the same time, * thereby gaining some efficiency. The result is placed in the out variable * $result. The return value is true if something was replaced. - * @static * @todo Should this be static? It doesn't seem to be used at all - **/ + * + * @param $magicarr + * @param $subject + * @param $result + * + * @return bool + */ function replaceMultiple( $magicarr, $subject, &$result ){ $search = array(); $replace = array(); @@ -499,6 +593,9 @@ class MagicWord { /** * Adds all the synonyms of this MagicWord to an array, to allow quick * lookup in a list of magic words + * + * @param $array + * @param $value */ function addToArray( &$array, $value ) { global $wgContLang; @@ -507,10 +604,16 @@ class MagicWord { } } + /** + * @return bool + */ function isCaseSensitive() { return $this->mCaseSensitive; } + /** + * @return int + */ function getId() { return $this->mId; } @@ -532,6 +635,8 @@ class MagicWordArray { /** * Add a magic word by name + * + * @param $name string */ public function add( $name ) { $this->names[] = $name; @@ -540,6 +645,8 @@ class MagicWordArray { /** * Add a number of magic words by name + * + * @param $names array */ public function addArray( $names ) { $this->names = array_merge( $this->names, array_values( $names ) ); @@ -608,6 +715,8 @@ class MagicWordArray { /** * Get a regex for matching variables with parameters + * + * @return string */ function getVariableRegex() { return str_replace( "\\$1", "(.*?)", $this->getRegex() ); @@ -615,6 +724,8 @@ class MagicWordArray { /** * Get a regex anchored to the start of the string that does not match parameters + * + * @return array */ function getRegexStart() { $base = $this->getBaseRegex(); @@ -623,13 +734,15 @@ class MagicWordArray { $newRegex[0] = "/^(?:{$base[0]})/iuS"; } if ( $base[1] !== '' ) { - $newRegex[1] = "/^(?:{$base[1]})/S"; + $newRegex[1] = "/^(?:{$base[1]})/S"; } return $newRegex; } /** * Get an anchored regex for matching variables with parameters + * + * @return array */ function getVariableStartToEndRegex() { $base = $this->getBaseRegex(); @@ -647,6 +760,10 @@ class MagicWordArray { * Parse a match array from preg_match * Returns array(magic word ID, parameter value) * If there is no parameter value, that element will be false. + * + * @param $m array + * + * @return array */ function parseMatch( $m ) { reset( $m ); @@ -673,6 +790,10 @@ class MagicWordArray { * Returns an array with the magic word name in the first element and the * parameter in the second element. * Both elements are false if there was no match. + * + * @param $text string + * + * @return array */ public function matchVariableStartToEnd( $text ) { $regexes = $this->getVariableStartToEndRegex(); @@ -690,6 +811,10 @@ class MagicWordArray { /** * Match some text, without parameter capture * Returns the magic word name, or false if there was no capture + * + * @param $text string + * + * @return string|bool False on failure */ public function matchStartToEnd( $text ) { $hash = $this->getHash(); @@ -707,6 +832,10 @@ class MagicWordArray { /** * Returns an associative array, ID => param value, for all items that match * Removes the matched items from the input string (passed by reference) + * + * @param $text string + * + * @return array */ public function matchAndRemove( &$text ) { $found = array(); @@ -730,6 +859,10 @@ class MagicWordArray { * the prefix from $text. * Return false if no match found and $text is not modified. * Does not match parameters. + * + * @param $text string + * + * @return int|bool False on failure */ public function matchStartAndRemove( &$text ) { $regexes = $this->getRegexStart();