includes/MagicWord.php

   1 <?php
   2 /**
   3  * See docs/magicword.md.
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  * @ingroup Parser
  22  */
  23
  24 use MediaWiki\MediaWikiServices;
  25
  26 /**
  27  * This class encapsulates "magic words" such as "#redirect", __NOTOC__, etc.
  28  *
  29  * @par Usage:
  30  * @code
  31  *     if ( $magicWordFactory->get( 'redirect' )->match( $text ) ) {
  32  *       // some code
  33  *     }
  34  * @endcode
  35  *
  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.
  38  *
  39  * To add magic words in an extension, use $magicWords in a file listed in
  40  * $wgExtensionMessagesFiles[].
  41  *
  42  * @par Example:
  43  * @code
  44  * $magicWords = [];
  45  *
  46  * $magicWords['en'] = [
  47  *   'magicwordkey' => [ 0, 'case_insensitive_magic_word' ],
  48  *   'magicwordkey2' => [ 1, 'CASE_sensitive_magic_word2' ],
  49  * ];
  50  * @endcode
  51  *
  52  * For magic words which name Parser double underscore names, add a
  53  * GetDoubleUnderscoreIDs hook. Use string keys.
  54  *
  55  * For magic words which name Parser magic variables, add a GetMagicVariableIDs
  56  * hook. Use string keys.
  57  *
  58  * @ingroup Parser
  59  */
  60 class MagicWord {
  61         /** #@- */
  62
  63         /** @var string */
  64         public $mId;
  65
  66         /** @var string[] */
  67         public $mSynonyms;
  68
  69         /** @var bool */
  70         public $mCaseSensitive;
  71
  72         /** @var string */
  73         private $mRegex = '';
  74
  75         /** @var string */
  76         private $mRegexStart = '';
  77
  78         /** @var string */
  79         private $mRegexStartToEnd = '';
  80
  81         /** @var string */
  82         private $mBaseRegex = '';
  83
  84         /** @var string */
  85         private $mVariableRegex = '';
  86
  87         /** @var string */
  88         private $mVariableStartToEndRegex = '';
  89
  90         /** @var bool */
  91         private $mModified = false;
  92
  93         /** @var bool */
  94         private $mFound = false;
  95
  96         /** @var Language */
  97         private $contLang;
  98
  99         /** #@- */
 100
 101         /**
 102          * Create a new MagicWord object
 103          *
 104          * Use factory instead: MagicWordFactory::get
 105          *
 106          * @param string|null $id The internal name of the magic word
 107          * @param string[]|string $syn synonyms for the magic word
 108          * @param bool $cs If magic word is case sensitive
 109          * @param Language|null $contLang Content language
 110          */
 111         public function __construct( $id = null, $syn = [], $cs = false, Language $contLang = null ) {
 112                 $this->mId = $id;
 113                 $this->mSynonyms = (array)$syn;
 114                 $this->mCaseSensitive = $cs;
 115                 $this->contLang = $contLang ?: MediaWikiServices::getInstance()->getContentLanguage();
 116         }
 117
 118         /**
 119          * Initialises this object with an ID
 120          *
 121          * @param string $id
 122          * @throws MWException
 123          */
 124         public function load( $id ) {
 125                 $this->mId = $id;
 126                 $this->contLang->getMagic( $this );
 127                 if ( !$this->mSynonyms ) {
 128                         $this->mSynonyms = [ 'brionmademeputthishere' ];
 129                         throw new MWException( "Error: invalid magic word '$id'" );
 130                 }
 131         }
 132
 133         /**
 134          * Preliminary initialisation
 135          * @internal
 136          */
 137         public function initRegex() {
 138                 // Sort the synonyms by length, descending, so that the longest synonym
 139                 // matches in precedence to the shortest
 140                 $synonyms = $this->mSynonyms;
 141                 usort( $synonyms, [ $this, 'compareStringLength' ] );
 142
 143                 $escSyn = [];
 144                 foreach ( $synonyms as $synonym ) {
 145                         // In case a magic word contains /, like that's going to happen;)
 146                         $escSyn[] = preg_quote( $synonym, '/' );
 147                 }
 148                 $this->mBaseRegex = implode( '|', $escSyn );
 149
 150                 $case = $this->mCaseSensitive ? '' : 'iu';
 151                 $this->mRegex = "/{$this->mBaseRegex}/{$case}";
 152                 $this->mRegexStart = "/^(?:{$this->mBaseRegex})/{$case}";
 153                 $this->mRegexStartToEnd = "/^(?:{$this->mBaseRegex})$/{$case}";
 154                 $this->mVariableRegex = str_replace( "\\$1", "(.*?)", $this->mRegex );
 155                 $this->mVariableStartToEndRegex = str_replace( "\\$1", "(.*?)",
 156                         "/^(?:{$this->mBaseRegex})$/{$case}" );
 157         }
 158
 159         /**
 160          * A comparison function that returns -1, 0 or 1 depending on whether the
 161          * first string is longer, the same length or shorter than the second
 162          * string.
 163          *
 164          * @param string $s1
 165          * @param string $s2
 166          *
 167          * @return int
 168          */
 169         public function compareStringLength( $s1, $s2 ) {
 170                 $l1 = strlen( $s1 );
 171                 $l2 = strlen( $s2 );
 172                 return $l2 <=> $l1; // descending
 173         }
 174
 175         /**
 176          * Gets a regex representing matching the word
 177          *
 178          * @return string
 179          */
 180         public function getRegex() {
 181                 if ( $this->mRegex == '' ) {
 182                         $this->initRegex();
 183                 }
 184                 return $this->mRegex;
 185         }
 186
 187         /**
 188          * Gets the regexp case modifier to use, i.e. i or nothing, to be used if
 189          * one is using MagicWord::getBaseRegex(), otherwise it'll be included in
 190          * the complete expression
 191          *
 192          * @return string
 193          */
 194         public function getRegexCase() {
 195                 if ( $this->mRegex === '' ) {
 196                         $this->initRegex();
 197                 }
 198
 199                 return $this->mCaseSensitive ? '' : 'iu';
 200         }
 201
 202         /**
 203          * Gets a regex matching the word, if it is at the string start
 204          *
 205          * @return string
 206          */
 207         public function getRegexStart() {
 208                 if ( $this->mRegex == '' ) {
 209                         $this->initRegex();
 210                 }
 211                 return $this->mRegexStart;
 212         }
 213
 214         /**
 215          * Gets a regex matching the word from start to end of a string
 216          *
 217          * @return string
 218          * @since 1.23
 219          */
 220         public function getRegexStartToEnd() {
 221                 if ( $this->mRegexStartToEnd == '' ) {
 222                         $this->initRegex();
 223                 }
 224                 return $this->mRegexStartToEnd;
 225         }
 226
 227         /**
 228          * regex without the slashes and what not
 229          *
 230          * @return string
 231          */
 232         public function getBaseRegex() {
 233                 if ( $this->mRegex == '' ) {
 234                         $this->initRegex();
 235                 }
 236                 return $this->mBaseRegex;
 237         }
 238
 239         /**
 240          * Returns true if the text contains the word
 241          *
 242          * @param string $text
 243          *
 244          * @return bool
 245          */
 246         public function match( $text ) {
 247                 return (bool)preg_match( $this->getRegex(), $text );
 248         }
 249
 250         /**
 251          * Returns true if the text starts with the word
 252          *
 253          * @param string $text
 254          *
 255          * @return bool
 256          */
 257         public function matchStart( $text ) {
 258                 return (bool)preg_match( $this->getRegexStart(), $text );
 259         }
 260
 261         /**
 262          * Returns true if the text matched the word
 263          *
 264          * @param string $text
 265          *
 266          * @return bool
 267          * @since 1.23
 268          */
 269         public function matchStartToEnd( $text ) {
 270                 return (bool)preg_match( $this->getRegexStartToEnd(), $text );
 271         }
 272
 273         /**
 274          * Returns NULL if there's no match, the value of $1 otherwise
 275          * The return code is the matched string, if there's no variable
 276          * part in the regex and the matched variable part ($1) if there
 277          * is one.
 278          *
 279          * @param string $text
 280          *
 281          * @return string|null
 282          */
 283         public function matchVariableStartToEnd( $text ) {
 284                 $matches = [];
 285                 $matchcount = preg_match( $this->getVariableStartToEndRegex(), $text, $matches );
 286                 if ( $matchcount == 0 ) {
 287                         return null;
 288                 } else {
 289                         # multiple matched parts (variable match); some will be empty because of
 290                         # synonyms. The variable will be the second non-empty one so remove any
 291                         # blank elements and re-sort the indices.
 292                         # See also T8526
 293
 294                         $matches = array_values( array_filter( $matches ) );
 295
 296                         if ( count( $matches ) == 1 ) {
 297                                 return $matches[0];
 298                         } else {
 299                                 return $matches[1];
 300                         }
 301                 }
 302         }
 303
 304         /**
 305          * Returns true if the text matches the word, and alters the
 306          * input string, removing all instances of the word
 307          *
 308          * @param string &$text
 309          *
 310          * @return bool
 311          */
 312         public function matchAndRemove( &$text ) {
 313                 $this->mFound = false;
 314                 $text = preg_replace_callback(
 315                         $this->getRegex(),
 316                         [ $this, 'pregRemoveAndRecord' ],
 317                         $text
 318                 );
 319
 320                 return $this->mFound;
 321         }
 322
 323         /**
 324          * @param string &$text
 325          * @return bool
 326          */
 327         public function matchStartAndRemove( &$text ) {
 328                 $this->mFound = false;
 329                 $text = preg_replace_callback(
 330                         $this->getRegexStart(),
 331                         [ $this, 'pregRemoveAndRecord' ],
 332                         $text
 333                 );
 334
 335                 return $this->mFound;
 336         }
 337
 338         /**
 339          * Used in matchAndRemove()
 340          *
 341          * @return string
 342          */
 343         public function pregRemoveAndRecord() {
 344                 $this->mFound = true;
 345                 return '';
 346         }
 347
 348         /**
 349          * Replaces the word with something else
 350          *
 351          * @param string $replacement
 352          * @param string $subject
 353          * @param int $limit
 354          *
 355          * @return string
 356          */
 357         public function replace( $replacement, $subject, $limit = -1 ) {
 358                 $res = preg_replace(
 359                         $this->getRegex(),
 360                         StringUtils::escapeRegexReplacement( $replacement ),
 361                         $subject,
 362                         $limit
 363                 );
 364                 $this->mModified = $res !== $subject;
 365                 return $res;
 366         }
 367
 368         /**
 369          * Variable handling: {{SUBST:xxx}} style words
 370          * Calls back a function to determine what to replace xxx with
 371          * Input word must contain $1
 372          *
 373          * @param string $text
 374          * @param callable $callback
 375          *
 376          * @return string
 377          */
 378         public function substituteCallback( $text, $callback ) {
 379                 $res = preg_replace_callback( $this->getVariableRegex(), $callback, $text );
 380                 $this->mModified = $res !== $text;
 381                 return $res;
 382         }
 383
 384         /**
 385          * Matches the word, where $1 is a wildcard
 386          *
 387          * @return string
 388          */
 389         public function getVariableRegex() {
 390                 if ( $this->mVariableRegex == '' ) {
 391                         $this->initRegex();
 392                 }
 393                 return $this->mVariableRegex;
 394         }
 395
 396         /**
 397          * Matches the entire string, where $1 is a wildcard
 398          *
 399          * @return string
 400          */
 401         public function getVariableStartToEndRegex() {
 402                 if ( $this->mVariableStartToEndRegex == '' ) {
 403                         $this->initRegex();
 404                 }
 405                 return $this->mVariableStartToEndRegex;
 406         }
 407
 408         /**
 409          * Accesses the synonym list directly
 410          *
 411          * @param int $i
 412          *
 413          * @return string
 414          */
 415         public function getSynonym( $i ) {
 416                 return $this->mSynonyms[$i];
 417         }
 418
 419         /**
 420          * @return string[]
 421          */
 422         public function getSynonyms() {
 423                 return $this->mSynonyms;
 424         }
 425
 426         /**
 427          * Returns true if the last call to replace() or substituteCallback()
 428          * returned a modified text, otherwise false.
 429          *
 430          * @return bool
 431          */
 432         public function getWasModified() {
 433                 return $this->mModified;
 434         }
 435
 436         /**
 437          * Adds all the synonyms of this MagicWord to an array, to allow quick
 438          * lookup in a list of magic words
 439          *
 440          * @param string[] &$array
 441          * @param string $value
 442          */
 443         public function addToArray( &$array, $value ) {
 444                 foreach ( $this->mSynonyms as $syn ) {
 445                         $array[$this->contLang->lc( $syn )] = $value;
 446                 }
 447         }
 448
 449         /**
 450          * @return bool
 451          */
 452         public function isCaseSensitive() {
 453                 return $this->mCaseSensitive;
 454         }
 455
 456         /**
 457          * @return string
 458          */
 459         public function getId() {
 460                 return $this->mId;
 461         }
 462 }