Project

General

Profile

1 4 ryan
<?php
2
/*
3
 * Session Management for PHP3
4
 *
5
 * (C) Copyright 1999-2000 NetUSE GmbH
6
 *                    Kristian Koehntopp
7
 *
8 522 Ruebenwurz
 * $Id: template.inc,v 1.15 2004/07/23 20:36:29 layne_weathers Exp $
9 4 ryan
 *
10
 */
11
12
/*
13
 * Change log since version 7.2c
14
 *
15
 * Bug fixes to version 7.2c compiled by Richard Archer <rha@juggernaut.com.au>:
16
 * (credits given to first person to post a diff to phplib mailing list)
17
 *
18
 * Normalised all comments and whitespace (rha)
19
 * replaced "$handle" with "$varname" and "$h" with "$v" throughout (from phplib-devel)
20
 * added braces around all one-line if statements in: get_undefined, loadfile and halt (rha)
21
 * set_var was missing two sets of braces (rha)
22
 * added a couple of "return true" statements (rha)
23
 * set_unknowns had "keep" as default instead of "remove" (from phplib-devel)
24
 * set_file failed to check for empty strings if passed an array of filenames (phplib-devel)
25
 * remove @ from call to preg_replace in subst -- report errors if there are any (NickM)
26
 * set_block unnecessarily required a newline in the template file (Marc Tardif)
27
 * pparse now calls this->finish to replace undefined vars (Layne Weathers)
28
 * get_var now checks for unset varnames (NickM & rha)
29
 * get_var when passed an array used the array key instead of the value (rha)
30
 * get_vars now uses a call to get_var rather than this->varvals to prevent undefined var warning (rha)
31
 * in finish, the replacement string referenced an unset variable (rha)
32
 * loadfile would try to load a file if the varval had been set to "" (rha)
33
 * in get_undefined, only match non-whitespace in variable tags as in finish (Layne Weathers & rha)
34
 * more elegant fix to the problem of subst stripping '$n', '\n' and '\\' strings (rha)
35 522 Ruebenwurz
 * parse uses get_var to obtain return value (Jordi via SF)
36
 * set_block reports an error if the block could not be extracted (rha)
37
 * filename is now windows-pathname aware (krabu @ SF)
38 4 ryan
 *
39
 *
40
 * Changes in functionality which go beyond bug fixes:
41
 *
42 522 Ruebenwurz
 * added ability for filename comments to be output (from phplib-users layne)
43 4 ryan
 * changed debug handling so set, get and internals can be tracked separately (rha)
44
 * added debug statements throughout to track most function calls (rha)
45
 * debug output contained raw HTML -- is now escaped with htmlentities (rha)
46
 * Alter regex in set_block to remove more whitespace around BEGIN/END tags to improve HTML layout (rha)
47
 * Add "append" option to set_var, works just like append in parse (dale at linuxwebpro.com, rha)
48
 * Altered parse so that append is honored if passed an array (Brian)
49
 * Converted comments and documentation to phpdoc style (rha)
50
 * Added clear_var to set the value of variables to "" (rha)
51
 * Added unset_var to usset variables (rha)
52
 *
53
 */
54
55
/**
56
 * The template class allows you to keep your HTML code in some external files
57
 * which are completely free of PHP code, but contain replacement fields.
58
 * The class provides you with functions which can fill in the replacement fields
59
 * with arbitrary strings. These strings can become very large, e.g. entire tables.
60
 *
61
 * Note: If you think that this is like FastTemplates, read carefully. It isn't.
62
 *
63
 */
64
65
class Template
66
{
67
 /**
68
  * Serialization helper, the name of this class.
69
  *
70
  * @var       string
71
  * @access    public
72
  */
73
  var $classname = "Template";
74
75
 /**
76
  * Determines how much debugging output Template will produce.
77
  * This is a bitwise mask of available debug levels:
78
  * 0 = no debugging
79
  * 1 = debug variable assignments
80
  * 2 = debug calls to get variable
81
  * 4 = debug internals (outputs all function calls with parameters).
82
  *
83
  * Note: setting $this->debug = true will enable debugging of variable
84
  * assignments only which is the same behaviour as versions up to release 7.2d.
85
  *
86
  * @var       int
87
  * @access    public
88
  */
89
  var $debug    = false;
90
91
 /**
92 522 Ruebenwurz
  * Determines whether Template outputs filename comments.
93
  * false = no filename outputs
94
  * true = HTML comments (e.g. <!-- START FILE $filename -->) placed in output
95
  *
96
  * @var       int
97
  * @access    public
98
  */
99
  var $filename_comments = false;
100
101
 /**
102
  * Determines the regular expression used to find unknown variable tags.
103
  * "loose"  = traditional match all curly braces with no whitespace between
104
  * "strict" = adopts PHP's variable naming rules
105
  *              ("loose" has a nasty habit of deleting JavaScript RegEx components)
106
  *              (should future major version releases of PHPLib default this "strict"?)
107
  *
108
  * @var       string
109
  * @access    public
110
  */
111
  var $unknown_regexp = "loose";
112
113
 /**
114 4 ryan
  * The base directory from which template files are loaded.
115
  *
116
  * @var       string
117
  * @access    private
118
  * @see       set_root
119
  */
120
  var $root     = ".";
121
122
 /**
123
  * A hash of strings forming a translation table which translates variable names
124
  * into names of files containing the variable content.
125
  * $file[varname] = "filename";
126
  *
127
  * @var       array
128
  * @access    private
129
  * @see       set_file
130
  */
131
  var $file     = array();
132
133
 /**
134
  * A hash of strings forming a translation table which translates variable names
135
  * into regular expressions for themselves.
136
  * $varkeys[varname] = "/varname/"
137
  *
138
  * @var       array
139
  * @access    private
140
  * @see       set_var
141
  */
142
  var $varkeys  = array();
143
144
 /**
145
  * A hash of strings forming a translation table which translates variable names
146
  * into values for their respective varkeys.
147
  * $varvals[varname] = "value"
148
  *
149
  * @var       array
150
  * @access    private
151
  * @see       set_var
152
  */
153
  var $varvals  = array();
154
155
 /**
156
  * Determines how to output variable tags with no assigned value in templates.
157
  *
158
  * @var       string
159
  * @access    private
160
  * @see       set_unknowns
161
  */
162
  var $unknowns = "remove";
163
164
 /**
165
  * Determines how Template handles error conditions.
166
  * "yes"      = the error is reported, then execution is halted
167
  * "report"   = the error is reported, then execution continues by returning "false"
168
  * "no"       = errors are silently ignored, and execution resumes reporting "false"
169
  *
170
  * @var       string
171
  * @access    public
172
  * @see       halt
173
  */
174
  var $halt_on_error  = "yes";
175
176
 /**
177
  * The last error message is retained in this variable.
178
  *
179
  * @var       string
180
  * @access    public
181
  * @see       halt
182
  */
183
  var $last_error     = "";
184
185
 /******************************************************************************
186
  * Class constructor. May be called with two optional parameters.
187
  * The first parameter sets the template directory the second parameter
188
  * sets the policy regarding handling of unknown variables.
189
  *
190
  * usage: Template([string $root = "."], [string $unknowns = "remove"])
191
  *
192
  * @param     $root        path to template directory
193
  * @param     $string      what to do with undefined variables
194
  * @see       set_root
195
  * @see       set_unknowns
196
  * @access    public
197
  * @return    void
198
  */
199
  function Template($root = ".", $unknowns = "remove") {
200
    if ($this->debug & 4) {
201
      echo "<p><b>Template:</b> root = $root, unknowns = $unknowns</p>\n";
202
    }
203
    $this->set_root($root);
204
    $this->set_unknowns($unknowns);
205
  }
206
207
208
 /******************************************************************************
209
  * Checks that $root is a valid directory and if so sets this directory as the
210
  * base directory from which templates are loaded by storing the value in
211
  * $this->root. Relative filenames are prepended with the path in $this->root.
212
  *
213
  * Returns true on success, false on error.
214
  *
215
  * usage: set_root(string $root)
216
  *
217
  * @param     $root         string containing new template directory
218
  * @see       root
219
  * @access    public
220
  * @return    boolean
221
  */
222
  function set_root($root) {
223 522 Ruebenwurz
    if(ereg('/$', $root)) {
224
      $root = substr($root, 0, -1);
225
    }
226 4 ryan
    if ($this->debug & 4) {
227
      echo "<p><b>set_root:</b> root = $root</p>\n";
228
    }
229
    if (!is_dir($root)) {
230
      $this->halt("set_root: $root is not a directory.");
231
      return false;
232
    }
233
234
    $this->root = $root;
235
    return true;
236
  }
237
238
239
 /******************************************************************************
240
  * Sets the policy for dealing with unresolved variable names.
241
  *
242
  * unknowns defines what to do with undefined template variables
243
  * "remove"   = remove undefined variables
244
  * "comment"  = replace undefined variables with comments
245
  * "keep"     = keep undefined variables
246
  *
247
  * Note: "comment" can cause unexpected results when the variable tag is embedded
248
  * inside an HTML tag, for example a tag which is expected to be replaced with a URL.
249
  *
250
  * usage: set_unknowns(string $unknowns)
251
  *
252
  * @param     $unknowns         new value for unknowns
253
  * @see       unknowns
254
  * @access    public
255
  * @return    void
256
  */
257
  function set_unknowns($unknowns = "remove") {
258
    if ($this->debug & 4) {
259
      echo "<p><b>unknowns:</b> unknowns = $unknowns</p>\n";
260
    }
261
    $this->unknowns = $unknowns;
262
  }
263
264
265
 /******************************************************************************
266
  * Defines a filename for the initial value of a variable.
267
  *
268
  * It may be passed either a varname and a file name as two strings or
269
  * a hash of strings with the key being the varname and the value
270
  * being the file name.
271
  *
272
  * The new mappings are stored in the array $this->file.
273
  * The files are not loaded yet, but only when needed.
274
  *
275
  * Returns true on success, false on error.
276
  *
277
  * usage: set_file(array $filelist = (string $varname => string $filename))
278
  * or
279
  * usage: set_file(string $varname, string $filename)
280
  *
281
  * @param     $varname      either a string containing a varname or a hash of varname/file name pairs.
282
  * @param     $filename     if varname is a string this is the filename otherwise filename is not required
283
  * @access    public
284
  * @return    boolean
285
  */
286
  function set_file($varname, $filename = "") {
287
    if (!is_array($varname)) {
288
      if ($this->debug & 4) {
289
        echo "<p><b>set_file:</b> (with scalar) varname = $varname, filename = $filename</p>\n";
290
      }
291
      if ($filename == "") {
292
        $this->halt("set_file: For varname $varname filename is empty.");
293
        return false;
294
      }
295
      $this->file[$varname] = $this->filename($filename);
296
    } else {
297
      reset($varname);
298 522 Ruebenwurz
      while (list($v, $f) = each($varname)) {
299 4 ryan
        if ($this->debug & 4) {
300
          echo "<p><b>set_file:</b> (with array) varname = $v, filename = $f</p>\n";
301
        }
302
        if ($f == "") {
303
          $this->halt("set_file: For varname $v filename is empty.");
304
          return false;
305
        }
306
        $this->file[$v] = $this->filename($f);
307
      }
308
    }
309
    return true;
310
  }
311
312
313
 /******************************************************************************
314
  * A variable $parent may contain a variable block defined by:
315
  * &lt;!-- BEGIN $varname --&gt; content &lt;!-- END $varname --&gt;. This function removes
316
  * that block from $parent and replaces it with a variable reference named $name.
317
  * The block is inserted into the varkeys and varvals hashes. If $name is
318
  * omitted, it is assumed to be the same as $varname.
319
  *
320
  * Blocks may be nested but care must be taken to extract the blocks in order
321
  * from the innermost block to the outermost block.
322
  *
323
  * Returns true on success, false on error.
324
  *
325
  * usage: set_block(string $parent, string $varname, [string $name = ""])
326
  *
327
  * @param     $parent       a string containing the name of the parent variable
328
  * @param     $varname      a string containing the name of the block to be extracted
329
  * @param     $name         the name of the variable in which to store the block
330
  * @access    public
331
  * @return    boolean
332
  */
333
  function set_block($parent, $varname, $name = "") {
334
    if ($this->debug & 4) {
335
      echo "<p><b>set_block:</b> parent = $parent, varname = $varname, name = $name</p>\n";
336
    }
337
    if (!$this->loadfile($parent)) {
338
      $this->halt("set_block: unable to load $parent.");
339
      return false;
340
    }
341
    if ($name == "") {
342
      $name = $varname;
343
    }
344
345
    $str = $this->get_var($parent);
346
    $reg = "/[ \t]*<!--\s+BEGIN $varname\s+-->\s*?\n?(\s*.*?\n?)\s*<!--\s+END $varname\s+-->\s*?\n?/sm";
347
    preg_match_all($reg, $str, $m);
348 522 Ruebenwurz
    if (!isset($m[1][0])) {
349
      $this->halt("set_block: unable to set block $varname.");
350
      return false;
351
    }
352
    $str = preg_replace($reg, "{" . $name . "}", $str);
353 4 ryan
    $this->set_var($varname, $m[1][0]);
354
    $this->set_var($parent, $str);
355
    return true;
356
  }
357
358
359
 /******************************************************************************
360
  * This functions sets the value of a variable.
361
  *
362
  * It may be called with either a varname and a value as two strings or an
363
  * an associative array with the key being the varname and the value being
364
  * the new variable value.
365
  *
366
  * The function inserts the new value of the variable into the $varkeys and
367
  * $varvals hashes. It is not necessary for a variable to exist in these hashes
368
  * before calling this function.
369
  *
370
  * An optional third parameter allows the value for each varname to be appended
371
  * to the existing variable instead of replacing it. The default is to replace.
372
  * This feature was introduced after the 7.2d release.
373
  *
374
  *
375
  * usage: set_var(string $varname, [string $value = ""], [boolean $append = false])
376
  * or
377
  * usage: set_var(array $varname = (string $varname => string $value), [mixed $dummy_var], [boolean $append = false])
378
  *
379
  * @param     $varname      either a string containing a varname or a hash of varname/value pairs.
380
  * @param     $value        if $varname is a string this contains the new value for the variable otherwise this parameter is ignored
381
  * @param     $append       if true, the value is appended to the variable's existing value
382
  * @access    public
383
  * @return    void
384
  */
385
  function set_var($varname, $value = "", $append = false) {
386
    if (!is_array($varname)) {
387
      if (!empty($varname)) {
388
        if ($this->debug & 1) {
389
          printf("<b>set_var:</b> (with scalar) <b>%s</b> = '%s'<br>\n", $varname, htmlentities($value));
390
        }
391
        $this->varkeys[$varname] = "/".$this->varname($varname)."/";
392
        if ($append && isset($this->varvals[$varname])) {
393
          $this->varvals[$varname] .= $value;
394
        } else {
395
          $this->varvals[$varname] = $value;
396
        }
397
      }
398
    } else {
399
      reset($varname);
400 522 Ruebenwurz
      while (list($k, $v) = each($varname)) {
401 4 ryan
        if (!empty($k)) {
402
          if ($this->debug & 1) {
403
            printf("<b>set_var:</b> (with array) <b>%s</b> = '%s'<br>\n", $k, htmlentities($v));
404
          }
405
          $this->varkeys[$k] = "/".$this->varname($k)."/";
406
          if ($append && isset($this->varvals[$k])) {
407
            $this->varvals[$k] .= $v;
408
          } else {
409
            $this->varvals[$k] = $v;
410
          }
411
        }
412
      }
413
    }
414
  }
415
416
417
 /******************************************************************************
418
  * This functions clears the value of a variable.
419
  *
420
  * It may be called with either a varname as a string or an array with the
421
  * values being the varnames to be cleared.
422
  *
423
  * The function sets the value of the variable in the $varkeys and $varvals
424
  * hashes to "". It is not necessary for a variable to exist in these hashes
425
  * before calling this function.
426
  *
427
  *
428
  * usage: clear_var(string $varname)
429
  * or
430
  * usage: clear_var(array $varname = (string $varname))
431
  *
432
  * @param     $varname      either a string containing a varname or an array of varnames.
433
  * @access    public
434
  * @return    void
435
  */
436
  function clear_var($varname) {
437
    if (!is_array($varname)) {
438
      if (!empty($varname)) {
439
        if ($this->debug & 1) {
440
          printf("<b>clear_var:</b> (with scalar) <b>%s</b><br>\n", $varname);
441
        }
442
        $this->set_var($varname, "");
443
      }
444
    } else {
445
      reset($varname);
446 522 Ruebenwurz
      while (list($k, $v) = each($varname)) {
447 4 ryan
        if (!empty($v)) {
448
          if ($this->debug & 1) {
449
            printf("<b>clear_var:</b> (with array) <b>%s</b><br>\n", $v);
450
          }
451
          $this->set_var($v, "");
452
        }
453
      }
454
    }
455
  }
456
457
458
 /******************************************************************************
459
  * This functions unsets a variable completely.
460
  *
461
  * It may be called with either a varname as a string or an array with the
462
  * values being the varnames to be cleared.
463
  *
464
  * The function removes the variable from the $varkeys and $varvals hashes.
465
  * It is not necessary for a variable to exist in these hashes before calling
466
  * this function.
467
  *
468
  *
469
  * usage: unset_var(string $varname)
470
  * or
471
  * usage: unset_var(array $varname = (string $varname))
472
  *
473
  * @param     $varname      either a string containing a varname or an array of varnames.
474
  * @access    public
475
  * @return    void
476
  */
477
  function unset_var($varname) {
478
    if (!is_array($varname)) {
479
      if (!empty($varname)) {
480
        if ($this->debug & 1) {
481
          printf("<b>unset_var:</b> (with scalar) <b>%s</b><br>\n", $varname);
482
        }
483
        unset($this->varkeys[$varname]);
484
        unset($this->varvals[$varname]);
485
      }
486
    } else {
487
      reset($varname);
488 522 Ruebenwurz
      while (list($k, $v) = each($varname)) {
489 4 ryan
        if (!empty($v)) {
490
          if ($this->debug & 1) {
491
            printf("<b>unset_var:</b> (with array) <b>%s</b><br>\n", $v);
492
          }
493
          unset($this->varkeys[$v]);
494
          unset($this->varvals[$v]);
495
        }
496
      }
497
    }
498
  }
499
500
501
 /******************************************************************************
502
  * This function fills in all the variables contained within the variable named
503
  * $varname. The resulting value is returned as the function result and the
504
  * original value of the variable varname is not changed. The resulting string
505
  * is not "finished", that is, the unresolved variable name policy has not been
506
  * applied yet.
507
  *
508
  * Returns: the value of the variable $varname with all variables substituted.
509
  *
510
  * usage: subst(string $varname)
511
  *
512
  * @param     $varname      the name of the variable within which variables are to be substituted
513
  * @access    public
514
  * @return    string
515
  */
516
  function subst($varname) {
517
    $varvals_quoted = array();
518
    if ($this->debug & 4) {
519
      echo "<p><b>subst:</b> varname = $varname</p>\n";
520
    }
521
    if (!$this->loadfile($varname)) {
522
      $this->halt("subst: unable to load $varname.");
523
      return false;
524
    }
525
526
    // quote the replacement strings to prevent bogus stripping of special chars
527
    reset($this->varvals);
528 522 Ruebenwurz
    while (list($k, $v) = each($this->varvals)) {
529 4 ryan
      $varvals_quoted[$k] = preg_replace(array('/\\\\/', '/\$/'), array('\\\\\\\\', '\\\\$'), $v);
530
    }
531
532
    $str = $this->get_var($varname);
533
    $str = preg_replace($this->varkeys, $varvals_quoted, $str);
534
    return $str;
535
  }
536
537
538
 /******************************************************************************
539
  * This is shorthand for print $this->subst($varname). See subst for further
540
  * details.
541
  *
542
  * Returns: always returns false.
543
  *
544
  * usage: psubst(string $varname)
545
  *
546
  * @param     $varname      the name of the variable within which variables are to be substituted
547
  * @access    public
548
  * @return    false
549
  * @see       subst
550
  */
551
  function psubst($varname) {
552
    if ($this->debug & 4) {
553
      echo "<p><b>psubst:</b> varname = $varname</p>\n";
554
    }
555
    print $this->subst($varname);
556
557
    return false;
558
  }
559
560
561
 /******************************************************************************
562
  * The function substitutes the values of all defined variables in the variable
563
  * named $varname and stores or appends the result in the variable named $target.
564
  *
565
  * It may be called with either a target and a varname as two strings or a
566
  * target as a string and an array of variable names in varname.
567
  *
568
  * The function inserts the new value of the variable into the $varkeys and
569
  * $varvals hashes. It is not necessary for a variable to exist in these hashes
570
  * before calling this function.
571
  *
572
  * An optional third parameter allows the value for each varname to be appended
573
  * to the existing target variable instead of replacing it. The default is to
574
  * replace.
575
  *
576
  * If $target and $varname are both strings, the substituted value of the
577
  * variable $varname is inserted into or appended to $target.
578
  *
579
  * If $handle is an array of variable names the variables named by $handle are
580
  * sequentially substituted and the result of each substitution step is
581
  * inserted into or appended to in $target. The resulting substitution is
582
  * available in the variable named by $target, as is each intermediate step
583
  * for the next $varname in sequence. Note that while it is possible, it
584
  * is only rarely desirable to call this function with an array of varnames
585
  * and with $append = true. This append feature was introduced after the 7.2d
586
  * release.
587
  *
588
  * Returns: the last value assigned to $target.
589
  *
590
  * usage: parse(string $target, string $varname, [boolean $append])
591
  * or
592
  * usage: parse(string $target, array $varname = (string $varname), [boolean $append])
593
  *
594
  * @param     $target      a string containing the name of the variable into which substituted $varnames are to be stored
595
  * @param     $varname     if a string, the name the name of the variable to substitute or if an array a list of variables to be substituted
596
  * @param     $append      if true, the substituted variables are appended to $target otherwise the existing value of $target is replaced
597
  * @access    public
598
  * @return    string
599
  * @see       subst
600
  */
601
  function parse($target, $varname, $append = false) {
602
    if (!is_array($varname)) {
603
      if ($this->debug & 4) {
604
        echo "<p><b>parse:</b> (with scalar) target = $target, varname = $varname, append = $append</p>\n";
605
      }
606
      $str = $this->subst($varname);
607
      if ($append) {
608
        $this->set_var($target, $this->get_var($target) . $str);
609
      } else {
610
        $this->set_var($target, $str);
611
      }
612
    } else {
613
      reset($varname);
614 522 Ruebenwurz
      while (list($i, $v) = each($varname)) {
615 4 ryan
        if ($this->debug & 4) {
616
          echo "<p><b>parse:</b> (with array) target = $target, i = $i, varname = $v, append = $append</p>\n";
617
        }
618
        $str = $this->subst($v);
619
        if ($append) {
620
          $this->set_var($target, $this->get_var($target) . $str);
621
        } else {
622
          $this->set_var($target, $str);
623
        }
624
      }
625
    }
626
627
    if ($this->debug & 4) {
628
      echo "<p><b>parse:</b> completed</p>\n";
629
    }
630 522 Ruebenwurz
    return $this->get_var($target);
631 4 ryan
  }
632
633
634
 /******************************************************************************
635
  * This is shorthand for print $this->parse(...) and is functionally identical.
636
  * See parse for further details.
637
  *
638
  * Returns: always returns false.
639
  *
640
  * usage: pparse(string $target, string $varname, [boolean $append])
641
  * or
642
  * usage: pparse(string $target, array $varname = (string $varname), [boolean $append])
643
  *
644
  * @param     $target      a string containing the name of the variable into which substituted $varnames are to be stored
645
  * @param     $varname     if a string, the name the name of the variable to substitute or if an array a list of variables to be substituted
646
  * @param     $append      if true, the substituted variables are appended to $target otherwise the existing value of $target is replaced
647
  * @access    public
648
  * @return    false
649
  * @see       parse
650
  */
651 569 thorn
  function pparse($target, $varname, $append = false, $clear = true) { // added $clear: whether to delete undefined vars or not (needed for wb-module code) - thorn
652 4 ryan
    if ($this->debug & 4) {
653
      echo "<p><b>pparse:</b> passing parameters to parse...</p>\n";
654
    }
655 569 thorn
		if($clear)
656
			print $this->finish($this->parse($target, $varname, $append));
657
		else
658
			print $this->parse($target, $varname, $append);
659 4 ryan
    return false;
660
  }
661
662
663
 /******************************************************************************
664
  * This function returns an associative array of all defined variables with the
665
  * name as the key and the value of the variable as the value.
666
  *
667
  * This is mostly useful for debugging. Also note that $this->debug can be used
668
  * to echo all variable assignments as they occur and to trace execution.
669
  *
670
  * Returns: a hash of all defined variable values keyed by their names.
671
  *
672
  * usage: get_vars()
673
  *
674
  * @access    public
675
  * @return    array
676
  * @see       $debug
677
  */
678
  function get_vars() {
679
    if ($this->debug & 4) {
680
      echo "<p><b>get_vars:</b> constructing array of vars...</p>\n";
681
    }
682
    reset($this->varkeys);
683 522 Ruebenwurz
    while (list($k, $v) = each($this->varkeys)) {
684 4 ryan
      $result[$k] = $this->get_var($k);
685
    }
686
    return $result;
687
  }
688
689
690
 /******************************************************************************
691
  * This function returns the value of the variable named by $varname.
692
  * If $varname references a file and that file has not been loaded yet, the
693
  * variable will be reported as empty.
694
  *
695
  * When called with an array of variable names this function will return a a
696
  * hash of variable values keyed by their names.
697
  *
698
  * Returns: a string or an array containing the value of $varname.
699
  *
700
  * usage: get_var(string $varname)
701
  * or
702
  * usage: get_var(array $varname)
703
  *
704
  * @param     $varname     if a string, the name the name of the variable to get the value of, or if an array a list of variables to return the value of
705
  * @access    public
706
  * @return    string or array
707
  */
708
  function get_var($varname) {
709
    if (!is_array($varname)) {
710
      if (isset($this->varvals[$varname])) {
711
        $str = $this->varvals[$varname];
712
      } else {
713
        $str = "";
714
      }
715
      if ($this->debug & 2) {
716
        printf ("<b>get_var</b> (with scalar) <b>%s</b> = '%s'<br>\n", $varname, htmlentities($str));
717
      }
718
      return $str;
719
    } else {
720
      reset($varname);
721 522 Ruebenwurz
      while (list($k, $v) = each($varname)) {
722 4 ryan
        if (isset($this->varvals[$v])) {
723
          $str = $this->varvals[$v];
724
        } else {
725
          $str = "";
726
        }
727
        if ($this->debug & 2) {
728
          printf ("<b>get_var:</b> (with array) <b>%s</b> = '%s'<br>\n", $v, htmlentities($str));
729
        }
730
        $result[$v] = $str;
731
      }
732
      return $result;
733
    }
734
  }
735
736
737
 /******************************************************************************
738
  * This function returns a hash of unresolved variable names in $varname, keyed
739
  * by their names (that is, the hash has the form $a[$name] = $name).
740
  *
741
  * Returns: a hash of varname/varname pairs or false on error.
742
  *
743
  * usage: get_undefined(string $varname)
744
  *
745
  * @param     $varname     a string containing the name the name of the variable to scan for unresolved variables
746
  * @access    public
747
  * @return    array
748
  */
749
  function get_undefined($varname) {
750
    if ($this->debug & 4) {
751
      echo "<p><b>get_undefined:</b> varname = $varname</p>\n";
752
    }
753
    if (!$this->loadfile($varname)) {
754
      $this->halt("get_undefined: unable to load $varname.");
755
      return false;
756
    }
757
758 522 Ruebenwurz
    preg_match_all(
759
        (("loose" == $this->unknown_regexp) ? "/{([^ \t\r\n}]+)}/" : "/{([_a-zA-Z]\\w+)}/"),
760
        $this->get_var($varname),
761
        $m);
762 4 ryan
    $m = $m[1];
763
    if (!is_array($m)) {
764
      return false;
765
    }
766
767
    reset($m);
768 522 Ruebenwurz
    while (list($k, $v) = each($m)) {
769 4 ryan
      if (!isset($this->varkeys[$v])) {
770
        if ($this->debug & 4) {
771
         echo "<p><b>get_undefined:</b> undefined: $v</p>\n";
772
        }
773
        $result[$v] = $v;
774
      }
775
    }
776
777
    if (count($result)) {
778
      return $result;
779
    } else {
780
      return false;
781
    }
782
  }
783
784
785
 /******************************************************************************
786
  * This function returns the finished version of $str. That is, the policy
787
  * regarding unresolved variable names will be applied to $str.
788
  *
789
  * Returns: a finished string derived from $str and $this->unknowns.
790
  *
791
  * usage: finish(string $str)
792
  *
793
  * @param     $str         a string to which to apply the unresolved variable policy
794
  * @access    public
795
  * @return    string
796
  * @see       set_unknowns
797
  */
798
  function finish($str) {
799
    switch ($this->unknowns) {
800
      case "keep":
801
      break;
802
803
      case "remove":
804 522 Ruebenwurz
        $str = preg_replace(
805
            (("loose" == $this->unknown_regexp) ? "/{([^ \t\r\n}]+)}/" : "/{([_a-zA-Z]\\w+)}/"),
806
            "",
807
            $str);
808 4 ryan
      break;
809
810
      case "comment":
811 522 Ruebenwurz
        $str = preg_replace(
812
             (("loose" == $this->unknown_regexp) ? "/{([^ \t\r\n}]+)}/" : "/{([_a-zA-Z]\\w+)}/"),
813
            "<!-- Template variable \\1 undefined -->",
814
            $str);
815 4 ryan
      break;
816
    }
817
818
    return $str;
819
  }
820
821
822
 /******************************************************************************
823
  * This function prints the finished version of the value of the variable named
824
  * by $varname. That is, the policy regarding unresolved variable names will be
825
  * applied to the variable $varname then it will be printed.
826
  *
827
  * usage: p(string $varname)
828
  *
829
  * @param     $varname     a string containing the name of the variable to finish and print
830
  * @access    public
831
  * @return    void
832
  * @see       set_unknowns
833
  * @see       finish
834
  */
835
  function p($varname) {
836
    print $this->finish($this->get_var($varname));
837
  }
838
839
840
 /******************************************************************************
841
  * This function returns the finished version of the value of the variable named
842
  * by $varname. That is, the policy regarding unresolved variable names will be
843
  * applied to the variable $varname and the result returned.
844
  *
845
  * Returns: a finished string derived from the variable $varname.
846
  *
847
  * usage: get(string $varname)
848
  *
849
  * @param     $varname     a string containing the name of the variable to finish
850
  * @access    public
851
  * @return    void
852
  * @see       set_unknowns
853
  * @see       finish
854
  */
855
  function get($varname) {
856
    return $this->finish($this->get_var($varname));
857
  }
858
859
860
 /******************************************************************************
861
  * When called with a relative pathname, this function will return the pathname
862
  * with $this->root prepended. Absolute pathnames are returned unchanged.
863
  *
864
  * Returns: a string containing an absolute pathname.
865
  *
866
  * usage: filename(string $filename)
867
  *
868
  * @param     $filename    a string containing a filename
869
  * @access    private
870
  * @return    string
871
  * @see       set_root
872
  */
873
  function filename($filename) {
874
    if ($this->debug & 4) {
875
      echo "<p><b>filename:</b> filename = $filename</p>\n";
876
    }
877 522 Ruebenwurz
    if (substr($filename, 0, 1) != "/"
878
       && substr($filename, 0, 1) != "\\"
879
       && substr($filename, 1, 2) != ":\\"
880
       && substr($filename, 1, 2) != ":/"
881
    ) {
882 4 ryan
      $filename = $this->root."/".$filename;
883
    }
884
885
    if (!file_exists($filename)) {
886
      $this->halt("filename: file $filename does not exist.");
887
    }
888
    return $filename;
889
  }
890
891
892
 /******************************************************************************
893
  * This function will construct a regexp for a given variable name with any
894
  * special chars quoted.
895
  *
896
  * Returns: a string containing an escaped variable name.
897
  *
898
  * usage: varname(string $varname)
899
  *
900
  * @param     $varname    a string containing a variable name
901
  * @access    private
902
  * @return    string
903
  */
904
  function varname($varname) {
905 522 Ruebenwurz
    return preg_quote("{" . $varname . "}");
906 4 ryan
  }
907
908
909
 /******************************************************************************
910
  * If a variable's value is undefined and the variable has a filename stored in
911
  * $this->file[$varname] then the backing file will be loaded and the file's
912
  * contents will be assigned as the variable's value.
913
  *
914
  * Note that the behaviour of this function changed slightly after the 7.2d
915
  * release. Where previously a variable was reloaded from file if the value
916
  * was empty, now this is not done. This allows a variable to be loaded then
917
  * set to "", and also prevents attempts to load empty variables. Files are
918
  * now only loaded if $this->varvals[$varname] is unset.
919
  *
920
  * Returns: true on success, false on error.
921
  *
922
  * usage: loadfile(string $varname)
923
  *
924
  * @param     $varname    a string containing the name of a variable to load
925
  * @access    private
926
  * @return    boolean
927
  * @see       set_file
928
  */
929
  function loadfile($varname) {
930
    if ($this->debug & 4) {
931
      echo "<p><b>loadfile:</b> varname = $varname</p>\n";
932
    }
933
934
    if (!isset($this->file[$varname])) {
935
      // $varname does not reference a file so return
936
      if ($this->debug & 4) {
937
        echo "<p><b>loadfile:</b> varname $varname does not reference a file</p>\n";
938
      }
939
      return true;
940
    }
941
942
    if (isset($this->varvals[$varname])) {
943
      // will only be unset if varname was created with set_file and has never been loaded
944
      // $varname has already been loaded so return
945
      if ($this->debug & 4) {
946
        echo "<p><b>loadfile:</b> varname $varname is already loaded</p>\n";
947
      }
948
      return true;
949
    }
950
    $filename = $this->file[$varname];
951
952
    /* use @file here to avoid leaking filesystem information if there is an error */
953
    $str = implode("", @file($filename));
954
    if (empty($str)) {
955
      $this->halt("loadfile: While loading $varname, $filename does not exist or is empty.");
956
      return false;
957
    }
958
959 522 Ruebenwurz
    if ($this->filename_comments) {
960
      $str = "<!-- START FILE $filename -->\n$str<!-- END FILE $filename -->\n";
961
    }
962 4 ryan
    if ($this->debug & 4) {
963
      printf("<b>loadfile:</b> loaded $filename into $varname<br>\n");
964
    }
965
    $this->set_var($varname, $str);
966
967
    return true;
968
  }
969
970
971
 /******************************************************************************
972
  * This function is called whenever an error occurs and will handle the error
973
  * according to the policy defined in $this->halt_on_error. Additionally the
974
  * error message will be saved in $this->last_error.
975
  *
976
  * Returns: always returns false.
977
  *
978
  * usage: halt(string $msg)
979
  *
980
  * @param     $msg         a string containing an error message
981
  * @access    private
982
  * @return    void
983
  * @see       $halt_on_error
984
  */
985
  function halt($msg) {
986
    $this->last_error = $msg;
987
988
    if ($this->halt_on_error != "no") {
989
      $this->haltmsg($msg);
990
    }
991
992
    if ($this->halt_on_error == "yes") {
993
      die("<b>Halted.</b>");
994
    }
995
996
    return false;
997
  }
998
999
1000
 /******************************************************************************
1001
  * This function prints an error message.
1002
  * It can be overridden by your subclass of Template. It will be called with an
1003
  * error message to display.
1004
  *
1005
  * usage: haltmsg(string $msg)
1006
  *
1007
  * @param     $msg         a string containing the error message to display
1008
  * @access    public
1009
  * @return    void
1010
  * @see       halt
1011
  */
1012
  function haltmsg($msg) {
1013
    printf("<b>Template Error:</b> %s<br>\n", $msg);
1014
  }
1015
1016
}
1017
?>