Package Torello.CSS

Class Comment

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.CharSequence, java.lang.Comparable<java.lang.CharSequence>
    public class Comment
extends CSSToken
implements java.lang.CharSequence, java.io.Serializable, java.lang.Comparable<java.lang.CharSequence>
    This is a Token Data-Class. It is a descendant of the root CSSToken-Class: CSSToken. Instances of the class are usually are produced by the CSSTokenizer class. Many (but not all) of these subclasses maintain a static-method for building instances of this class named 'build'. Any CSSToken-subclass that is neither a singleton-instance, nor an "Error-Subtype" should have such a builder. Singeton instances do not need builders, and the two Error-Subtype Classes can only be generated by the tokenizer.

    All CSSToken subclasses have a CSSToken.str field which contains the exact character data that was extracted and used to construct instances of this class. All sub-casses also have several "Loop Optimization" methods. These are methods that may or may not be useful in light of some of the newer additions to JDK 17 & 21 including the 'instanceof varName' conditional-expression variable-naming features.

    The algorithms used to write this tokenizer were generated based solely on the CSS Working-Group's Syntax-Documentation. This document may be viewed here: CSS Working-Group CSS-Syntax. There is an external site that maintain all thing CSS located at drafts.csswg.org
    Represents a CSS Comment-Block
    See Also:
    Serialized Form


    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1;

    • Method Detail

      • isComment

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean isComment()
        Description copied from class: CSSToken
        Loop Optimization: This method only returns TRUE if this is an actual instance of Comment.
        Overrides:
        isComment in class CSSToken
        Returns:
        This method returns FALSE for all instances of CSSToken, except when 'this' instance is actually the Comment Subclass.

        That class has overridden this method, and returns TRUE.
        See Also:
        isComment()

      • ifComment

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final Comment ifComment()
        Description copied from class: CSSToken
        Loop Optimization: When this method is invoked on an instance of sub-class Comment this method produces 'this' instance.
        Overrides:
        ifComment in class CSSToken
        Returns:
        This method shall return null, always, except when 'this' is an actual instance of Comment. When so, this method simply returns 'this'. All other sub-classes of (abstract) class CSSToken inherit this method, and therefore return null.
        See Also:
        ifComment()

      • build

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Comment build​(java.lang.String commentStr)
        Static-Builder Method for creating an instance of this class. This Static-Method is a substitute for an actual Constructor. Because many of the 'consume(...)' methods in the Token Classe for Torello.CSS actually generate / spit-out more than CSSToken instance, writing publicly available constructors is largely impossible.

        The upside to this approach is that the build methods and the consume methods share identical code. Furthermore this code is (nearly) perfectly based on the Pseudo-Code on the CSS Working-Group Website.
        Parameters:
        commentStr - Any Java-String that can be parsed into an instance of Comment
        Returns:
        An instance of Comment.

        If the contents of the Input-String parameter 'commentStr' cannot be consumed, exactly, by this class' 'consume' method, then an exception shall throw.
        Throws:
        TokenizeException - This exception may be thrown for any number of reasons involving the inability to parse input parameter 'commentStr'.

      • is

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean is​(int[] css,
                         int sPos)
        Checks whether or not the next token to consume is a Comment

        Tokenizer: Comment Check Method, Pseudo-Code

        Making use of the CSS Parser DOES NOT require any knowledge of how the underlying Pass 1 Tokenizer actually works. Below is the CSS Working Group's Comment Rail-Road Diagram. It is here for informational purposes.
        These Parsing Pseudo-Code Instructions and Rail-Road Diagrams have been copied, verbatim, from the CSS-Working-Group Web-Site:
        https://drafts.csswg.org/css-syntax/#comment-diagram
        comment
        /* anything but * followed by / */
        Parameters:
        css - CSS-String as an array of code-points.
        sPos - The array-index where the tokenizer is to consume its next token
        Returns:
        TRUE if and only if the next token in the array is a comment

      • consume

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        protected static void consume​
            (int[] css,
             ByRef<java.lang.Integer> POS,
             java.util.function.Consumer<CSSToken> returnParsedToken,
             java.util.function.Consumer<TokenizeError> errorEncountered)
        This is a tokenizer method which "consumes" the next Comment-Token from the input Code-Point Array.

        Tokenizer: Comment Consume Method, Pseudo-Code

        Making use of the CSS Parser DOES NOT require any knowledge of how the underlying Pass 1 Tokenizer actually works.

        Below is the CSS Working Group's Comment Pseudo-Code. You may review it if you are at wit's end, and have nothing better to do. There is no need to actually invoke this method yourself, it is here solely so that users may understand how the Tokenization-Stage operates.
        These Parsing Pseudo-Code Instructions and Rail-Road Diagrams have been copied, verbatim, from the CSS-Working-Group Web-Site:
        https://drafts.csswg.org/css-syntax/#consume-comment

        Consume comments

        This section describes how to consume comments from a stream of code points. It returns nothing.

        If the next two input code point are U+002F SOLIDUS (/) followed by a U+002A ASTERISK (*), consume them and all following code points up to and including the first U+002A ASTERISK (*) followed by a U+002F SOLIDUS (/), or up to an EOF code point. Return to the start of this step.

        If the preceding paragraph ended by consuming an EOF code point, this is a parse error.

        Return nothing.