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
 3.14
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
 2
 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 * 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
24namespace MediaWiki\Parser;
25
26use Wikimedia\ObjectCache\WANObjectCache;
27
28/**
29 * @ingroup Parser
30 */
31abstract 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 */
158class_alias( Preprocessor::class, 'Preprocessor' );