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