includes/parser/Preprocessor.php

   1 <?php
   2 /**
   3  * Interfaces for preprocessors
   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 namespace MediaWiki\Parser;
  25
  26 use Wikimedia\ObjectCache\WANObjectCache;
  27
  28 /**
  29  * @ingroup Parser
  30  */
  31 abstract class Preprocessor {
  32         /** Transclusion mode flag for Preprocessor::preprocessToObj() */
  33         public const DOM_FOR_INCLUSION = 1;
  34         /** Language conversion construct omission flag for Preprocessor::preprocessToObj() */
  35         public const DOM_LANG_CONVERSION_DISABLED = 2;
  36         /** Preprocessor cache bypass flag for Preprocessor::preprocessToObj */
  37         public const DOM_UNCACHED = 4;
  38
  39         /** @var Parser */
  40         public $parser;
  41
  42         /** @var WANObjectCache */
  43         protected $wanCache;
  44
  45         /** @var bool Whether language variant conversion is disabled */
  46         protected $disableLangConversion;
  47
  48         /** @var array Brace matching rules */
  49         protected $rules = [
  50                 '{' => [
  51                         'end' => '}',
  52                         'names' => [
  53                                 2 => 'template',
  54                                 3 => 'tplarg',
  55                         ],
  56                         'min' => 2,
  57                         'max' => 3,
  58                 ],
  59                 '[' => [
  60                         'end' => ']',
  61                         'names' => [ 2 => null ],
  62                         'min' => 2,
  63                         'max' => 2,
  64                 ],
  65                 '-{' => [
  66                         'end' => '}-',
  67                         'names' => [ 2 => null ],
  68                         'min' => 2,
  69                         'max' => 2,
  70                 ],
  71         ];
  72
  73         /**
  74          * @param Parser $parser
  75          * @param WANObjectCache|null $wanCache
  76          * @param array $options Map of additional options, including:
  77          *       - disableLangConversion: disable language variant conversion. [Default: false]
  78          */
  79         public function __construct(
  80                 Parser $parser,
  81                 ?WANObjectCache $wanCache = null,
  82                 array $options = []
  83         ) {
  84                 $this->parser = $parser;
  85                 $this->wanCache = $wanCache ?: WANObjectCache::newEmpty();
  86                 $this->disableLangConversion = !empty( $options['disableLangConversion'] );
  87         }
  88
  89         /**
  90          * Allows resetting the internal Parser reference after Preprocessor is
  91          * cloned.
  92          *
  93          * Do not use this function in new code, since this method will be
  94          * moved once Parser cloning goes away (T250448)
  95          *
  96          * @param ?Parser $parser
  97          * @internal
  98          */
  99         public function resetParser( ?Parser $parser ) {
 100                 // @phan-suppress-next-line PhanPossiblyNullTypeMismatchProperty For internal use only
 101                 $this->parser = $parser;
 102         }
 103
 104         /**
 105          * Create a new top-level frame for expansion of a page
 106          *
 107          * @return PPFrame
 108          */
 109         abstract public function newFrame();
 110
 111         /**
 112          * Create a new custom frame for programmatic use of parameter replacement
 113          *
 114          * This is useful for certain types of extensions
 115          *
 116          * @param array $args
 117          * @return PPFrame
 118          */
 119         abstract public function newCustomFrame( $args );
 120
 121         /**
 122          * Create a new custom node for programmatic use of parameter replacement
 123          *
 124          * This is useful for certain types of extensions
 125          *
 126          * @param array $values
 127          */
 128         abstract public function newPartNodeArray( $values );
 129
 130         /**
 131          * Get the document object model for the given wikitext
 132          *
 133          * Any flag added to the $flags parameter here, or any other parameter liable to cause
 134          * a change in the DOM tree for the given wikitext, must be passed through the section
 135          * identifier in the section edit link and thus back to extractSections().
 136          *
 137          * @param string $text Wikitext
 138          * @param int $flags Bit field of Preprocessor::DOM_* flags:
 139          *   - Preprocessor::DOM_FOR_INCLUSION: treat the wikitext as transcluded content from
 140          *      a page rather than direct content of a page or message. By default, the text is
 141          *      assumed to be undergoing processing for use by direct page views. The use of this
 142          *      flag causes text within <noinclude> tags to be ignored, text within <includeonly>
 143          *      to be included, and text outside of <onlyinclude> to be ignored.
 144          *   - Preprocessor::DOM_NO_LANG_CONV: do not parse "-{ ... }-" constructs, which are
 145          *      involved in language variant conversion. (deprecated since 1.36)
 146          *   - Preprocessor::DOM_UNCACHED: disable use of the preprocessor cache.
 147          * @return PPNode
 148          */
 149         abstract public function preprocessToObj( $text, $flags = 0 );
 150 }
 151
 152 /** @deprecated class alias since 1.43 */
 153 class_alias( Preprocessor::class, 'Preprocessor' );