9 * This class encapsulates "magic words" such as #redirect, __NOTOC__, etc.
11 * if (MagicWord::get( 'redirect' )->match( $text ) )
13 * Possible future improvements:
14 * * Simultaneous searching for a number of magic words
15 * * MagicWord::$mObjects in shared memory
17 * Please avoid reading the data out of one of these objects and then writing
18 * special case code. If possible, add another match()-like function here.
20 * To add magic words in an extension, use the LanguageGetMagic hook. For
21 * magic words which are also Parser variables, add a MagicWordwgVariableIDs
22 * hook. Use string keys.
30 var $mId, $mSynonyms, $mCaseSensitive, $mRegex;
31 var $mRegexStart, $mBaseRegex, $mVariableRegex;
32 var $mModified, $mFound;
34 static public $mVariableIDsInitialised = false;
35 static public $mVariableIDs = array(
38 'currentmonthnamegen',
107 static public $mObjects = array();
111 function MagicWord($id = 0, $syn = '', $cs = false) {
113 $this->mSynonyms
= (array)$syn;
114 $this->mCaseSensitive
= $cs;
116 $this->mRegexStart
= '';
117 $this->mVariableRegex
= '';
118 $this->mVariableStartToEndRegex
= '';
119 $this->mModified
= false;
123 * Factory: creates an object representing an ID
126 static function &get( $id ) {
127 if (!array_key_exists( $id, self
::$mObjects ) ) {
128 $mw = new MagicWord();
130 self
::$mObjects[$id] = $mw;
132 return self
::$mObjects[$id];
136 * Get an array of parser variable IDs
138 static function getVariableIDs() {
139 if ( !self
::$mVariableIDsInitialised ) {
140 # Deprecated constant definition hook, available for extensions that need it
141 $magicWords = array();
142 wfRunHooks( 'MagicWordMagicWords', array( &$magicWords ) );
143 foreach ( $magicWords as $word ) {
144 define( $word, $word );
148 wfRunHooks( 'MagicWordwgVariableIDs', array( &self
::$mVariableIDs ) );
149 self
::$mVariableIDsInitialised = true;
151 return self
::$mVariableIDs;
154 # Initialises this object with an ID
155 function load( $id ) {
158 $wgContLang->getMagic( $this );
159 if ( !$this->mSynonyms
) {
160 $this->mSynonyms
= array( 'dkjsagfjsgashfajsh' );
161 #throw new MWException( "Error: invalid magic word '$id'" );
162 wfDebugLog( 'exception', "Error: invalid magic word '$id'\n" );
167 * Preliminary initialisation
170 function initRegex() {
171 #$variableClass = Title::legalChars();
172 # This was used for matching "$1" variables, but different uses of the feature will have
173 # different restrictions, which should be checked *after* the MagicWord has been matched,
177 foreach ( $this->mSynonyms
as $synonym )
178 // In case a magic word contains /, like that's going to happen;)
179 $escSyn[] = preg_quote( $synonym, '/' );
180 $this->mBaseRegex
= implode( '|', $escSyn );
182 $case = $this->mCaseSensitive ?
'' : 'iu';
183 $this->mRegex
= "/{$this->mBaseRegex}/{$case}";
184 $this->mRegexStart
= "/^(?:{$this->mBaseRegex})/{$case}";
185 $this->mVariableRegex
= str_replace( "\\$1", "(.*?)", $this->mRegex
);
186 $this->mVariableStartToEndRegex
= str_replace( "\\$1", "(.*?)",
187 "/^(?:{$this->mBaseRegex})$/{$case}" );
191 * Gets a regex representing matching the word
193 function getRegex() {
194 if ($this->mRegex
== '' ) {
197 return $this->mRegex
;
201 * Gets the regexp case modifier to use, i.e. i or nothing, to be used if
202 * one is using MagicWord::getBaseRegex(), otherwise it'll be included in
203 * the complete expression
205 function getRegexCase() {
206 if ( $this->mRegex
=== '' )
209 return $this->mCaseSensitive ?
'' : 'iu';
213 * Gets a regex matching the word, if it is at the string start
215 function getRegexStart() {
216 if ($this->mRegex
== '' ) {
219 return $this->mRegexStart
;
223 * regex without the slashes and what not
225 function getBaseRegex() {
226 if ($this->mRegex
== '') {
229 return $this->mBaseRegex
;
233 * Returns true if the text contains the word
236 function match( $text ) {
237 return preg_match( $this->getRegex(), $text );
241 * Returns true if the text starts with the word
244 function matchStart( $text ) {
245 return preg_match( $this->getRegexStart(), $text );
249 * Returns NULL if there's no match, the value of $1 otherwise
250 * The return code is the matched string, if there's no variable
251 * part in the regex and the matched variable part ($1) if there
254 function matchVariableStartToEnd( $text ) {
256 $matchcount = preg_match( $this->getVariableStartToEndRegex(), $text, $matches );
257 if ( $matchcount == 0 ) {
260 # multiple matched parts (variable match); some will be empty because of
261 # synonyms. The variable will be the second non-empty one so remove any
262 # blank elements and re-sort the indices.
265 $matches = array_values(array_filter($matches));
267 if ( count($matches) == 1 ) { return $matches[0]; }
268 else { return $matches[1]; }
274 * Returns true if the text matches the word, and alters the
275 * input string, removing all instances of the word
277 function matchAndRemove( &$text ) {
278 $this->mFound
= false;
279 $text = preg_replace_callback( $this->getRegex(), array( &$this, 'pregRemoveAndRecord' ), $text );
280 return $this->mFound
;
283 function matchStartAndRemove( &$text ) {
284 $this->mFound
= false;
285 $text = preg_replace_callback( $this->getRegexStart(), array( &$this, 'pregRemoveAndRecord' ), $text );
286 return $this->mFound
;
290 * Used in matchAndRemove()
293 function pregRemoveAndRecord( ) {
294 $this->mFound
= true;
299 * Replaces the word with something else
301 function replace( $replacement, $subject, $limit=-1 ) {
302 $res = preg_replace( $this->getRegex(), StringUtils
::escapeRegexReplacement( $replacement ), $subject, $limit );
303 $this->mModified
= !($res === $subject);
308 * Variable handling: {{SUBST:xxx}} style words
309 * Calls back a function to determine what to replace xxx with
310 * Input word must contain $1
312 function substituteCallback( $text, $callback ) {
313 $res = preg_replace_callback( $this->getVariableRegex(), $callback, $text );
314 $this->mModified
= !($res === $text);
319 * Matches the word, where $1 is a wildcard
321 function getVariableRegex() {
322 if ( $this->mVariableRegex
== '' ) {
325 return $this->mVariableRegex
;
329 * Matches the entire string, where $1 is a wildcard
331 function getVariableStartToEndRegex() {
332 if ( $this->mVariableStartToEndRegex
== '' ) {
335 return $this->mVariableStartToEndRegex
;
339 * Accesses the synonym list directly
341 function getSynonym( $i ) {
342 return $this->mSynonyms
[$i];
345 function getSynonyms() {
346 return $this->mSynonyms
;
350 * Returns true if the last call to replace() or substituteCallback()
351 * returned a modified text, otherwise false.
353 function getWasModified(){
354 return $this->mModified
;
358 * $magicarr is an associative array of (magic word ID => replacement)
359 * This method uses the php feature to do several replacements at the same time,
360 * thereby gaining some efficiency. The result is placed in the out variable
361 * $result. The return value is true if something was replaced.
364 function replaceMultiple( $magicarr, $subject, &$result ){
367 foreach( $magicarr as $id => $replacement ){
368 $mw = MagicWord
::get( $id );
369 $search[] = $mw->getRegex();
370 $replace[] = $replacement;
373 $result = preg_replace( $search, $replace, $subject );
374 return !($result === $subject);
378 * Adds all the synonyms of this MagicWord to an array, to allow quick
379 * lookup in a list of magic words
381 function addToArray( &$array, $value ) {
383 foreach ( $this->mSynonyms
as $syn ) {
384 $array[$wgContLang->lc($syn)] = $value;
388 function isCaseSensitive() {
389 return $this->mCaseSensitive
;