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.

  • 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:

    • 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:

    • 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 LexicalUnit.LexicalType.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 LexicalUnit.LexicalType.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:

    • getFunctionName

      String getFunctionName()
      Returns the name of the function.
      Returns:
      the function name, or null if this unit is not a function.
      See Also:

    • 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:

    • 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:

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