<?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            $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            $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            $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            $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            $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            $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            $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            $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            $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            $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            $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;
    }
}