WordPress.org
Get WordPress

Make WordPress Core

Changeset 55727


Ignore:
Timestamp:
05/08/2023 05:30:41 PM (3 years ago)
Author:
SergeyBiryukov
Message:

Docs: Update code examples formatting in WP_HTML_Tag_Processor documentation.

Per the ​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.
Fixes #58028.

Location:
trunk/src/wp-includes
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-theme-json.php

    r55712 r55727  
    6767         * They are a unkeyed array of values such as:
    6868         *
    69          * ```php
    70          * array(
    71          *   array(
    72          *     'slug'      => 'unique-name-within-the-set',
    73          *     'name'      => 'Name for the UI',
    74          *     <value_key> => 'value'
    75          *   ),
    76          * )
    77          * ```
     69         *     array(
     70         *       array(
     71         *         'slug'      => 'unique-name-within-the-set',
     72         *         'name'      => 'Name for the UI',
     73         *         <value_key> => 'value'
     74         *       ),
     75         *     )
    7876         *
    7977         * This contains the necessary metadata to process them:
    … …  
    25332531         * For metadata values that can either be booleans or paths to booleans, gets the value.
    25342532         *
    2535          * ```php
    2536          * $data = array(
    2537          *   'color' => array(
    2538          *     'defaultPalette' => true
    2539          *   )
    2540          * );
    2541          *
    2542          * static::get_metadata_boolean( $data, false );
    2543          * // => false
    2544          *
    2545          * static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) );
    2546          * // => true
    2547          * ```
     2533         *     $data = array(
     2534         *       'color' => array(
     2535         *         'defaultPalette' => true
     2536         *       )
     2537         *     );
     2538         *
     2539         *     static::get_metadata_boolean( $data, false );
     2540         *     // => false
     2541         *
     2542         *     static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) );
     2543         *     // => true
    25482544         *
    25492545         * @since 6.0.0

  • trunk/src/wp-includes/html-api/class-wp-html-tag-processor.php

    r55725 r55727  
    3939 *
    4040 * Example:
    41  * ```php
    42  * $tags = new WP_HTML_Tag_Processor( $html );
    43  * if ( $tags->next_tag( 'option' ) ) {
    44  *     $tags->set_attribute( 'selected', true );
    45  * }
    46  * ```
     41 *
     42 *     $tags = new WP_HTML_Tag_Processor( $html );
     43 *     if ( $tags->next_tag( 'option' ) ) {
     44 *         $tags->set_attribute( 'selected', true );
     45 *     }
    4746 *
    4847 * ### Finding tags
    … …  
    5554 *
    5655 * If you want to _find whatever the next tag is_:
    57  * ```php
    58  * $tags->next_tag();
    59  * ```
     56 *
     57 *     $tags->next_tag();
    6058 *
    6159 * | Goal                                                      | Query                                                                           |
    … …  
    8886 *
    8987 * Example:
    90  * ```php
    91  * // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
    92  * $remaining_count = 5;
    93  * while ( $remaining_count > 0 && $tags->next_tag() ) {
    94  *     if (
    95  *          ( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) &&
    96  *          'jazzy' === $tags->get_attribute( 'data-style' )
    97  *     ) {
    98  *         $tags->add_class( 'theme-style-everest-jazz' );
    99  *         $remaining_count--;
     88 *
     89 *     // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
     90 *     $remaining_count = 5;
     91 *     while ( $remaining_count > 0 && $tags->next_tag() ) {
     92 *         if (
     93 *              ( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) &&
     94 *              'jazzy' === $tags->get_attribute( 'data-style' )
     95 *         ) {
     96 *             $tags->add_class( 'theme-style-everest-jazz' );
     97 *             $remaining_count--;
     98 *         }
    10099 *     }
    101  * }
    102  * ```
    103100 *
    104101 * `get_attribute()` will return `null` if the attribute wasn't present
    … …  
    117114 *
    118115 * Example:
    119  * ```php
    120  * if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
    121  *     $tags->set_attribute( 'title', 'This groups the contained content.' );
    122  *     $tags->remove_attribute( 'data-test-id' );
    123  * }
    124  * ```
     116 *
     117 *     if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
     118 *         $tags->set_attribute( 'title', 'This groups the contained content.' );
     119 *         $tags->remove_attribute( 'data-test-id' );
     120 *     }
    125121 *
    126122 * If `set_attribute()` is called for an existing attribute it will
    … …  
    142138 *
    143139 * Example:
    144  * ```php
    145  * // from `<span>Yippee!</span>`
    146  * //   to `<span class="is-active">Yippee!</span>`
    147  * $tags->add_class( 'is-active' );
    148  *
    149  * // from `<span class="excited">Yippee!</span>`
    150  * //   to `<span class="excited is-active">Yippee!</span>`
    151  * $tags->add_class( 'is-active' );
    152  *
    153  * // from `<span class="is-active heavy-accent">Yippee!</span>`
    154  * //   to `<span class="is-active heavy-accent">Yippee!</span>`
    155  * $tags->add_class( 'is-active' );
    156  *
    157  * // from `<input type="text" class="is-active rugby not-disabled" length="24">`
    158  * //   to `<input type="text" class="is-active not-disabled" length="24">
    159  * $tags->remove_class( 'rugby' );
    160  *
    161  * // from `<input type="text" class="rugby" length="24">`
    162  * //   to `<input type="text" length="24">
    163  * $tags->remove_class( 'rugby' );
    164  *
    165  * // from `<input type="text" length="24">`
    166  * //   to `<input type="text" length="24">
    167  * $tags->remove_class( 'rugby' );
    168  * ```
     140 *
     141 *     // from `<span>Yippee!</span>`
     142 *     //   to `<span class="is-active">Yippee!</span>`
     143 *     $tags->add_class( 'is-active' );
     144 *
     145 *     // from `<span class="excited">Yippee!</span>`
     146 *     //   to `<span class="excited is-active">Yippee!</span>`
     147 *     $tags->add_class( 'is-active' );
     148 *
     149 *     // from `<span class="is-active heavy-accent">Yippee!</span>`
     150 *     //   to `<span class="is-active heavy-accent">Yippee!</span>`
     151 *     $tags->add_class( 'is-active' );
     152 *
     153 *     // from `<input type="text" class="is-active rugby not-disabled" length="24">`
     154 *     //   to `<input type="text" class="is-active not-disabled" length="24">
     155 *     $tags->remove_class( 'rugby' );
     156 *
     157 *     // from `<input type="text" class="rugby" length="24">`
     158 *     //   to `<input type="text" length="24">
     159 *     $tags->remove_class( 'rugby' );
     160 *
     161 *     // from `<input type="text" length="24">`
     162 *     //   to `<input type="text" length="24">
     163 *     $tags->remove_class( 'rugby' );
    169164 *
    170165 * When class changes are enqueued but a direct change to `class` is made via
    … …  
    185180 * bookmark and update it frequently, such as within a loop.
    186181 *
    187  * ```php
    188  * $total_todos = 0;
    189  * while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
    190  *     $p->set_bookmark( 'list-start' );
    191  *     while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
    192  *         if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) {
    193  *             $p->set_bookmark( 'list-end' );
    194  *             $p->seek( 'list-start' );
    195  *             $p->set_attribute( 'data-contained-todos', (string) $total_todos );
    196  *             $total_todos = 0;
    197  *             $p->seek( 'list-end' );
    198  *             break;
    199  *         }
    200  *
    201  *         if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) {
    202  *             $total_todos++;
     182 *     $total_todos = 0;
     183 *     while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
     184 *         $p->set_bookmark( 'list-start' );
     185 *         while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
     186 *             if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) {
     187 *                 $p->set_bookmark( 'list-end' );
     188 *                 $p->seek( 'list-start' );
     189 *                 $p->set_attribute( 'data-contained-todos', (string) $total_todos );
     190 *                 $total_todos = 0;
     191 *                 $p->seek( 'list-end' );
     192 *                 break;
     193 *             }
     194 *
     195 *             if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) {
     196 *                 $total_todos++;
     197 *             }
    203198 *         }
    204199 *     }
    205  * }
    206  * ```
    207200 *
    208201 * ## Design and limitations
    … …  
    336329         *
    337330         * Example:
    338          * ```
    339          *   <div id="test">...
    340          *   01234
    341          *    - tag name starts at 1
    342          * ```
     331         *
     332         *     <div id="test">...
     333         *     01234
     334         *      - tag name starts at 1
    343335         *
    344336         * @since 6.2.0
    … …  
    351343         *
    352344         * Example:
    353          * ```
    354          *   <div id="test">...
    355          *   01234
    356          *    --- tag name length is 3
    357          * ```
     345         *
     346         *     <div id="test">...
     347         *     01234
     348         *      --- tag name length is 3
    358349         *
    359350         * @since 6.2.0
    … …  
    366357         *
    367358         * Example:
    368          * ```
    369          *   <div id="test">...
    370          *   0         1   |
    371          *   01234567890123456
    372          *    --- tag name ends at 14
    373          * ```
     359         *
     360         *     <div id="test">...
     361         *     0         1   |
     362         *     01234567890123456
     363         *      --- tag name ends at 14
    374364         *
    375365         * @since 6.2.0
    … …  
    389379         *
    390380         * Example:
    391          * ```php
    392          * // supposing the parser is working through this content
    393          * // and stops after recognizing the `id` attribute
    394          * // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
    395          * //                 ^ parsing will continue from this point
    396          * $this->attributes = array(
    397          *     'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 )
    398          * );
    399          *
    400          * // when picking up parsing again, or when asking to find the
    401          * // `class` attribute we will continue and add to this array
    402          * $this->attributes = array(
    403          *     'id'    => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ),
    404          *     'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 )
    405          * );
    406          *
    407          * // Note that only the `class` attribute value is stored in the index.
    408          * // That's because it is the only value used by this class at the moment.
    409          * ```
     381         *
     382         *     // Supposing the parser is working through this content
     383         *     // and stops after recognizing the `id` attribute.
     384         *     // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
     385         *     //                 ^ parsing will continue from this point.
     386         *     $this->attributes = array(
     387         *         'id' => new WP_HTML_Attribute_Match( 'id', null, 6, 17 )
     388         *     );
     389         *
     390         *     // When picking up parsing again, or when asking to find the
     391         *     // `class` attribute we will continue and add to this array.
     392         *     $this->attributes = array(
     393         *         'id'    => new WP_HTML_Attribute_Match( 'id', null, 6, 17 ),
     394         *         'class' => new WP_HTML_Attribute_Match( 'class', 'outline', 18, 32 )
     395         *     );
     396         *
     397         *     // Note that only the `class` attribute value is stored in the index.
     398         *     // That's because it is the only value used by this class at the moment.
    410399         *
    411400         * @since 6.2.0
    … …  
    426415         *
    427416         * Example:
    428          * ```php
    429          * // Add the `wp-block-group` class, remove the `wp-group` class.
    430          * $classname_updates = array(
    431          *     // Indexed by a comparable class name
    432          *     'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
    433          *     'wp-group'       => WP_HTML_Tag_Processor::REMOVE_CLASS
    434          * );
    435          * ```
     417         *
     418         *     // Add the `wp-block-group` class, remove the `wp-group` class.
     419         *     $classname_updates = array(
     420         *         // Indexed by a comparable class name.
     421         *         'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
     422         *         'wp-group'       => WP_HTML_Tag_Processor::REMOVE_CLASS
     423         *     );
    436424         *
    437425         * @since 6.2.0
    … …  
    480468         *
    481469         * Example:
    482          * ```php
    483          * // Replace an attribute stored with a new value, indices
    484          * // sourced from the lazily-parsed HTML recognizer.
    485          * $start = $attributes['src']->start;
    486          * $end   = $attributes['src']->end;
    487          * $modifications[] = new WP_HTML_Text_Replacement( $start, $end, $new_value );
    488          *
    489          * // Correspondingly, something like this will appear in this array.
    490          * $lexical_updates = array(
    491          *     WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
    492          * );
    493          * ```
     470         *
     471         *     // Replace an attribute stored with a new value, indices
     472         *     // sourced from the lazily-parsed HTML recognizer.
     473         *     $start = $attributes['src']->start;
     474         *     $end   = $attributes['src']->end;
     475         *     $modifications[] = new WP_HTML_Text_Replacement( $start, $end, $new_value );
     476         *
     477         *     // Correspondingly, something like this will appear in this array.
     478         *     $lexical_updates = array(
     479         *         WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
     480         *     );
    494481         *
    495482         * @since 6.2.0
    … …  
    609596         *
    610597         * Example:
    611          * ```
     598         *
    612599         *     <main><h2>Surprising fact you may not know!</h2></main>
    613600         *           ^  ^
    … …  
    617604         *                             ^  ^
    618605         *                              \-|-- it shifts with edits
    619          * ```
    620606         *
    621607         * Bookmarks provide the ability to seek to a previously-scanned
    … …  
    624610         *
    625611         * Example:
    626          * ```
     612         *
    627613         *     <ul><li>One</li><li>Two</li><li>Three</li></ul>
    628614         *                                 ^^^^
    … …  
    651637         *         }
    652638         *     }
    653          * ```
    654639         *
    655640         * Bookmarks intentionally hide the internal string offsets
    … …  
    728713         * @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state
    729714         *
    730          * @param string $tag_name – the lowercase tag name which will close the RCDATA region.
     715         * @param string $tag_name The lowercase tag name which will close the RCDATA region.
    731716         * @return bool Whether an end to the RCDATA region was found before the end of the document.
    732717         */
    … …  
    16251610                 *
    16261611                 * Example:
    1627                  * ```
     1612                 *
    16281613                 *     $p->set_attribute( 'data-TEST-id', 'update' );
    16291614                 *     'update' === $p->get_enqueued_attribute_value( 'data-test-id' );
    1630                  * ```
    16311615                 *
    16321616                 * Detect this difference based on the absence of the `=`, which _must_ exist in any
    … …  
    16591643         *
    16601644         * Example:
    1661          * ```php
    1662          * $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' );
    1663          * $p->next_tag( array( 'class_name' => 'test' ) ) === true;
    1664          * $p->get_attribute( 'data-test-id' ) === '14';
    1665          * $p->get_attribute( 'enabled' ) === true;
    1666          * $p->get_attribute( 'aria-label' ) === null;
    1667          *
    1668          * $p->next_tag() === false;
    1669          * $p->get_attribute( 'class' ) === null;
    1670          * ```
     1645         *
     1646         *     $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' );
     1647         *     $p->next_tag( array( 'class_name' => 'test' ) ) === true;
     1648         *     $p->get_attribute( 'data-test-id' ) === '14';
     1649         *     $p->get_attribute( 'enabled' ) === true;
     1650         *     $p->get_attribute( 'aria-label' ) === null;
     1651         *
     1652         *     $p->next_tag() === false;
     1653         *     $p->get_attribute( 'class' ) === null;
    16711654         *
    16721655         * @since 6.2.0
    … …  
    17401723         *
    17411724         * Example:
    1742          * ```php
    1743          * $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
    1744          * $p->next_tag( array( 'class_name' => 'test' ) ) === true;
    1745          * $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
    1746          *
    1747          * $p->next_tag() === false;
    1748          * $p->get_attribute_names_with_prefix( 'data-' ) === null;
    1749          * ```
     1725         *
     1726         *     $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
     1727         *     $p->next_tag( array( 'class_name' => 'test' ) ) === true;
     1728         *     $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
     1729         *
     1730         *     $p->next_tag() === false;
     1731         *     $p->get_attribute_names_with_prefix( 'data-' ) === null;
    17501732         *
    17511733         * @since 6.2.0
    … …  
    17761758         *
    17771759         * Example:
    1778          * ```php
    1779          * $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' );
    1780          * $p->next_tag() === true;
    1781          * $p->get_tag() === 'DIV';
    1782          *
    1783          * $p->next_tag() === false;
    1784          * $p->get_tag() === null;
    1785          * ```
     1760         *
     1761         *     $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' );
     1762         *     $p->next_tag() === true;
     1763         *     $p->get_tag() === 'DIV';
     1764         *
     1765         *     $p->next_tag() === false;
     1766         *     $p->get_tag() === null;
    17861767         *
    17871768         * @since 6.2.0
    … …  
    18281809         *
    18291810         * Example:
    1830          * ```php
    1831          * $p = new WP_HTML_Tag_Processor( '<div></div>' );
    1832          * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
    1833          * $p->is_tag_closer() === false;
    1834          *
    1835          * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
    1836          * $p->is_tag_closer() === true;
    1837          * ```
     1811         *
     1812         *     $p = new WP_HTML_Tag_Processor( '<div></div>' );
     1813         *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
     1814         *     $p->is_tag_closer() === false;
     1815         *
     1816         *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
     1817         *     $p->is_tag_closer() === true;
    18381818         *
    18391819         * @since 6.2.0
    … …  
    19411921                         *
    19421922                         * Example – set attribute id to "new" in <div id="initial_id" />:
    1943                          *    <div id="initial_id"/>
    1944                          *         ^-------------^
    1945                          *         start         end
    1946                          *    replacement: `id="new"`
    19471923                         *
    1948                          *    Result: <div id="new"/>
     1924                         *     <div id="initial_id"/>
     1925                         *          ^-------------^
     1926                         *          start         end
     1927                         *     replacement: `id="new"`
     1928                         *
     1929                         *     Result: <div id="new"/>
    19491930                         */
    19501931                        $existing_attribute                        = $this->attributes[ $comparable_name ];
    … …  
    19591940                         *
    19601941                         * Example – add attribute id="new" to <div />:
    1961                          *    <div/>
    1962                          *        ^
    1963                          *        start and end
    1964                          *    replacement: ` id="new"`
    19651942                         *
    1966                          *    Result: <div id="new"/>
     1943                         *     <div/>
     1944                         *         ^
     1945                         *         start and end
     1946                         *     replacement: ` id="new"`
     1947                         *
     1948                         *     Result: <div id="new"/>
    19671949                         */
    19681950                        $this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
Note: See TracChangeset for help on using the changeset viewer.