includes/parser/PPNode.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  * @ingroup Parser
  20  */
  21
  22 /**
  23  * There are three types of nodes:
  24  *     * Tree nodes, which have a name and contain other nodes as children
  25  *     * Array nodes, which also contain other nodes but aren't considered part of a tree
  26  *     * Leaf nodes, which contain the actual data
  27  *
  28  * This interface provides access to the tree structure and to the contents of array nodes,
  29  * but it does not provide access to the internal structure of leaf nodes. Access to leaf
  30  * data is provided via two means:
  31  *     * PPFrame::expand(), which provides expanded text
  32  *     * The PPNode::split*() functions, which provide metadata about certain types of tree node
  33  * @ingroup Parser
  34  */
  35 interface PPNode {
  36         /**
  37          * Get an array-type node containing the children of this node.
  38          * Returns false if this is not a tree node.
  39          * @return false|PPNode
  40          */
  41         public function getChildren();
  42
  43         /**
  44          * Get the first child of a tree node. False if there isn't one.
  45          *
  46          * @return false|PPNode
  47          */
  48         public function getFirstChild();
  49
  50         /**
  51          * Get the next sibling of any node. False if there isn't one
  52          * @return false|PPNode
  53          */
  54         public function getNextSibling();
  55
  56         /**
  57          * Get all children of this tree node which have a given name.
  58          * Returns an array-type node, or false if this is not a tree node.
  59          * @param string $type
  60          * @return false|PPNode
  61          */
  62         public function getChildrenOfType( $type );
  63
  64         /**
  65          * Returns the length of the array, or false if this is not an array-type node
  66          */
  67         public function getLength();
  68
  69         /**
  70          * Returns an item of an array-type node
  71          * @param int $i
  72          * @return bool|PPNode
  73          */
  74         public function item( $i );
  75
  76         /**
  77          * Get the name of this node. The following names are defined here:
  78          *
  79          *    h             A heading node.
  80          *    template      A double-brace node.
  81          *    tplarg        A triple-brace node.
  82          *    title         The first argument to a template or tplarg node.
  83          *    part          Subsequent arguments to a template or tplarg node.
  84          *    #nodelist     An array-type node
  85          *
  86          * The subclass may define various other names for tree and leaf nodes.
  87          * @return string
  88          */
  89         public function getName();
  90
  91         /**
  92          * Split a "<part>" node into an associative array containing:
  93          *    name          PPNode name
  94          *    index         String index
  95          *    value         PPNode value
  96          * @return array
  97          */
  98         public function splitArg();
  99
 100         /**
 101          * Split an "<ext>" node into an associative array containing name, attr, inner and close
 102          * All values in the resulting array are PPNodes. Inner and close are optional.
 103          * @return array
 104          */
 105         public function splitExt();
 106
 107         /**
 108          * Split an "<h>" node
 109          * @return array
 110          */
 111         public function splitHeading();
 112 }