sdc-build-wp 4.1.0 → 4.1.2

package/vendor/phpcsstandards/phpcsutils/PHPCSUtils/Utils/Parentheses.php

@@ -1,419 +0,0 @@
-<?php
-/**
- * PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
- *
- * @package   PHPCSUtils
- * @copyright 2019-2020 PHPCSUtils Contributors
- * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
- * @link      https://github.com/PHPCSStandards/PHPCSUtils
- */
-
-namespace PHPCSUtils\Utils;
-
-use PHP_CodeSniffer\Files\File;
-use PHP_CodeSniffer\Util\Tokens;
-
-/**
- * Utility functions for use when examining parenthesis tokens and arbitrary tokens wrapped
- * in parentheses.
- *
- * In contrast to PHPCS natively, `isset()`, `unset()`, `empty()`, `exit()`, `die()` and `eval()`
- * will be considered parentheses owners by the functions in this class.
- *
- * @since 1.0.0
- */
-final class Parentheses
-{
-
-    /**
-     * Extra tokens which should be considered parentheses owners.
-     *
-     * - `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EXIT` and `T_EVAL` are not PHPCS native parentheses
-     *    owners, but are considered such for the purposes of this class.
-     *    Also see {@link https://github.com/squizlabs/PHP_CodeSniffer/issues/3118 PHPCS#3118}.
-     *
-     * @since 1.0.0
-     *
-     * @var array<int|string, int|string>
-     */
-    private static $extraParenthesesOwners = [
-        \T_ISSET => \T_ISSET,
-        \T_UNSET => \T_UNSET,
-        \T_EMPTY => \T_EMPTY,
-        \T_EXIT  => \T_EXIT,
-        \T_EVAL  => \T_EVAL,
-    ];
-
-    /**
-     * Get the stack pointer to the parentheses owner of an open/close parenthesis.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
-     * @param int                         $stackPtr  The position of `T_OPEN/CLOSE_PARENTHESIS` token.
-     *
-     * @return int|false Integer stack pointer to the parentheses owner; or `FALSE` if the
-     *                   parenthesis does not have a (direct) owner or if the token passed
-     *                   was not a parenthesis.
-     */
-    public static function getOwner(File $phpcsFile, $stackPtr)
-    {
-        $tokens = $phpcsFile->getTokens();
-
-        if (isset($tokens[$stackPtr]['parenthesis_owner'])) {
-            return $tokens[$stackPtr]['parenthesis_owner'];
-        }
-
-        /*
-         * As the 'parenthesis_owner' index is only set on parentheses, we didn't need to do any
-         * input validation before, but now we do.
-         */
-        if (isset($tokens[$stackPtr]) === false
-            || ($tokens[$stackPtr]['code'] !== \T_OPEN_PARENTHESIS
-            && $tokens[$stackPtr]['code'] !== \T_CLOSE_PARENTHESIS)
-        ) {
-            return false;
-        }
-
-        if ($tokens[$stackPtr]['code'] === \T_CLOSE_PARENTHESIS) {
-            $stackPtr = $tokens[$stackPtr]['parenthesis_opener'];
-        }
-
-        $prevNonEmpty = $phpcsFile->findPrevious(Tokens::$emptyTokens, ($stackPtr - 1), null, true);
-        if ($prevNonEmpty !== false
-            && isset(self::$extraParenthesesOwners[$tokens[$prevNonEmpty]['code']]) === true
-        ) {
-            return $prevNonEmpty;
-        }
-
-        return false;
-    }
-
-    /**
-     * Check whether the parenthesis owner of an open/close parenthesis is within a limited
-     * set of valid owners.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of `T_OPEN/CLOSE_PARENTHESIS` token.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return bool `TRUE` if the owner is within the list of `$validOwners`; `FALSE` if not and
-     *              if the parenthesis does not have a (direct) owner.
-     */
-    public static function isOwnerIn(File $phpcsFile, $stackPtr, $validOwners)
-    {
-        $owner = self::getOwner($phpcsFile, $stackPtr);
-        if ($owner === false) {
-            return false;
-        }
-
-        $tokens      = $phpcsFile->getTokens();
-        $validOwners = (array) $validOwners;
-
-        return \in_array($tokens[$owner]['code'], $validOwners, true);
-    }
-
-    /**
-     * Check whether the passed token is nested within parentheses owned by one of the valid owners.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of the token we are checking.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return bool
-     */
-    public static function hasOwner(File $phpcsFile, $stackPtr, $validOwners)
-    {
-        return (self::nestedParensWalker($phpcsFile, $stackPtr, $validOwners) !== false);
-    }
-
-    /**
-     * Retrieve the stack pointer to the parentheses opener of the first (outer) set of parentheses
-     * an arbitrary token is wrapped in.
-     *
-     * If the optional `$validOwners` parameter is passed, the stack pointer to the opener to
-     * the first set of parentheses, which has an owner which is in the list of valid owners,
-     * will be returned. This may be a nested set of parentheses.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of the token we are checking.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return int|false Integer stack pointer to the parentheses opener; or `FALSE` if the token
-     *                   does not have parentheses owned by any of the valid owners or if
-     *                   the token is not nested in parentheses at all.
-     */
-    public static function getFirstOpener(File $phpcsFile, $stackPtr, $validOwners = [])
-    {
-        return self::nestedParensWalker($phpcsFile, $stackPtr, $validOwners, false);
-    }
-
-    /**
-     * Retrieve the stack pointer to the parentheses closer of the first (outer) set of parentheses
-     * an arbitrary token is wrapped in.
-     *
-     * If the optional `$validOwners` parameter is passed, the stack pointer to the closer to
-     * the first set of parentheses, which has an owner which is in the list of valid owners,
-     * will be returned. This may be a nested set of parentheses.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of the token we are checking.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return int|false Integer stack pointer to the parentheses closer; or `FALSE` if the token
-     *                   does not have parentheses owned by any of the valid owners or if
-     *                   the token is not nested in parentheses at all.
-     */
-    public static function getFirstCloser(File $phpcsFile, $stackPtr, $validOwners = [])
-    {
-        $opener = self::getFirstOpener($phpcsFile, $stackPtr, $validOwners);
-        $tokens = $phpcsFile->getTokens();
-        if ($opener !== false && isset($tokens[$opener]['parenthesis_closer']) === true) {
-            return $tokens[$opener]['parenthesis_closer'];
-        }
-
-        return false;
-    }
-
-    /**
-     * Retrieve the stack pointer to the parentheses owner of the first (outer) set of parentheses
-     * an arbitrary token is wrapped in.
-     *
-     * If the optional `$validOwners` parameter is passed, the stack pointer to the owner of
-     * the first set of parentheses, which has an owner which is in the list of valid owners,
-     * will be returned. This may be a nested set of parentheses.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of the token we are checking.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return int|false Integer stack pointer to the parentheses owner; or `FALSE` if the token
-     *                   does not have parentheses owned by any of the valid owners or if
-     *                   the token is not nested in parentheses at all.
-     */
-    public static function getFirstOwner(File $phpcsFile, $stackPtr, $validOwners = [])
-    {
-        $opener = self::getFirstOpener($phpcsFile, $stackPtr, $validOwners);
-        if ($opener !== false) {
-            return self::getOwner($phpcsFile, $opener);
-        }
-
-        return false;
-    }
-
-    /**
-     * Retrieve the stack pointer to the parentheses opener of the last (inner) set of parentheses
-     * an arbitrary token is wrapped in.
-     *
-     * If the optional `$validOwners` parameter is passed, the stack pointer to the opener to
-     * the last set of parentheses, which has an owner which is in the list of valid owners,
-     * will be returned. This may be a set of parentheses higher up.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of the token we are checking.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return int|false Integer stack pointer to the parentheses opener; or `FALSE` if the token
-     *                   does not have parentheses owned by any of the valid owners or if
-     *                   the token is not nested in parentheses at all.
-     */
-    public static function getLastOpener(File $phpcsFile, $stackPtr, $validOwners = [])
-    {
-        return self::nestedParensWalker($phpcsFile, $stackPtr, $validOwners, true);
-    }
-
-    /**
-     * Retrieve the stack pointer to the parentheses closer of the last (inner) set of parentheses
-     * an arbitrary token is wrapped in.
-     *
-     * If the optional `$validOwners` parameter is passed, the stack pointer to the closer to
-     * the last set of parentheses, which has an owner which is in the list of valid owners,
-     * will be returned. This may be a set of parentheses higher up.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of the token we are checking.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return int|false Integer stack pointer to the parentheses closer; or `FALSE` if the token
-     *                   does not have parentheses owned by any of the valid owners or if
-     *                   the token is not nested in parentheses at all.
-     */
-    public static function getLastCloser(File $phpcsFile, $stackPtr, $validOwners = [])
-    {
-        $opener = self::getLastOpener($phpcsFile, $stackPtr, $validOwners);
-        $tokens = $phpcsFile->getTokens();
-        if ($opener !== false && isset($tokens[$opener]['parenthesis_closer']) === true) {
-            return $tokens[$opener]['parenthesis_closer'];
-        }
-
-        return false;
-    }
-
-    /**
-     * Retrieve the stack pointer to the parentheses owner of the last (inner) set of parentheses
-     * an arbitrary token is wrapped in.
-     *
-     * If the optional `$validOwners` parameter is passed, the stack pointer to the owner of
-     * the last set of parentheses, which has an owner which is in the list of valid owners,
-     * will be returned. This may be a set of parentheses higher up.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of the token we are checking.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return int|false Integer stack pointer to the parentheses owner; or `FALSE` if the token
-     *                   does not have parentheses owned by any of the valid owners or if
-     *                   the token is not nested in parentheses at all.
-     */
-    public static function getLastOwner(File $phpcsFile, $stackPtr, $validOwners = [])
-    {
-        $opener = self::getLastOpener($phpcsFile, $stackPtr, $validOwners);
-        if ($opener !== false) {
-            return self::getOwner($phpcsFile, $opener);
-        }
-
-        return false;
-    }
-
-    /**
-     * Check whether the owner of the outermost wrapping set of parentheses of an arbitrary token
-     * is within a limited set of acceptable token types.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position in the stack of the
-     *                                                  token to verify.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return int|false Integer stack pointer to the valid parentheses owner; or `FALSE` if
-     *                   the token was not wrapped in parentheses or if the outermost set
-     *                   of parentheses in which the token is wrapped does not have an owner
-     *                   within the set of owners considered valid.
-     */
-    public static function firstOwnerIn(File $phpcsFile, $stackPtr, $validOwners)
-    {
-        $opener = self::getFirstOpener($phpcsFile, $stackPtr);
-
-        if ($opener !== false && self::isOwnerIn($phpcsFile, $opener, $validOwners) === true) {
-            return self::getOwner($phpcsFile, $opener);
-        }
-
-        return false;
-    }
-
-    /**
-     * Check whether the owner of the innermost wrapping set of parentheses of an arbitrary token
-     * is within a limited set of acceptable token types.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position in the stack of the
-     *                                                  token to verify.
-     * @param int|string|array<int|string> $validOwners Array of token constants for the owners
-     *                                                  which should be considered valid.
-     *
-     * @return int|false Integer stack pointer to the valid parentheses owner; or `FALSE` if
-     *                   the token was not wrapped in parentheses or if the innermost set
-     *                   of parentheses in which the token is wrapped does not have an owner
-     *                   within the set of owners considered valid.
-     */
-    public static function lastOwnerIn(File $phpcsFile, $stackPtr, $validOwners)
-    {
-        $opener = self::getLastOpener($phpcsFile, $stackPtr);
-
-        if ($opener !== false && self::isOwnerIn($phpcsFile, $opener, $validOwners) === true) {
-            return self::getOwner($phpcsFile, $opener);
-        }
-
-        return false;
-    }
-
-    /**
-     * Helper method. Retrieve the position of a parentheses opener for an arbitrary passed token.
-     *
-     * If no `$validOwners` are specified, the opener to the first set of parentheses surrounding
-     * the token - or if `$reverse = true`, the last set of parentheses - will be returned.
-     *
-     * @since 1.0.0
-     *
-     * @param \PHP_CodeSniffer\Files\File  $phpcsFile   The file where this token was found.
-     * @param int                          $stackPtr    The position of the token we are checking.
-     * @param int|string|array<int|string> $validOwners Optional. Array of token constants for the owners
-     *                                                  which should be considered valid.
-     * @param bool                         $reverse     Optional. Whether to search for the first/outermost
-     *                                                  (`false`) or the last/innermost (`true`) set of
-     *                                                  parentheses with the specified owner(s).
-     *
-     * @return int|false Integer stack pointer to the parentheses opener; or `FALSE` if the token
-     *                   does not have parentheses owned by any of the valid owners or if
-     *                   the token is not nested in parentheses at all.
-     */
-    private static function nestedParensWalker(File $phpcsFile, $stackPtr, $validOwners = [], $reverse = false)
-    {
-        $tokens = $phpcsFile->getTokens();
-
-        // Check for the existence of the token.
-        if (isset($tokens[$stackPtr]) === false) {
-            return false;
-        }
-
-        // Make sure the token is nested in parenthesis.
-        if (empty($tokens[$stackPtr]['nested_parenthesis']) === true) {
-            return false;
-        }
-
-        $validOwners = (array) $validOwners;
-        $parentheses = $tokens[$stackPtr]['nested_parenthesis'];
-
-        if (empty($validOwners) === true) {
-            // No owners specified, just return the first/last parentheses opener.
-            if ($reverse === true) {
-                \end($parentheses);
-            } else {
-                \reset($parentheses);
-            }
-
-            return \key($parentheses);
-        }
-
-        if ($reverse === true) {
-            $parentheses = \array_reverse($parentheses, true);
-        }
-
-        foreach ($parentheses as $opener => $closer) {
-            if (self::isOwnerIn($phpcsFile, $opener, $validOwners) === true) {
-                // We found a token with a valid owner.
-                return $opener;
-            }
-        }
-
-        return false;
-    }
-}