package Torello.CSS;

import Torello.Java.Additional.ByRef;
import java.util.function.Consumer;

/** The root abstract-parent class for all CSSToken Sub-Classes. */
public abstract class CSSToken
    implements CharSequence, java.io.Serializable, Comparable<CharSequence>
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;


    // ********************************************************************************************
    // ********************************************************************************************
    // Public & Final Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * The "Reconstituted Character Data" (re-built from the input Code-Points array) that comprise
     * this {@code CSSToken}.
     */
    public final String str;


    // ********************************************************************************************
    // ********************************************************************************************
    // Private Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    CSSToken(int[] cssCodePoints, int sPos, int ePos)
    { this.str = new String(cssCodePoints, sPos, ePos - sPos); }

    // This is used by Punct, CDO, CDC and Delimiter **ONLY**
    CSSToken(String str)
    { this.str = str; }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.CharSequence
    // ********************************************************************************************
    // ********************************************************************************************


    public final char charAt(int index)
    { return str.charAt(index); }

    public final int length()
    { return str.length(); }

    public final String subSequence(int start, int end)
    { return str.substring(start, end); }

    public final String toString()
    { return str; }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object, java.lang.Comparable
    // ********************************************************************************************
    // ********************************************************************************************


    public final int compareTo(CharSequence other)
    { return str.compareTo(other.toString()); }

    public final boolean equals(Object other)
    {
        if (this == other) return true;

        if (! other.getClass().equals(this.getClass()))return false;

        return ((CSSToken) other).str.equals(this.str);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // User's Constructor: Static "build" Method (and associated Helper-Interfaces)
    // ********************************************************************************************
    // ********************************************************************************************


    /*
    // These Package-Private Methods (for internal use only) are for creating a CSSToken instance
    // using a User-Provided String - RATHER THAN A STRING THAT HAS BEEN EXTRACTED BY THE TOKENIZER
    // This whole process is a little tricky because, generally, a constructor makes a lot more
    // sense to the End-User.
    // 
    // However, there are two major stipulations behind the Java-HTML CSS-Tokenizer:
    // 
    //      * First, as with the Java-HTML HTML-Parser:the sum of all CSSTokens must be identical
    //        to the Origina-File.
    // 
    //      * The tokenizer must implement the CSS Working-Group Website's "Pass-1 CSS-Tokenizer"
    //        EXACTLY, as specified.  Because all of that Web-Site's Algorithm's 'consume' methods
    //        make invocations to each other, using Constructors would make the code next to
    //        unreadable.
    //
    // Futhermore, since it wasn't until JDK-22's release that "Statements before this() and
    // super()" inside of a constructor were even legal, and since this code is currently living in
    // "Java 11" - since the JavaDoc-Upgrader's "Upgrade to JDK-21" is a few more months away - it
    // is simply not possible to avoid "Static-Builder's" rather than constructors.
    //
    // TLDR ==>  Constructor's are usually much easier to read, and explaining things is usually
    //           much more direct.  Howeveer since that isn't possible, static build-methods are
    //           provided instead.
    //
    // Because the Token-Classes in Torello.CSS were all written using the CSS-WG Site, the
    // "consume" methods are all intended to be used by the parser-tokenizer "Main Tokenize Loop".
    //
    // It is some work (but only a few lines) to convert the CSSToken class' "consume" methods into
    // "build" methods that are suitable for an "End-User" to build their own Tokens.
    */

    // Please don't ask...  This cute little thing is not that hard.  It's just a function-pointer
    @FunctionalInterface
    static interface TokenConsumer4
    {
        public void consume(
            final int[]                     css,
            final ByRef<Integer>            POS,
            final Consumer<CSSToken>        returnParsedToken,
            final Consumer<TokenizeError>   errorEncountered
        );
    }

    // Function-Pointer for "consme" methods that take 3-arguments (no error-out), instead of 4
    @FunctionalInterface
    static interface TokenConsumer3
    {
        public void consume(
            final int[]                     css,
            final ByRef<Integer>            POS,
            final Consumer<CSSToken>        returnParsedToken
        );
    }

    // Each Sub-Class has a "Check for Errors" Function-Pointer that throws "TokenizeException"
    @FunctionalInterface
    interface InputChecker { public void check(int[] css); }


    // This Build Method is for CSSToken classes whose consume-method accepts 3 parameters
    //
    // The 'TokenConsumer4' accepts:
    //      int[] css                               ==> The CSS-as-a-String (of Code-Points)
    //      ByRef<Integer> pos                      ==> Pointer to the next location in the array
    //                                                  to be processed.  
    //      Consumer<CSSToken> returnParsedToken    ==> This is the "Convoluted-Way" for returning
    //                                                  the CSS-Token to the "build" method
    //      Consumer<TokenizeError> errorEncountered==> If an error occurs, this is also the
    //                                                  "Convoluted-Way" for returning the error
    //
    // NOTE: These "Convoluted" (Consumer) things are a very simple and straight-foward way to add
    //       newly constructed tokens to the output-vector - FROM THE PERSPECTIVE OF THE TOKENIZE
    //       algorithm.
    //
    // FROM THE PERSPECTIVE OF A "BUILD" METHOD, THEY MAY (PERHAPS) SEEM A LITTLE BACKWARDS.
    // Main Point Being: The individual CSSToken Classes "Consume" method can be used by EITHER the
    // Tokenizer or a User's String input.

    static CSSToken build(
            final String            inputStr,   // The User's Input-String which he-or-she would 
                                                // like to convert into a CSSToken instance
            final InputChecker      inputChecker,
            final TokenConsumer4    tokenConsumer   // "4" ==> css, pos, output, error-output
        )
    {
        if (inputStr.length() == 0) throw new TokenizeException();

        final int[] css = inputStr.codePoints().toArray();

        inputChecker.check(css);

        final ByRef<CSSToken> R = new ByRef<>(null);

        // All this is doing is calling the relevant/pertinent "consume" method (which was passed 
        // by the 'tokenConsumer' function-pointer).  

        tokenConsumer.consume(
            css,
            new ByRef<>(0),
            (CSSToken t) -> R.f = t,
            (TokenizeError te) -> te.throwException()
        );

        // Need to guarantee that the entire String was consumed in the process of tokenizing the
        // input String.  'TokenzeException' has a nicely worded Esception-Message to explain what
        // has occured here.

        if (inputStr.length() != R.f.str.length()) throw new TokenizeException(inputStr, R.f.str);

        return R.f;
    }

    // SAME AS ABOVE - EXCEPT THIS METHOD CAN BE INVOKED BY CSSToken Classes whose "consume" method
    // only acdepts three parameters.  Just to be aware the fourth parameter that is left out is
    // one that accepts "TokenizeError" instances.
    //
    // Many of the CSSToken classes do need to check for input-error.  This is primarily becuase
    // in as-many-cases-as-possible, the tokenizer will check for validity before attempting to
    // invoke a token's "consume" method.

    static CSSToken build(
            final String            inputStr,       // The User's Input-String which he-or-she 
                                                    // would like to convert into a CSSToken
            final InputChecker      inputChecker,
            final TokenConsumer3    tokenConsumer   // "3" ==> css, pos, output
        )
    {
        if (inputStr.length() == 0) throw new TokenizeException();

        final int[] css = inputStr.codePoints().toArray();

        inputChecker.check(css);

        final ByRef<CSSToken> R = new ByRef<>(null);

        tokenConsumer.consume(
            css,
            new ByRef<>(0),
            (CSSToken t) -> R.f = t
        );

        // Need to guarantee that the entire String was consumed in the process of tokenizing the
        // input String.  'TokenzeException' has a nicely worded Esception-Message to explain what
        // has occured here.

        if (inputStr.length() != R.f.str.length()) throw new TokenizeException(inputStr, R.f.str);

        return R.f;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // "is"
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-TOK=AtKeyword>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see AtKeyword#isAtKeyword()
     */
    public boolean isAtKeyword() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=BadStr>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see BadStr#isBadStr()
     */
    public boolean isBadStr() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=BadURL>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see BadURL#isBadURL()
     */
    public boolean isBadURL() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=CDC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see CDC#isCDC()
     */
    public boolean isCDC() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=CDO>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see CDO#isCDO()
     */
    public boolean isCDO() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Comment>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Comment#isComment()
     */
    public boolean isComment() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Delimiter>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Delimiter#isDelimiter()
     */
    public boolean isDelimiter() { return false; }

    /**
     * Checks whether {@code 'this'} instance is a {@code Delimiter} instance.
     * @param c Any Java {@code char}.
     * @return {@code TRUE} if {@code 'this'} is a delimiter containing {@code 'c'}.
     */
    public boolean isDelimiter(char c)
    { return this.isDelimiter() && (((Delimiter) this).c == c); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Dimension>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Dimension#isDimension()
     */
    public boolean isDimension() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Func>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Func#isFunc()
     */
    public boolean isFunc() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Hash>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Hash#isHash()
     */
    public boolean isHash() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Identifier>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Identifier#isIdentifier()
     */
    public boolean isIdentifier() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Num>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Num#isNum()
     */
    public boolean isNum() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Percentage>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Percentage#isPercentage()
     */
    public boolean isPercentage() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Punct>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Punct#isPunct()
     */
    public boolean isPunct() { return false; }

    /**
     * Checks whether {@code 'this'} instance is a punctuation character
     * @param c Any Java {@code char}.
     * @return {@code TRUE} if {@code 'this'} is a punctuation of {@code 'c'}.
     */
    public final boolean isPunct(char c)
    { return isPunct() && (((Punct) this).c == c); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Str>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Str#isStr()
     */
    public boolean isStr() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=UnicodeRange>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see UnicodeRange#isUnicodeRange()
     */
    public boolean isUnicodeRange() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=URLToken>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see URLToken#isURL()
     */
    public boolean isURL() { return false; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Whitespace>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IS_RETURNS>
     * @see Whitespace#isWhitespace()
     */
    public boolean isWhitespace() { return false; }


    // ********************************************************************************************
    // ********************************************************************************************
    // "as"
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-TOK=AtKeyword>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final AtKeyword asAtKeyword() { return AtKeyword.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=BadStr>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final BadStr asBadStr() { return BadStr.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=BadURL>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final BadURL asBadURL() { return BadURL.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=CDC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final CDC asCDC() { return CDC.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=CDO>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final CDO asCDO() { return CDO.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Comment>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Comment asComment() { return Comment.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Delimiter>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Delimiter asDelimiter() { return Delimiter.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Dimension>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Dimension asDimension() { return Dimension.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Func>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Func asFunc() { return Func.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Hash>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Hash asHash() { return Hash.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Identifier>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Identifier asIdentifier() { return Identifier.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Num>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Num asNum() { return Num.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Percentage>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Percentage asPercentage() { return Percentage.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Punct>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Punct asPunct() { return Punct.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Str>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Str asStr() { return Str.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=UnicodeRange>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final UnicodeRange asUnicodeRange() { return UnicodeRange.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=URLToken>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final URLToken asURL() { return URLToken.class.cast(this); }

    /**
     * <EMBED CLASS=defs DATA-TOK=Whitespace>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_AS_RETURNS>
     * @throws <EMBED CLASS='external-html' DATA-FILE-ID=CCST_AS_CCEX>
     */
    public final Whitespace asWhitespace() { return Whitespace.class.cast(this); }


    // ********************************************************************************************
    // ********************************************************************************************
    // "if"
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-TOK=AtKeyword>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see AtKeyword#ifAtKeyword()
     */
    public AtKeyword ifAtKeyword() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=BadStr>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see BadStr#ifBadStr()
     */
    public BadStr ifBadStr() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=BadURL>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see BadURL#ifBadURL()
     */
    public BadURL ifBadURL() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=CDC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see CDC#ifCDC()
     */
    public CDC ifCDC() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=CDO>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see CDO#ifCDO()
     */
    public CDO ifCDO() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Comment>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Comment#ifComment()
     */
    public Comment ifComment() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Delimiter>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Delimiter#ifDelimiter()
     */
    public Delimiter ifDelimiter() { return null; }

    /**
     * This one actually does this cute little dance, and then and goes and makes funny
     * faces at your mother.
     * 
     * @param c The Delimiter Character.
     * 
     * @return {@code TRUE} if and only {@code 'this'} is an instance of {@link Delimiter}, and one
     * whose {@link Delimiter#c} matches parameter {@code 'c'}.
     * 
     * @see Delimiter#isDelimiter()
     */
    public final Delimiter ifDelimiter(char c)
    { return isDelimiter() && (((Delimiter) this).c == c) ? Delimiter.class.cast(this) : null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Dimension>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Dimension#ifDimension()
     */
    public Dimension ifDimension() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Func>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Func#ifFunc()
     */
    public Func ifFunc() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Hash>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Hash#ifHash()
     */
    public Hash ifHash() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Identifier>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Identifier#ifIdentifier()
     */
    public Identifier ifIdentifier() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Num>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Num#ifNum()
     */
    public Num ifNum() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Percentage>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Percentage#ifPercentage()
     */
    public Percentage ifPercentage() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Punct>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Punct#ifPunct()
     */
    public Punct ifPunct() { return null; }

    /**
     * This one actually does this cute little dance, and then and goes and makes funny
     * faces at your mother.
     * 
     * @param c The Punctuation Character.
     * 
     * @return {@code TRUE} if and only {@code 'this'} is an instance of {@link Punct}, and one
     * whose {@link Punct#c c field} matches parameter {@code 'c'}.
     * 
     * @see Punct#isPunct()
     */
    public final Punct ifPunct(char c)
    { return this.isPunct() && (((Punct) this).c == c) ? Punct.class.cast(this) : null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Str>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Str#ifStr()
     */
    public Str ifStr() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=UnicodeRange>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see UnicodeRange#ifUnicodeRange()
     */
    public UnicodeRange ifUnicodeRange() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=URLToken>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see URLToken#ifURL()
     */
    public URLToken ifURL() { return null; }

    /**
     * <EMBED CLASS=defs DATA-TOK=Whitespace>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_DESCRIPTION>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=CSST_IF_RETURNS>
     * @see Whitespace#ifWhitespace()
     */
    public Whitespace ifWhitespace() { return null; }

}