263 lines
12 KiB
PHP
263 lines
12 KiB
PHP
|
<?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\Exceptions\RuntimeException;
|
||
|
|
use PHP_CodeSniffer\Files\File;
|
||
|
|
use PHP_CodeSniffer\Util\Tokens;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Utility functions to retrieve the content of a set of tokens as a string.
|
||
|
|
*
|
||
|
|
* In contrast to the PHPCS native {@see \PHP_CodeSniffer\Files\File::getTokensAsString()} method,
|
||
|
|
* which has `$length` as the third parameter, all methods in this class expect a stack pointer to
|
||
|
|
* an `$end` token (inclusive) as the third parameter.
|
||
|
|
*
|
||
|
|
* @since 1.0.0 The principle of this class is loosely based on and inspired by the
|
||
|
|
* {@see \PHP_CodeSniffer\Files\File::getTokensAsString()} method in the
|
||
|
|
* PHPCS native `File` class.
|
||
|
|
* Also see {@see \PHPCSUtils\BackCompat\BCFile::getTokensAsString()}.
|
||
|
|
*/
|
||
|
|
final class GetTokensAsString
|
||
|
|
{
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Retrieve the tab-replaced content of the tokens from the specified start position in
|
||
|
|
* the token stack to the specified end position (inclusive).
|
||
|
|
*
|
||
|
|
* Alias for the {@see \PHPCSUtils\Utils\GetTokensAsString::tabReplaced()} method.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
|
||
|
|
* @param int $start The position to start from in the token stack.
|
||
|
|
* @param int $end The position to end at in the token stack (inclusive).
|
||
|
|
*
|
||
|
|
* @return string The token contents.
|
||
|
|
*
|
||
|
|
* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified start position does not exist.
|
||
|
|
*/
|
||
|
|
public static function normal(File $phpcsFile, $start, $end)
|
||
|
|
{
|
||
|
|
return self::tabReplaced($phpcsFile, $start, $end);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Retrieve the tab-replaced content of the tokens from the specified start position in
|
||
|
|
* the token stack to the specified end position (inclusive).
|
||
|
|
*
|
||
|
|
* This is the default behaviour for PHPCS.
|
||
|
|
*
|
||
|
|
* If the `tabWidth` is set, either via a (custom) ruleset, the config file or by passing it
|
||
|
|
* on the command-line, PHPCS will automatically replace tabs with spaces.
|
||
|
|
* The `'content'` index key in the `$tokens` array will contain the tab-replaced content.
|
||
|
|
* The `'orig_content'` index key in the `$tokens` array will contain the original content.
|
||
|
|
*
|
||
|
|
* @see \PHP_CodeSniffer\Files\File::getTokensAsString() Similar length-based function.
|
||
|
|
* @see \PHPCSUtils\BackCompat\BCFile::getTokensAsString() Cross-version compatible version of the original.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
|
||
|
|
* @param int $start The position to start from in the token stack.
|
||
|
|
* @param int $end The position to end at in the token stack (inclusive).
|
||
|
|
*
|
||
|
|
* @return string The token contents.
|
||
|
|
*
|
||
|
|
* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified start position does not exist.
|
||
|
|
*/
|
||
|
|
public static function tabReplaced(File $phpcsFile, $start, $end)
|
||
|
|
{
|
||
|
|
return self::getString($phpcsFile, $start, $end);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Retrieve the original content of the tokens from the specified start position in
|
||
|
|
* the token stack to the specified end position (inclusive).
|
||
|
|
*
|
||
|
|
* In contrast to the {@see GetTokensAsString::tabReplaced()} method, this method will return
|
||
|
|
* the original token content for the specified tokens.
|
||
|
|
* That means that if the original content contained tabs, the return value of this function
|
||
|
|
* will also contain tabs.
|
||
|
|
*
|
||
|
|
* The same can be achieved in PHPCS since version 3.3.0, by calling the
|
||
|
|
* {@see \PHP_CodeSniffer\Files\File::getTokensAsString()} method and passing `true` as the
|
||
|
|
* value for the `$origContent` parameter.
|
||
|
|
*
|
||
|
|
* @see \PHP_CodeSniffer\Files\File::getTokensAsString() Similar length-based function.
|
||
|
|
* @see \PHPCSUtils\BackCompat\BCFile::getTokensAsString() Cross-version compatible version of the original.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
|
||
|
|
* @param int $start The position to start from in the token stack.
|
||
|
|
* @param int $end The position to end at in the token stack (inclusive).
|
||
|
|
*
|
||
|
|
* @return string The token contents.
|
||
|
|
*
|
||
|
|
* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified start position does not exist.
|
||
|
|
*/
|
||
|
|
public static function origContent(File $phpcsFile, $start, $end)
|
||
|
|
{
|
||
|
|
return self::getString($phpcsFile, $start, $end, true);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Retrieve the content of the tokens from the specified start position in the token
|
||
|
|
* stack to the specified end position (inclusive) without comments.
|
||
|
|
*
|
||
|
|
* @see \PHP_CodeSniffer\Files\File::getTokensAsString() Loosely related function.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
|
||
|
|
* @param int $start The position to start from in the token stack.
|
||
|
|
* @param int $end The position to end at in the token stack (inclusive).
|
||
|
|
*
|
||
|
|
* @return string The token contents stripped off comments.
|
||
|
|
*
|
||
|
|
* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified start position does not exist.
|
||
|
|
*/
|
||
|
|
public static function noComments(File $phpcsFile, $start, $end)
|
||
|
|
{
|
||
|
|
return self::getString($phpcsFile, $start, $end, false, true);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Retrieve the code-tokens only content of the tokens from the specified start position
|
||
|
|
* in the token stack to the specified end position (inclusive) without whitespace or comments.
|
||
|
|
*
|
||
|
|
* This is useful, for instance, to retrieve a namespace name without stray whitespace or comments.
|
||
|
|
* Use this function selectively and with care!
|
||
|
|
*
|
||
|
|
* @see \PHP_CodeSniffer\Files\File::getTokensAsString() Loosely related function.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
|
||
|
|
* @param int $start The position to start from in the token stack.
|
||
|
|
* @param int $end The position to end at in the token stack (inclusive).
|
||
|
|
*
|
||
|
|
* @return string The token contents stripped off comments and whitespace.
|
||
|
|
*
|
||
|
|
* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified start position does not exist.
|
||
|
|
*/
|
||
|
|
public static function noEmpties(File $phpcsFile, $start, $end)
|
||
|
|
{
|
||
|
|
return self::getString($phpcsFile, $start, $end, false, true, true);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Retrieve the content of the tokens from the specified start position in the token
|
||
|
|
* stack to the specified end position (inclusive) with all consecutive whitespace tokens - tabs,
|
||
|
|
* new lines, multiple spaces - replaced by a single space and optionally without comments.
|
||
|
|
*
|
||
|
|
* @see \PHP_CodeSniffer\Files\File::getTokensAsString() Loosely related function.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
|
||
|
|
* @param int $start The position to start from in the token stack.
|
||
|
|
* @param int $end The position to end at in the token stack (inclusive).
|
||
|
|
* @param bool $stripComments Whether comments should be stripped from the contents.
|
||
|
|
* Defaults to `false`.
|
||
|
|
*
|
||
|
|
* @return string The token contents with compacted whitespace and optionally stripped off comments.
|
||
|
|
*
|
||
|
|
* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified start position does not exist.
|
||
|
|
*/
|
||
|
|
public static function compact(File $phpcsFile, $start, $end, $stripComments = false)
|
||
|
|
{
|
||
|
|
return self::getString($phpcsFile, $start, $end, false, $stripComments, false, true);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Retrieve the content of the tokens from the specified start position in the token stack
|
||
|
|
* to the specified end position (inclusive).
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
|
||
|
|
* @param int $start The position to start from in the token stack.
|
||
|
|
* @param int $end The position to end at in the token stack (inclusive).
|
||
|
|
* @param bool $origContent Whether the original content or the tab replaced
|
||
|
|
* content should be used.
|
||
|
|
* Defaults to `false` (= tabs replaced with spaces).
|
||
|
|
* @param bool $stripComments Whether comments should be stripped from the contents.
|
||
|
|
* Defaults to `false`.
|
||
|
|
* @param bool $stripWhitespace Whether whitespace should be stripped from the contents.
|
||
|
|
* Defaults to `false`.
|
||
|
|
* @param bool $compact Whether all consecutive whitespace tokens should be
|
||
|
|
* replaced with a single space. Defaults to `false`.
|
||
|
|
*
|
||
|
|
* @return string The token contents.
|
||
|
|
*
|
||
|
|
* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified start position does not exist.
|
||
|
|
*/
|
||
|
|
protected static function getString(
|
||
|
|
File $phpcsFile,
|
||
|
|
$start,
|
||
|
|
$end,
|
||
|
|
$origContent = false,
|
||
|
|
$stripComments = false,
|
||
|
|
$stripWhitespace = false,
|
||
|
|
$compact = false
|
||
|
|
) {
|
||
|
|
$tokens = $phpcsFile->getTokens();
|
||
|
|
|
||
|
|
if (\is_int($start) === false || isset($tokens[$start]) === false) {
|
||
|
|
throw new RuntimeException(
|
||
|
|
'The $start position for GetTokensAsString methods must exist in the token stack'
|
||
|
|
);
|
||
|
|
}
|
||
|
|
|
||
|
|
if (\is_int($end) === false || $end < $start) {
|
||
|
|
return '';
|
||
|
|
}
|
||
|
|
|
||
|
|
$str = '';
|
||
|
|
if ($end >= $phpcsFile->numTokens) {
|
||
|
|
$end = ($phpcsFile->numTokens - 1);
|
||
|
|
}
|
||
|
|
|
||
|
|
$lastAdded = null;
|
||
|
|
for ($i = $start; $i <= $end; $i++) {
|
||
|
|
if ($stripComments === true && isset(Tokens::$commentTokens[$tokens[$i]['code']])) {
|
||
|
|
continue;
|
||
|
|
}
|
||
|
|
|
||
|
|
if ($stripWhitespace === true && $tokens[$i]['code'] === \T_WHITESPACE) {
|
||
|
|
continue;
|
||
|
|
}
|
||
|
|
|
||
|
|
if ($compact === true && $tokens[$i]['code'] === \T_WHITESPACE) {
|
||
|
|
if (isset($lastAdded) === false || $tokens[$lastAdded]['code'] !== \T_WHITESPACE) {
|
||
|
|
$str .= ' ';
|
||
|
|
$lastAdded = $i;
|
||
|
|
}
|
||
|
|
continue;
|
||
|
|
}
|
||
|
|
|
||
|
|
// If tabs are being converted to spaces by the tokenizer, the
|
||
|
|
// original content should be used instead of the converted content.
|
||
|
|
if ($origContent === true && isset($tokens[$i]['orig_content']) === true) {
|
||
|
|
$str .= $tokens[$i]['orig_content'];
|
||
|
|
} else {
|
||
|
|
$str .= $tokens[$i]['content'];
|
||
|
|
}
|
||
|
|
|
||
|
|
$lastAdded = $i;
|
||
|
|
}
|
||
|
|
|
||
|
|
return $str;
|
||
|
|
}
|
||
|
|
}
|