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

Docs: Update code examples formatting in `WP_HTML_Tag_Processor` documentation. 

Per the [https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#description documentation standards], code samples should be created by indenting every line of the code by 4 spaces, with a blank line before and after. This matches the format used by the rest of core.

Follow-up to [55203], [55304], [55718], [55724].

Props juanmaguitar, coffee2code, azaozz, costdev, dmsnell, johnbillion, SergeyBiryukov.
Merges [55727] to the 6.2 branch.
Fixes #58028.
Built from https://develop.svn.wordpress.org/branches/6.2@55729


git-svn-id: http://core.svn.wordpress.org/branches/6.2@55241 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2023-05-08 19:59:23 +00:00
parent 63f3e3a5a5
commit 8df7e41b8a
3 changed files with 64 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
wp-includes/class-wp-theme-json.php
View File

@ -66,15 +66,13 @@ class WP_Theme_JSON {
* *
* They are a unkeyed array of values such as: * They are a unkeyed array of values such as:
* *
* ```php * array(
* array( * array(
* array( * 'slug' => 'unique-name-within-the-set',
* 'slug' => 'unique-name-within-the-set', * 'name' => 'Name for the UI',
* 'name' => 'Name for the UI', * <value_key> => 'value'
* <value_key> => 'value' * ),
* ), * )
* )
* ```
* *
* This contains the necessary metadata to process them: * This contains the necessary metadata to process them:
* *
@ -2531,19 +2529,17 @@ class WP_Theme_JSON {
/** /**
* For metadata values that can either be booleans or paths to booleans, gets the value. * For metadata values that can either be booleans or paths to booleans, gets the value.
* *
* ```php * $data = array(
* $data = array( * 'color' => array(
* 'color' => array( * 'defaultPalette' => true
* 'defaultPalette' => true * )
* ) * );
* );
* *
* static::get_metadata_boolean( $data, false ); * static::get_metadata_boolean( $data, false );
* // => false * // => false
* *
* static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) ); * static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) );
* // => true * // => true
* ```
* *
* @since 6.0.0 * @since 6.0.0
* *

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

@ -38,12 +38,11 @@
* 3. Request changes to the attributes in those tag(s). * 3. Request changes to the attributes in those tag(s).
* *
* Example: * Example:
* ```php *
* $tags = new WP_HTML_Tag_Processor( $html ); * $tags = new WP_HTML_Tag_Processor( $html );
* if ( $tags->next_tag( 'option' ) ) { * if ( $tags->next_tag( 'option' ) ) {
* $tags->set_attribute( 'selected', true ); * $tags->set_attribute( 'selected', true );
* } * }
* ```
* *
* ### Finding tags * ### Finding tags
* *
@ -54,9 +53,8 @@
* regardless of what kind it is. * regardless of what kind it is.
* *
* If you want to _find whatever the next tag is_: * If you want to _find whatever the next tag is_:
* ```php *
* $tags->next_tag(); * $tags->next_tag();
* ```
* *
* | Goal | Query | * | Goal | Query |
* |-----------------------------------------------------------|---------------------------------------------------------------------------------| * |-----------------------------------------------------------|---------------------------------------------------------------------------------|
@ -87,7 +85,7 @@
* provided by the processor or external state or variables. * provided by the processor or external state or variables.
* *
* Example: * Example:
* ```php *
* // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style. * // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
* $remaining_count = 5; * $remaining_count = 5;
* while ( $remaining_count > 0 && $tags->next_tag() ) { * while ( $remaining_count > 0 && $tags->next_tag() ) {
@ -99,7 +97,6 @@
* $remaining_count--; * $remaining_count--;
* } * }
* } * }
* ```
* *
* `get_attribute()` will return `null` if the attribute wasn't present * `get_attribute()` will return `null` if the attribute wasn't present
* on the tag when it was called. It may return `""` (the empty string) * on the tag when it was called. It may return `""` (the empty string)
@ -116,12 +113,11 @@
* nothing and move on to the next opening tag. * nothing and move on to the next opening tag.
* *
* Example: * Example:
* ```php *
* if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) { * if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
* $tags->set_attribute( 'title', 'This groups the contained content.' ); * $tags->set_attribute( 'title', 'This groups the contained content.' );
* $tags->remove_attribute( 'data-test-id' ); * $tags->remove_attribute( 'data-test-id' );
* } * }
* ```
* *
* If `set_attribute()` is called for an existing attribute it will * If `set_attribute()` is called for an existing attribute it will
* overwrite the existing value. Similarly, calling `remove_attribute()` * overwrite the existing value. Similarly, calling `remove_attribute()`
@ -141,7 +137,7 @@
* entire `class` attribute will be removed. * entire `class` attribute will be removed.
* *
* Example: * Example:
* ```php *
* // from `<span>Yippee!</span>` * // from `<span>Yippee!</span>`
* // to `<span class="is-active">Yippee!</span>` * // to `<span class="is-active">Yippee!</span>`
* $tags->add_class( 'is-active' ); * $tags->add_class( 'is-active' );
@ -165,7 +161,6 @@
* // from `<input type="text" length="24">` * // from `<input type="text" length="24">`
* // to `<input type="text" length="24"> * // to `<input type="text" length="24">
* $tags->remove_class( 'rugby' ); * $tags->remove_class( 'rugby' );
* ```
* *
* When class changes are enqueued but a direct change to `class` is made via * When class changes are enqueued but a direct change to `class` is made via
* `set_attribute` then the changes to `set_attribute` (or `remove_attribute`) * `set_attribute` then the changes to `set_attribute` (or `remove_attribute`)
@ -184,7 +179,6 @@
* and so on. It's fine from a performance standpoint to create a * and so on. It's fine from a performance standpoint to create a
* bookmark and update it frequently, such as within a loop. * bookmark and update it frequently, such as within a loop.
* *
* ```php
* $total_todos = 0; * $total_todos = 0;
* while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) { * while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
* $p->set_bookmark( 'list-start' ); * $p->set_bookmark( 'list-start' );
@ -203,7 +197,6 @@
* } * }
* } * }
* } * }
* ```
* *
* ## Design and limitations * ## Design and limitations
* *
@ -335,11 +328,10 @@ class WP_HTML_Tag_Processor {
* Byte offset in input document where current tag name starts. * Byte offset in input document where current tag name starts.
* *
* Example: * Example:
* ``` *
* <div id="test">... * <div id="test">...
* 01234 * 01234
* - tag name starts at 1 * - tag name starts at 1
* ```
* *
* @since 6.2.0 * @since 6.2.0
* @var int|null * @var int|null
@ -350,11 +342,10 @@ class WP_HTML_Tag_Processor {
* Byte length of current tag name. * Byte length of current tag name.
* *
* Example: * Example:
* ``` *
* <div id="test">... * <div id="test">...
* 01234 * 01234
* --- tag name length is 3 * --- tag name length is 3
* ```
* *
* @since 6.2.0 * @since 6.2.0
* @var int|null * @var int|null
@ -365,12 +356,11 @@ class WP_HTML_Tag_Processor {
* Byte offset in input document where current tag token ends. * Byte offset in input document where current tag token ends.
* *
* Example: * Example:
* ``` *
* <div id="test">... * <div id="test">...
* 0 1 | * 0 1 |
* 01234567890123456 * 01234567890123456
* --- tag name ends at 14 * --- tag name ends at 14
* ```
* *
* @since 6.2.0 * @since 6.2.0
* @var int|null * @var int|null
@ -388,17 +378,17 @@ class WP_HTML_Tag_Processor {
* Lazily-built index of attributes found within an HTML tag, keyed by the attribute name. * Lazily-built index of attributes found within an HTML tag, keyed by the attribute name.
* *
* Example: * Example:
* ```php *
* // supposing the parser is working through this content * // Supposing the parser is working through this content
* // and stops after recognizing the `id` attribute * // and stops after recognizing the `id` attribute.
* // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8"> * // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
* // ^ parsing will continue from this point * // ^ parsing will continue from this point.
* $this->attributes = array( * $this->attributes = array(
* 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ) * 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 )
* ); * );
* *
* // when picking up parsing again, or when asking to find the * // When picking up parsing again, or when asking to find the
* // `class` attribute we will continue and add to this array * // `class` attribute we will continue and add to this array.
* $this->attributes = array( * $this->attributes = array(
* 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ), * 'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ),
* 'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 ) * 'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 )
@ -406,7 +396,6 @@ class WP_HTML_Tag_Processor {
* *
* // Note that only the `class` attribute value is stored in the index. * // 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. * // That's because it is the only value used by this class at the moment.
* ```
* *
* @since 6.2.0 * @since 6.2.0
* @var WP_HTML_Attribute_Token[] * @var WP_HTML_Attribute_Token[]
@ -425,14 +414,13 @@ class WP_HTML_Tag_Processor {
* into a single `set_attribute( 'class', $changes )` call. * into a single `set_attribute( 'class', $changes )` call.
* *
* Example: * Example:
* ```php *
* // Add the `wp-block-group` class, remove the `wp-group` class. * // Add the `wp-block-group` class, remove the `wp-group` class.
* $classname_updates = array( * $classname_updates = array(
* // Indexed by a comparable class name * // Indexed by a comparable class name.
* 'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS, * 'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
* 'wp-group' => WP_HTML_Tag_Processor::REMOVE_CLASS * 'wp-group' => WP_HTML_Tag_Processor::REMOVE_CLASS
* ); * );
* ```
* *
* @since 6.2.0 * @since 6.2.0
* @var bool[] * @var bool[]
@ -479,7 +467,7 @@ class WP_HTML_Tag_Processor {
* copies when applying many updates to a single document. * copies when applying many updates to a single document.
* *
* Example: * Example:
* ```php *
* // Replace an attribute stored with a new value, indices * // Replace an attribute stored with a new value, indices
* // sourced from the lazily-parsed HTML recognizer. * // sourced from the lazily-parsed HTML recognizer.
* $start = $attributes['src']->start; * $start = $attributes['src']->start;
@ -490,7 +478,6 @@ class WP_HTML_Tag_Processor {
* $lexical_updates = array( * $lexical_updates = array(
* WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' ) * WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
* ); * );
* ```
* *
* @since 6.2.0 * @since 6.2.0
* @var WP_HTML_Text_Replacement[] * @var WP_HTML_Text_Replacement[]
@ -608,7 +595,7 @@ class WP_HTML_Tag_Processor {
* Release bookmarks when they are no longer needed. * Release bookmarks when they are no longer needed.
* *
* Example: * Example:
* ``` *
* <main><h2>Surprising fact you may not know!</h2></main> * <main><h2>Surprising fact you may not know!</h2></main>
* ^ ^ * ^ ^
* \-|-- this `H2` opener bookmark tracks the token * \-|-- this `H2` opener bookmark tracks the token
@ -616,14 +603,13 @@ class WP_HTML_Tag_Processor {
* <main class="clickbait"><h2>Surprising fact you may no… * <main class="clickbait"><h2>Surprising fact you may no…
* ^ ^ * ^ ^
* \-|-- it shifts with edits * \-|-- it shifts with edits
* ```
* *
* Bookmarks provide the ability to seek to a previously-scanned * Bookmarks provide the ability to seek to a previously-scanned
* place in the HTML document. This avoids the need to re-scan * place in the HTML document. This avoids the need to re-scan
* the entire document. * the entire document.
* *
* Example: * Example:
* ``` *
* <ul><li>One</li><li>Two</li><li>Three</li></ul> * <ul><li>One</li><li>Two</li><li>Three</li></ul>
* ^^^^ * ^^^^
* want to note this last item * want to note this last item
@ -650,7 +636,6 @@ class WP_HTML_Tag_Processor {
* $p->set_bookmark( 'last-li' ); * $p->set_bookmark( 'last-li' );
* } * }
* } * }
* ```
* *
* Bookmarks intentionally hide the internal string offsets * Bookmarks intentionally hide the internal string offsets
* to which they refer. They are maintained internally as * to which they refer. They are maintained internally as
@ -727,7 +712,7 @@ class WP_HTML_Tag_Processor {
* *
* @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state * @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state
* *
* @param string $tag_name – the lowercase tag name which will close the RCDATA region. * @param string $tag_name The lowercase tag name which will close the RCDATA region.
* @return bool Whether an end to the RCDATA region was found before the end of the document. * @return bool Whether an end to the RCDATA region was found before the end of the document.
*/ */
private function skip_rcdata( $tag_name ) { private function skip_rcdata( $tag_name ) {
@ -1615,10 +1600,9 @@ class WP_HTML_Tag_Processor {
* or trailing whitespace, and that the casing follows the name given in `set_attribute`. * or trailing whitespace, and that the casing follows the name given in `set_attribute`.
* *
* Example: * Example:
* ``` *
* $p->set_attribute( 'data-TEST-id', 'update' ); * $p->set_attribute( 'data-TEST-id', 'update' );
* 'update' === $p->get_enqueued_attribute_value( 'data-test-id' ); * 'update' === $p->get_enqueued_attribute_value( 'data-test-id' );
* ```
* *
* Detect this difference based on the absence of the `=`, which _must_ exist in any * Detect this difference based on the absence of the `=`, which _must_ exist in any
* attribute containing a value, e.g. `<input type="text" enabled />`. * attribute containing a value, e.g. `<input type="text" enabled />`.
@ -1649,7 +1633,7 @@ class WP_HTML_Tag_Processor {
* Returns the value of a requested attribute from a matched tag opener if that attribute exists. * Returns the value of a requested attribute from a matched tag opener if that attribute exists.
* *
* Example: * Example:
* ```php *
* $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' ); * $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->next_tag( array( 'class_name' => 'test' ) ) === true;
* $p->get_attribute( 'data-test-id' ) === '14'; * $p->get_attribute( 'data-test-id' ) === '14';
@ -1658,7 +1642,6 @@ class WP_HTML_Tag_Processor {
* *
* $p->next_tag() === false; * $p->next_tag() === false;
* $p->get_attribute( 'class' ) === null; * $p->get_attribute( 'class' ) === null;
* ```
* *
* @since 6.2.0 * @since 6.2.0
* *
@ -1730,14 +1713,13 @@ class WP_HTML_Tag_Processor {
* - HTML 5 spec * - HTML 5 spec
* *
* Example: * Example:
* ```php *
* $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' ); * $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->next_tag( array( 'class_name' => 'test' ) ) === true;
* $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' ); * $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
* *
* $p->next_tag() === false; * $p->next_tag() === false;
* $p->get_attribute_names_with_prefix( 'data-' ) === null; * $p->get_attribute_names_with_prefix( 'data-' ) === null;
* ```
* *
* @since 6.2.0 * @since 6.2.0
* *
@ -1766,14 +1748,13 @@ class WP_HTML_Tag_Processor {
* Returns the uppercase name of the matched tag. * Returns the uppercase name of the matched tag.
* *
* Example: * Example:
* ```php *
* $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' ); * $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' );
* $p->next_tag() === true; * $p->next_tag() === true;
* $p->get_tag() === 'DIV'; * $p->get_tag() === 'DIV';
* *
* $p->next_tag() === false; * $p->next_tag() === false;
* $p->get_tag() === null; * $p->get_tag() === null;
* ```
* *
* @since 6.2.0 * @since 6.2.0
* *
@ -1793,14 +1774,13 @@ class WP_HTML_Tag_Processor {
* Indicates if the current tag token is a tag closer. * Indicates if the current tag token is a tag closer.
* *
* Example: * Example:
* ```php *
* $p = new WP_HTML_Tag_Processor( '<div></div>' ); * $p = new WP_HTML_Tag_Processor( '<div></div>' );
* $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) ); * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
* $p->is_tag_closer() === false; * $p->is_tag_closer() === false;
* *
* $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) ); * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
* $p->is_tag_closer() === true; * $p->is_tag_closer() === true;
* ```
* *
* @since 6.2.0 * @since 6.2.0
* *
@ -1906,12 +1886,13 @@ class WP_HTML_Tag_Processor {
* Update an existing attribute. * Update an existing attribute.
* *
* Example – set attribute id to "new" in <div id="initial_id" />: * Example – set attribute id to "new" in <div id="initial_id" />:
* <div id="initial_id"/>
* ^-------------^
* start end
* replacement: `id="new"`
* *
* Result: <div id="new"/> * <div id="initial_id"/>
* ^-------------^
* start end
* replacement: `id="new"`
*
* Result: <div id="new"/>
*/ */
$existing_attribute = $this->attributes[ $comparable_name ]; $existing_attribute = $this->attributes[ $comparable_name ];
$this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement( $this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
@ -1924,12 +1905,13 @@ class WP_HTML_Tag_Processor {
* Create a new attribute at the tag's name end. * Create a new attribute at the tag's name end.
* *
* Example – add attribute id="new" to <div />: * Example – add attribute id="new" to <div />:
* <div/>
* ^
* start and end
* replacement: ` id="new"`
* *
* Result: <div id="new"/> * <div/>
* ^
* start and end
* replacement: ` id="new"`
*
* Result: <div id="new"/>
*/ */
$this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement( $this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
$this->tag_name_starts_at + $this->tag_name_length, $this->tag_name_starts_at + $this->tag_name_length,

2
wp-includes/version.php
View File

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