Module io.sf.carte.css4j

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

Interface LexicalUnit

public interface LexicalUnit

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.
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.
LexicalUnit	getNextLexicalUnit()	The next lexical unit.
LexicalUnit	getParameters()	The function parameters including operators (like the comma).
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.
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.

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.

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.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

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.

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.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

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.

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.

Here are some examples of matching:

Value	Syntax	Match
attr(data-width 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.

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.