3 * See docs/magicword.txt.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 use MediaWiki\MediaWikiServices
;
27 * This class encapsulates "magic words" such as "#redirect", __NOTOC__, etc.
31 * if ( $magicWordFactory->get( 'redirect' )->match( $text ) ) {
36 * Please avoid reading the data out of one of these objects and then writing
37 * special case code. If possible, add another match()-like function here.
39 * To add magic words in an extension, use $magicWords in a file listed in
40 * $wgExtensionMessagesFiles[].
46 * $magicWords['en'] = [
47 * 'magicwordkey' => [ 0, 'case_insensitive_magic_word' ],
48 * 'magicwordkey2' => [ 1, 'CASE_sensitive_magic_word2' ],
52 * For magic words which are also Parser variables, add a MagicWordwgVariableIDs
53 * hook. Use string keys.
67 public $mCaseSensitive;
73 private $mRegexStart = '';
76 private $mRegexStartToEnd = '';
79 private $mBaseRegex = '';
82 private $mVariableRegex = '';
85 private $mVariableStartToEndRegex = '';
88 private $mModified = false;
91 private $mFound = false;
96 * Create a new MagicWord object
98 * Use factory instead: MagicWordFactory::get
100 * @param string|null $id The internal name of the magic word
101 * @param string[]|string $syn synonyms for the magic word
102 * @param bool $cs If magic word is case sensitive
104 public function __construct( $id = null, $syn = [], $cs = false ) {
106 $this->mSynonyms
= (array)$syn;
107 $this->mCaseSensitive
= $cs;
111 * Factory: creates an object representing an ID
113 * @param string $id The internal name of the magic word
116 * @deprecated since 1.32, use MagicWordFactory::get
118 public static function get( $id ) {
119 return MediaWikiServices
::getInstance()->getMagicWordFactory()->get( $id );
123 * Get an array of parser variable IDs
126 * @deprecated since 1.32, use MagicWordFactory::getVariableIDs
128 public static function getVariableIDs() {
129 return MediaWikiServices
::getInstance()->getMagicWordFactory()->getVariableIDs();
133 * Get an array of parser substitution modifier IDs
135 * @deprecated since 1.32, use MagicWordFactory::getSubstIDs
137 public static function getSubstIDs() {
138 return MediaWikiServices
::getInstance()->getMagicWordFactory()->getSubstIDs();
142 * Allow external reads of TTL array
146 * @deprecated since 1.32, use MagicWordFactory::getCacheTTL
148 public static function getCacheTTL( $id ) {
149 return MediaWikiServices
::getInstance()->getMagicWordFactory()->getCacheTTL( $id );
153 * Get a MagicWordArray of double-underscore entities
155 * @return MagicWordArray
156 * @deprecated since 1.32, use MagicWordFactory::getDoubleUnderscoreArray
158 public static function getDoubleUnderscoreArray() {
159 return MediaWikiServices
::getInstance()->getMagicWordFactory()->getDoubleUnderscoreArray();
163 * Initialises this object with an ID
166 * @throws MWException
168 public function load( $id ) {
171 $wgContLang->getMagic( $this );
172 if ( !$this->mSynonyms
) {
173 $this->mSynonyms
= [ 'brionmademeputthishere' ];
174 throw new MWException( "Error: invalid magic word '$id'" );
179 * Preliminary initialisation
182 public function initRegex() {
183 // Sort the synonyms by length, descending, so that the longest synonym
184 // matches in precedence to the shortest
185 $synonyms = $this->mSynonyms
;
186 usort( $synonyms, [ $this, 'compareStringLength' ] );
189 foreach ( $synonyms as $synonym ) {
190 // In case a magic word contains /, like that's going to happen;)
191 $escSyn[] = preg_quote( $synonym, '/' );
193 $this->mBaseRegex
= implode( '|', $escSyn );
195 $case = $this->mCaseSensitive ?
'' : 'iu';
196 $this->mRegex
= "/{$this->mBaseRegex}/{$case}";
197 $this->mRegexStart
= "/^(?:{$this->mBaseRegex})/{$case}";
198 $this->mRegexStartToEnd
= "/^(?:{$this->mBaseRegex})$/{$case}";
199 $this->mVariableRegex
= str_replace( "\\$1", "(.*?)", $this->mRegex
);
200 $this->mVariableStartToEndRegex
= str_replace( "\\$1", "(.*?)",
201 "/^(?:{$this->mBaseRegex})$/{$case}" );
205 * A comparison function that returns -1, 0 or 1 depending on whether the
206 * first string is longer, the same length or shorter than the second
214 public function compareStringLength( $s1, $s2 ) {
217 return $l2 <=> $l1; // descending
221 * Gets a regex representing matching the word
225 public function getRegex() {
226 if ( $this->mRegex
== '' ) {
229 return $this->mRegex
;
233 * Gets the regexp case modifier to use, i.e. i or nothing, to be used if
234 * one is using MagicWord::getBaseRegex(), otherwise it'll be included in
235 * the complete expression
239 public function getRegexCase() {
240 if ( $this->mRegex
=== '' ) {
244 return $this->mCaseSensitive ?
'' : 'iu';
248 * Gets a regex matching the word, if it is at the string start
252 public function getRegexStart() {
253 if ( $this->mRegex
== '' ) {
256 return $this->mRegexStart
;
260 * Gets a regex matching the word from start to end of a string
265 public function getRegexStartToEnd() {
266 if ( $this->mRegexStartToEnd
== '' ) {
269 return $this->mRegexStartToEnd
;
273 * regex without the slashes and what not
277 public function getBaseRegex() {
278 if ( $this->mRegex
== '' ) {
281 return $this->mBaseRegex
;
285 * Returns true if the text contains the word
287 * @param string $text
291 public function match( $text ) {
292 return (bool)preg_match( $this->getRegex(), $text );
296 * Returns true if the text starts with the word
298 * @param string $text
302 public function matchStart( $text ) {
303 return (bool)preg_match( $this->getRegexStart(), $text );
307 * Returns true if the text matched the word
309 * @param string $text
314 public function matchStartToEnd( $text ) {
315 return (bool)preg_match( $this->getRegexStartToEnd(), $text );
319 * Returns NULL if there's no match, the value of $1 otherwise
320 * The return code is the matched string, if there's no variable
321 * part in the regex and the matched variable part ($1) if there
324 * @param string $text
328 public function matchVariableStartToEnd( $text ) {
330 $matchcount = preg_match( $this->getVariableStartToEndRegex(), $text, $matches );
331 if ( $matchcount == 0 ) {
334 # multiple matched parts (variable match); some will be empty because of
335 # synonyms. The variable will be the second non-empty one so remove any
336 # blank elements and re-sort the indices.
339 $matches = array_values( array_filter( $matches ) );
341 if ( count( $matches ) == 1 ) {
350 * Returns true if the text matches the word, and alters the
351 * input string, removing all instances of the word
353 * @param string &$text
357 public function matchAndRemove( &$text ) {
358 $this->mFound
= false;
359 $text = preg_replace_callback(
361 [ $this, 'pregRemoveAndRecord' ],
365 return $this->mFound
;
369 * @param string &$text
372 public function matchStartAndRemove( &$text ) {
373 $this->mFound
= false;
374 $text = preg_replace_callback(
375 $this->getRegexStart(),
376 [ $this, 'pregRemoveAndRecord' ],
380 return $this->mFound
;
384 * Used in matchAndRemove()
388 public function pregRemoveAndRecord() {
389 $this->mFound
= true;
394 * Replaces the word with something else
396 * @param string $replacement
397 * @param string $subject
402 public function replace( $replacement, $subject, $limit = -1 ) {
405 StringUtils
::escapeRegexReplacement( $replacement ),
409 $this->mModified
= $res !== $subject;
414 * Variable handling: {{SUBST:xxx}} style words
415 * Calls back a function to determine what to replace xxx with
416 * Input word must contain $1
418 * @param string $text
419 * @param callable $callback
423 public function substituteCallback( $text, $callback ) {
424 $res = preg_replace_callback( $this->getVariableRegex(), $callback, $text );
425 $this->mModified
= $res !== $text;
430 * Matches the word, where $1 is a wildcard
434 public function getVariableRegex() {
435 if ( $this->mVariableRegex
== '' ) {
438 return $this->mVariableRegex
;
442 * Matches the entire string, where $1 is a wildcard
446 public function getVariableStartToEndRegex() {
447 if ( $this->mVariableStartToEndRegex
== '' ) {
450 return $this->mVariableStartToEndRegex
;
454 * Accesses the synonym list directly
460 public function getSynonym( $i ) {
461 return $this->mSynonyms
[$i];
467 public function getSynonyms() {
468 return $this->mSynonyms
;
472 * Returns true if the last call to replace() or substituteCallback()
473 * returned a modified text, otherwise false.
477 public function getWasModified() {
478 return $this->mModified
;
482 * Adds all the synonyms of this MagicWord to an array, to allow quick
483 * lookup in a list of magic words
485 * @param string[] &$array
486 * @param string $value
488 public function addToArray( &$array, $value ) {
490 foreach ( $this->mSynonyms
as $syn ) {
491 $array[$wgContLang->lc( $syn )] = $value;
498 public function isCaseSensitive() {
499 return $this->mCaseSensitive
;
505 public function getId() {