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