summaryrefslogtreecommitdiff
path: root/includes/parser/Preprocessor.php
blob: c31f37bf3639e0df0fad6e2947a4963e2d02ca25 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
<?php
/**
 * Interfaces for preprocessors
 *
 * @file
 */

/**
 * @ingroup Parser
 */
interface Preprocessor {
	/** Create a new preprocessor object based on an initialised Parser object */
	function __construct( $parser );

	/** Create a new top-level frame for expansion of a page */
	function newFrame();

	/** Create a new custom frame for programmatic use of parameter replacement as used in some extensions */
	function newCustomFrame( $args );

	/** Create a new custom node for programmatic use of parameter replacement as used in some extensions */
	function newPartNodeArray( $values );

	/** Preprocess text to a PPNode */
	function preprocessToObj( $text, $flags = 0 );
}

/**
 * @ingroup Parser
 */
interface PPFrame {
	const NO_ARGS = 1;
	const NO_TEMPLATES = 2;
	const STRIP_COMMENTS = 4;
	const NO_IGNORE = 8;
	const RECOVER_COMMENTS = 16;

	const RECOVER_ORIG = 27; // = 1|2|8|16 no constant expression support in PHP yet

	/**
	 * Create a child frame
	 */
	function newChild( $args = false, $title = false );

	/**
	 * Expand a document tree node
	 */
	function expand( $root, $flags = 0 );

	/**
	 * Implode with flags for expand()
	 */
	function implodeWithFlags( $sep, $flags /*, ... */ );

	/**
	 * Implode with no flags specified
	 */
	function implode( $sep /*, ... */ );

	/**
	 * Makes an object that, when expand()ed, will be the same as one obtained
	 * with implode()
	 */
	function virtualImplode( $sep /*, ... */ );

	/**
	 * Virtual implode with brackets
	 */
	function virtualBracketedImplode( $start, $sep, $end /*, ... */ );

	/**
	 * Returns true if there are no arguments in this frame
	 */
	function isEmpty();

	/**
	 * Returns all arguments of this frame
	 */
	function getArguments();

	/**
	 * Returns all numbered arguments of this frame
	 */
	function getNumberedArguments();

	/**
	 * Returns all named arguments of this frame
	 */
	function getNamedArguments();

	/**
	 * Get an argument to this frame by name
	 */
	function getArgument( $name );

	/**
	 * Returns true if the infinite loop check is OK, false if a loop is detected
	 */
	function loopCheck( $title );

	/**
	 * Return true if the frame is a template frame
	 */
	function isTemplate();
}

/**
 * There are three types of nodes:
 *     * Tree nodes, which have a name and contain other nodes as children
 *     * Array nodes, which also contain other nodes but aren't considered part of a tree
 *     * Leaf nodes, which contain the actual data
 *
 * This interface provides access to the tree structure and to the contents of array nodes,
 * but it does not provide access to the internal structure of leaf nodes. Access to leaf
 * data is provided via two means:
 *     * PPFrame::expand(), which provides expanded text
 *     * The PPNode::split*() functions, which provide metadata about certain types of tree node
 * @ingroup Parser
 */
interface PPNode {
	/**
	 * Get an array-type node containing the children of this node.
	 * Returns false if this is not a tree node.
	 */
	function getChildren();

	/**
	 * Get the first child of a tree node. False if there isn't one.
	 */
	function getFirstChild();

	/**
	 * Get the next sibling of any node. False if there isn't one
	 */
	function getNextSibling();

	/**
	 * Get all children of this tree node which have a given name.
	 * Returns an array-type node, or false if this is not a tree node.
	 */
	function getChildrenOfType( $type );


	/**
	 * Returns the length of the array, or false if this is not an array-type node
	 */
	function getLength();

	/**
	 * Returns an item of an array-type node
	 */
	function item( $i );

	/**
	 * Get the name of this node. The following names are defined here:
	 *
	 *    h             A heading node.
	 *    template      A double-brace node.
	 *    tplarg        A triple-brace node.
	 *    title         The first argument to a template or tplarg node.
	 *    part          Subsequent arguments to a template or tplarg node.
	 *    #nodelist     An array-type node
	 *
	 * The subclass may define various other names for tree and leaf nodes.
	 */
	function getName();

	/**
	 * Split a <part> node into an associative array containing:
	 *    name          PPNode name
	 *    index         String index
	 *    value         PPNode value
	 */
	function splitArg();

	/**
	 * Split an <ext> node into an associative array containing name, attr, inner and close
	 * All values in the resulting array are PPNodes. Inner and close are optional.
	 */
	function splitExt();

	/**
	 * Split an <h> node
	 */
	function splitHeading();
}