[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Interfaces for preprocessors
   4   *
   5   * This program is free software; you can redistribute it and/or modify
   6   * it under the terms of the GNU General Public License as published by
   7   * the Free Software Foundation; either version 2 of the License, or
   8   * (at your option) any later version.
   9   *
  10   * This program is distributed in the hope that it will be useful,
  11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13   * GNU General Public License for more details.
  14   *
  15   * You should have received a copy of the GNU General Public License along
  16   * with this program; if not, write to the Free Software Foundation, Inc.,
  17   * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18   * http://www.gnu.org/copyleft/gpl.html
  19   *
  20   * @file
  21   * @ingroup Parser
  22   */
  23  
  24  /**
  25   * @ingroup Parser
  26   */
  27  interface Preprocessor {
  28      /**
  29       * Create a new preprocessor object based on an initialised Parser object
  30       *
  31       * @param Parser $parser
  32       */
  33  	public function __construct( $parser );
  34  
  35      /**
  36       * Create a new top-level frame for expansion of a page
  37       *
  38       * @return PPFrame
  39       */
  40  	public function newFrame();
  41  
  42      /**
  43       * Create a new custom frame for programmatic use of parameter replacement
  44       * as used in some extensions.
  45       *
  46       * @param array $args
  47       *
  48       * @return PPFrame
  49       */
  50  	public function newCustomFrame( $args );
  51  
  52      /**
  53       * Create a new custom node for programmatic use of parameter replacement
  54       * as used in some extensions.
  55       *
  56       * @param array $values
  57       */
  58  	public function newPartNodeArray( $values );
  59  
  60      /**
  61       * Preprocess text to a PPNode
  62       *
  63       * @param string $text
  64       * @param int $flags
  65       *
  66       * @return PPNode
  67       */
  68  	public function preprocessToObj( $text, $flags = 0 );
  69  }
  70  
  71  /**
  72   * @ingroup Parser
  73   */
  74  interface PPFrame {
  75      const NO_ARGS = 1;
  76      const NO_TEMPLATES = 2;
  77      const STRIP_COMMENTS = 4;
  78      const NO_IGNORE = 8;
  79      const RECOVER_COMMENTS = 16;
  80      const NO_TAGS = 32;
  81  
  82      const RECOVER_ORIG = 59; // = 1|2|8|16|32 no constant expression support in PHP yet
  83  
  84      /** This constant exists when $indexOffset is supported in newChild() */
  85      const SUPPORTS_INDEX_OFFSET = 1;
  86  
  87      /**
  88       * Create a child frame
  89       *
  90       * @param array|bool $args
  91       * @param bool|Title $title
  92       * @param int $indexOffset A number subtracted from the index attributes of the arguments
  93       *
  94       * @return PPFrame
  95       */
  96  	public function newChild( $args = false, $title = false, $indexOffset = 0 );
  97  
  98      /**
  99       * Expand a document tree node, caching the result on its parent with the given key
 100       * @param string|int $key
 101       * @param string|PPNode $root
 102       * @param int $flags
 103       * @return string
 104       */
 105  	public function cachedExpand( $key, $root, $flags = 0 );
 106  
 107      /**
 108       * Expand a document tree node
 109       * @param string|PPNode $root
 110       * @param int $flags
 111       * @return string
 112       */
 113  	public function expand( $root, $flags = 0 );
 114  
 115      /**
 116       * Implode with flags for expand()
 117       * @param string $sep
 118       * @param int $flags
 119       * @param string|PPNode $args,...
 120       * @return string
 121       */
 122  	public function implodeWithFlags( $sep, $flags /*, ... */ );
 123  
 124      /**
 125       * Implode with no flags specified
 126       * @param string $sep
 127       * @param string|PPNode $args,...
 128       * @return string
 129       */
 130  	public function implode( $sep /*, ... */ );
 131  
 132      /**
 133       * Makes an object that, when expand()ed, will be the same as one obtained
 134       * with implode()
 135       * @param string $sep
 136       * @param string|PPNode $args,...
 137       * @return PPNode
 138       */
 139  	public function virtualImplode( $sep /*, ... */ );
 140  
 141      /**
 142       * Virtual implode with brackets
 143       * @param string $start
 144       * @param string $sep
 145       * @param string $end
 146       * @param string|PPNode $args,...
 147       * @return PPNode
 148       */
 149  	public function virtualBracketedImplode( $start, $sep, $end /*, ... */ );
 150  
 151      /**
 152       * Returns true if there are no arguments in this frame
 153       *
 154       * @return bool
 155       */
 156  	public function isEmpty();
 157  
 158      /**
 159       * Returns all arguments of this frame
 160       * @return array
 161       */
 162  	public function getArguments();
 163  
 164      /**
 165       * Returns all numbered arguments of this frame
 166       * @return array
 167       */
 168  	public function getNumberedArguments();
 169  
 170      /**
 171       * Returns all named arguments of this frame
 172       * @return array
 173       */
 174  	public function getNamedArguments();
 175  
 176      /**
 177       * Get an argument to this frame by name
 178       * @param string $name
 179       * @return bool
 180       */
 181  	public function getArgument( $name );
 182  
 183      /**
 184       * Returns true if the infinite loop check is OK, false if a loop is detected
 185       *
 186       * @param Title $title
 187       * @return bool
 188       */
 189  	public function loopCheck( $title );
 190  
 191      /**
 192       * Return true if the frame is a template frame
 193       * @return bool
 194       */
 195  	public function isTemplate();
 196  
 197      /**
 198       * Set the "volatile" flag.
 199       *
 200       * Note that this is somewhat of a "hack" in order to make extensions
 201       * with side effects (such as Cite) work with the PHP parser. New
 202       * extensions should be written in a way that they do not need this
 203       * function, because other parsers (such as Parsoid) are not guaranteed
 204       * to respect it, and it may be removed in the future.
 205       *
 206       * @param bool $flag
 207       */
 208  	public function setVolatile( $flag = true );
 209  
 210      /**
 211       * Get the "volatile" flag.
 212       *
 213       * Callers should avoid caching the result of an expansion if it has the
 214       * volatile flag set.
 215       *
 216       * @see self::setVolatile()
 217       * @return bool
 218       */
 219  	public function isVolatile();
 220  
 221      /**
 222       * Get the TTL of the frame's output.
 223       *
 224       * This is the maximum amount of time, in seconds, that this frame's
 225       * output should be cached for. A value of null indicates that no
 226       * maximum has been specified.
 227       *
 228       * Note that this TTL only applies to caching frames as parts of pages.
 229       * It is not relevant to caching the entire rendered output of a page.
 230       *
 231       * @return int|null
 232       */
 233  	public function getTTL();
 234  
 235      /**
 236       * Set the TTL of the output of this frame and all of its ancestors.
 237       * Has no effect if the new TTL is greater than the one already set.
 238       * Note that it is the caller's responsibility to change the cache
 239       * expiry of the page as a whole, if such behavior is desired.
 240       *
 241       * @see self::getTTL()
 242       * @param int $ttl
 243       */
 244  	public function setTTL( $ttl );
 245  
 246      /**
 247       * Get a title of frame
 248       *
 249       * @return Title
 250       */
 251  	public function getTitle();
 252  }
 253  
 254  /**
 255   * There are three types of nodes:
 256   *     * Tree nodes, which have a name and contain other nodes as children
 257   *     * Array nodes, which also contain other nodes but aren't considered part of a tree
 258   *     * Leaf nodes, which contain the actual data
 259   *
 260   * This interface provides access to the tree structure and to the contents of array nodes,
 261   * but it does not provide access to the internal structure of leaf nodes. Access to leaf
 262   * data is provided via two means:
 263   *     * PPFrame::expand(), which provides expanded text
 264   *     * The PPNode::split*() functions, which provide metadata about certain types of tree node
 265   * @ingroup Parser
 266   */
 267  interface PPNode {
 268      /**
 269       * Get an array-type node containing the children of this node.
 270       * Returns false if this is not a tree node.
 271       * @return PPNode
 272       */
 273  	public function getChildren();
 274  
 275      /**
 276       * Get the first child of a tree node. False if there isn't one.
 277       *
 278       * @return PPNode
 279       */
 280  	public function getFirstChild();
 281  
 282      /**
 283       * Get the next sibling of any node. False if there isn't one
 284       * @return PPNode
 285       */
 286  	public function getNextSibling();
 287  
 288      /**
 289       * Get all children of this tree node which have a given name.
 290       * Returns an array-type node, or false if this is not a tree node.
 291       * @param string $type
 292       * @return bool|PPNode
 293       */
 294  	public function getChildrenOfType( $type );
 295  
 296      /**
 297       * Returns the length of the array, or false if this is not an array-type node
 298       */
 299  	public function getLength();
 300  
 301      /**
 302       * Returns an item of an array-type node
 303       * @param int $i
 304       * @return bool|PPNode
 305       */
 306  	public function item( $i );
 307  
 308      /**
 309       * Get the name of this node. The following names are defined here:
 310       *
 311       *    h             A heading node.
 312       *    template      A double-brace node.
 313       *    tplarg        A triple-brace node.
 314       *    title         The first argument to a template or tplarg node.
 315       *    part          Subsequent arguments to a template or tplarg node.
 316       *    #nodelist     An array-type node
 317       *
 318       * The subclass may define various other names for tree and leaf nodes.
 319       * @return string
 320       */
 321  	public function getName();
 322  
 323      /**
 324       * Split a "<part>" node into an associative array containing:
 325       *    name          PPNode name
 326       *    index         String index
 327       *    value         PPNode value
 328       * @return array
 329       */
 330  	public function splitArg();
 331  
 332      /**
 333       * Split an "<ext>" node into an associative array containing name, attr, inner and close
 334       * All values in the resulting array are PPNodes. Inner and close are optional.
 335       * @return array
 336       */
 337  	public function splitExt();
 338  
 339      /**
 340       * Split an "<h>" node
 341       * @return array
 342       */
 343  	public function splitHeading();
 344  }