[Sommaire] [Imprimer]

   1  <?php
   2  
   3  /**
   4  * 
   5  * Parse structured wiki text and render into arbitrary formats such as XHTML.
   6  * 
   7  * @category Text
   8  * 
   9  * @package Text_Wiki
  10  * 
  11  * @author Paul M. Jones <pmjones@ciaweb.net>
  12  * 
  13  * @license LGPL
  14  * 
  15  * @version $Id: Wiki.php,v 1.27 2005/02/01 16:56:56 pmjones Exp $
  16  * 
  17  */
  18  
  19  /**
  20  * The baseline abstract parser class.
  21  */
  22  
  23  require_once dirname(__FILE__) . '/Wiki/Parse.php';
  24  
  25  /**
  26  * The baseline abstract render class.
  27  */
  28  
  29  require_once dirname(__FILE__) . '/Wiki/Render.php';
  30  
  31  
  32  /**
  33  * 
  34  * Parse structured wiki text and render into arbitrary formats such as XHTML.
  35  * 
  36  * This is the "master" class for handling the management and convenience
  37  * functions to transform Wiki-formatted text.
  38  * 
  39  * @category Text
  40  * 
  41  * @package Text_Wiki
  42  * 
  43  * @version 0.25.0 beta
  44  * 
  45  */
  46  
  47  class Text_Wiki {
  48      
  49      /**
  50      * 
  51      * The default list of rules, in order, to apply to the source text.
  52      * 
  53      * @access public
  54      * 
  55      * @var array
  56      * 
  57      */
  58      
  59      var $rules = array(
  60          'Prefilter',
  61          'Delimiter',
  62          'Code',
  63          'Function',
  64          'Html',
  65          'Raw',
  66          'Include',
  67          'Embed',
  68          'Anchor',
  69          'Heading',
  70          'Toc',
  71          'Horiz',
  72          'Break',
  73          'Blockquote',
  74          'List',
  75          'Deflist',
  76          'Table',
  77          'Image',
  78          'Phplookup',
  79          'Center',
  80          'Newline',
  81          'Paragraph',
  82          'Url',
  83          'Freelink',
  84          'Interwiki',
  85          'Wikilink',
  86          'Colortext',
  87          'Strong',
  88          'Bold',
  89          'Emphasis',
  90          'Italic',
  91          'Tt',
  92          'Superscript',
  93          'Revise',
  94          'Tighten'
  95      );
  96      
  97      
  98      /**
  99      * 
 100      * The list of rules to not-apply to the source text.
 101      * 
 102      * @access public
 103      * 
 104      * @var array
 105      * 
 106      */
 107      
 108      var $disable = array(
 109          'Html',
 110          'Include',
 111          'Embed'
 112      );
 113      
 114      
 115      /**
 116      * 
 117      * Custom configuration for rules at the parsing stage.
 118      *
 119      * In this array, the key is the parsing rule name, and the value is
 120      * an array of key-value configuration pairs corresponding to the $conf
 121      * property in the target parsing rule.
 122      * 
 123      * For example:
 124      * 
 125      * <code>
 126      * $parseConf = array(
 127      *     'Include' => array(
 128      *         'base' => '/path/to/scripts/'
 129      *     )
 130      * );
 131      * </code>
 132      * 
 133      * Note that most default rules do not need any parsing configuration.
 134      * 
 135      * @access public
 136      * 
 137      * @var array
 138      * 
 139      */
 140      
 141      var $parseConf = array();
 142      
 143      
 144      /**
 145      * 
 146      * Custom configuration for rules at the rendering stage.
 147      *
 148      * Because rendering may be different for each target format, the
 149      * first-level element in this array is always a format name (e.g.,
 150      * 'Xhtml').
 151      * 
 152      * Within that first level element, the subsequent elements match the
 153      * $parseConf format. That is, the sub-key is the rendering rule name,
 154      * and the sub-value is an array of key-value configuration pairs
 155      * corresponding to the $conf property in the target rendering rule.
 156      * 
 157      * @access public
 158      * 
 159      * @var array
 160      * 
 161      */
 162      
 163      var $renderConf = array(
 164          'Docbook' => array(),
 165          'Latex' => array(),
 166          'Pdf' => array(),
 167          'Plain' => array(),
 168          'Rtf' => array(),
 169          'Xhtml' => array()
 170      );
 171      
 172      
 173      /**
 174      * 
 175      * Custom configuration for the output format itself.
 176      *
 177      * Even though Text_Wiki will render the tokens from parsed text,
 178      * the format itself may require some configuration.  For example,
 179      * RTF needs to know font names and sizes, PDF requires page layout
 180      * information, and DocBook needs a section hierarchy.  This array
 181      * matches the $conf property of the the format-level renderer
 182      * (e.g., Text_Wiki_Render_Xhtml).
 183      * 
 184      * In this array, the key is the rendering format name, and the value is
 185      * an array of key-value configuration pairs corresponding to the $conf
 186      * property in the rendering format rule.
 187      * 
 188      * @access public
 189      * 
 190      * @var array
 191      * 
 192      */
 193      
 194      var $formatConf = array(
 195          'Docbook' => array(),
 196          'Latex' => array(),
 197          'Pdf' => array(),
 198          'Plain' => array(),
 199          'Rtf' => array(),
 200          'Xhtml' => array()
 201      );
 202      
 203      
 204      /**
 205      * 
 206      * The delimiter for token numbers of parsed elements in source text.
 207      * 
 208      * @access public
 209      * 
 210      * @var string
 211      * 
 212      */
 213      
 214      var $delim = "\xFF"; 
 215      
 216      
 217      /**
 218      * 
 219      * The tokens generated by rules as the source text is parsed.
 220      * 
 221      * As Text_Wiki applies rule classes to the source text, it will
 222      * replace portions of the text with a delimited token number.  This
 223      * is the array of those tokens, representing the replaced text and
 224      * any options set by the parser for that replaced text.
 225      * 
 226      * The tokens array is sequential; each element is itself a sequential
 227      * array where element 0 is the name of the rule that generated the
 228      * token, and element 1 is an associative array where the key is an
 229      * option name and the value is an option value.
 230      * 
 231      * @access private
 232      * 
 233      * @var array
 234      * 
 235      */
 236      
 237      var $tokens = array();
 238      
 239      
 240      /**
 241      * 
 242      * The source text to which rules will be applied.
 243      * 
 244      * This text will be transformed in-place, which means that it will
 245      * change as the rules are applied.
 246      * 
 247      * @access private
 248      * 
 249      * @var string
 250      * 
 251      */
 252      
 253      var $source = '';
 254      
 255      
 256      /**
 257      * 
 258      * Array of rule parsers.
 259      * 
 260      * Text_Wiki creates one instance of every rule that is applied to
 261      * the source text; this array holds those instances.  The array key
 262      * is the rule name, and the array value is an instance of the rule
 263      * class.
 264      * 
 265      * @access private
 266      * 
 267      * @var array
 268      * 
 269      */
 270      
 271      var $parseObj = array();
 272      
 273      
 274      /**
 275      * 
 276      * Array of rule renderers.
 277      * 
 278      * Text_Wiki creates one instance of every rule that is applied to
 279      * the source text; this array holds those instances.  The array key
 280      * is the rule name, and the array value is an instance of the rule
 281      * class.
 282      * 
 283      * @access private
 284      * 
 285      * @var array
 286      * 
 287      */
 288      
 289      var $renderObj = array();
 290      
 291      
 292      /**
 293      * 
 294      * Array of format renderers.
 295      * 
 296      * @access private
 297      * 
 298      * @var array
 299      * 
 300      */
 301      
 302      var $formatObj = array();
 303      
 304      
 305      /**
 306      * 
 307      * Array of paths to search, in order, for parsing and rendering rules.
 308      * 
 309      * @access private
 310      * 
 311      * @var array
 312      * 
 313      */
 314      
 315      var $path = array(
 316          'parse' => array(),
 317          'render' => array()
 318      );
 319      
 320      
 321      
 322      /**
 323      * 
 324      * The directory separator character.
 325      * 
 326      * @access private
 327      * 
 328      * @var string
 329      * 
 330      */
 331      
 332      var $_dirSep = DIRECTORY_SEPARATOR;
 333      
 334      
 335      /**
 336      * 
 337      * Constructor.
 338      * 
 339      * @access public
 340      * 
 341      * @param array $rules The set of rules to load for this object.
 342      *     
 343      */
 344      
 345      function Text_Wiki($rules = null)
 346      {
 347          if (is_array($rules)) {
 348              $this->rules = $rules;
 349          }
 350          
 351          $this->addPath(
 352              'parse',
 353              $this->fixPath(dirname(__FILE__)) . 'Wiki/Parse/Default/'
 354          );
 355          
 356          $this->addPath(
 357              'render',
 358              $this->fixPath(dirname(__FILE__)) . 'Wiki/Render/'
 359          );
 360          
 361      }
 362      
 363      
 364      /**
 365      * 
 366      * Set parser configuration for a specific rule and key.
 367      * 
 368      * @access public
 369      * 
 370      * @param string $rule The parse rule to set config for.
 371      * 
 372      * @param array|string $arg1 The full config array to use for the
 373      * parse rule, or a conf key in that array.
 374      * 
 375      * @param string $arg2 The config value for the key.
 376      * 
 377      * @return void
 378      *
 379      */
 380      
 381      function setParseConf($rule, $arg1, $arg2 = null)
 382      {
 383          $rule = ucwords(strtolower($rule));
 384          
 385          if (! isset($this->parseConf[$rule])) {
 386              $this->parseConf[$rule] = array();
 387          }
 388          
 389          // if first arg is an array, use it as the entire
 390          // conf array for the rule.  otherwise, treat arg1
 391          // as a key and arg2 as a value for the rule conf.
 392          if (is_array($arg1)) {
 393              $this->parseConf[$rule] = $arg1;
 394          } else {
 395              $this->parseConf[$rule][$arg1] = $arg2;
 396          }
 397      }
 398      
 399      
 400      /**
 401      * 
 402      * Get parser configuration for a specific rule and key.
 403      * 
 404      * @access public
 405      * 
 406      * @param string $rule The parse rule to get config for.
 407      * 
 408      * @param string $key A key in the conf array; if null,
 409      * returns the entire conf array.
 410      * 
 411      * @return mixed The whole conf array if no key is specified,
 412      * or the specific conf key value.
 413      *
 414      */
 415      
 416      function getParseConf($rule, $key = null)
 417      {
 418          $rule = ucwords(strtolower($rule));
 419          
 420          // the rule does not exist
 421          if (! isset($this->parseConf[$rule])) {
 422              return null;
 423          }
 424          
 425          // no key requested, return the whole array
 426          if (is_null($key)) {
 427              return $this->parseConf[$rule];
 428          }
 429          
 430          // does the requested key exist?
 431          if (isset($this->parseConf[$rule][$key])) {
 432              // yes, return that value
 433              return $this->parseConf[$rule][$key];
 434          } else {
 435              // no
 436              return null;
 437          }
 438      }
 439      
 440      
 441      /**
 442      * 
 443      * Set renderer configuration for a specific format, rule, and key.
 444      * 
 445      * @access public
 446      * 
 447      * @param string $format The render format to set config for.
 448      * 
 449      * @param string $rule The render rule to set config for in the format.
 450      * 
 451      * @param array|string $arg1 The config array, or the config key
 452      * within the render rule.
 453      * 
 454      * @param string $arg2 The config value for the key.
 455      * 
 456      * @return void
 457      *
 458      */
 459      
 460      function setRenderConf($format, $rule, $arg1, $arg2 = null)
 461      {
 462          $format = ucwords(strtolower($format));
 463          $rule = ucwords(strtolower($rule));
 464          
 465          if (! isset($this->renderConf[$format])) {
 466              $this->renderConf[$format] = array();
 467          }
 468          
 469          if (! isset($this->renderConf[$format][$rule])) {
 470              $this->renderConf[$format][$rule] = array();
 471          }
 472          
 473          // if first arg is an array, use it as the entire
 474          // conf array for the render rule.  otherwise, treat arg1
 475          // as a key and arg2 as a value for the render rule conf.
 476          if (is_array($arg1)) {
 477              $this->renderConf[$format][$rule] = $arg1;
 478          } else {
 479              $this->renderConf[$format][$rule][$arg1] = $arg2;
 480          }
 481      }
 482      
 483      
 484      /**
 485      * 
 486      * Get renderer configuration for a specific format, rule, and key.
 487      * 
 488      * @access public
 489      * 
 490      * @param string $format The render format to get config for.
 491      * 
 492      * @param string $rule The render format rule to get config for.
 493      * 
 494      * @param string $key A key in the conf array; if null,
 495      * returns the entire conf array.
 496      * 
 497      * @return mixed The whole conf array if no key is specified,
 498      * or the specific conf key value.
 499      *
 500      */
 501      
 502      function getRenderConf($format, $rule, $key = null)
 503      {
 504          $format = ucwords(strtolower($format));
 505          $rule = ucwords(strtolower($rule));
 506          
 507          if (! isset($this->renderConf[$format]) ||
 508              ! isset($this->renderConf[$format][$rule])) {
 509              return null;
 510          }
 511          
 512          // no key requested, return the whole array
 513          if (is_null($key)) {
 514              return $this->renderConf[$format][$rule];
 515          }
 516          
 517          // does the requested key exist?
 518          if (isset($this->renderConf[$format][$rule][$key])) {
 519              // yes, return that value
 520              return $this->renderConf[$format][$rule][$key];
 521          } else {
 522              // no
 523              return null;
 524          }
 525          
 526      }
 527      
 528      /**
 529      * 
 530      * Set format configuration for a specific rule and key.
 531      * 
 532      * @access public
 533      * 
 534      * @param string $format The format to set config for.
 535      * 
 536      * @param string $key The config key within the format.
 537      * 
 538      * @param string $val The config value for the key.
 539      * 
 540      * @return void
 541      *
 542      */
 543      
 544      function setFormatConf($format, $arg1, $arg2 = null)
 545      {
 546          if (! is_array($this->formatConf[$format])) {
 547              $this->formatConf[$format] = array();
 548          }
 549          
 550          // if first arg is an array, use it as the entire
 551          // conf array for the format.  otherwise, treat arg1
 552          // as a key and arg2 as a value for the format conf.
 553          if (is_array($arg1)) {
 554              $this->formatConf[$format] = $arg1;
 555          } else {
 556              $this->formatConf[$format][$arg1] = $arg2;
 557          }
 558      }
 559      
 560      
 561      
 562      /**
 563      * 
 564      * Get configuration for a specific format and key.
 565      * 
 566      * @access public
 567      * 
 568      * @param string $format The format to get config for.
 569      * 
 570      * @param mixed $key A key in the conf array; if null,
 571      * returns the entire conf array.
 572      * 
 573      * @return mixed The whole conf array if no key is specified,
 574      * or the specific conf key value.
 575      *
 576      */
 577      
 578      function getFormatConf($format, $key = null)
 579      {
 580          // the format does not exist
 581          if (! isset($this->formatConf[$format])) {
 582              return null;
 583          }
 584          
 585          // no key requested, return the whole array
 586          if (is_null($key)) {
 587              return $this->formatConf[$format];
 588          }
 589          
 590          // does the requested key exist?
 591          if (isset($this->formatConf[$format][$key])) {
 592              // yes, return that value
 593              return $this->formatConf[$format][$key];
 594          } else {
 595              // no
 596              return null;
 597          }
 598      }
 599      
 600      
 601      /**
 602      * 
 603      * Inserts a rule into to the rule set.
 604      * 
 605      * @access public
 606      * 
 607      * @param string $name The name of the rule.  Should be different from
 608      * all other keys in the rule set.
 609      * 
 610      * @param string $tgt The rule after which to insert this new rule.  By
 611      * default (null) the rule is inserted at the end; if set to '', inserts
 612      * at the beginning.
 613      * 
 614      * @return void
 615      * 
 616      */
 617      
 618      function insertRule($name, $tgt = null)
 619      {
 620          $name = ucwords(strtolower($name));
 621          if (! is_null($tgt)) {
 622              $tgt = ucwords(strtolower($tgt));
 623          }
 624          
 625          // does the rule name to be inserted already exist?
 626          if (in_array($name, $this->rules)) {
 627              // yes, return
 628              return null;
 629          }
 630          
 631          // the target name is not null, and not '', but does not exist
 632          // in the list of rules. this means we're trying to insert after
 633          // a target key, but the target key isn't there.
 634          if (! is_null($tgt) && $tgt != '' &&
 635              ! in_array($tgt, $this->rules)) {
 636              return false;
 637          }
 638          
 639          // if $tgt is null, insert at the end.  We know this is at the
 640          // end (instead of resetting an existing rule) becuase we exited
 641          // at the top of this method if the rule was already in place.
 642          if (is_null($tgt)) {
 643              $this->rules[] = $name;
 644              return true;
 645          }
 646          
 647          // save a copy of the current rules, then reset the rule set
 648          // so we can insert in the proper place later.
 649          // where to insert the rule?
 650          if ($tgt == '') {
 651              // insert at the beginning
 652              array_unshift($this->rules, $name);
 653              return true;
 654          }
 655          
 656          // insert after the named rule
 657          $tmp = $this->rules;
 658          $this->rules = array();
 659          
 660          foreach ($tmp as $val) {
 661              $this->rules[] = $val;
 662              if ($val == $tgt) {
 663                  $this->rules[] = $name;
 664              }
 665          }
 666          
 667          return true;
 668          
 669      }
 670      
 671      
 672      /**
 673      * 
 674      * Delete (remove or unset) a rule from the $rules property.
 675      * 
 676      * @access public
 677      * 
 678      * @param string $rule The name of the rule to remove.
 679      * 
 680      * @return void
 681      *     
 682      */
 683      
 684      function deleteRule($name)
 685      {
 686          $name = ucwords(strtolower($name));
 687          $key = array_search($name, $this->rules);
 688          if ($key !== false) {
 689              unset($this->rules[$key]);
 690          }
 691      }
 692      
 693      
 694      /**
 695      * 
 696      * Change from one rule to another in-place.
 697      * 
 698      * @access public
 699      * 
 700      * @param string $old The name of the rule to change from.
 701      * 
 702      * @param string $new The name of the rule to change to.
 703      * 
 704      * @return void
 705      *     
 706      */
 707      
 708      function changeRule($old, $new)
 709      {
 710          $old = ucwords(strtolower($old));
 711          $new = ucwords(strtolower($new));
 712          $key = array_search($old, $this->rules);
 713          if ($key !== false) {
 714              $this->rules[$old] = $new;
 715          }
 716      }
 717      
 718      
 719      /**
 720      * 
 721      * Enables a rule so that it is applied when parsing.
 722      * 
 723      * @access public
 724      * 
 725      * @param string $rule The name of the rule to enable.
 726      * 
 727      * @return void
 728      *     
 729      */
 730      
 731      function enableRule($name)
 732      {
 733          $name = ucwords(strtolower($name));
 734          $key = array_search($name, $this->disable);
 735          if ($key !== false) {
 736              unset($this->disable[$key]);
 737          }
 738      }
 739      
 740      
 741      /**
 742      * 
 743      * Disables a rule so that it is not applied when parsing.
 744      * 
 745      * @access public
 746      * 
 747      * @param string $rule The name of the rule to disable.
 748      * 
 749      * @return void
 750      *     
 751      */
 752      
 753      function disableRule($name)
 754      {
 755          $name = ucwords(strtolower($name));
 756          $key = array_search($name, $this->disable);
 757          if ($key === false) {
 758              $this->disable[] = $name;
 759          }
 760      }
 761      
 762      
 763      /**
 764      * 
 765      * Parses and renders the text passed to it, and returns the results.
 766      * 
 767      * First, the method parses the source text, applying rules to the
 768      * text as it goes.  These rules will modify the source text
 769      * in-place, replacing some text with delimited tokens (and
 770      * populating the $this->tokens array as it goes).
 771      * 
 772      * Next, the method renders the in-place tokens into the requested
 773      * output format.
 774      * 
 775      * Finally, the method returns the transformed text.  Note that the
 776      * source text is transformed in place; once it is transformed, it is
 777      * no longer the same as the original source text.
 778      * 
 779      * @access public
 780      * 
 781      * @param string $text The source text to which wiki rules should be
 782      * applied, both for parsing and for rendering.
 783      * 
 784      * @param string $format The target output format, typically 'xhtml'.
 785      *  If a rule does not support a given format, the output from that
 786      * rule is rule-specific.
 787      * 
 788      * @return string The transformed wiki text.
 789      * 
 790      */
 791      
 792      function transform($text, $format = 'Xhtml')
 793      {
 794          $this->parse($text);
 795          return $this->render($format);
 796      }
 797      
 798      
 799      /**
 800      * 
 801      * Sets the $_source text property, then parses it in place and
 802      * retains tokens in the $_tokens array property.
 803      * 
 804      * @access public
 805      * 
 806      * @param string $text The source text to which wiki rules should be
 807      * applied, both for parsing and for rendering.
 808      * 
 809      * @return void
 810      * 
 811      */
 812      
 813      function parse($text)
 814      {
 815          // set the object property for the source text
 816          $this->source = $text;
 817          
 818          // reset the tokens.
 819          $this->tokens = array();
 820          
 821          // apply the parse() method of each requested rule to the source
 822          // text.
 823          foreach ($this->rules as $name) {
 824              // do not parse the rules listed in $disable
 825              if (! in_array($name, $this->disable)) {
 826                  
 827                  // load the parsing object
 828                  $this->loadParseObj($name);
 829                  
 830                  // load may have failed; only parse if
 831                  // an object is in the array now
 832                  if (is_object($this->parseObj[$name])) {
 833                      $this->parseObj[$name]->parse();
 834                  }
 835              }
 836          }
 837      }
 838      
 839      
 840      /**
 841      * 
 842      * Renders tokens back into the source text, based on the requested format.
 843      * 
 844      * @access public
 845      * 
 846      * @param string $format The target output format, typically 'xhtml'. 
 847      * If a rule does not support a given format, the output from that
 848      * rule is rule-specific.
 849      * 
 850      * @return string The transformed wiki text.
 851      * 
 852      */
 853      
 854      function render($format = 'Xhtml')
 855      {
 856          // the rendering method we're going to use from each rule
 857          $format = ucwords(strtolower($format));
 858          
 859          // the eventual output text
 860          $output = '';
 861          
 862          // when passing through the parsed source text, keep track of when
 863          // we are in a delimited section
 864          $in_delim = false;
 865          
 866          // when in a delimited section, capture the token key number
 867          $key = '';
 868          
 869          // load the format object
 870          $this->loadFormatObj($format);
 871          
 872          // pre-rendering activity
 873          if (is_object($this->formatObj[$format])) {
 874              $output .= $this->formatObj[$format]->pre();
 875          }
 876          
 877          // load the render objects
 878          foreach (array_keys($this->parseObj) as $rule) {
 879              $this->loadRenderObj($format, $rule);
 880          }
 881          
 882          // pass through the parsed source text character by character
 883          $k = strlen($this->source);
 884          for ($i = 0; $i < $k; $i++) {
 885              
 886              // the current character
 887              $char = $this->source{$i};
 888              
 889              // are alredy in a delimited section?
 890              if ($in_delim) {
 891              
 892                  // yes; are we ending the section?
 893                  if ($char == $this->delim) {
 894                      
 895                      // yes, get the replacement text for the delimited
 896                      // token number and unset the flag.
 897                      $key = (int)$key;
 898                      $rule = $this->tokens[$key][0];
 899                      $opts = $this->tokens[$key][1];
 900                      $output .= $this->renderObj[$rule]->token($opts);
 901                      $in_delim = false;
 902                      
 903                  } else {
 904                  
 905                      // no, add to the dlimited token key number
 906                      $key .= $char;
 907                      
 908                  }
 909                  
 910              } else {
 911                  
 912                  // not currently in a delimited section.
 913                  // are we starting into a delimited section?
 914                  if ($char == $this->delim) {
 915                      // yes, reset the previous key and
 916                      // set the flag.
 917                      $key = '';
 918                      $in_delim = true;
 919                  } else {
 920                      // no, add to the output as-is
 921                      $output .= $char;
 922                  }
 923              }
 924          }
 925          
 926          // post-rendering activity
 927          if (is_object($this->formatObj[$format])) {
 928              $output .= $this->formatObj[$format]->post();
 929          }
 930          
 931          // return the rendered source text.
 932          return $output;
 933      }
 934      
 935      
 936      /**
 937      * 
 938      * Returns the parsed source text with delimited token placeholders.
 939      * 
 940      * @access public
 941      * 
 942      * @return string The parsed source text.
 943      * 
 944      */
 945      
 946      function getSource()
 947      {
 948          return $this->source;
 949      }
 950      
 951      
 952      /**
 953      * 
 954      * Returns tokens that have been parsed out of the source text.
 955      * 
 956      * @access public
 957      * 
 958      * @param array $rules If an array of rule names is passed, only return
 959      * tokens matching these rule names.  If no array is passed, return all
 960      * tokens.
 961      * 
 962      * @return array An array of tokens.
 963      * 
 964      */
 965      
 966      function getTokens($rules = null)
 967      {
 968          if (is_null($rules)) {
 969              return $this->tokens;
 970          } else {
 971              settype($rules, 'array');
 972              $result = array();
 973              foreach ($this->tokens as $key => $val) {
 974                  if (in_array($val[0], $rules)) {
 975                      $result[] = $val;
 976                  }
 977              }
 978              return $result;
 979          }
 980      }
 981      
 982      
 983      /**
 984      * 
 985      * Add a token to the Text_Wiki tokens array, and return a delimited
 986      * token number.
 987      * 
 988      * @access public
 989      * 
 990      * @param array $options An associative array of options for the new
 991      * token array element.  The keys and values are specific to the
 992      * rule, and may or may not be common to other rule options.  Typical
 993      * options keys are 'text' and 'type' but may include others.
 994      * 
 995      * @param boolean $id_only If true, return only the token number, not
 996      * a delimited token string.
 997      * 
 998      * @return string|int By default, return the number of the
 999      * newly-created token array element with a delimiter prefix and
1000      * suffix; however, if $id_only is set to true, return only the token
1001      * number (no delimiters).
1002      * 
1003      */
1004      
1005      function addToken($rule, $options = array(), $id_only = false)
1006      {
1007          // increment the token ID number.  note that if you parse
1008          // multiple times with the same Text_Wiki object, the ID number
1009          // will not reset to zero.
1010          static $id;
1011          if (! isset($id)) {
1012              $id = 0;
1013          } else {
1014              $id ++;
1015          }
1016          
1017          // force the options to be an array
1018          settype($options, 'array');
1019          
1020          // add the token
1021          $this->tokens[$id] = array(
1022              0 => $rule,
1023              1 => $options
1024          );
1025          
1026          // return a value
1027          if ($id_only) {
1028              // return the last token number
1029              return $id;
1030          } else {
1031              // return the token number with delimiters
1032              return $this->delim . $id . $this->delim;
1033          }
1034      }
1035      
1036      
1037      /**
1038      * 
1039      * Set or re-set a token with specific information, overwriting any
1040      * previous rule name and rule options.
1041      * 
1042      * @access public
1043      * 
1044      * @param int $id The token number to reset.
1045      * 
1046      * @param int $rule The rule name to use.
1047      * 
1048      * @param array $options An associative array of options for the
1049      * token array element.  The keys and values are specific to the
1050      * rule, and may or may not be common to other rule options.  Typical
1051      * options keys are 'text' and 'type' but may include others.
1052      * 
1053      * @return void
1054      * 
1055      */
1056      
1057      function setToken($id, $rule, $options = array())
1058      {
1059          // reset the token
1060          $this->tokens[$id] = array(
1061              0 => $rule,
1062              1 => $options
1063          );
1064      }
1065      
1066      
1067      /**
1068      * 
1069      * Load a rule parser class file.
1070      * 
1071      * @access public
1072      * 
1073      * @return bool True if loaded, false if not.
1074      * 
1075      */
1076      
1077      function loadParseObj($rule)
1078      {
1079          $rule = ucwords(strtolower($rule));
1080          $file = $rule . '.php';
1081          $class = "Text_Wiki_Parse_$rule";
1082          
1083          if (! class_exists($class)) {
1084              $loc = $this->findFile('parse', $file);
1085              if ($loc) {
1086                  // found the class
1087                  include_once $loc;
1088              } else {
1089                  // can't find the class
1090                  $this->parseObj[$rule] = null;
1091                  return false;
1092              }
1093          }
1094          
1095          $this->parseObj[$rule] =& new $class($this);
1096  
1097      }
1098      
1099      
1100      /**
1101      * 
1102      * Load a rule-render class file.
1103      * 
1104      * @access public
1105      * 
1106      * @return bool True if loaded, false if not.
1107      * 
1108      */
1109      
1110      function loadRenderObj($format, $rule)
1111      {
1112          $format = ucwords(strtolower($format));
1113          $rule = ucwords(strtolower($rule));
1114          $file = "$format/$rule.php";
1115          $class = "Text_Wiki_Render_$format" . "_$rule";
1116          
1117          if (! class_exists($class)) {
1118              // load the class
1119              $loc = $this->findFile('render', $file);
1120              if ($loc) {
1121                  // found the class
1122                  include_once $loc;
1123              } else {
1124                  // can't find the class
1125                  return false;
1126              }
1127          }
1128          
1129          $this->renderObj[$rule] =& new $class($this);
1130      }
1131      
1132      
1133      /**
1134      * 
1135      * Load a format-render class file.
1136      * 
1137      * @access public
1138      * 
1139      * @return bool True if loaded, false if not.
1140      * 
1141      */
1142      
1143      function loadFormatObj($format)
1144      {
1145          $format = ucwords(strtolower($format));
1146          $file = $format . '.php';
1147          $class = "Text_Wiki_Render_$format";
1148          
1149          if (! class_exists($class)) {
1150              $loc = $this->findFile('render', $file);
1151              if ($loc) {
1152                  // found the class
1153                  include_once $loc;
1154              } else {
1155                  // can't find the class
1156                  return false;
1157              }
1158          }
1159          
1160          $this->formatObj[$format] =& new $class($this);
1161      }
1162      
1163      
1164      /**
1165      * 
1166      * Add a path to a path array.
1167      * 
1168      * @access public
1169      * 
1170      * @param string $type The path-type to add (parse or render).
1171      * 
1172      * @param string $dir The directory to add to the path-type.
1173      * 
1174      * @return void
1175      * 
1176      */
1177      
1178      function addPath($type, $dir)
1179      {
1180          $dir = $this->fixPath($dir);
1181          if (! isset($this->path[$type])) {
1182              $this->path[$type] = array($dir);
1183          } else {
1184              array_unshift($this->path[$type], $dir);
1185          }
1186      }
1187      
1188      
1189      /**
1190      * 
1191      * Get the current path array for a path-type.
1192      * 
1193      * @access public
1194      * 
1195      * @param string $type The path-type to look up (plugin, filter, or
1196      * template).  If not set, returns all path types.
1197      * 
1198      * @return array The array of paths for the requested type.
1199      * 
1200      */
1201      
1202      function getPath($type = null)
1203      {
1204          if (is_null($type)) {
1205              return $this->path;
1206          } elseif (! isset($this->path[$type])) {
1207              return array();
1208          } else {
1209              return $this->path[$type];
1210          }
1211      }
1212      
1213      
1214      /**
1215      * 
1216      * Searches a series of paths for a given file.
1217      * 
1218      * @param array $type The type of paths to search (template, plugin,
1219      * or filter).
1220      * 
1221      * @param string $file The file name to look for.
1222      * 
1223      * @return string|bool The full path and file name for the target file,
1224      * or boolean false if the file is not found in any of the paths.
1225      *
1226      */
1227      
1228      function findFile($type, $file)
1229      {
1230          // get the set of paths
1231          $set = $this->getPath($type);
1232          
1233          // start looping through them
1234          foreach ($set as $path) {
1235              $fullname = $path . $file;
1236              if (file_exists($fullname) && is_readable($fullname)) {
1237                  return $fullname;
1238              }
1239          }
1240          
1241          // could not find the file in the set of paths
1242          return false;
1243      }
1244      
1245      
1246      /**
1247      * 
1248      * Append a trailing '/' to paths, unless the path is empty.
1249      * 
1250      * @access private
1251      * 
1252      * @param string $path The file path to fix
1253      * 
1254      * @return string The fixed file path
1255      * 
1256      */
1257      
1258      function fixPath($path)
1259      {
1260          $len = strlen($this->_dirSep);
1261          
1262          if (! empty($path) &&
1263              substr($path, -1 * $len, $len) != $this->_dirSep)    {
1264              return $path . $this->_dirSep;
1265          } else {
1266              return $path;
1267          }
1268      }
1269  }
1270  
1271  ?>