Skip to content

Add type annotations for CSSList #283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 27, 2021
Merged

Add type annotations for CSSList #283

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 67 additions & 23 deletions src/CSSList/CSSList.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,12 @@

namespace Sabberworm\CSS\CSSList;

use Sabberworm\CSS\Comment\Comment;
use Sabberworm\CSS\Comment\Commentable;
use Sabberworm\CSS\OutputFormat;
use Sabberworm\CSS\Parsing\ParserState;
use Sabberworm\CSS\Parsing\SourceException;
use Sabberworm\CSS\Parsing\UnexpectedEOFException;
use Sabberworm\CSS\Parsing\UnexpectedTokenException;
use Sabberworm\CSS\Property\AtRule;
use Sabberworm\CSS\Property\Charset;
Expand All @@ -22,18 +24,20 @@
use Sabberworm\CSS\Value\Value;

/**
* A CSSList is the most generic container available. Its contents include RuleSet as well as other CSSList objects.
* Also, it may contain Import and Charset objects stemming from at-rules.
* A `CSSList` is the most generic container available. Its contents include `RuleSet` as well as other `CSSList`
* objects.
*
* Also, it may contain `Import` and `Charset` objects stemming from at-rules.
*/
abstract class CSSList implements Renderable, Commentable
{
/**
* @var array
* @var array<array-key, Comment> $aComments
*/
protected $aComments;

/**
* @var array<int, RuleSet|Import|Charset|CSSList>
* @var array<int, RuleSet|CSSList|Import|Charset>
*/
protected $aContents;

Expand All @@ -52,6 +56,12 @@ public function __construct($iLineNo = 0)
$this->iLineNo = $iLineNo;
}

/**
* @throws SourceException
* @throws UnexpectedTokenException
*
* @return void
*/
public static function parseList(ParserState $oParserState, CSSList $oList)
{
$bIsRoot = $oList instanceof Document;
Expand Down Expand Up @@ -86,6 +96,13 @@ public static function parseList(ParserState $oParserState, CSSList $oList)
}
}

/**
* @return AtRuleBlockList|KeyFrame|Charset|CSSNamespace|Import|AtRuleSet|DeclarationBlock|null|false
*
* @throws SourceException
* @throws UnexpectedEOFException
* @throws UnexpectedTokenException
*/
private static function parseListItem(ParserState $oParserState, CSSList $oList)
{
$bIsRoot = $oList instanceof Document;
Expand Down Expand Up @@ -130,6 +147,15 @@ private static function parseListItem(ParserState $oParserState, CSSList $oList)
}
}

/**
* @param ParserState $oParserState
*
* @return AtRuleBlockList|KeyFrame|Charset|CSSNamespace|Import|AtRuleSet|null
*
* @throws SourceException
* @throws UnexpectedTokenException
* @throws UnexpectedEOFException
*/
private static function parseAtRule(ParserState $oParserState)
{
$oParserState->consume('@');
Expand Down Expand Up @@ -213,6 +239,11 @@ private static function parseAtRule(ParserState $oParserState)
/**
* Tests an identifier for a given value. Since identifiers are all keywords, they can be vendor-prefixed.
* We need to check for these versions too.
*
* @param string $sIdentifier
* @param string $sMatch
*
* @return bool
*/
private static function identifierIs($sIdentifier, $sMatch)
{
Expand All @@ -229,31 +260,37 @@ public function getLineNo()
}

/**
* Prepend item to list of contents.
* Prepends an item to the list of contents.
*
* @param RuleSet|CSSList|Import|Charset $oItem
*
* @param RuleSet|Import|Charset|CSSList $oItem Item.
* @return void
*/
public function prepend($oItem)
{
array_unshift($this->aContents, $oItem);
}

/**
* Append item to list of contents.
* Appends an item to tje list of contents.
*
* @param RuleSet|CSSList|Import|Charset $oItem
*
* @param RuleSet|Import|Charset|CSSList $oItem Item.
* @return void
*/
public function append($oItem)
{
$this->aContents[] = $oItem;
}

/**
* Splice the list of contents.
* Splices the list of contents.
*
* @param int $iOffset Offset.
* @param int $iLength Length. Optional.
* @param RuleSet[] $mReplacement Replacement. Optional.
* @param int $iOffset
* @param int $iLength
* @param array<int, RuleSet|CSSList|Import|Charset> $mReplacement
*
* @return void
*/
public function splice($iOffset, $iLength = null, $mReplacement = null)
{
Expand All @@ -267,7 +304,7 @@ public function splice($iOffset, $iLength = null, $mReplacement = null)
* May be a RuleSet (most likely a DeclarationBlock), a Import,
* a Charset or another CSSList (most likely a MediaQuery)
*
* @return bool Whether the item was removed.
* @return bool whether the item was removed
*/
public function remove($oItemToRemove)
{
Expand All @@ -283,8 +320,10 @@ public function remove($oItemToRemove)
* Replaces an item from the CSS list.
*
* @param RuleSet|Import|Charset|CSSList $oOldItem
* May be a RuleSet (most likely a DeclarationBlock), a Import, a Charset
* or another CSSList (most likely a MediaQuery)
* May be a `RuleSet` (most likely a `DeclarationBlock`), an `Import`, a `Charset`
* or another `CSSList` (most likely a `MediaQuery`)
*
* @return bool
*/
public function replace($oOldItem, $mNewItem)
{
Expand All @@ -301,9 +340,7 @@ public function replace($oOldItem, $mNewItem)
}

/**
* Set the contents.
*
* @param array<int, RuleSet|Import|Charset|CSSList> $aContents Objects to set as content.
* @param array<int, RuleSet|Import|Charset|CSSList> $aContents
*/
public function setContents(array $aContents)
{
Expand All @@ -316,8 +353,10 @@ public function setContents(array $aContents)
/**
* Removes a declaration block from the CSS list if it matches all given selectors.
*
* @param array|string $mSelector The selectors to match.
* @param boolean $bRemoveAll Whether to stop at the first declaration block found or remove all blocks
* @param DeclarationBlock|array<array-key, Selector>|string $mSelector the selectors to match
* @param bool $bRemoveAll whether to stop at the first declaration block found or remove all blocks
*
* @return void
*/
public function removeDeclarationBlockBySelector($mSelector, $bRemoveAll = false)
{
Expand Down Expand Up @@ -352,6 +391,9 @@ public function removeDeclarationBlockBySelector($mSelector, $bRemoveAll = false
}
}

/**
* @return string
*/
public function __toString()
{
return $this->render(new OutputFormat());
Expand Down Expand Up @@ -394,6 +436,8 @@ public function render(OutputFormat $oOutputFormat)

/**
* Return true if the list can not be further outdented. Only important when rendering.
*
* @return bool
*/
abstract public function isRootList();

Expand All @@ -406,23 +450,23 @@ public function getContents()
}

/**
* @param array $aComments Array of comments.
* @param array<array-key, Comment> $aComments
*/
public function addComments(array $aComments)
{
$this->aComments = array_merge($this->aComments, $aComments);
}

/**
* @return array
* @return array<array-key, Comment>
*/
public function getComments()
{
return $this->aComments;
}

/**
* @param array $aComments Array containing Comment objects.
* @param array<array-key, Comment> $aComments
*/
public function setComments(array $aComments)
{
Expand Down