An implementation of the tree building portion of the HTML5 parsing spec. More...

Public Member Functions
	__construct (array $config=[])
	Create a new Balancer. More...

	balance ($text, $processingCallback=null, $processingArgs=[])
	Return a balanced HTML string for the HTML fragment given by $text, subject to the caveats listed in the class description. More...

Public Attributes
const	VALID_COMMENT_REGEX
	Valid HTML5 comments. More...

Private Member Functions
	advance ()
	Grab the next "token" from $bitsIterator. More...

	endCaption ()

	endCell ()

	endRow ()

	endSection ()

	inBodyMode ($token, $value, $attribs=null, $selfclose=false)

	inCaptionMode ($token, $value, $attribs=null, $selfclose=false)

	inCellMode ($token, $value, $attribs=null, $selfclose=false)

	inColumnGroupMode ($token, $value, $attribs=null, $selfclose=false)

	inHeadMode ($token, $value, $attribs=null, $selfclose=false)

	inRowMode ($token, $value, $attribs=null, $selfclose=false)

	inSelectInTableMode ($token, $value, $attribs=null, $selfclose=false)

	inSelectMode ($token, $value, $attribs=null, $selfclose=false)

	insertForeignToken ($token, $value, $attribs=null, $selfclose=false)

	insertToken ($token, $value, $attribs=null, $selfclose=false)
	Pass a token to the tree builder. More...

	inTableBodyMode ($token, $value, $attribs=null, $selfclose=false)

	inTableMode ($token, $value, $attribs=null, $selfclose=false)

	inTableTextMode ($token, $value, $attribs=null, $selfclose=false)

	inTemplateMode ($token, $value, $attribs=null, $selfclose=false)

	inTextMode ($token, $value, $attribs=null, $selfclose=false)

	parseRawText ($value, $attribs=null)

	resetInsertionMode ()

	stopParsing ()

	switchMode ($mode)

	switchModeAndReprocess ($mode, $token, $value, $attribs, $selfclose)

Private Attributes
	$afe

	$allowComments

	$allowedHtmlElements

	$bitsIterator

	$formElementPointer

	$fragmentContext

	$ignoreLinefeed

	$inRAWTEXT

	$inRCDATA

	$originalInsertionMode

	$parseMode

	$pendingTableText

	$stack

	$strict

	$textIntegrationMode

	$tidyCompat

Detailed Description

An implementation of the tree building portion of the HTML5 parsing spec.

This is used to balance and tidy output so that the result can always be cleanly serialized/deserialized by an HTML5 parser. It does not guarantee "conforming" output – the HTML5 spec contains a number of constraints which are not enforced by the HTML5 parsing process. But the result will be free of gross errors: misnested or unclosed tags, for example, and will be unchanged by spec-complient parsing followed by serialization.

The tree building stage is structured as a state machine. When comparing the implementation to https://www.w3.org/TR/html5/syntax.html#tree-construction note that each state is implemented as a function with a name ending in Mode (because the HTML spec refers to them as insertion modes). The current insertion mode is held by the $parseMode property.

The following simplifications have been made:

We handle body content only (ie, we start in body.)
The document is never in "quirks mode".
All occurrences of < and > have been entity escaped, so we can parse tags by simply splitting on those two characters. (This also simplifies the handling of < inside <textarea>.) The character < must not appear inside comments. Similarly, all attributes have been "cleaned" and are double-quoted and escaped.
All null characters are assumed to have been removed.
The following elements are disallowed: <html>, <head>, <body>, <frameset>, <frame>, <plaintext>, <isindex>, <xmp>, <iframe>, <noembed>, <noscript>, <script>, <title>. As a result, further simplifications can be made:
- frameset-ok is not tracked.
- head element pointer is not tracked (but presumed non-null)
- Tokenizer has only a single mode. (<textarea> wants RCDATA and <style>/<noframes> want RAWTEXT modes which we only loosely emulate.)
We generally mark places where we omit cases from the spec due to disallowed elements with a comment: # OMITTED: <element-name>.

The HTML spec keeps a flag during the parsing process to track whether or not a "parse error" has been encountered. We don't bother to track that flag, we just implement the error-handling process as specified.

Since: 1.27

See Also: https://html.spec.whatwg.org/multipage/syntax.html#tree-construction

Definition at line 1785 of file Balancer.php.

Constructor & Destructor Documentation

MediaWiki\Tidy\Balancer::__construct ( array $config = [] )

Create a new Balancer.

Parameters

array $config Balancer configuration. Includes: 'strict' : boolean, defaults to false. When true, enforces syntactic constraints on input: all non-tag '<' must be escaped, all attributes must be separated by a single space and double-quoted. This is consistent with the output of the Sanitizer. 'allowedHtmlElements' : array, defaults to null. When present, the keys of this associative array give the acceptable HTML tag names. When not present, no tag sanitization is done. 'tidyCompat' : boolean, defaults to false. When true, the serialization algorithm is tweaked to provide historical compatibility with the old "tidy" program:

-wrapping is done to the children of <body> and

elements, and empty elements are removed. 'allowComments': boolean, defaults to true. When true, allows HTML comments in the input. The Sanitizer generally strips all comments, so if you are running on sanitized output you can set this to false to get a bit more performance.

Definition at line 1859 of file Balancer.php.

References MediaWiki\$config, MediaWiki\Tidy\BalanceSets\$unsupportedSet, and MediaWiki\Tidy\BalanceSets\HTML_NAMESPACE.

Member Function Documentation

MediaWiki\Tidy\Balancer::advance ( )

private

Grab the next "token" from $bitsIterator.

This is either a open/close tag or text or a comment, depending on whether the Sanitizer approves.

Definition at line 2128 of file Balancer.php.

References $attribs, $t, Sanitizer\decodeTagAttributes(), Sanitizer\ELEMENT_BITS_REGEX, MediaWiki\Tidy\Balancer\insertToken(), list, MediaWiki\Tidy\Balancer\VALID_COMMENT_REGEX, Sanitizer\validateTag(), and Sanitizer\validateTagAttributes().

Referenced by MediaWiki\Tidy\Balancer\balance().

MediaWiki\Tidy\Balancer::balance	(	$text,
		$processingCallback = `null`,
		$processingArgs = `[]`
	)

Return a balanced HTML string for the HTML fragment given by $text, subject to the caveats listed in the class description.

The result will typically be idempotent – that is, rebalancing the output would result in no change.

Parameters

string	$text	The markup to be balanced
callable	$processingCallback	Callback to do any variable or parameter replacements in HTML attributes values
array \| bool	$processingArgs	Arguments for the processing callback

Returns: string The balanced markup

Definition at line 1904 of file Balancer.php.

References $e, MediaWiki\Tidy\Balancer\$tidyCompat, MediaWiki\Tidy\Balancer\advance(), MediaWiki\Tidy\BalanceSets\HTML_NAMESPACE, MediaWiki\Tidy\Balancer\insertToken(), and MediaWiki\Tidy\Balancer\resetInsertionMode().

MediaWiki\Tidy\Balancer::endCaption ( )

private

Definition at line 3060 of file Balancer.php.

MediaWiki\Tidy\Balancer::endCell ( )

private

Definition at line 3303 of file Balancer.php.

MediaWiki\Tidy\Balancer::endRow ( )

private

Definition at line 3237 of file Balancer.php.

MediaWiki\Tidy\Balancer::endSection ( )

private

Definition at line 3170 of file Balancer.php.

MediaWiki\Tidy\Balancer::inBodyMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 2412 of file Balancer.php.

References MediaWiki\Tidy\BalanceSets\$addressDivPSet, $attribs, MediaWiki\Tidy\Balancer\$formElementPointer, MediaWiki\Tidy\BalanceSets\$headingSet, MediaWiki\Tidy\BalanceSets\$specialSet, $value, as, MediaWiki\Tidy\Balancer\inHeadMode(), MediaWiki\Tidy\Balancer\insertToken(), MediaWiki\Tidy\Balancer\inTemplateMode(), MediaWiki\Tidy\BalanceSets\MATHML_NAMESPACE, MediaWiki\Tidy\Balancer\stopParsing(), MediaWiki\Tidy\BalanceSets\SVG_NAMESPACE, and MediaWiki\Tidy\Balancer\switchMode().

MediaWiki\Tidy\Balancer::inCaptionMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3071 of file Balancer.php.

MediaWiki\Tidy\Balancer::inCellMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3314 of file Balancer.php.

MediaWiki\Tidy\Balancer::inColumnGroupMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3118 of file Balancer.php.

MediaWiki\Tidy\Balancer::inHeadMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 2342 of file Balancer.php.

References $attribs, $matches, MediaWiki\Tidy\Balancer\$parseMode, $value, MediaWiki\Tidy\Balancer\insertToken(), MediaWiki\Tidy\Balancer\parseRawText(), MediaWiki\Tidy\Balancer\resetInsertionMode(), and MediaWiki\Tidy\Balancer\switchMode().

Referenced by MediaWiki\Tidy\Balancer\inBodyMode().

MediaWiki\Tidy\Balancer::inRowMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3246 of file Balancer.php.

MediaWiki\Tidy\Balancer::inSelectInTableMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3444 of file Balancer.php.

MediaWiki\Tidy\Balancer::inSelectMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3368 of file Balancer.php.

MediaWiki\Tidy\Balancer::insertForeignToken	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 2022 of file Balancer.php.

References $attribs, MediaWiki\Tidy\Balancer\$parseMode, $value, as, and MediaWiki\Tidy\Balancer\insertToken().

Referenced by MediaWiki\Tidy\Balancer\insertToken().

MediaWiki\Tidy\Balancer::insertToken	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Pass a token to the tree builder.

The $token will be one of the strings "tag", "endtag", or "text".

Definition at line 1954 of file Balancer.php.

References $attribs, MediaWiki\Tidy\Balancer\$parseMode, MediaWiki\Tidy\BalanceSets\$unsupportedSet, $value, MediaWiki\Tidy\BalanceSets\HTML_NAMESPACE, MediaWiki\Tidy\Balancer\insertForeignToken(), and MediaWiki\Tidy\BalanceSets\MATHML_NAMESPACE.

Referenced by MediaWiki\Tidy\Balancer\advance(), MediaWiki\Tidy\Balancer\balance(), MediaWiki\Tidy\Balancer\inBodyMode(), MediaWiki\Tidy\Balancer\inHeadMode(), MediaWiki\Tidy\Balancer\insertForeignToken(), and MediaWiki\Tidy\Balancer\switchModeAndReprocess().

MediaWiki\Tidy\Balancer::inTableBodyMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3183 of file Balancer.php.

MediaWiki\Tidy\Balancer::inTableMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 2928 of file Balancer.php.

MediaWiki\Tidy\Balancer::inTableTextMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3037 of file Balancer.php.

MediaWiki\Tidy\Balancer::inTemplateMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 3469 of file Balancer.php.

Referenced by MediaWiki\Tidy\Balancer\inBodyMode().

MediaWiki\Tidy\Balancer::inTextMode	(	$token,
		$value,
		$attribs = `null`,
		$selfclose = `false`
	)

private

Definition at line 2325 of file Balancer.php.

References $attribs, $value, MediaWiki\Tidy\Balancer\switchMode(), and MediaWiki\Tidy\Balancer\switchModeAndReprocess().

MediaWiki\Tidy\Balancer::parseRawText	(	$value,
		$attribs = `null`
	)

private

Definition at line 2318 of file Balancer.php.

References $attribs, $value, and MediaWiki\Tidy\Balancer\switchMode().

Referenced by MediaWiki\Tidy\Balancer\inHeadMode().

MediaWiki\Tidy\Balancer::resetInsertionMode ( )

private

Definition at line 2235 of file Balancer.php.

References MediaWiki\Tidy\Balancer\$fragmentContext, $last, MediaWiki\Tidy\BalanceSets\$tableCellSet, as, and MediaWiki\Tidy\Balancer\switchMode().

Referenced by MediaWiki\Tidy\Balancer\balance(), and MediaWiki\Tidy\Balancer\inHeadMode().

MediaWiki\Tidy\Balancer::stopParsing ( )

private

Definition at line 2305 of file Balancer.php.

Referenced by MediaWiki\Tidy\Balancer\inBodyMode().

MediaWiki\Tidy\Balancer::switchMode ( $mode )

private

Definition at line 2221 of file Balancer.php.

References MediaWiki\Tidy\Balancer\$parseMode.

Referenced by MediaWiki\Tidy\Balancer\inBodyMode(), MediaWiki\Tidy\Balancer\inHeadMode(), MediaWiki\Tidy\Balancer\inTextMode(), MediaWiki\Tidy\Balancer\parseRawText(), MediaWiki\Tidy\Balancer\resetInsertionMode(), and MediaWiki\Tidy\Balancer\switchModeAndReprocess().

MediaWiki\Tidy\Balancer::switchModeAndReprocess	(	$mode,
		$token,
		$value,
		$attribs,
		$selfclose
	)

private

Definition at line 2230 of file Balancer.php.

References $attribs, $value, MediaWiki\Tidy\Balancer\insertToken(), and MediaWiki\Tidy\Balancer\switchMode().

Referenced by MediaWiki\Tidy\Balancer\inTextMode().

Member Data Documentation

MediaWiki\Tidy\Balancer::$afe

private

Definition at line 1789 of file Balancer.php.

MediaWiki\Tidy\Balancer::$allowComments

private

Definition at line 1793 of file Balancer.php.

MediaWiki\Tidy\Balancer::$allowedHtmlElements

private

Definition at line 1788 of file Balancer.php.

MediaWiki\Tidy\Balancer::$bitsIterator

private

Definition at line 1787 of file Balancer.php.

MediaWiki\Tidy\Balancer::$formElementPointer

private

Definition at line 1799 of file Balancer.php.

Referenced by MediaWiki\Tidy\Balancer\inBodyMode().

MediaWiki\Tidy\Balancer::$fragmentContext

private

Definition at line 1798 of file Balancer.php.

Referenced by MediaWiki\Tidy\Balancer\resetInsertionMode().

MediaWiki\Tidy\Balancer::$ignoreLinefeed

private

Definition at line 1800 of file Balancer.php.

MediaWiki\Tidy\Balancer::$inRAWTEXT

private

Definition at line 1802 of file Balancer.php.

MediaWiki\Tidy\Balancer::$inRCDATA

private

Definition at line 1801 of file Balancer.php.

MediaWiki\Tidy\Balancer::$originalInsertionMode

private

Definition at line 1797 of file Balancer.php.

MediaWiki\Tidy\Balancer::$parseMode

private

Definition at line 1786 of file Balancer.php.

Referenced by MediaWiki\Tidy\Balancer\inHeadMode(), MediaWiki\Tidy\Balancer\insertForeignToken(), MediaWiki\Tidy\Balancer\insertToken(), and MediaWiki\Tidy\Balancer\switchMode().

MediaWiki\Tidy\Balancer::$pendingTableText

private

Definition at line 1796 of file Balancer.php.

MediaWiki\Tidy\Balancer::$stack

private

Definition at line 1790 of file Balancer.php.

MediaWiki\Tidy\Balancer::$strict

private

Definition at line 1791 of file Balancer.php.

MediaWiki\Tidy\Balancer::$textIntegrationMode

private

Definition at line 1795 of file Balancer.php.

MediaWiki\Tidy\Balancer::$tidyCompat

private

Definition at line 1792 of file Balancer.php.

Referenced by MediaWiki\Tidy\Balancer\balance().

const MediaWiki\Tidy\Balancer::VALID_COMMENT_REGEX

Initial value:

= "~ !--
        (                             # 1. Comment match detector
            > | -> | # Invalid short close
            (                         # 2. Comment contents
                (?:
                    (?! --> )
                    (?! --!> )
                    (?! --! \z )
                    (?! -- \z )
                    (?! - \z )
                    .
                )*+
            )
            (                         # 3. Comment close
                --> |   # Normal close
                --!> |  # Comment end bang
                (                     # 4. Indicate matches requiring EOF
                    --! |   # EOF in comment end bang state
                    -- |    # EOF in comment end state
                    -  |    # EOF in comment end dash state
                            # EOF in comment state
                )
            )
        )
        ([^<]*) \z                    # 5. Non-tag text after the comment
        ~xs"

Valid HTML5 comments.

Regex borrowed from Tim Starling's "remex-html" project.

Definition at line 1808 of file Balancer.php.

Referenced by MediaWiki\Tidy\Balancer\advance().

The documentation for this class was generated from the following file:

includes/tidy/Balancer.php

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation