[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Utilities for accessing the parser
   4   *
   5   * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
   6   * @author     Harry Fuecks <hfuecks@gmail.com>
   7   * @author     Andreas Gohr <andi@splitbrain.org>
   8   */
   9  
  10  if(!defined('DOKU_INC')) die('meh.');
  11  
  12  /**
  13   * How many pages shall be rendered for getting metadata during one request
  14   * at maximum? Note that this limit isn't respected when METADATA_RENDER_UNLIMITED
  15   * is passed as render parameter to p_get_metadata.
  16   */
  17  if (!defined('P_GET_METADATA_RENDER_LIMIT')) define('P_GET_METADATA_RENDER_LIMIT', 5);
  18  
  19  /** Don't render metadata even if it is outdated or doesn't exist */
  20  define('METADATA_DONT_RENDER', 0);
  21  /**
  22   * Render metadata when the page is really newer or the metadata doesn't exist.
  23   * Uses just a simple check, but should work pretty well for loading simple
  24   * metadata values like the page title and avoids rendering a lot of pages in
  25   * one request. The P_GET_METADATA_RENDER_LIMIT is used in this mode.
  26   * Use this if it is unlikely that the metadata value you are requesting
  27   * does depend e.g. on pages that are included in the current page using
  28   * the include plugin (this is very likely the case for the page title, but
  29   * not for relation references).
  30   */
  31  define('METADATA_RENDER_USING_SIMPLE_CACHE', 1);
  32  /**
  33   * Render metadata using the metadata cache logic. The P_GET_METADATA_RENDER_LIMIT
  34   * is used in this mode. Use this mode when you are requesting more complex
  35   * metadata. Although this will cause rendering more often it might actually have
  36   * the effect that less current metadata is returned as it is more likely than in
  37   * the simple cache mode that metadata needs to be rendered for all pages at once
  38   * which means that when the metadata for the page is requested that actually needs
  39   * to be updated the limit might have been reached already.
  40   */
  41  define('METADATA_RENDER_USING_CACHE', 2);
  42  /**
  43   * Render metadata without limiting the number of pages for which metadata is
  44   * rendered. Use this mode with care, normally it should only be used in places
  45   * like the indexer or in cli scripts where the execution time normally isn't
  46   * limited. This can be combined with the simple cache using
  47   * METADATA_RENDER_USING_CACHE | METADATA_RENDER_UNLIMITED.
  48   */
  49  define('METADATA_RENDER_UNLIMITED', 4);
  50  
  51  /**
  52   * Returns the parsed Wikitext in XHTML for the given id and revision.
  53   *
  54   * If $excuse is true an explanation is returned if the file
  55   * wasn't found
  56   *
  57   * @author Andreas Gohr <andi@splitbrain.org>
  58   *
  59   * @param string $id page id
  60   * @param string|int $rev revision timestamp or empty string
  61   * @param bool $excuse
  62   * @param string $date_at
  63   *
  64   * @return null|string
  65   */
  66  function p_wiki_xhtml($id, $rev='', $excuse=true,$date_at=''){
  67      $file = wikiFN($id,$rev);
  68      $ret  = '';
  69  
  70      //ensure $id is in global $ID (needed for parsing)
  71      global $ID;
  72      $keep = $ID;
  73      $ID   = $id;
  74  
  75      if($rev || $date_at){
  76          if(file_exists($file)){
  77              $ret = p_render('xhtml',p_get_instructions(io_readWikiPage($file,$id,$rev)),$info,$date_at); //no caching on old revisions
  78          }elseif($excuse){
  79              $ret = p_locale_xhtml('norev');
  80          }
  81      }else{
  82          if(file_exists($file)){
  83              $ret = p_cached_output($file,'xhtml',$id);
  84          }elseif($excuse){
  85              //check if the page once existed
  86              $changelog = new PageChangelog($id);
  87              if($changelog->hasRevisions()) {
  88                  $ret = p_locale_xhtml('onceexisted');
  89              } else {
  90                  $ret = p_locale_xhtml('newpage');
  91              }
  92          }
  93      }
  94  
  95      //restore ID (just in case)
  96      $ID = $keep;
  97  
  98      return $ret;
  99  }
 100  
 101  /**
 102   * Returns the specified local text in parsed format
 103   *
 104   * @author Andreas Gohr <andi@splitbrain.org>
 105   *
 106   * @param string $id page id
 107   * @return null|string
 108   */
 109  function p_locale_xhtml($id){
 110      //fetch parsed locale
 111      $html = p_cached_output(localeFN($id));
 112      return $html;
 113  }
 114  
 115  /**
 116   * Returns the given file parsed into the requested output format
 117   *
 118   * @author Andreas Gohr <andi@splitbrain.org>
 119   * @author Chris Smith <chris@jalakai.co.uk>
 120   *
 121   * @param string $file filename, path to file
 122   * @param string $format
 123   * @param string $id page id
 124   * @return null|string
 125   */
 126  function p_cached_output($file, $format='xhtml', $id='') {
 127      global $conf;
 128  
 129      $cache = new cache_renderer($id, $file, $format);
 130      if ($cache->useCache()) {
 131          $parsed = $cache->retrieveCache(false);
 132          if($conf['allowdebug'] && $format=='xhtml') {
 133              $parsed .= "\n<!-- cachefile {$cache->cache} used -->\n";
 134          }
 135      } else {
 136          $parsed = p_render($format, p_cached_instructions($file,false,$id), $info);
 137  
 138          if ($info['cache'] && $cache->storeCache($parsed)) {              // storeCache() attempts to save cachefile
 139              if($conf['allowdebug'] && $format=='xhtml') {
 140                  $parsed .= "\n<!-- no cachefile used, but created {$cache->cache} -->\n";
 141              }
 142          }else{
 143              $cache->removeCache();                     //try to delete cachefile
 144              if($conf['allowdebug'] && $format=='xhtml') {
 145                  $parsed .= "\n<!-- no cachefile used, caching forbidden -->\n";
 146              }
 147          }
 148      }
 149  
 150      return $parsed;
 151  }
 152  
 153  /**
 154   * Returns the render instructions for a file
 155   *
 156   * Uses and creates a serialized cache file
 157   *
 158   * @author Andreas Gohr <andi@splitbrain.org>
 159   *
 160   * @param string $file      filename, path to file
 161   * @param bool   $cacheonly
 162   * @param string $id        page id
 163   * @return array|null
 164   */
 165  function p_cached_instructions($file,$cacheonly=false,$id='') {
 166      static $run = null;
 167      if(is_null($run)) $run = array();
 168  
 169      $cache = new cache_instructions($id, $file);
 170  
 171      if ($cacheonly || $cache->useCache() || (isset($run[$file]) && !defined('DOKU_UNITTEST'))) {
 172          return $cache->retrieveCache();
 173      } else if (file_exists($file)) {
 174          // no cache - do some work
 175          $ins = p_get_instructions(io_readWikiPage($file,$id));
 176          if ($cache->storeCache($ins)) {
 177              $run[$file] = true; // we won't rebuild these instructions in the same run again
 178          } else {
 179              msg('Unable to save cache file. Hint: disk full; file permissions; safe_mode setting.',-1);
 180          }
 181          return $ins;
 182      }
 183  
 184      return null;
 185  }
 186  
 187  /**
 188   * turns a page into a list of instructions
 189   *
 190   * @author Harry Fuecks <hfuecks@gmail.com>
 191   * @author Andreas Gohr <andi@splitbrain.org>
 192   *
 193   * @param string $text  raw wiki syntax text
 194   * @return array a list of instruction arrays
 195   */
 196  function p_get_instructions($text){
 197  
 198      $modes = p_get_parsermodes();
 199  
 200      // Create the parser
 201      $Parser = new Doku_Parser();
 202  
 203      // Add the Handler
 204      $Parser->Handler = new Doku_Handler();
 205  
 206      //add modes to parser
 207      foreach($modes as $mode){
 208          $Parser->addMode($mode['mode'],$mode['obj']);
 209      }
 210  
 211      // Do the parsing
 212      trigger_event('PARSER_WIKITEXT_PREPROCESS', $text);
 213      $p = $Parser->parse($text);
 214      //  dbg($p);
 215      return $p;
 216  }
 217  
 218  /**
 219   * returns the metadata of a page
 220   *
 221   * @param string $id      The id of the page the metadata should be returned from
 222   * @param string $key     The key of the metdata value that shall be read (by default everything) - separate hierarchies by " " like "date created"
 223   * @param int    $render  If the page should be rendererd - possible values:
 224   *     METADATA_DONT_RENDER, METADATA_RENDER_USING_SIMPLE_CACHE, METADATA_RENDER_USING_CACHE
 225   *     METADATA_RENDER_UNLIMITED (also combined with the previous two options),
 226   *     default: METADATA_RENDER_USING_CACHE
 227   * @return mixed The requested metadata fields
 228   *
 229   * @author Esther Brunner <esther@kaffeehaus.ch>
 230   * @author Michael Hamann <michael@content-space.de>
 231   */
 232  function p_get_metadata($id, $key='', $render=METADATA_RENDER_USING_CACHE){
 233      global $ID;
 234      static $render_count = 0;
 235      // track pages that have already been rendered in order to avoid rendering the same page
 236      // again
 237      static $rendered_pages = array();
 238  
 239      // cache the current page
 240      // Benchmarking shows the current page's metadata is generally the only page metadata
 241      // accessed several times. This may catch a few other pages, but that shouldn't be an issue.
 242      $cache = ($ID == $id);
 243      $meta = p_read_metadata($id, $cache);
 244  
 245      if (!is_numeric($render)) {
 246          if ($render) {
 247              $render = METADATA_RENDER_USING_SIMPLE_CACHE;
 248          } else {
 249              $render = METADATA_DONT_RENDER;
 250          }
 251      }
 252  
 253      // prevent recursive calls in the cache
 254      static $recursion = false;
 255      if (!$recursion && $render != METADATA_DONT_RENDER && !isset($rendered_pages[$id])&& page_exists($id)){
 256          $recursion = true;
 257  
 258          $cachefile = new cache_renderer($id, wikiFN($id), 'metadata');
 259  
 260          $do_render = false;
 261          if ($render & METADATA_RENDER_UNLIMITED || $render_count < P_GET_METADATA_RENDER_LIMIT) {
 262              if ($render & METADATA_RENDER_USING_SIMPLE_CACHE) {
 263                  $pagefn = wikiFN($id);
 264                  $metafn = metaFN($id, '.meta');
 265                  if (!file_exists($metafn) || @filemtime($pagefn) > @filemtime($cachefile->cache)) {
 266                      $do_render = true;
 267                  }
 268              } elseif (!$cachefile->useCache()){
 269                  $do_render = true;
 270              }
 271          }
 272          if ($do_render) {
 273              if (!defined('DOKU_UNITTEST')) {
 274                  ++$render_count;
 275                  $rendered_pages[$id] = true;
 276              }
 277              $old_meta = $meta;
 278              $meta = p_render_metadata($id, $meta);
 279              // only update the file when the metadata has been changed
 280              if ($meta == $old_meta || p_save_metadata($id, $meta)) {
 281                  // store a timestamp in order to make sure that the cachefile is touched
 282                  // this timestamp is also stored when the meta data is still the same
 283                  $cachefile->storeCache(time());
 284              } else {
 285                  msg('Unable to save metadata file. Hint: disk full; file permissions; safe_mode setting.',-1);
 286              }
 287          }
 288  
 289          $recursion = false;
 290      }
 291  
 292      $val = $meta['current'];
 293  
 294      // filter by $key
 295      foreach(preg_split('/\s+/', $key, 2, PREG_SPLIT_NO_EMPTY) as $cur_key) {
 296          if (!isset($val[$cur_key])) {
 297              return null;
 298          }
 299          $val = $val[$cur_key];
 300      }
 301      return $val;
 302  }
 303  
 304  /**
 305   * sets metadata elements of a page
 306   *
 307   * @see http://www.dokuwiki.org/devel:metadata#functions_to_get_and_set_metadata
 308   *
 309   * @param String  $id         is the ID of a wiki page
 310   * @param Array   $data       is an array with key ⇒ value pairs to be set in the metadata
 311   * @param Boolean $render     whether or not the page metadata should be generated with the renderer
 312   * @param Boolean $persistent indicates whether or not the particular metadata value will persist through
 313   *                            the next metadata rendering.
 314   * @return boolean true on success
 315   *
 316   * @author Esther Brunner <esther@kaffeehaus.ch>
 317   * @author Michael Hamann <michael@content-space.de>
 318   */
 319  function p_set_metadata($id, $data, $render=false, $persistent=true){
 320      if (!is_array($data)) return false;
 321  
 322      global $ID, $METADATA_RENDERERS;
 323  
 324      // if there is currently a renderer change the data in the renderer instead
 325      if (isset($METADATA_RENDERERS[$id])) {
 326          $orig =& $METADATA_RENDERERS[$id];
 327          $meta = $orig;
 328      } else {
 329          // cache the current page
 330          $cache = ($ID == $id);
 331          $orig = p_read_metadata($id, $cache);
 332  
 333          // render metadata first?
 334          $meta = $render ? p_render_metadata($id, $orig) : $orig;
 335      }
 336  
 337      // now add the passed metadata
 338      $protected = array('description', 'date', 'contributor');
 339      foreach ($data as $key => $value){
 340  
 341          // be careful with sub-arrays of $meta['relation']
 342          if ($key == 'relation'){
 343  
 344              foreach ($value as $subkey => $subvalue){
 345                  if(isset($meta['current'][$key][$subkey]) && is_array($meta['current'][$key][$subkey])) {
 346                      $meta['current'][$key][$subkey] = array_replace($meta['current'][$key][$subkey], (array)$subvalue);
 347                  } else {
 348                      $meta['current'][$key][$subkey] = $subvalue;
 349                  }
 350                  if($persistent) {
 351                      if(isset($meta['persistent'][$key][$subkey]) && is_array($meta['persistent'][$key][$subkey])) {
 352                          $meta['persistent'][$key][$subkey] = array_replace($meta['persistent'][$key][$subkey], (array)$subvalue);
 353                      } else {
 354                          $meta['persistent'][$key][$subkey] = $subvalue;
 355                      }
 356                  }
 357              }
 358  
 359              // be careful with some senisitive arrays of $meta
 360          } elseif (in_array($key, $protected)){
 361  
 362              // these keys, must have subkeys - a legitimate value must be an array
 363              if (is_array($value)) {
 364                  $meta['current'][$key] = !empty($meta['current'][$key]) ? array_replace((array)$meta['current'][$key],$value) : $value;
 365  
 366                  if ($persistent) {
 367                      $meta['persistent'][$key] = !empty($meta['persistent'][$key]) ? array_replace((array)$meta['persistent'][$key],$value) : $value;
 368                  }
 369              }
 370  
 371              // no special treatment for the rest
 372          } else {
 373              $meta['current'][$key] = $value;
 374              if ($persistent) $meta['persistent'][$key] = $value;
 375          }
 376      }
 377  
 378      // save only if metadata changed
 379      if ($meta == $orig) return true;
 380  
 381      if (isset($METADATA_RENDERERS[$id])) {
 382          // set both keys individually as the renderer has references to the individual keys
 383          $METADATA_RENDERERS[$id]['current']    = $meta['current'];
 384          $METADATA_RENDERERS[$id]['persistent'] = $meta['persistent'];
 385          return true;
 386      } else {
 387          return p_save_metadata($id, $meta);
 388      }
 389  }
 390  
 391  /**
 392   * Purges the non-persistant part of the meta data
 393   * used on page deletion
 394   *
 395   * @author Michael Klier <chi@chimeric.de>
 396   *
 397   * @param string $id page id
 398   * @return bool  success / fail
 399   */
 400  function p_purge_metadata($id) {
 401      $meta = p_read_metadata($id);
 402      foreach($meta['current'] as $key => $value) {
 403          if(is_array($meta[$key])) {
 404              $meta['current'][$key] = array();
 405          } else {
 406              $meta['current'][$key] = '';
 407          }
 408  
 409      }
 410      return p_save_metadata($id, $meta);
 411  }
 412  
 413  /**
 414   * read the metadata from source/cache for $id
 415   * (internal use only - called by p_get_metadata & p_set_metadata)
 416   *
 417   * @author   Christopher Smith <chris@jalakai.co.uk>
 418   *
 419   * @param    string   $id      absolute wiki page id
 420   * @param    bool     $cache   whether or not to cache metadata in memory
 421   *                             (only use for metadata likely to be accessed several times)
 422   *
 423   * @return   array             metadata
 424   */
 425  function p_read_metadata($id,$cache=false) {
 426      global $cache_metadata;
 427  
 428      if (isset($cache_metadata[(string)$id])) return $cache_metadata[(string)$id];
 429  
 430      $file = metaFN($id, '.meta');
 431      $meta = file_exists($file) ? unserialize(io_readFile($file, false)) : array('current'=>array(),'persistent'=>array());
 432  
 433      if ($cache) {
 434          $cache_metadata[(string)$id] = $meta;
 435      }
 436  
 437      return $meta;
 438  }
 439  
 440  /**
 441   * This is the backend function to save a metadata array to a file
 442   *
 443   * @param    string   $id      absolute wiki page id
 444   * @param    array    $meta    metadata
 445   *
 446   * @return   bool              success / fail
 447   */
 448  function p_save_metadata($id, $meta) {
 449      // sync cached copies, including $INFO metadata
 450      global $cache_metadata, $INFO;
 451  
 452      if (isset($cache_metadata[$id])) $cache_metadata[$id] = $meta;
 453      if (!empty($INFO) && ($id == $INFO['id'])) { $INFO['meta'] = $meta['current']; }
 454  
 455      return io_saveFile(metaFN($id, '.meta'), serialize($meta));
 456  }
 457  
 458  /**
 459   * renders the metadata of a page
 460   *
 461   * @author Esther Brunner <esther@kaffeehaus.ch>
 462   *
 463   * @param string $id    page id
 464   * @param array  $orig  the original metadata
 465   * @return array|null array('current'=> array,'persistent'=> array);
 466   */
 467  function p_render_metadata($id, $orig){
 468      // make sure the correct ID is in global ID
 469      global $ID, $METADATA_RENDERERS;
 470  
 471      // avoid recursive rendering processes for the same id
 472      if (isset($METADATA_RENDERERS[$id])) {
 473          return $orig;
 474      }
 475  
 476      // store the original metadata in the global $METADATA_RENDERERS so p_set_metadata can use it
 477      $METADATA_RENDERERS[$id] =& $orig;
 478  
 479      $keep = $ID;
 480      $ID   = $id;
 481  
 482      // add an extra key for the event - to tell event handlers the page whose metadata this is
 483      $orig['page'] = $id;
 484      $evt = new Doku_Event('PARSER_METADATA_RENDER', $orig);
 485      if ($evt->advise_before()) {
 486  
 487          // get instructions
 488          $instructions = p_cached_instructions(wikiFN($id),false,$id);
 489          if(is_null($instructions)){
 490              $ID = $keep;
 491              unset($METADATA_RENDERERS[$id]);
 492              return null; // something went wrong with the instructions
 493          }
 494  
 495          // set up the renderer
 496          $renderer = new Doku_Renderer_metadata();
 497          $renderer->meta =& $orig['current'];
 498          $renderer->persistent =& $orig['persistent'];
 499  
 500          // loop through the instructions
 501          foreach ($instructions as $instruction){
 502              // execute the callback against the renderer
 503              call_user_func_array(array(&$renderer, $instruction[0]), (array) $instruction[1]);
 504          }
 505  
 506          $evt->result = array('current'=>&$renderer->meta,'persistent'=>&$renderer->persistent);
 507      }
 508      $evt->advise_after();
 509  
 510      // clean up
 511      $ID = $keep;
 512      unset($METADATA_RENDERERS[$id]);
 513      return $evt->result;
 514  }
 515  
 516  /**
 517   * returns all available parser syntax modes in correct order
 518   *
 519   * @author Andreas Gohr <andi@splitbrain.org>
 520   *
 521   * @return array[] with for each plugin the array('sort' => sortnumber, 'mode' => mode string, 'obj'  => plugin object)
 522   */
 523  function p_get_parsermodes(){
 524      global $conf;
 525  
 526      //reuse old data
 527      static $modes = null;
 528      if($modes != null && !defined('DOKU_UNITTEST')){
 529          return $modes;
 530      }
 531  
 532      //import parser classes and mode definitions
 533      require_once  DOKU_INC . 'inc/parser/parser.php';
 534  
 535      // we now collect all syntax modes and their objects, then they will
 536      // be sorted and added to the parser in correct order
 537      $modes = array();
 538  
 539      // add syntax plugins
 540      $pluginlist = plugin_list('syntax');
 541      if(count($pluginlist)){
 542          global $PARSER_MODES;
 543          $obj = null;
 544          foreach($pluginlist as $p){
 545              /** @var DokuWiki_Syntax_Plugin $obj */
 546              if(!$obj = plugin_load('syntax',$p)) continue; //attempt to load plugin into $obj
 547              $PARSER_MODES[$obj->getType()][] = "plugin_$p"; //register mode type
 548              //add to modes
 549              $modes[] = array(
 550                      'sort' => $obj->getSort(),
 551                      'mode' => "plugin_$p",
 552                      'obj'  => $obj,
 553                      );
 554              unset($obj); //remove the reference
 555          }
 556      }
 557  
 558      // add default modes
 559      $std_modes = array('listblock','preformatted','notoc','nocache',
 560              'header','table','linebreak','footnote','hr',
 561              'unformatted','php','html','code','file','quote',
 562              'internallink','rss','media','externallink',
 563              'emaillink','windowssharelink','eol');
 564      if($conf['typography']){
 565          $std_modes[] = 'quotes';
 566          $std_modes[] = 'multiplyentity';
 567      }
 568      foreach($std_modes as $m){
 569          $class = "Doku_Parser_Mode_$m";
 570          $obj   = new $class();
 571          $modes[] = array(
 572                  'sort' => $obj->getSort(),
 573                  'mode' => $m,
 574                  'obj'  => $obj
 575                  );
 576      }
 577  
 578      // add formatting modes
 579      $fmt_modes = array('strong','emphasis','underline','monospace',
 580              'subscript','superscript','deleted');
 581      foreach($fmt_modes as $m){
 582          $obj   = new Doku_Parser_Mode_formatting($m);
 583          $modes[] = array(
 584                  'sort' => $obj->getSort(),
 585                  'mode' => $m,
 586                  'obj'  => $obj
 587                  );
 588      }
 589  
 590      // add modes which need files
 591      $obj     = new Doku_Parser_Mode_smiley(array_keys(getSmileys()));
 592      $modes[] = array('sort' => $obj->getSort(), 'mode' => 'smiley','obj'  => $obj );
 593      $obj     = new Doku_Parser_Mode_acronym(array_keys(getAcronyms()));
 594      $modes[] = array('sort' => $obj->getSort(), 'mode' => 'acronym','obj'  => $obj );
 595      $obj     = new Doku_Parser_Mode_entity(array_keys(getEntities()));
 596      $modes[] = array('sort' => $obj->getSort(), 'mode' => 'entity','obj'  => $obj );
 597  
 598      // add optional camelcase mode
 599      if($conf['camelcase']){
 600          $obj     = new Doku_Parser_Mode_camelcaselink();
 601          $modes[] = array('sort' => $obj->getSort(), 'mode' => 'camelcaselink','obj'  => $obj );
 602      }
 603  
 604      //sort modes
 605      usort($modes,'p_sort_modes');
 606  
 607      return $modes;
 608  }
 609  
 610  /**
 611   * Callback function for usort
 612   *
 613   * @author Andreas Gohr <andi@splitbrain.org>
 614   *
 615   * @param array $a
 616   * @param array $b
 617   * @return int $a is lower/equal/higher than $b
 618   */
 619  function p_sort_modes($a, $b){
 620      if($a['sort'] == $b['sort']) return 0;
 621      return ($a['sort'] < $b['sort']) ? -1 : 1;
 622  }
 623  
 624  /**
 625   * Renders a list of instruction to the specified output mode
 626   *
 627   * In the $info array is information from the renderer returned
 628   *
 629   * @author Harry Fuecks <hfuecks@gmail.com>
 630   * @author Andreas Gohr <andi@splitbrain.org>
 631   *
 632   * @param string $mode
 633   * @param array|null|false $instructions
 634   * @param array $info returns render info like enabled toc and cache
 635   * @param string $date_at
 636   * @return null|string rendered output
 637   */
 638  function p_render($mode,$instructions,&$info,$date_at=''){
 639      if(is_null($instructions)) return '';
 640      if($instructions === false) return '';
 641  
 642      $Renderer = p_get_renderer($mode);
 643      if (is_null($Renderer)) return null;
 644  
 645      $Renderer->reset();
 646  
 647      if($date_at) {
 648          $Renderer->date_at = $date_at;
 649      }
 650  
 651      $Renderer->smileys = getSmileys();
 652      $Renderer->entities = getEntities();
 653      $Renderer->acronyms = getAcronyms();
 654      $Renderer->interwiki = getInterwiki();
 655  
 656      // Loop through the instructions
 657      foreach ( $instructions as $instruction ) {
 658          // Execute the callback against the Renderer
 659          if(method_exists($Renderer, $instruction[0])){
 660              call_user_func_array(array(&$Renderer, $instruction[0]), $instruction[1] ? $instruction[1] : array());
 661          }
 662      }
 663  
 664      //set info array
 665      $info = $Renderer->info;
 666  
 667      // Post process and return the output
 668      $data = array($mode,& $Renderer->doc);
 669      trigger_event('RENDERER_CONTENT_POSTPROCESS',$data);
 670      return $Renderer->doc;
 671  }
 672  
 673  /**
 674   * Figure out the correct renderer class to use for $mode,
 675   * instantiate and return it
 676   *
 677   * @param string $mode Mode of the renderer to get
 678   * @return null|Doku_Renderer The renderer
 679   *
 680   * @author Christopher Smith <chris@jalakai.co.uk>
 681   */
 682  function p_get_renderer($mode) {
 683      /** @var Doku_Plugin_Controller $plugin_controller */
 684      global $conf, $plugin_controller;
 685  
 686      $rname = !empty($conf['renderer_'.$mode]) ? $conf['renderer_'.$mode] : $mode;
 687      $rclass = "Doku_Renderer_$rname";
 688  
 689      // if requested earlier or a bundled renderer
 690      if( class_exists($rclass) ) {
 691          $Renderer = new $rclass();
 692          return $Renderer;
 693      }
 694  
 695      // not bundled, see if its an enabled renderer plugin & when $mode is 'xhtml', the renderer can supply that format.
 696      /** @var Doku_Renderer $Renderer */
 697      $Renderer = $plugin_controller->load('renderer',$rname);
 698      if ($Renderer && is_a($Renderer, 'Doku_Renderer')  && ($mode != 'xhtml' || $mode == $Renderer->getFormat())) {
 699          return $Renderer;
 700      }
 701  
 702      // there is a configuration error!
 703      // not bundled, not a valid enabled plugin, use $mode to try to fallback to a bundled renderer
 704      $rclass = "Doku_Renderer_$mode";
 705      if ( class_exists($rclass) ) {
 706          // viewers should see renderered output, so restrict the warning to admins only
 707          $msg = "No renderer '$rname' found for mode '$mode', check your plugins";
 708          if ($mode == 'xhtml') {
 709              $msg .= " and the 'renderer_xhtml' config setting";
 710          }
 711          $msg .= ".<br/>Attempting to fallback to the bundled renderer.";
 712          msg($msg,-1,'','',MSG_ADMINS_ONLY);
 713  
 714          $Renderer = new $rclass;
 715          $Renderer->nocache();     // fallback only (and may include admin alerts), don't cache
 716          return $Renderer;
 717      }
 718  
 719      // fallback failed, alert the world
 720      msg("No renderer '$rname' found for mode '$mode'",-1);
 721      return null;
 722  }
 723  
 724  /**
 725   * Gets the first heading from a file
 726   *
 727   * @param   string   $id       dokuwiki page id
 728   * @param   int      $render   rerender if first heading not known
 729   *                             default: METADATA_RENDER_USING_SIMPLE_CACHE
 730   *                             Possible values: METADATA_DONT_RENDER,
 731   *                                              METADATA_RENDER_USING_SIMPLE_CACHE,
 732   *                                              METADATA_RENDER_USING_CACHE,
 733   *                                              METADATA_RENDER_UNLIMITED
 734   * @return string|null The first heading
 735   *
 736   * @author Andreas Gohr <andi@splitbrain.org>
 737   * @author Michael Hamann <michael@content-space.de>
 738   */
 739  function p_get_first_heading($id, $render=METADATA_RENDER_USING_SIMPLE_CACHE){
 740      return p_get_metadata(cleanID($id),'title',$render);
 741  }
 742  
 743  /**
 744   * Wrapper for GeSHi Code Highlighter, provides caching of its output
 745   *
 746   * @param  string   $code       source code to be highlighted
 747   * @param  string   $language   language to provide highlighting
 748   * @param  string   $wrapper    html element to wrap the returned highlighted text
 749   * @return string xhtml code
 750   *
 751   * @author Christopher Smith <chris@jalakai.co.uk>
 752   * @author Andreas Gohr <andi@splitbrain.org>
 753   */
 754  function p_xhtml_cached_geshi($code, $language, $wrapper='pre', array $options=null) {
 755      global $conf, $config_cascade, $INPUT;
 756      $language = strtolower($language);
 757  
 758      // remove any leading or trailing blank lines
 759      $code = preg_replace('/^\s*?\n|\s*?\n$/','',$code);
 760  
 761      $optionsmd5 = md5(serialize($options));
 762      $cache = getCacheName($language.$code.$optionsmd5,".code");
 763      $ctime = @filemtime($cache);
 764      if($ctime && !$INPUT->bool('purge') &&
 765              $ctime > filemtime(DOKU_INC.'vendor/composer/installed.json') &&  // libraries changed
 766              $ctime > filemtime(reset($config_cascade['main']['default']))){ // dokuwiki changed
 767          $highlighted_code = io_readFile($cache, false);
 768      } else {
 769  
 770          $geshi = new GeSHi($code, $language);
 771          $geshi->set_encoding('utf-8');
 772          $geshi->enable_classes();
 773          $geshi->set_header_type(GESHI_HEADER_PRE);
 774          $geshi->set_link_target($conf['target']['extern']);
 775          if($options !== null) {
 776              foreach ($options as $function => $params) {
 777                  if(is_callable(array($geshi, $function))) {
 778                      $geshi->$function($params);
 779                  }
 780              }
 781          }
 782  
 783          // remove GeSHi's wrapper element (we'll replace it with our own later)
 784          // we need to use a GeSHi wrapper to avoid <BR> throughout the highlighted text
 785          $highlighted_code = trim(preg_replace('!^<pre[^>]*>|</pre>$!','',$geshi->parse_code()),"\n\r");
 786          io_saveFile($cache,$highlighted_code);
 787      }
 788  
 789      // add a wrapper element if required
 790      if ($wrapper) {
 791          return "<$wrapper class=\"code $language\">$highlighted_code</$wrapper>";
 792      } else {
 793          return $highlighted_code;
 794      }
 795  }
 796