WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs: Improve formatting of markup in the docs for `WP_HTML_Tag_Processor`. 

Code blocks wrapped inside backtacks don't need to be indented.

See #57840

Built from https://develop.svn.wordpress.org/trunk@55718


git-svn-id: http://core.svn.wordpress.org/trunk@55230 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2023-05-03 23:55:16 +00:00
parent c3e63b8046
commit 89cbdce5c3
2 changed files with 106 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
wp-includes/html-api/class-wp-html-tag-processor.php
View File

@ -39,10 +39,10 @@
*
* Example:
* ```php
* $tags = new WP_HTML_Tag_Processor( $html );
* if ( $tags->next_tag( 'option' ) ) {
* $tags->set_attribute( 'selected', true );
* }
* $tags = new WP_HTML_Tag_Processor( $html );
* if ( $tags->next_tag( 'option' ) ) {
* $tags->set_attribute( 'selected', true );
* }
* ```
*
* ### Finding tags
@ -55,7 +55,7 @@
*
* If you want to _find whatever the next tag is_:
* ```php
* $tags->next_tag();
* $tags->next_tag();
* ```
*
* | Goal | Query |
@ -88,17 +88,17 @@
*
* Example:
* ```php
* // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
* $remaining_count = 5;
* while ( $remaining_count > 0 && $tags->next_tag() ) {
* if (
* ( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) &&
* 'jazzy' === $tags->get_attribute( 'data-style' )
* ) {
* $tags->add_class( 'theme-style-everest-jazz' );
* $remaining_count--;
* }
* // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
* $remaining_count = 5;
* while ( $remaining_count > 0 && $tags->next_tag() ) {
* if (
* ( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) &&
* 'jazzy' === $tags->get_attribute( 'data-style' )
* ) {
* $tags->add_class( 'theme-style-everest-jazz' );
* $remaining_count--;
* }
* }
* ```
*
* `get_attribute()` will return `null` if the attribute wasn't present
@ -117,10 +117,10 @@
*
* Example:
* ```php
* if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
* $tags->set_attribute( 'title', 'This groups the contained content.' );
* $tags->remove_attribute( 'data-test-id' );
* }
* if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
* $tags->set_attribute( 'title', 'This groups the contained content.' );
* $tags->remove_attribute( 'data-test-id' );
* }
* ```
*
* If `set_attribute()` is called for an existing attribute it will
@ -142,29 +142,29 @@
*
* Example:
* ```php
* // from `<span>Yippee!</span>`
* // to `<span class="is-active">Yippee!</span>`
* $tags->add_class( 'is-active' );
* // from `<span>Yippee!</span>`
* // to `<span class="is-active">Yippee!</span>`
* $tags->add_class( 'is-active' );
*
* // from `<span class="excited">Yippee!</span>`
* // to `<span class="excited is-active">Yippee!</span>`
* $tags->add_class( 'is-active' );
* // from `<span class="excited">Yippee!</span>`
* // to `<span class="excited is-active">Yippee!</span>`
* $tags->add_class( 'is-active' );
*
* // from `<span class="is-active heavy-accent">Yippee!</span>`
* // to `<span class="is-active heavy-accent">Yippee!</span>`
* $tags->add_class( 'is-active' );
* // from `<span class="is-active heavy-accent">Yippee!</span>`
* // to `<span class="is-active heavy-accent">Yippee!</span>`
* $tags->add_class( 'is-active' );
*
* // from `<input type="text" class="is-active rugby not-disabled" length="24">`
* // to `<input type="text" class="is-active not-disabled" length="24">
* $tags->remove_class( 'rugby' );
* // from `<input type="text" class="is-active rugby not-disabled" length="24">`
* // to `<input type="text" class="is-active not-disabled" length="24">
* $tags->remove_class( 'rugby' );
*
* // from `<input type="text" class="rugby" length="24">`
* // to `<input type="text" length="24">
* $tags->remove_class( 'rugby' );
* // from `<input type="text" class="rugby" length="24">`
* // to `<input type="text" length="24">
* $tags->remove_class( 'rugby' );
*
* // from `<input type="text" length="24">`
* // to `<input type="text" length="24">
* $tags->remove_class( 'rugby' );
* // from `<input type="text" length="24">`
* // to `<input type="text" length="24">
* $tags->remove_class( 'rugby' );
* ```
*
* When class changes are enqueued but a direct change to `class` is made via
@ -185,24 +185,24 @@
* bookmark and update it frequently, such as within a loop.
*
* ```php
* $total_todos = 0;
* while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
* $p->set_bookmark( 'list-start' );
* while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
* if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) {
* $p->set_bookmark( 'list-end' );
* $p->seek( 'list-start' );
* $p->set_attribute( 'data-contained-todos', (string) $total_todos );
* $total_todos = 0;
* $p->seek( 'list-end' );
* break;
* }
* $total_todos = 0;
* while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
* $p->set_bookmark( 'list-start' );
* while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
* if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) {
* $p->set_bookmark( 'list-end' );
* $p->seek( 'list-start' );
* $p->set_attribute( 'data-contained-todos', (string) $total_todos );
* $total_todos = 0;
* $p->seek( 'list-end' );
* break;
* }
*
* if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) {
* $total_todos++;
* }
* if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) {
* $total_todos++;
* }
* }
* }
* ```
*
* ## Design and limitations
@ -229,7 +229,7 @@
* The Tag Processor's design incorporates a "garbage-in-garbage-out" philosophy.
* HTML5 specifies that certain invalid content be transformed into different forms
* for display, such as removing null bytes from an input document and replacing
* invalid characters with the Unicode replacement character U+FFFD <EFBFBD>. Where errors
* invalid characters with the Unicode replacement character `U+FFFD`. Where errors
* or transformations exist within the HTML5 specification, the Tag Processor leaves
* those invalid inputs untouched, passing them through to the final browser to handle.
* While this implies that certain operations will be non-spec-compliant, such as
@ -387,23 +387,23 @@ class WP_HTML_Tag_Processor {
*
* Example:
* ```php
* // supposing the parser is working through this content
* // and stops after recognizing the `id` attribute
* // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
* // ^ parsing will continue from this point
* $this->attributes = array(
* 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 )
* );
* // supposing the parser is working through this content
* // and stops after recognizing the `id` attribute
* // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
* // ^ parsing will continue from this point
* $this->attributes = array(
* 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 )
* );
*
* // when picking up parsing again, or when asking to find the
* // `class` attribute we will continue and add to this array
* $this->attributes = array(
* 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ),
* 'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 )
* );
* // when picking up parsing again, or when asking to find the
* // `class` attribute we will continue and add to this array
* $this->attributes = array(
* 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ),
* 'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 )
* );
*
* // Note that only the `class` attribute value is stored in the index.
* // That's because it is the only value used by this class at the moment.
* // Note that only the `class` attribute value is stored in the index.
* // That's because it is the only value used by this class at the moment.
* ```
*
* @since 6.2.0
@ -424,12 +424,12 @@ class WP_HTML_Tag_Processor {
*
* Example:
* ```php
* // Add the `wp-block-group` class, remove the `wp-group` class.
* $classname_updates = array(
* // Indexed by a comparable class name
* 'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
* 'wp-group' => WP_HTML_Tag_Processor::REMOVE_CLASS
* );
* // Add the `wp-block-group` class, remove the `wp-group` class.
* $classname_updates = array(
* // Indexed by a comparable class name
* 'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
* 'wp-group' => WP_HTML_Tag_Processor::REMOVE_CLASS
* );
* ```
*
* @since 6.2.0
@ -478,16 +478,16 @@ class WP_HTML_Tag_Processor {
*
* Example:
* ```php
* // Replace an attribute stored with a new value, indices
* // sourced from the lazily-parsed HTML recognizer.
* $start = $attributes['src']->start;
* $end = $attributes['src']->end;
* $modifications[] = new WP_HTML_Text_Replacement( $start, $end, $new_value );
* // Replace an attribute stored with a new value, indices
* // sourced from the lazily-parsed HTML recognizer.
* $start = $attributes['src']->start;
* $end = $attributes['src']->end;
* $modifications[] = new WP_HTML_Text_Replacement( $start, $end, $new_value );
*
* // Correspondingly, something like this will appear in this array.
* $lexical_updates = array(
* WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
* );
* // Correspondingly, something like this will appear in this array.
* $lexical_updates = array(
* WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
* );
* ```
*
* @since 6.2.0
@ -1661,14 +1661,14 @@ class WP_HTML_Tag_Processor {
*
* Example:
* ```php
* $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' );
* $p->next_tag( array( 'class_name' => 'test' ) ) === true;
* $p->get_attribute( 'data-test-id' ) === '14';
* $p->get_attribute( 'enabled' ) === true;
* $p->get_attribute( 'aria-label' ) === null;
* $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' );
* $p->next_tag( array( 'class_name' => 'test' ) ) === true;
* $p->get_attribute( 'data-test-id' ) === '14';
* $p->get_attribute( 'enabled' ) === true;
* $p->get_attribute( 'aria-label' ) === null;
*
* $p->next_tag() === false;
* $p->get_attribute( 'class' ) === null;
* $p->next_tag() === false;
* $p->get_attribute( 'class' ) === null;
* ```
*
* @since 6.2.0
@ -1744,12 +1744,12 @@ class WP_HTML_Tag_Processor {
*
* Example:
* ```php
* $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
* $p->next_tag( array( 'class_name' => 'test' ) ) === true;
* $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
* $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
* $p->next_tag( array( 'class_name' => 'test' ) ) === true;
* $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
*
* $p->next_tag() === false;
* $p->get_attribute_names_with_prefix( 'data-' ) === null;
* $p->next_tag() === false;
* $p->get_attribute_names_with_prefix( 'data-' ) === null;
* ```
*
* @since 6.2.0
@ -1778,12 +1778,12 @@ class WP_HTML_Tag_Processor {
*
* Example:
* ```php
* $p = new WP_HTML_Tag_Processor( '<DIV CLASS="test">Test</DIV>' );
* $p->next_tag() === true;
* $p->get_tag() === 'DIV';
* $p = new WP_HTML_Tag_Processor( '<DIV CLASS="test">Test</DIV>' );
* $p->next_tag() === true;
* $p->get_tag() === 'DIV';
*
* $p->next_tag() === false;
* $p->get_tag() === null;
* $p->next_tag() === false;
* $p->get_tag() === null;
* ```
*
* @since 6.2.0
@ -1830,12 +1830,12 @@ class WP_HTML_Tag_Processor {
*
* Example:
* ```php
* $p = new WP_HTML_Tag_Processor( '<div></div>' );
* $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
* $p->is_tag_closer() === false;
* $p = new WP_HTML_Tag_Processor( '<div></div>' );
* $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
* $p->is_tag_closer() === false;
*
* $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
* $p->is_tag_closer() === true;
* $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
* $p->is_tag_closer() === true;
* ```
*
* @since 6.2.0

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
$wp_version = '6.3-alpha-55717';
$wp_version = '6.3-alpha-55718';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.