Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues 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:
*
* ```php
* array(
* array(
* 'slug' => 'unique-name-within-the-set',
* 'name' => 'Name for the UI',
* <value_key> => 'value'
* ),
* )
* ```
* array(
* array(
* 'slug' => 'unique-name-within-the-set',
* 'name' => 'Name for the UI',
* <value_key> => 'value'
* ),
* )
*
* 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.
*
* ```php
* $data = array(
* 'color' => array(
* 'defaultPalette' => true
* )
* );
* $data = array(
* 'color' => array(
* 'defaultPalette' => true
* )
* );
*
* static::get_metadata_boolean( $data, false );
* // => false
* static::get_metadata_boolean( $data, false );
* // => false
*
* static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) );
* // => true
* ```
* static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) );
* // => true
*
* @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).
*
* Example:
* ```php
*
* $tags = new WP_HTML_Tag_Processor( $html );
* if ( $tags->next_tag( 'option' ) ) {
* $tags->set_attribute( 'selected', true );
* }
* ```
*
* ### Finding tags
*
@ -54,9 +53,8 @@
* regardless of what kind it is.
*
* If you want to _find whatever the next tag is_:
* ```php
*
* $tags->next_tag();
* ```
*
* | Goal | Query |
* |-----------------------------------------------------------|---------------------------------------------------------------------------------|
@ -87,7 +85,7 @@
* provided by the processor or external state or variables.
*
* 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() ) {
@ -99,7 +97,6 @@
* $remaining_count--;
* }
* }
* ```
*
* `get_attribute()` will return `null` if the attribute wasn't present
* 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.
*
* 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 `set_attribute()` is called for an existing attribute it will
* overwrite the existing value. Similarly, calling `remove_attribute()`
@ -141,7 +137,7 @@
* entire `class` attribute will be removed.
*
* Example:
* ```php
*
* // from `<span>Yippee!</span>`
* // to `<span class="is-active">Yippee!</span>`
* $tags->add_class( 'is-active' );
@ -165,7 +161,6 @@
* // 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
* `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
* 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' );
@ -203,7 +197,6 @@
* }
* }
* }
* ```
*
* ## Design and limitations
*
@ -335,11 +328,10 @@ class WP_HTML_Tag_Processor {
* Byte offset in input document where current tag name starts.
*
* Example:
* ```
* <div id="test">...
* 01234
* - tag name starts at 1
* ```
*
* <div id="test">...
* 01234
* - tag name starts at 1
*
* @since 6.2.0
* @var int|null
@ -350,11 +342,10 @@ class WP_HTML_Tag_Processor {
* Byte length of current tag name.
*
* Example:
* ```
* <div id="test">...
* 01234
* --- tag name length is 3
* ```
*
* <div id="test">...
* 01234
* --- tag name length is 3
*
* @since 6.2.0
* @var int|null
@ -365,12 +356,11 @@ class WP_HTML_Tag_Processor {
* Byte offset in input document where current tag token ends.
*
* Example:
* ```
* <div id="test">...
* 0 1 |
* 01234567890123456
* --- tag name ends at 14
* ```
*
* <div id="test">...
* 0 1 |
* 01234567890123456
* --- tag name ends at 14
*
* @since 6.2.0
* @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.
*
* Example:
* ```php
* // supposing the parser is working through this content
* // and stops after recognizing the `id` attribute
*
* // 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
* // ^ 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
* // 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 )
@ -406,7 +396,6 @@ class WP_HTML_Tag_Processor {
*
* // 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
* @var WP_HTML_Attribute_Token[]
@ -425,14 +414,13 @@ class WP_HTML_Tag_Processor {
* into a single `set_attribute( 'class', $changes )` call.
*
* Example:
* ```php
*
* // Add the `wp-block-group` class, remove the `wp-group` class.
* $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-group' => WP_HTML_Tag_Processor::REMOVE_CLASS
* );
* ```
*
* @since 6.2.0
* @var bool[]
@ -479,7 +467,7 @@ class WP_HTML_Tag_Processor {
* copies when applying many updates to a single document.
*
* Example:
* ```php
*
* // Replace an attribute stored with a new value, indices
* // sourced from the lazily-parsed HTML recognizer.
* $start = $attributes['src']->start;
@ -490,7 +478,6 @@ class WP_HTML_Tag_Processor {
* $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
* @var WP_HTML_Text_Replacement[]
@ -608,7 +595,7 @@ class WP_HTML_Tag_Processor {
* Release bookmarks when they are no longer needed.
*
* Example:
* ```
*
* <main><h2>Surprising fact you may not know!</h2></main>
* ^ ^
* \-|-- 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…
* ^ ^
* \-|-- it shifts with edits
* ```
*
* Bookmarks provide the ability to seek to a previously-scanned
* place in the HTML document. This avoids the need to re-scan
* the entire document.
*
* Example:
* ```
*
* <ul><li>One</li><li>Two</li><li>Three</li></ul>
* ^^^^
* want to note this last item
@ -650,7 +636,6 @@ class WP_HTML_Tag_Processor {
* $p->set_bookmark( 'last-li' );
* }
* }
* ```
*
* Bookmarks intentionally hide the internal string offsets
* 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
*
* @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.
*/
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`.
*
* Example:
* ```
*
* $p->set_attribute( 'data-TEST-id', 'update' );
* 'update' === $p->get_enqueued_attribute_value( 'data-test-id' );
* ```
*
* Detect this difference based on the absence of the `=`, which _must_ exist in any
* 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.
*
* 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';
@ -1658,7 +1642,6 @@ class WP_HTML_Tag_Processor {
*
* $p->next_tag() === false;
* $p->get_attribute( 'class' ) === null;
* ```
*
* @since 6.2.0
*
@ -1730,14 +1713,13 @@ class WP_HTML_Tag_Processor {
* - HTML 5 spec
*
* 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->next_tag() === false;
* $p->get_attribute_names_with_prefix( 'data-' ) === null;
* ```
*
* @since 6.2.0
*
@ -1766,14 +1748,13 @@ class WP_HTML_Tag_Processor {
* Returns the uppercase name of the matched tag.
*
* Example:
* ```php
*
* $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;
* ```
*
* @since 6.2.0
*
@ -1793,14 +1774,13 @@ class WP_HTML_Tag_Processor {
* Indicates if the current tag token is a tag closer.
*
* 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->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
* $p->is_tag_closer() === true;
* ```
*
* @since 6.2.0
*
@ -1906,12 +1886,13 @@ class WP_HTML_Tag_Processor {
* Update an existing attribute.
*
* 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 ];
$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.
*
* 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->tag_name_starts_at + $this->tag_name_length,

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
*
* @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.