tighten return codes
[diogenes.git] / include / Text / Wiki / Parse.php
1 <?php
2
3 /**
4 *
5 * Baseline rule class for extension into a "real" parser component.
6 *
7 <<<<<<< Parse.php
8 * Text_Wiki_Parse_* classes do not stand on their own; they are called by a
9 * Text_Wiki object, typcially in the transform() method. Each rule class
10 * performs two separate activities: parse and process.
11 =======
12 * @category Text
13 *
14 * @package Text_Wiki
15 *
16 * @author Paul M. Jones <pmjones@php.net>
17 *
18 * @license LGPL
19 *
20 */
21
22 /**
23 *
24 * Baseline rule class for extension into a "real" parser component.
25 *
26 * Text_Wiki_Rule classes do not stand on their own; they are called by a
27 * Text_Wiki object, typcially in the transform() method. Each rule class
28 * performs three main activities: parse, process, and render.
29 >>>>>>> 1.4
30 *
31 * The parse() method takes a regex and applies it to the whole block of
32 * source text at one time. Each match is sent as $matches to the
33 * process() method.
34 *
35 * The process() method acts on the matched text from the source, and
36 * then processes the source text is some way. This may mean the
37 * creation of a delimited token using addToken(). In every case, the
38 * process() method returns the text that should replace the matched text
39 * from parse().
40 *
41 * @category Text
42 *
43 * @package Text_Wiki
44 *
45 * @author Paul M. Jones <pmjones@php.net>
46 *
47 */
48
49 class Text_Wiki_Parse {
50
51
52 /**
53 *
54 * Configuration options for this parser rule.
55 *
56 * @access public
57 *
58 * @var string
59 *
60 */
61
62 var $conf = array();
63
64
65 /**
66 *
67 * Regular expression to find matching text for this rule.
68 *
69 * @access public
70 *
71 * @var string
72 *
73 * @see parse()
74 *
75 */
76
77 var $regex = null;
78
79
80 /**
81 *
82 * The name of this rule for new token array elements.
83 *
84 * @access public
85 *
86 * @var string
87 *
88 */
89
90 var $rule = null;
91
92
93 /**
94 *
95 * A reference to the calling Text_Wiki object.
96 *
97 * This is needed so that each rule has access to the same source
98 * text, token set, URLs, interwiki maps, page names, etc.
99 *
100 * @access public
101 *
102 * @var object
103 */
104
105 var $wiki = null;
106
107
108 /**
109 *
110 * Constructor for this parser rule.
111 *
112 * @access public
113 *
114 * @param object &$obj The calling "parent" Text_Wiki object.
115 *
116 */
117
118 function Text_Wiki_Parse(&$obj)
119 {
120 // set the reference to the calling Text_Wiki object;
121 // this allows us access to the shared source text, token
122 // array, etc.
123 $this->wiki =& $obj;
124
125 // set the name of this rule; generally used when adding
126 // to the tokens array. strip off the Text_Wiki_Parse_ portion.
127 // text_wiki_parse_
128 // 0123456789012345
129 $tmp = substr(get_class($this), 16);
130 $this->rule = ucwords(strtolower($tmp));
131
132 // override config options for the rule if specified
133 if (isset($this->wiki->parseConf[$this->rule]) &&
134 is_array($this->wiki->parseConf[$this->rule])) {
135
136 $this->conf = array_merge(
137 $this->conf,
138 $this->wiki->parseConf[$this->rule]
139 );
140
141 }
142 }
143
144
145 /**
146 *
147 * Abstrct method to parse source text for matches.
148 *
149 * Applies the rule's regular expression to the source text, passes
150 * every match to the process() method, and replaces the matched text
151 * with the results of the processing.
152 *
153 * @access public
154 *
155 * @see Text_Wiki_Parse::process()
156 *
157 */
158
159 function parse()
160 {
161 $this->wiki->source = preg_replace_callback(
162 $this->regex,
163 array(&$this, 'process'),
164 $this->wiki->source
165 );
166 }
167
168
169 /**
170 *
171 * Abstract method to generate replacements for matched text.
172 *
173 * @access public
174 *
175 * @param array $matches An array of matches from the parse() method
176 * as generated by preg_replace_callback. $matches[0] is the full
177 * matched string, $matches[1] is the first matched pattern,
178 * $matches[2] is the second matched pattern, and so on.
179 *
180 * @return string The processed text replacement; defaults to the
181 * full matched string (i.e., no changes to the text).
182 *
183 * @see Text_Wiki_Parse::parse()
184 *
185 */
186
187 function process(&$matches)
188 {
189 return $matches[0];
190 }
191
192
193 /**
194 *
195 * Simple method to safely get configuration key values.
196 *
197 * @access public
198 *
199 * @param string $key The configuration key.
200 *
201 * @param mixed $default If the key does not exist, return this value
202 * instead.
203 *
204 * @return mixed The configuration key value (if it exists) or the
205 * default value (if not).
206 *
207 */
208
209 function getConf($key, $default = null)
210 {
211 if (isset($this->conf[$key])) {
212 return $this->conf[$key];
213 } else {
214 return $default;
215 }
216 }
217
218
219 /**
220 *
221 * Extract 'attribute="value"' portions of wiki markup.
222 *
223 * This kind of markup is typically used only in macros, but is useful
224 * anywhere.
225 *
226 * The syntax is pretty strict; there can be no spaces between the
227 * option name, the equals, and the first double-quote; the value
228 * must be surrounded by double-quotes. You can escape characters in
229 * the value with a backslash, and the backslash will be stripped for
230 * you.
231 *
232 * @access public
233 *
234 * @param string $text The "attributes" portion of markup.
235 *
236 * @return array An associative array of key-value pairs where the
237 * key is the option name and the value is the option value.
238 *
239 */
240
241 function getAttrs($text)
242 {
243 // find the =" sections;
244 $tmp = explode('="', trim($text));
245
246 // basic setup
247 $k = count($tmp) - 1;
248 $attrs = array();
249 $key = null;
250
251 // loop through the sections
252 foreach ($tmp as $i => $val) {
253
254 // first element is always the first key
255 if ($i == 0) {
256 $key = trim($val);
257 continue;
258 }
259
260 // find the last double-quote in the value.
261 // the part to the left is the value for the last key,
262 // the part to the right is the next key name
263 $pos = strrpos($val, '"');
264 $attrs[$key] = stripslashes(substr($val, 0, $pos));
265 $key = trim(substr($val, $pos+1));
266
267 }
268
269 return $attrs;
270
271 }
272 }
273 ?>