Make WordPress Core

Changeset 55727 for trunk


Ignore:
Timestamp:
05/08/2023 05:30:41 PM (18 months 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.