[Sommaire] [Imprimer]

   1  <?php
   2  /* vim: set expandtab tabstop=4 shiftwidth=4: */
   3  // +----------------------------------------------------------------------+
   4  // | PHP version 4                                                        |
   5  // +----------------------------------------------------------------------+
   6  // | Copyright (c) 1997-2003 The PHP Group                                |
   7  // +----------------------------------------------------------------------+
   8  // | This source file is subject to version 2.0 of the PHP license,       |
   9  // | that is bundled with this package in the file LICENSE, and is        |
  10  // | available through the world-wide-web at                              |
  11  // | http://www.php.net/license/2_02.txt.                                 |
  12  // | If you did not receive a copy of the PHP license and are unable to   |
  13  // | obtain it through the world-wide-web, please send a note to          |
  14  // | license@php.net so we can mail you a copy immediately.               |
  15  // +----------------------------------------------------------------------+
  16  // | Authors: Paul M. Jones <pmjones@ciaweb.net>                          |
  17  // +----------------------------------------------------------------------+
  18  //
  19  // $Id: Rule.php,v 1.3 2004/12/02 10:54:31 nohn Exp $
  20  
  21  /**
  22  * 
  23  * Baseline rule class for extension into a "real" wiki rule.
  24  * 
  25  * Text_Wiki_Rule classes do not stand on their own; they are called by a
  26  * Text_Wiki object, typcially in the transform()method. Each rule class
  27  * performs three main activities: parse, process, and render.
  28  * 
  29  * The parse() method takes a regex and applies it to the whole block of
  30  * source text at one time. Each match is sent as $matches to the
  31  * process() method.
  32  * 
  33  * The process() method acts on the matched text from the source, and
  34  * then processes the source text is some way.  This may mean the
  35  * creation of a delimited token using addToken().  In every case, the
  36  * process() method returns the text that should replace the matched text
  37  * from parse().
  38  * 
  39  * Finally, the render*() methods take any token created by the rule and
  40  * creates output text matching a specific format.  Individual rules may
  41  * or may not have options for specific formats.
  42  *
  43  * Typically, the extended rule only needs to define the process() and
  44  * render() methods; the parse() method is generally the same from rule
  45  * to rule, and has been included here.  However, there is no reason that
  46  * rules cannot override these methods, so long as the new methods operate
  47  * in substantially the same manner; similarly, the rule need not generate
  48  * any tokens at all, and may use a specialized parse() method to filter
  49  * the source text.  See the default rule classes for many examples.
  50  * 
  51  * @author Paul M. Jones <pmjones@ciaweb.net>
  52  * 
  53  * @package Text_Wiki
  54  * 
  55  */
  56  
  57  class Text_Wiki_Rule {
  58      
  59      
  60      /**
  61      * 
  62      * The regular expression used to parse the source text and find
  63      * matches conforming to this rule.  Used by the parse() method.
  64      * 
  65      * @access public
  66      * 
  67      * @var string
  68      * 
  69      * @see parse()
  70      * 
  71      */
  72      
  73      var $regex = null;
  74      
  75      
  76      /**
  77      * 
  78      * A reference to the calling Text_Wiki object.  This is needed so
  79      * that each rule has access to the same source text, token set,
  80      * URLs, interwiki maps, page names, etc.
  81      * 
  82      * @access public
  83      * 
  84      * @var object
  85      */
  86      
  87      var $_wiki = null;
  88      
  89      
  90      /**
  91      * 
  92      * The name of this rule; used when inserting new token array
  93      * elements.
  94      * 
  95      * @access private
  96      * 
  97      * @var string
  98      * 
  99      */
 100      
 101      var $_rule = null;
 102      
 103      
 104      /**
 105      * 
 106      * Configuration options for this rule.
 107      * 
 108      * @access private
 109      * 
 110      * @var string
 111      * 
 112      */
 113      
 114      var $_conf = null;
 115      
 116      
 117      /**
 118      * 
 119      * Constructor for the rule.
 120      * 
 121      * @access public
 122      * 
 123      * @param object &$obj The calling "parent" Text_Wiki object.
 124      * 
 125      * @param string $name The token name to use for this rule.
 126      * 
 127      */
 128      
 129      function Text_Wiki_Rule(&$obj, $name)
 130      {
 131          // set the reference to the calling Text_Wiki object;
 132          // this allows us access to the shared source text, token
 133          // array, etc.
 134          $this->_wiki =& $obj;
 135          
 136          // set the name of this rule; generally used when adding
 137          // to the tokens array.
 138          $this->_rule = $name;
 139          
 140          // config options reference
 141          $this->_conf =& $this->_wiki->rules[$this->_rule]['conf'];
 142      }
 143      
 144      
 145      /**
 146      * 
 147      * Add a token to the Text_Wiki tokens array, and return a delimited
 148      * token number.
 149      * 
 150      * @access public
 151      * 
 152      * @param array $options An associative array of options for the new
 153      * token array element.  The keys and values are specific to the
 154      * rule, and may or may not be common to other rule options.  Typical
 155      * options keys are 'text' and 'type' but may include others.
 156      * 
 157      * @param boolean $id_only If true, return only the token number, not
 158      * a delimited token string.
 159      * 
 160      * @return string|int By default, return the number of the
 161      * newly-created token array element with a delimiter prefix and
 162      * suffix; however, if $id_only is set to true, return only the token
 163      * number (no delimiters).
 164      * 
 165      */
 166      
 167      function addToken($options = array(), $id_only = false)
 168      {
 169          // force the options to be an array
 170          settype($options, 'array');
 171          
 172          // find the next token number
 173          $id = count($this->_wiki->_tokens);
 174          
 175          // add the token
 176          $this->_wiki->_tokens[$id] = array(
 177              0 => $this->_rule,
 178              1 => $options
 179          );
 180          
 181          // return a value
 182          if ($id_only) {
 183              // return the last token number
 184              return $id;
 185          } else {
 186              // return the token number with delimiters
 187              return $this->_wiki->delim . $id . $this->_wiki->delim;
 188          }
 189      }
 190      
 191      
 192      /**
 193      * 
 194      * Set or re-set a token with specific information, overwriting any
 195      * previous rule name and rule options.
 196      * 
 197      * @access public
 198      * 
 199      * @param int $id The token number to reset.
 200      * 
 201      * @param int $rule The rule name to use; by default, use the current
 202      * rule name, although you can specify any rule.
 203      * 
 204      * @param array $options An associative array of options for the
 205      * token array element.  The keys and values are specific to the
 206      * rule, and may or may not be common to other rule options.  Typical
 207      * options keys are 'text' and 'type' but may include others.
 208      * 
 209      * @return void
 210      * 
 211      */
 212      
 213      function setToken($id, $rule = null, $options = array())
 214      {
 215          // get a rule name
 216          if (is_null($rule)) {
 217              $rule = $this->_rule;
 218          }
 219          
 220          // reset the token
 221          $this->_wiki->_tokens[$id] = array(
 222              0 => $rule,
 223              1 => $options
 224          );
 225      }
 226      
 227      
 228      /**
 229      * 
 230      * Simple parsing method to apply the rule's regular expression to
 231      * the source text, pass every match to the process() method, and
 232      * replace the matched text with the results of the processing.
 233      *
 234      * @access public
 235      * 
 236      */
 237      
 238      function parse()
 239      {
 240          $this->_wiki->_source = preg_replace_callback(
 241              $this->regex,
 242              array(&$this, 'process'),
 243              $this->_wiki->_source
 244          );
 245      }
 246      
 247      
 248      /**
 249      * 
 250      * Simple processing mathod to take matched text and generate
 251      * replacement text. This is one of the methods you will definitely
 252      * want to override in your rule class extensions.
 253      * 
 254      * @access public
 255      * 
 256      * @param array $matches An array of matches from the parse() method
 257      * as generated by preg_replace_callback.  $matches[0] is the full
 258      * matched string, $matches[1] is the first matched pattern,
 259      * $matches[2] is the second matched pattern, and so on.
 260      * 
 261      * @return string The processed text replacement; defaults to the
 262      * full matched string (i.e., no changes to the text).
 263      * 
 264      */
 265      
 266      function process(&$matches)
 267      {
 268          return $matches[0];
 269      }
 270      
 271      
 272      /**
 273      * 
 274      * Simple rendering method to take a set of token options and
 275      * generate replacement text for it.  This is another method you will
 276      * definitely want to override in your rule subclass extensions.
 277      *
 278      * @access public
 279      * 
 280      * @param array $options The "options" portion of the token (second element).
 281      * 
 282      * @return string The text rendered from the token options; by default,
 283      * no text is returned.  You should change this in your subclass.  ;-)
 284      * 
 285      */
 286      
 287      function renderXhtml($options)
 288      {
 289          return '';
 290      }
 291      
 292      
 293      /**
 294      * 
 295      * Simple method to extract 'option="value"' portions of wiki markup,
 296      * typically used only in macros.
 297      * 
 298      * The syntax is pretty strict; there can be no spaces between the
 299      * option name, the equals, and the first double-quote; the value
 300      * must be surrounded by double-quotes.  You can escape characters in
 301      * the value with a backslash, and the backslash will be stripped for
 302      * you.
 303      * 
 304      * @access public
 305      * 
 306      * @param string $text The "macro options" portion of macro markup.
 307      * 
 308      * @return array An associative array of key-value pairs where the
 309      * key is the option name and the value is the option value.
 310      * 
 311      */
 312      
 313      function getMacroArgs($text)
 314      {
 315          // find the =" sections;
 316          $tmp = explode('="', trim($text));
 317          
 318          // basic setup
 319          $k = count($tmp) - 1;
 320          $arg = array();
 321          $key = null;
 322          
 323          // loop through the sections
 324          foreach ($tmp as $i => $val) {
 325              
 326              // first element is always the first key
 327              if ($i == 0) {
 328                  $key = trim($val);
 329                  continue;
 330              }
 331              
 332              // find the last double-quote in the value.
 333              // the part to the left is the value for the last key,
 334              // the part to the right is the next key name
 335              $pos = strrpos($val, '"');
 336              $arg[$key] = stripslashes(substr($val, 0, $pos));
 337              $key = trim(substr($val, $pos+1));
 338              
 339          }
 340          
 341          return $arg;
 342          
 343      }
 344  }
 345  ?>