// require_once('Tokenizer.php');
/**
- * PHP Parser
- *
- * Processes wiki markup
- *
- * There are two main entry points into the Parser class:
- * parse()
- * produces HTML output
- * preSaveTransform().
- * produces altered wiki markup.
- *
- * Globals used:
- * objects: $wgLang, $wgDateFormatter, $wgLinkCache, $wgCurParser
- *
- * NOT $wgArticle, $wgUser or $wgTitle. Keep them away!
- *
- * settings:
- * $wgUseTex*, $wgUseDynamicDates*, $wgInterwikiMagic*,
- * $wgNamespacesWithSubpages, $wgAllowExternalImages*,
- * $wgLocaltimezone
- *
- * * only within ParserOptions
+ * File for Parser and related classes
*
* @package MediaWiki
+ * @version $Id$
*/
/**
* Variable substitution O(N^2) attack
*
-* Without countermeasures, it would be possible to attack the parser by saving
-* a page filled with a large number of inclusions of large pages. The size of
-* the generated page would be proportional to the square of the input size.
-* Hence, we limit the number of inclusions of any given page, thus bringing any
-* attack back to O(N).
-*/
+ * Without countermeasures, it would be possible to attack the parser by saving
+ * a page filled with a large number of inclusions of large pages. The size of
+ * the generated page would be proportional to the square of the input size.
+ * Hence, we limit the number of inclusions of any given page, thus bringing any
+ * attack back to O(N).
+ */
define( 'MAX_INCLUDE_REPEAT', 100 );
define( 'MAX_INCLUDE_SIZE', 1000000 ); // 1 Million
);
/**
- * @todo document
+ * PHP Parser
+ *
+ * Processes wiki markup
+ *
+ * <pre>
+ * There are three main entry points into the Parser class:
+ * parse()
+ * produces HTML output
+ * preSaveTransform().
+ * produces altered wiki markup.
+ * transformMsg()
+ * performs brace substitution on MediaWiki messages
+ *
+ * Globals used:
+ * objects: $wgLang, $wgDateFormatter, $wgLinkCache, $wgCurParser
+ *
+ * NOT $wgArticle, $wgUser or $wgTitle. Keep them away!
+ *
+ * settings:
+ * $wgUseTex*, $wgUseDynamicDates*, $wgInterwikiMagic*,
+ * $wgNamespacesWithSubpages, $wgAllowExternalImages*,
+ * $wgLocaltimezone
+ *
+ * * only within ParserOptions
+ * </pre>
+ *
* @package MediaWiki
*/
class Parser
{
+ /**#@+
+ * @access private
+ */
# Persistent:
var $mTagHooks;
// multiple SQL queries for the same string
$mTemplatePath; // stores an unsorted hash of all the templates already loaded
// in this path. Used for loop detection.
+ /**#@-*/
+ /**
+ * Constructor
+ *
+ * @access public
+ */
function Parser() {
$this->mTemplates = array();
$this->mTemplatePath = array();
$this->clearState();
}
+ /**
+ * Clear Parser state
+ *
+ * @access private
+ */
function clearState() {
$this->mOutput = new ParserOutput;
$this->mAutonumber = 0;
$this->mInPre = false;
}
- # First pass--just handle <nowiki> sections, pass the rest off
- # to internalParse() which does all the real work.
- #
- # Returns a ParserOutput
- #
+ /**
+ * First pass--just handle <nowiki> sections, pass the rest off
+ * to internalParse() which does all the real work.
+ *
+ * @access private
+ * @return ParserOutput a ParserOutput
+ */
function parse( $text, &$title, $options, $linestart = true, $clearState = true ) {
global $wgUseTidy;
$fname = 'Parser::parse';
return $this->mOutput;
}
- /* static */ function getRandomString() {
+ /**
+ * Get a random string
+ *
+ * @access private
+ * @static
+ */
+ function getRandomString() {
return dechex(mt_rand(0, 0x7fffffff)) . dechex(mt_rand(0, 0x7fffffff));
}
- # Replaces all occurrences of <$tag>content</$tag> in the text
- # with a random marker and returns the new text. the output parameter
- # $content will be an associative array filled with data on the form
- # $unique_marker => content.
-
- # If $content is already set, the additional entries will be appended
-
- # If $tag is set to STRIP_COMMENTS, the function will extract
- # <!-- HTML comments -->
-
- /* static */ function extractTags($tag, $text, &$content, $uniq_prefix = ''){
+ /**
+ * Replaces all occurrences of <$tag>content</$tag> in the text
+ * with a random marker and returns the new text. the output parameter
+ * $content will be an associative array filled with data on the form
+ * $unique_marker => content.
+ *
+ * If $content is already set, the additional entries will be appended
+ * If $tag is set to STRIP_COMMENTS, the function will extract
+ * <!-- HTML comments -->
+ *
+ * @access private
+ * @static
+ */
+ function extractTags($tag, $text, &$content, $uniq_prefix = ''){
$rnd = $uniq_prefix . '-' . $tag . Parser::getRandomString();
if ( !$content ) {
$content = array( );
return $stripped;
}
- # Strips and renders <nowiki>, <pre>, <math>, <hiero>
- # If $render is set, performs necessary rendering operations on plugins
- # Returns the text, and fills an array with data needed in unstrip()
- # If the $state is already a valid strip state, it adds to the state
-
- # When $stripcomments is set, HTML comments <!-- like this -->
- # will be stripped in addition to other tags. This is important
- # for section editing, where these comments cause confusion when
- # counting the sections in the wikisource
+ /**
+ * Strips and renders nowiki, pre, math, hiero
+ * If $render is set, performs necessary rendering operations on plugins
+ * Returns the text, and fills an array with data needed in unstrip()
+ * If the $state is already a valid strip state, it adds to the state
+ *
+ * @param bool $stripcomments when set, HTML comments <!-- like this -->
+ * will be stripped in addition to other tags. This is important
+ * for section editing, where these comments cause confusion when
+ * counting the sections in the wikisource
+ *
+ * @access private
+ */
function strip( $text, &$state, $stripcomments = false ) {
$render = ($this->mOutputType == OT_HTML);
$html_content = array();
return $text;
}
- # always call unstripNoWiki() after this one
+ /**
+ * restores pre, math, and heiro removed by strip()
+ *
+ * always call unstripNoWiki() after this one
+ * @access private
+ */
function unstrip( $text, &$state ) {
# Must expand in reverse order, otherwise nested tags will be corrupted
$contentDict = end( $state );
return $text;
}
- # always call this after unstrip() to preserve the order
+
+ /**
+ * always call this after unstrip() to preserve the order
+ *
+ * @access private
+ */
function unstripNoWiki( $text, &$state ) {
# Must expand in reverse order, otherwise nested tags will be corrupted
for ( $content = end($state['nowiki']); $content !== false; $content = prev( $state['nowiki'] ) ) {
return $text;
}
- # Add an item to the strip state
- # Returns the unique tag which must be inserted into the stripped text
- # The tag will be replaced with the original text in unstrip()
+ /**
+ * Add an item to the strip state
+ * Returns the unique tag which must be inserted into the stripped text
+ * The tag will be replaced with the original text in unstrip()
+ *
+ * @access private
+ */
function insertStripItem( $text, &$state ) {
$rnd = UNIQ_PREFIX . '-item' . Parser::getRandomString();
if ( !$state ) {
return $rnd;
}
- # Return allowed HTML attributes
+ /**
+ * Return allowed HTML attributes
+ *
+ * @access private
+ */
function getHTMLattrs () {
$htmlattrs = array( # Allowed attributes--no scripting, etc.
'title', 'align', 'lang', 'dir', 'width', 'height',
return $htmlattrs ;
}
- # Remove non approved attributes and javascript in css
+ /**
+ * Remove non approved attributes and javascript in css
+ *
+ * @access private
+ */
function fixTagAttributes ( $t ) {
if ( trim ( $t ) == '' ) return '' ; # Saves runtime ;-)
$htmlattrs = $this->getHTMLattrs() ;
return trim ( $t ) ;
}
- # interface with html tidy, used if $wgUseTidy = true
+ /**
+ * interface with html tidy, used if $wgUseTidy = true
+ *
+ * @access private
+ */
function tidy ( $text ) {
global $wgTidyConf, $wgTidyBin, $wgTidyOpts;
global $wgInputEncoding, $wgOutputEncoding;
}
}
- # parse the wiki syntax used to render tables
+ /**
+ * parse the wiki syntax used to render tables
+ *
+ * @access private
+ */
function doTableStuff ( $t ) {
$fname = 'Parser::doTableStuff';
wfProfileIn( $fname );
return $t ;
}
+ /**
+ * Helper function for parse() that transforms wiki markup into
+ * HTML. Only called for $mOutputType == OT_HTML.
+ *
+ * @access private
+ */
function internalParse( $text, $linestart, $args = array(), $isMain=true ) {
global $wgLang;
$text = $this->replaceExternalLinks( $text );
$text = $this->doMagicLinks( $text );
$text = $this->replaceInternalLinks ( $text );
+ # Another call to replace links and images inside captions of images
$text = $this->replaceInternalLinks ( $text );
$text = $this->unstrip( $text, $this->mStripState );
return $text;
}
- /* private */ function &doMagicLinks( &$text ) {
+ /**
+ * Replace special strings like "ISBN xxx" and "RFC xxx" with
+ * magic external links.
+ *
+ * @access private
+ */
+ function &doMagicLinks( &$text ) {
global $wgUseGeoMode;
$text = $this->magicISBN( $text );
if ( isset( $wgUseGeoMode ) && $wgUseGeoMode ) {
return $text;
}
- # Parse ^^ tokens and return html
- /* private */ function doExponent ( $text ) {
+ /**
+ * Parse ^^ tokens and return html
+ *
+ * @access private
+ */
+ function doExponent ( $text ) {
$fname = 'Parser::doExponent';
wfProfileIn( $fname);
$text = preg_replace('/\^\^(.*)\^\^/','<small><sup>\\1</sup></small>', $text);
return $text;
}
- # Parse headers and return html
- /* private */ function doHeadings( $text ) {
+ /**
+ * Parse headers and return html
+ *
+ * @access private
+ */
+ function doHeadings( $text ) {
$fname = 'Parser::doHeadings';
wfProfileIn( $fname );
for ( $i = 6; $i >= 1; --$i ) {
return $text;
}
- /* private */ function doAllQuotes( $text ) {
+ /**
+ * Replace single quotes with HTML markup
+ * @access private
+ * @return string the altered text
+ */
+ function doAllQuotes( $text ) {
$fname = 'Parser::doAllQuotes';
wfProfileIn( $fname );
$outtext = '';
return $outtext;
}
- /* private */ function doQuotes( $text ) {
+ /**
+ * Helper function for doAllQuotes()
+ * @access private
+ */
+ function doQuotes( $text ) {
$arr = preg_split ("/(''+)/", $text, -1, PREG_SPLIT_DELIM_CAPTURE);
if (count ($arr) == 1)
return $text;
}
}
- # Note: we have to do external links before the internal ones,
- # and otherwise take great care in the order of things here, so
- # that we don't end up interpreting some URLs twice.
-
- /* private */ function replaceExternalLinks( $text ) {
+ /**
+ * Replace external links
+ *
+ * Note: we have to do external links before the internal ones,
+ * and otherwise take great care in the order of things here, so
+ * that we don't end up interpreting some URLs twice.
+ *
+ * @access private
+ */
+ function replaceExternalLinks( $text ) {
$fname = 'Parser::replaceExternalLinks';
wfProfileIn( $fname );
return $s;
}
- # Replace anything that looks like a URL with a link
+ /**
+ * Replace anything that looks like a URL with a link
+ * @access private
+ */
function replaceFreeExternalLinks( $text ) {
$bits = preg_split( '/((?:'.URL_PROTOCOLS.'):)/', $text, -1, PREG_SPLIT_DELIM_CAPTURE );
$s = array_shift( $bits );
return $s;
}
- # make an image if it's allowed
+ /**
+ * make an image if it's allowed
+ * @access private
+ */
function maybeMakeImageLink( $url ) {
$sk =& $this->mOptions->getSkin();
$text = false;
return $text;
}
- # The wikilinks [[ ]] are procedeed here.
- /* private */ function replaceInternalLinks( $s ) {
+ /**
+ * Process [[ ]] wikilinks
+ *
+ * @access private
+ */
+ function replaceInternalLinks( $s ) {
global $wgLang, $wgLinkCache;
global $wgNamespacesWithSubpages;
static $fname = 'Parser::replaceInternalLinks' ;
return $s;
}
- # Some functions here used by doBlockLevels()
- #
+ /**#@+
+ * Used by doBlockLevels()
+ * @access private
+ */
/* private */ function closeParagraph() {
$result = '';
if ( '' != $this->mLastSection ) {
else { return '<!-- ERR 3 -->'; }
return $text."\n";
}
+ /**#@-*/
- /* private */ function doBlockLevels( $text, $linestart ) {
+ /**
+ * Make lists from lines starting with ':', '*', '#', etc.
+ *
+ * @access private
+ * @return string the lists rendered as HTML
+ */
+ function doBlockLevels( $text, $linestart ) {
$fname = 'Parser::doBlockLevels';
wfProfileIn( $fname );
return $output;
}
- # Return value of a magic variable (like PAGENAME)
+ /**
+ * Return value of a magic variable (like PAGENAME)
+ *
+ * @access private
+ */
function getVariableValue( $index ) {
global $wgLang, $wgSitename, $wgServer;
}
}
- # initialise the magic variables (like CURRENTMONTHNAME)
+ /**
+ * initialise the magic variables (like CURRENTMONTHNAME)
+ *
+ * @access private
+ */
function initialiseVariables() {
global $wgVariableIDs;
$this->mVariables = array();
}
}
- /* private */ function replaceVariables( $text, $args = array() ) {
+ /**
+ * Replace magic variables, templates, and template arguments
+ * with the appropriate text. Templates are substituted recursively,
+ * taking care to avoid infinite loops.
+ *
+ * Note that the substitution depends on value of $mOutputType:
+ * OT_WIKI: only {{subst:}} templates
+ * OT_MSG: only magic variables
+ * OT_HTML: all templates and magic variables
+ *
+ * @param string $tex The text to transform
+ * @param array $args Key-value pairs representing template parameters to substitute
+ * @access private
+ */
+ function replaceVariables( $text, $args = array() ) {
global $wgLang, $wgScript, $wgArticlePath;
# Prevent too big inclusions
return $args;
}
+ /**
+ * Return the text of a template, after recursively
+ * replacing any variables or templates within the template.
+ *
+ * @param array $matches The parts of the template
+ * $matches[1]: the title, i.e. the part before the |
+ * $matches[2]: the parameters (including a leading |), if any
+ * @return string the text of the template
+ * @access private
+ */
function braceSubstitution( $matches ) {
global $wgLinkCache, $wgLang;
$fname = 'Parser::braceSubstitution';
}
}
- # Triple brace replacement -- used for template arguments
+ /**
+ * Triple brace replacement -- used for template arguments
+ * @access private
+ */
function argSubstitution( $matches ) {
$arg = trim( $matches[1] );
$text = $matches[0];
return $text;
}
- # Returns true if the function is allowed to include this entity
+ /**
+ * Returns true if the function is allowed to include this entity
+ * @access private
+ */
function incrementIncludeCount( $dbk ) {
if ( !array_key_exists( $dbk, $this->mIncludeCount ) ) {
$this->mIncludeCount[$dbk] = 0;
}
- # Cleans up HTML, removes dangerous tags and attributes
- /* private */ function removeHTMLtags( $text ) {
+ /**
+ * Cleans up HTML, removes dangerous tags and attributes, and
+ * removes HTML comments
+ * @access private
+ */
+ function removeHTMLtags( $text ) {
global $wgUseTidy, $wgUserHtml;
$fname = 'Parser::removeHTMLtags';
wfProfileIn( $fname );
return $text;
}
- # This function accomplishes several tasks:
- # 1) Auto-number headings if that option is enabled
- # 2) Add an [edit] link to sections for logged in users who have enabled the option
- # 3) Add a Table of contents on the top for users who have enabled the option
- # 4) Auto-anchor headings
- #
- # It loops through all headlines, collects the necessary data, then splits up the
- # string and re-inserts the newly formatted headlines.
+ /**
+ * This function accomplishes several tasks:
+ * 1) Auto-number headings if that option is enabled
+ * 2) Add an [edit] link to sections for logged in users who have enabled the option
+ * 3) Add a Table of contents on the top for users who have enabled the option
+ * 4) Auto-anchor headings
+ *
+ * It loops through all headlines, collects the necessary data, then splits up the
+ * string and re-inserts the newly formatted headlines.
+ * @access private
+ */
/* private */ function formatHeadings( $text, $isMain=true ) {
global $wgInputEncoding, $wgMaxTocLevel, $wgLang, $wgLinkHolders;
}
}
- # Return an HTML link for the "ISBN 123456" text
- /* private */ function magicISBN( $text ) {
+ /**
+ * Return an HTML link for the "ISBN 123456" text
+ * @access private
+ */
+ function magicISBN( $text ) {
global $wgLang;
$fname = 'Parser::magicISBN';
wfProfileIn( $fname );
return $text;
}
- # Return an HTML link for the "GEO ..." text
- /* private */ function magicGEO( $text ) {
+ /**
+ * Return an HTML link for the "GEO ..." text
+ * @access private
+ */
+ function magicGEO( $text ) {
global $wgLang, $wgUseGeoMode;
$fname = 'Parser::magicGEO';
wfProfileIn( $fname );
return $text;
}
+ /**
+ * Transform wiki markup when saving a page by doing \r\n -> \n
+ * conversion, substitting signatures, {{subst:}} templates, etc.
+ *
+ * @param string $text the text to transform
+ * @param Title &$title the Title object for the current article
+ * @param User &$user the User object describing the current user
+ * @param ParserOptions $options parsing options
+ * @param bool $clearState whether to clear the parser state first
+ * @return string the altered wiki markup
+ * @access public
+ */
function preSaveTransform( $text, &$title, &$user, $options, $clearState = true ) {
$this->mOptions = $options;
$this->mTitle =& $title;
return $text;
}
- /* private */ function pstPass2( $text, &$user ) {
+ /**
+ * Pre-save transform helper function
+ * @access private
+ */
+ function pstPass2( $text, &$user ) {
global $wgLang, $wgLocaltimezone, $wgCurParser;
# Variable replacement
return $text;
}
- # Set up some variables which are usually set up in parse()
- # so that an external function can call some class members with confidence
+ /**
+ * Set up some variables which are usually set up in parse()
+ * so that an external function can call some class members with confidence
+ * @access public
+ */
function startExternalParse( &$title, $options, $outputType, $clearState = true ) {
$this->mTitle =& $title;
$this->mOptions = $options;
}
}
+ /**
+ * Transform a MediaWiki message by replacing magic variables.
+ *
+ * @param string $text the text to transform
+ * @param ParserOptions $options options
+ * @return string the text with variables substituted
+ * @access public
+ */
function transformMsg( $text, $options ) {
global $wgTitle;
static $executing = false;
return $text;
}
- # Create an HTML-style tag, e.g. <yourtag>special text</yourtag>
- # Callback will be called with the text within
- # Transform and return the text within
+ /**
+ * Create an HTML-style tag, e.g. <yourtag>special text</yourtag>
+ * Callback will be called with the text within
+ * Transform and return the text within
+ * @access public
+ */
function setHook( $tag, $callback ) {
$oldVal = @$this->mTagHooks[$tag];
$this->mTagHooks[$tag] = $callback;