Tag rules

Rules are contained in s9e\TextFormatter\Configurator\Collections\Ruleset.
They are set on a per-tag basis, for example:

$configurator = new Configurator;

$tag = $configurator->tags->add('B');
$tag->rules->autoReopen();
$tag->rules->denyChild('X');

Method calls can be chained for convenience. The same example can be written as:

$configurator = new Configurator;

$tag = $configurator->tags->add('B');
$tag->rules->autoReopen()
           ->denyChild('X');

Rules can be:

• boolean — they accept true or false as argument, with true being the default.
• targeted — they accept a tag name as argument.

Rules that apply to descendants also apply to children. Rules that apply to ancestors also apply to the parent. A tag that is explicitly denied cannot be allowed by another rule.

allowChild

Example: $tag->rules->allowChild('X');

Allows tag X to be used as a child of given tag.

allowDescendant

Example: $tag->rules->allowDescendant('X');

Allows tag X to be used as a non-child descendant of given tag.

autoClose

Example: $tag->rules->autoClose(true);

Start tags of this tag are automatically closed if they are not paired with an end tag. This rule exists primarily to deal with void elements such as <img>.

autoReopen

Example: $tag->rules->autoReopen(false);

Automatically reopens this tag if it's closed by a non-matching tag. This rule helps dealing with misnested tags such as <B><I></B></I>. In this case, if I has an autoReopen rule, it will automatically be reopened when B closes.

breakParagraph

Example: $tag->rules->breakParagraph();

This tag will break current paragraph if applicable.

closeAncestor

Example: $tag->rules->closeAncestor('X');

Forces all ancestor tags X to be closed when this tag is encountered.

closeParent

Example: $tag->rules->closeParent('LI');

Forces current parent LI to be closed when this tag is encountered. Helps dealing with optional end tags. For instance, if LI has a closeParent rule targeting LI, the following <LI>one<LI>two is interpreted as <LI>one</LI><LI>two.

createChild

Example: $tag->rules->createChild('LI');

Automatically creates a LI tag at the first non-whitespace position after current tag.

createParagraphs

Example: $configurator->rootRules->createParagraphs();

Automatically creates paragraphs (HTML element <p>) to host content. Using two consecutive new lines indicates a paragraph break in content.

denyChild

Example: $tag->rules->denyChild('X');

Prevents tag X to be used as a child of this tag.

denyDescendant

Example: $tag->rules->denyDescendant('X');

Prevents tag X to be used as a non-child descendant of this tag.

disableAutoLineBreaks

Example: $tag->rules->disableAutoLineBreaks();

Turns off the conversion of new lines in the scope of this tag. Conversion can be turned back on by descendants.

enableAutoLineBreaks

Example: $tag->rules->enableAutoLineBreaks();

Turns on the conversion of new lines to <br/>. Conversion applies to descendants as well, unless selectively disabled or suspended.

fosterParent

Example: $tag->rules->fosterParent('X');

Forces current parent X to be closed when this tag is encountered, and reopened as its child. If this tag is a self-closing tag, X is reopened as its next sibling.

ignoreSurroundingWhitespace

Example: $tag->rules->ignoreSurroundingWhitespace();

Whether whitespace around this tag should be ignored. Useful for allowing whitespace around block elements without extra newlines being displayed. Limited to 1 newline before the template, 1 newline at the start and at the end of its content, and up to 2 newlines after it.

ignoreTags

Example: $tag->rules->ignoreTags();

Silently ignore all tags until current tag is closed. Does not effect the automatic conversion of new lines or system tags such as line breaks, paragraphs breaks and ignore tags.

ignoreText

Example: $tag->rules->ignoreText();

Prevents plain text from being displayed as a child of this tag. Also disables line breaks. This rule deals with elements that do not allow text, such as lists. Does not apply to descendants.

isTransparent

Example: $tag->rules->isTransparent();

Indicates that this tag uses the transparent content model and their allow/deny rules are inherited from its parent.

preventLineBreaks

Example: $tag->rules->preventLineBreaks();

Prevent manual line breaks in this tag's context. Does not apply to descendants. Does not apply to automatic line breaks.

requireParent

Example: $tag->rules->requireParent('X');

Prevents this tag from being used unless it's as a child of X. If multiple requireParent rules are set, only one has to be satisfied.

requireAncestor

Example: $tag->rules->requireAncestor('X');

Prevents this tag from being used unless it's as a descendant of X. If multiple requireAncestor rules are set, all of them must be satisfied.

suspendAutoLineBreaks

Example: $tag->rules->suspendAutoLineBreaks();

Temporarily turns off the conversion of new lines into br elements in this tag's text. Does not apply to descendants.

trimFirstLine

Example: $tag->rules->trimFirstLine();

Removes the first character inside given tag if it's a newline.