Module io.sf.carte.css4j

Package io.sf.carte.doc.style.css.nsac

Interface LexicalUnit

public interface LexicalUnit

A CSS lexical unit.

This lexical unit may be followed by a number of subsequent units, accessible via the getNextLexicalUnit() method. May also be preceded by other units that can be accessed by the getPreviousLexicalUnit().

It is recommended that implementations of this interface override the equals() and hashCode() methods, but in doing that do not take into account subsequent lexical units in the chain.

Based on SAC's LexicalUnit interface by Philippe Le Hegaret.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	LexicalUnit.LexicalType	The lexical type.

Method Summary

Modifier and Type	Method	Description
LexicalUnit	clone()	Creates a deep copy of this lexical unit and the next ones, unlinked to any previous lexical unit.
int	countReplaceBy(LexicalUnit replacementUnit)	Replace this unit in the chain of lexical units (by the unit or sequence of units in the argument) and return the count of replacement units.
default int	getContextIndex()	Gives the index of this unit in its processing context.
String	getCssText()	Get a parsable representation of this unit.
short	getCssUnit()	An integer indicating the type of CSS unit that this lexical value represents.
String	getDimensionUnitText()	If this unit is a DIMENSION, returns the string representation of the CSS unit returned by getCssUnit().
float	getFloatValue()	Returns the float value represented by this unit.
String	getFunctionName()	Returns the name of the function.
int	getIntegerValue()	Returns the integer value represented by this unit.
LexicalUnit.LexicalType	getLexicalUnitType()	Gives the type of LexicalUnit.
default CSSMathFunctionValue.MathFunction	getMathFunction()	Gives the ID of this unit as a mathematical function, according to CSSMathFunctionValue.MathFunction.
default int	getMathFunctionIndex()	Gives the index of this unit as a mathematical function.
LexicalUnit	getNextLexicalUnit()	The next lexical unit.
LexicalUnit	getParameters()	The function parameters including operators (like the comma).
StringList	getPrecedingComments()	Get the list of preceding comments.
LexicalUnit	getPreviousLexicalUnit()	The previous lexical unit.
String	getStringValue()	Returns the string value.
LexicalUnit	getSubValues()	Returns a sequence of units inside the sub-expression or unicode range.
default CSSValueSyntax	getSyntax()	Get the syntax specified by this unit.
StringList	getTrailingComments()	Get the list of trailing comments.
default TransformFunctions	getTransformFunction()	Gives the ID of this unit as a transform function, according to TransformFunctions.
void	insertNextLexicalUnit(LexicalUnit nextUnit)	Insert the given unit as the next lexical unit.
boolean	isParameter()	Check if this lexical unit is a parameter that was made available through its parent's getParameters() method.
CSSValueSyntax.Match	matches(CSSValueSyntax syntax)	Verify whether this value matches the given grammar.
LexicalUnit	remove()	Remove this unit from the chain of lexical units and replace it by the next one, if any.
LexicalUnit	replaceBy(LexicalUnit replacementUnit)	Replace this unit in the chain of lexical units.
LexicalUnit	shallowClone()	Creates a shallow copy of this lexical unit, ignoring the next ones, and unlinked to any previous lexical unit.
CSSValueSyntax.Match	shallowMatch(CSSValueSyntax syntax)	Verify whether this lexical unit matches the given grammar, ignoring further units in the lexical chain.

Method Details

getLexicalUnitType

LexicalUnit.LexicalType getLexicalUnitType()

Gives the type of LexicalUnit.

Returns:

the type of LexicalUnit.

getCssUnit

short getCssUnit()

An integer indicating the type of CSS unit that this lexical value represents.

Returns:

an integer indicating the type of CSS unit. If this value does not represent a dimension, must return an invalid unit identifier.

getNextLexicalUnit

LexicalUnit getNextLexicalUnit()

The next lexical unit.

Lexical units can form chains of units which can be traversed with getNextLexicalUnit() and getPreviousLexicalUnit().

Returns:

the next lexical unit, or null if none.

getPreviousLexicalUnit

LexicalUnit getPreviousLexicalUnit()

The previous lexical unit.

See also getNextLexicalUnit().

Returns:

the previous lexical unit, or null if none.

insertNextLexicalUnit

void insertNextLexicalUnit(LexicalUnit nextUnit)

Insert the given unit as the next lexical unit.

After the insertion, nextUnit shall be the next lexical unit, and the former next lexical unit will be the next one after the last unit in the nextUnit unit chain.

Parameters:

nextUnit - the lexical unit to be set as the next one.

Throws:

IllegalArgumentException - if the argument is a parameter or has a previous unit.

remove

LexicalUnit remove()

Remove this unit from the chain of lexical units and replace it by the next one, if any.

Returns:

the next lexical unit, or null if there is no next lexical unit.

countReplaceBy

int countReplaceBy(LexicalUnit replacementUnit)
            throws CSSBudgetException

Replace this unit in the chain of lexical units (by the unit or sequence of units in the argument) and return the count of replacement units.

The replaced unit always returns null for getNextLexicalUnit() and getPreviousLexicalUnit(), false for isParameter().

Parameters:

replacementUnit - the lexical unit that replaces this one. If null, this unit is replaced by the next one. If EMPTY, this unit is replaced by the next non-empty unit in the parameter's lexical chain or, if there is none, by the next unit in this chain (same as if parameter was null).

Returns:

the number of units that replace this one (i.e. the argument, or 0 if the argument is null).

Throws:

IllegalArgumentException - if the replacement unit is a parameter or has a previous unit.

CSSBudgetException - if the replacement unit has too many chained units (to avoid potential DoS).

replaceBy

LexicalUnit replaceBy(LexicalUnit replacementUnit)
               throws CSSBudgetException

Replace this unit in the chain of lexical units.

The replaced unit always returns null for getNextLexicalUnit() and getPreviousLexicalUnit(), false for isParameter().

This method is very similar to countReplaceBy(LexicalUnit) which gives important information when you need to replace this unit by an arbitrary (and potentially large) chunk of values.

Parameters:

replacementUnit - the lexical unit that replaces this one. If null, this unit is replaced by the next one.

Returns:

the unit that replaces this one (i.e. the argument, or the next lexical unit if the argument is null).

Throws:

IllegalArgumentException - if the replacement unit is a parameter or has a previous unit.

CSSBudgetException - if the replacement unit has too many chained units (to avoid potential DoS).

See Also:

• countReplaceBy(LexicalUnit)

getIntegerValue

int getIntegerValue()

Returns the integer value represented by this unit.

Returns:

the integer value, or zero if this is not an integer unit.

See Also:

• LexicalUnit.LexicalType.INTEGER

getFloatValue

float getFloatValue()

Returns the float value represented by this unit.

Returns:

the float value, or NaN if this value is not a float.

getDimensionUnitText

String getDimensionUnitText()

If this unit is a DIMENSION, returns the string representation of the CSS unit returned by getCssUnit().

Returns:

the string representation of the CSS unit, or the empty string if this lexical unit does not represent a DIMENSION.

getStringValue

String getStringValue()

Returns the string value.

If the type is URI, the return value doesn't contain uri(....) or quotes.

If the type is UNICODE_WILDCARD, the return value is the wildcard without the preceding "U+".

Returns:

the string value, or null if this unit does not have a string to return.

See Also:

• LexicalUnit.LexicalType.IDENT
• LexicalUnit.LexicalType.STRING
• LexicalUnit.LexicalType.URI
• LexicalUnit.LexicalType.UNICODE_WILDCARD
• LexicalUnit.LexicalType.ELEMENT_REFERENCE

getFunctionName

String getFunctionName()

Returns the name of the function.

Returns:

the function name, or null if this unit is not a function.

See Also:

• LexicalUnit.LexicalType.CALC
• LexicalUnit.LexicalType.FUNCTION
• LexicalUnit.LexicalType.COUNTER_FUNCTION
• LexicalUnit.LexicalType.COUNTERS_FUNCTION
• LexicalUnit.LexicalType.CUBIC_BEZIER_FUNCTION
• LexicalUnit.LexicalType.MATH_FUNCTION
• LexicalUnit.LexicalType.STEPS_FUNCTION
• LexicalUnit.LexicalType.RECT_FUNCTION
• LexicalUnit.LexicalType.RGBCOLOR
• LexicalUnit.LexicalType.HSLCOLOR
• LexicalUnit.LexicalType.HWBCOLOR
• LexicalUnit.LexicalType.LABCOLOR
• LexicalUnit.LexicalType.LCHCOLOR
• LexicalUnit.LexicalType.OKLABCOLOR
• LexicalUnit.LexicalType.OKLCHCOLOR
• LexicalUnit.LexicalType.COLOR_FUNCTION
• LexicalUnit.LexicalType.COLOR_MIX
• LexicalUnit.LexicalType.ELEMENT_REFERENCE
• LexicalUnit.LexicalType.VAR
• LexicalUnit.LexicalType.ATTR

getMathFunction

default CSSMathFunctionValue.MathFunction getMathFunction()

Gives the ID of this unit as a mathematical function, according to CSSMathFunctionValue.MathFunction.

Returns:

the function enum, or null if this lexical unit is not a mathematical function (MATH_FUNCTION).

See Also:

• LexicalUnit.LexicalType.MATH_FUNCTION

getMathFunctionIndex

default int getMathFunctionIndex()

Gives the index of this unit as a mathematical function.

Returns:

the zero-based function index, or -1 if this lexical unit is not a mathematical function (MATH_FUNCTION).

See Also:

• LexicalUnit.LexicalType.MATH_FUNCTION

getContextIndex

default int getContextIndex()

Gives the index of this unit in its processing context.

This helps to speed processing in some contexts, like math or transform functions.

For example, if this unit represents a MATH_FUNCTION, this method would return the same result as getMathFunctionIndex().

Returns:

the zero-based function index, or -1 if this lexical unit does not belong to any processing context.

getTransformFunction

default TransformFunctions getTransformFunction()

Gives the ID of this unit as a transform function, according to TransformFunctions.

Returns:

the function enum, or null if this lexical unit is not a transform function (TRANSFORM_FUNCTION).

See Also:

• LexicalUnit.LexicalType.TRANSFORM_FUNCTION

getParameters

LexicalUnit getParameters()

The function parameters including operators (like the comma).

A RGB color like #000 is converted to rgb(0, 0, 0).

May return null if type is FUNCTION.

Since version 5, also returns the sub-values if this is an expression or a unicode range. Therefore, can be used as a more streamlined version of getSubValues().

Returns:

the parameters of this function, or null if this unit is not a function, or an empty FUNCTION.

See Also:

• LexicalUnit.LexicalType.CALC
• LexicalUnit.LexicalType.FUNCTION
• LexicalUnit.LexicalType.COUNTER_FUNCTION
• LexicalUnit.LexicalType.COUNTERS_FUNCTION
• LexicalUnit.LexicalType.CUBIC_BEZIER_FUNCTION
• LexicalUnit.LexicalType.STEPS_FUNCTION
• LexicalUnit.LexicalType.RECT_FUNCTION
• LexicalUnit.LexicalType.TYPE_FUNCTION
• LexicalUnit.LexicalType.RGBCOLOR
• LexicalUnit.LexicalType.HSLCOLOR
• LexicalUnit.LexicalType.HWBCOLOR
• LexicalUnit.LexicalType.LABCOLOR
• LexicalUnit.LexicalType.LCHCOLOR
• LexicalUnit.LexicalType.OKLABCOLOR
• LexicalUnit.LexicalType.OKLCHCOLOR
• LexicalUnit.LexicalType.COLOR_FUNCTION
• LexicalUnit.LexicalType.COLOR_MIX
• LexicalUnit.LexicalType.ELEMENT_REFERENCE
• LexicalUnit.LexicalType.VAR
• LexicalUnit.LexicalType.ATTR

isParameter

boolean isParameter()

Check if this lexical unit is a parameter that was made available through its parent's getParameters() method.

Returns:

true if this lexical unit is a parameter.

getSubValues

LexicalUnit getSubValues()

Returns a sequence of units inside the sub-expression or unicode range.

Returns:

the values in the sub-expression, or null if this unit is not a sub-expression nor a unicode range.

See Also:

• LexicalUnit.LexicalType.SUB_EXPRESSION
• LexicalUnit.LexicalType.UNICODE_RANGE

getSyntax

default CSSValueSyntax getSyntax()
                          throws IllegalStateException

Get the syntax specified by this unit.

Returns:

the CSS syntax.

Throws:

IllegalStateException - if this is not a syntax unit.

See Also:

• LexicalUnit.LexicalType.SYNTAX

getCssText

String getCssText()

Get a parsable representation of this unit.

The serialization must only include this lexical unit, ignoring the next units if they exist.

The text should be close to how the value was specified (for example, preserving hex or functional notation in rgb colors) but must parse without errors (except for compatibility values like COMPAT_IDENT).

Returns:

the parsable serialization of this unit.

getPrecedingComments

StringList getPrecedingComments()

Get the list of preceding comments.

Returns:

the list of preceding comments, or null if none.

getTrailingComments

StringList getTrailingComments()

Get the list of trailing comments.

Returns:

the list of trailing comments, or null if none.

matches

CSSValueSyntax.Match matches(CSSValueSyntax syntax)

Verify whether this value matches the given grammar.

This method is intended to be used for generic sanity checks and, consequently, some corner cases may not be taken into account. For example, when matching var(), the implementations are allowed to assume that the property substitution shall not be empty, otherwise values like var(--data) 1px would give a non-FALSE match simultaneously on syntaxes with and without a multiplier (+ or #), which would probably not be what that use case wants.

In the case of calc(), if implementations do not perform a full dimensional analysis it is more acceptable to return a bogus TRUE than a FALSE.

This method takes into account the next units in the lexical chain, if you do not want that please use shallowMatch(CSSValueSyntax) instead.

Here are some examples of matching:

Value	Syntax	Match
attr(data-width type(<length>), 8%)	<percentage> | <length>	TRUE
	<length>	PENDING
	<percentage>	PENDING
	<length>#	PENDING
	<length-percentage>	TRUE
	<resolution>	FALSE
	*	TRUE
6pt var(--custom) 12.3px	<length>+	PENDING
	<length>#	PENDING1
	<length>	FALSE
	<number>+	FALSE
	*	TRUE

1. Despite the value containing no commas, the syntax with a # multiplier matches as PENDING because the custom property could have commas and start and end with one.

See also: SyntaxParser, shallowMatch(CSSValueSyntax).

Parameters:

syntax - the syntax.

Returns:

the matching for the syntax.

shallowMatch

CSSValueSyntax.Match shallowMatch(CSSValueSyntax syntax)

Verify whether this lexical unit matches the given grammar, ignoring further units in the lexical chain.

This method is intended for use during shorthand decompositions, gradient processing, etc.

See also: SyntaxParser, matches(CSSValueSyntax).

Parameters:

syntax - the syntax.

Returns:

the matching for the syntax.

clone

LexicalUnit clone()

Creates a deep copy of this lexical unit and the next ones, unlinked to any previous lexical unit.

The clone's getPreviousLexicalUnit() returns null (and isParameter() false) regardless of what the the original object returned.

Returns:

a copy of this unit.

shallowClone

LexicalUnit shallowClone()

Creates a shallow copy of this lexical unit, ignoring the next ones, and unlinked to any previous lexical unit.

The shallow clone's getPreviousLexicalUnit() and getNextLexicalUnit() both return null (and isParameter() false) regardless of what the the original object returned.

Returns:

a shallow copy of this unit.