Skip to content

Add type annotations for DeclarationBlock #281

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 DeclarationBlock #281

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
119 changes: 94 additions & 25 deletions src/RuleSet/DeclarationBlock.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\RuleSet;

use Sabberworm\CSS\CSSList\CSSList;
use Sabberworm\CSS\CSSList\KeyFrame;
use Sabberworm\CSS\OutputFormat;
use Sabberworm\CSS\Parsing\OutputException;
use Sabberworm\CSS\Parsing\ParserState;
use Sabberworm\CSS\Parsing\UnexpectedEOFException;
use Sabberworm\CSS\Parsing\UnexpectedTokenException;
use Sabberworm\CSS\Property\KeyframeSelector;
use Sabberworm\CSS\Property\Selector;
Expand All @@ -17,22 +19,34 @@
use Sabberworm\CSS\Value\Value;

/**
* Declaration blocks are the parts of a css file which denote the rules belonging to a selector.
* Declaration blocks usually appear directly inside a Document or another CSSList (mostly a MediaQuery).
* Declaration blocks are the parts of a CSS file which denote the rules belonging to a selector.
*
* Declaration blocks usually appear directly inside a `Document` or another `CSSList` (mostly a `MediaQuery`).
*/
class DeclarationBlock extends RuleSet
{
/**
* @var array<int, Selector>
* @var array<int, Selector|string>
*/
private $aSelectors;

/**
* @param int $iLineNo
*/
public function __construct($iLineNo = 0)
{
parent::__construct($iLineNo);
$this->aSelectors = [];
}

/**
* @param CSSList|null $oList
*
* @return DeclarationBlock|false
*
* @throws UnexpectedTokenException
* @throws UnexpectedEOFException
*/
public static function parse(ParserState $oParserState, $oList = null)
{
$aComments = [];
Expand Down Expand Up @@ -70,6 +84,12 @@ public static function parse(ParserState $oParserState, $oList = null)
return $oResult;
}

/**
* @param array<int, Selector|string>|string $mSelector
* @param CSSList|null $oList
*
* @throws UnexpectedTokenException
*/
public function setSelectors($mSelector, $oList = null)
{
if (is_array($mSelector)) {
Expand Down Expand Up @@ -104,6 +124,10 @@ public function setSelectors($mSelector, $oList = null)

/**
* Remove one of the selectors of the block.
*
* @param Selector|string $mSelector
*
* @return bool
*/
public function removeSelector($mSelector)
{
Expand All @@ -120,6 +144,8 @@ public function removeSelector($mSelector)
}

/**
* @return array<int, Selector|string>
*
* @deprecated use `getSelectors()`
*/
public function getSelector()
Expand All @@ -128,6 +154,11 @@ public function getSelector()
}

/**
* @param Selector|string $mSelector
* @param CSSList|null $oList
*
* @return void
*
* @deprecated use `setSelectors()`
*/
public function setSelector($mSelector, $oList = null)
Expand All @@ -136,18 +167,18 @@ public function setSelector($mSelector, $oList = null)
}

/**
* Get selectors.
*
* @return array<int, Selector> Selectors.
* @return array<int, Selector|string>
*/
public function getSelectors()
{
return $this->aSelectors;
}

/**
* Split shorthand declarations (e.g. +margin+ or +font+) into their constituent parts.
* */
* Splits shorthand declarations (e.g. `margin` or `font`) into their constituent parts.
*
* @return void
*/
public function expandShorthands()
{
// border must be expanded before dimensions
Expand All @@ -159,8 +190,10 @@ public function expandShorthands()
}

/**
* Create shorthand declarations (e.g. +margin+ or +font+) whenever possible.
* */
* Creates shorthand declarations (e.g. `margin` or `font`) whenever possible.
*
* @return void
*/
public function createShorthands()
{
$this->createBackgroundShorthand();
Expand All @@ -172,10 +205,14 @@ public function createShorthands()
}

/**
* Split shorthand border declarations (e.g. <tt>border: 1px red;</tt>)
* Additional splitting happens in expandDimensionsShorthand
* Multiple borders are not yet supported as of 3
* */
* Splits shorthand border declarations (e.g. `border: 1px red;`).
*
* Additional splitting happens in expandDimensionsShorthand.
*
* Multiple borders are not yet supported as of 3.
*
* @return void
*/
public function expandBorderShorthand()
{
$aBorderRules = [
Expand Down Expand Up @@ -230,10 +267,13 @@ public function expandBorderShorthand()
}

/**
* Split shorthand dimensional declarations (e.g. <tt>margin: 0px auto;</tt>)
* Splits shorthand dimensional declarations (e.g. `margin: 0px auto;`)
* into their constituent parts.
* Handles margin, padding, border-color, border-style and border-width.
* */
*
* Handles `margin`, `padding`, `border-color`, `border-style` and `border-width`.
*
* @return void
*/
public function expandDimensionsShorthand()
{
$aExpansions = [
Expand Down Expand Up @@ -288,10 +328,12 @@ public function expandDimensionsShorthand()
}

/**
* Convert shorthand font declarations
* Converts shorthand font declarations
* (e.g. `font: 300 italic 11px/14px verdana, helvetica, sans-serif;`)
* into their constituent parts.
* */
*
* @return void
*/
public function expandFontShorthand()
{
$aRules = $this->getRulesAssoc();
Expand Down Expand Up @@ -359,6 +401,8 @@ public function expandFontShorthand()
* into their constituent parts.
*
* @see http://www.w3.org/TR/21/colors.html#propdef-background
*
* @return void
*/
public function expandBackgroundShorthand()
{
Expand Down Expand Up @@ -429,6 +473,9 @@ public function expandBackgroundShorthand()
$this->removeRule('background');
}

/**
* @return void
*/
public function expandListStyleShorthand()
{
$aListProperties = [
Expand Down Expand Up @@ -506,6 +553,12 @@ public function expandListStyleShorthand()
$this->removeRule('list-style');
}

/**
* @param array<array-key, string> $aProperties
* @param string $sShorthand
*
* @return void
*/
public function createShorthandProperties(array $aProperties, $sShorthand)
{
$aRules = $this->getRulesAssoc();
Expand Down Expand Up @@ -538,6 +591,9 @@ public function createShorthandProperties(array $aProperties, $sShorthand)
}
}

/**
* @return void
*/
public function createBackgroundShorthand()
{
$aProperties = [
Expand All @@ -550,6 +606,9 @@ public function createBackgroundShorthand()
$this->createShorthandProperties($aProperties, 'background');
}

/**
* @return void
*/
public function createListStyleShorthand()
{
$aProperties = [
Expand All @@ -561,9 +620,12 @@ public function createListStyleShorthand()
}

/**
* Combine border-color, border-style and border-width into border
* Should be run after create_dimensions_shorthand!
* */
* Combines `border-color`, `border-style` and `border-width` into `border`.
*
* Should be run after `create_dimensions_shorthand`!
*
* @return void
*/
public function createBorderShorthand()
{
$aProperties = [
Expand All @@ -578,6 +640,8 @@ public function createBorderShorthand()
* Looks for long format CSS dimensional properties
* (margin, padding, border-color, border-style and border-width)
* and converts them into shorthand CSS properties.
*
* @return void
*/
public function createDimensionsShorthand()
{
Expand Down Expand Up @@ -649,7 +713,9 @@ public function createDimensionsShorthand()
* Looks for long format CSS font properties (e.g. `font-weight`) and
* tries to convert them into a shorthand CSS `font` property.
*
* At least font-size AND font-family must be present in order to create a shorthand declaration.
* At least `font-size` AND `font-family` must be present in order to create a shorthand declaration.
*
* @return void
*/
public function createFontShorthand()
{
Expand Down Expand Up @@ -729,14 +795,17 @@ public function createFontShorthand()
}
}

/**
* @return string
*
* @throws OutputException
*/
public function __toString()
{
return $this->render(new OutputFormat());
}

/**
* @param OutputFormat $oOutputFormat
*
* @return string
*
* @throws OutputException
Expand Down