Package com.google.common.css.compiler.ast

Class CssStringNode

  • All Implemented Interfaces:
    Locatable
    public class CssStringNode
extends CssValueNode
    Node corresponding to a string value.

    TODO(user): refactor the encoding/decoding logic out of this class, thereby restoring the architectural integrity of the CssNode type hierarchy; all these classes should be value types with no elaborate behaviors.

    This node represents both a CSS fragment and the abstract value represented by that concrete syntax. For example, the following three declarations mean precisely the same thing in CSS: .warning { content-before: 'warning:'; } .warning { content-before: "warning:"; } .warning { content-before: 'war\06e ing:"; }

    Some clients care about concrete CSS syntax. For high-fidelity roundtrip CSS processing it is necessary to preserve the original author's choice of quote character. On the other hand, some clients care about abstract values. For purposes of machine translation or typeface resolution, we are uninterested in the differences that distinguish the cases shown above; in these applications we would like to deal in terms of the simple Java String warning:.

    Java's Character and String classes represent values in the UTF-16 encoding; some codepoints are represented by surrogate pairs of Character instances. CSS escape sequences are designed without a particular encoding in mind; there are CSS escape sequences that correspond to a single Unicode character and multiple Java Character instances.

    Java's Character repertoire is a strict subset of the codepoints that can be represented in CSS. When decoding CSS escape sequences, this class substitutes the Unicode replacement character for characters that cannot be represented in Java Strings, as permitted by http://www.w3.org/TR/CSS2/syndata.html#characters

    • Field Detail

      • HTML_ESCAPER

        public static final java.util.function.UnaryOperator<java.lang.String> HTML_ESCAPER
        Represents this node's value in CSS syntax that is also safe for inclusion in HTML attribute values and element contents. This is a good choice when you want defense in depth against client code that fails to escape things properly.

      • SHORT_ESCAPER

        public static final java.util.function.Function<java.lang.String,​java.lang.String> SHORT_ESCAPER
        Replaces characters that have no literal representation in CSS with their escape codes. This implementation compromises computational efficiency in order to produce the shortest possible output for each replaced character. This is a good choice for readability.

    • Constructor Detail

      • CssStringNode

        public CssStringNode​(CssStringNode.Type type,
                     SourceCodeLocation location)
        Constructor of a string node.
        Parameters:
        type - CSS provides multiple syntax alternatives for strings; which was used for this term?
        location - The location in source code corresponding to this node

      • CssStringNode

        public CssStringNode​(CssStringNode.Type type,
                     java.lang.String value)
        Constructor of a string node.
        Parameters:
        type - CSS provides multiple syntax alternatives for strings; which was used for this term?
        value - the Java String representation of this string (not its concrete CSS syntax)

      • CssStringNode

        public CssStringNode​(CssStringNode node)
        Copy constructor.

    • Method Detail

      • setConcreteValue

        public java.lang.String setConcreteValue​(java.lang.String concreteValue)
        Specifies the characters that should appear between the quotes when this node is written as CSS, and updates this node's value accordingly.

        For example, the Java method invocation: n.setConcreteValue("hi\\\""); could result in the CSS: p { content-after: "hi\""; } or perhaps p { content-after: 'hi\"'; } , depending on the CssStringNode.Type of n and the CssTree in which it occurs, but it would never result in p { content-after: "hi\000022"; }

      • getConcreteValue

        public java.lang.String getConcreteValue()
        Retrieves the characters that should appear between the quotes when this node is written in concrete CSS syntax.

      • setValue

        public void setValue​(java.lang.String value)
        Establishes a value for this node by conservatively escaping value and delegating to setConcreteValue(java.lang.String) to maintain consistency between the CssValueNode.value and the concreteValue.

        This function stores a normalized representation of the given value; if you want to work in more exact terms, try setConcreteValue(java.lang.String).

        For example, the Java snippet: n.setValue("Senator's Response") could result in the CSS snippet: p { content-before: "Senator's Response"; } or p { content-before: 'Senator\'s Response'; } or p { content-before: 'Senator\27 s Response'; } , depending on the CssStringNode.Type of n and the CssTree in which it occurs and the choice of the CssTreeVisitor that renders the output.

        Note that the value parameter here will normally not begin or end with a quotation mark.

        Overrides:
        setValue in class CssValueNode

      • toString

        public java.lang.String toString()
        Description copied from class: CssValueNode
        Use for debugging only.
        Overrides:
        toString in class CssValueNode
        See Also:
        Object.toString()

      • unescape

        public static java.lang.String unescape​(java.lang.String escaped)
        Determines the canonical Java String representation of a value encoded in CSS syntax.
        Parameters:
        escaped - whatever lies between the quotes (excluding the quotes themselves).

      • escape

        public static java.lang.String escape​(CssStringNode.Type type,
                                      java.util.function.Function<? super java.lang.String,​java.lang.String> discretionaryEscaper,
                                      java.lang.String raw)
        Encodes a CSS term denoting raw. In general, there are multiple representations in CSS of the same value; we allow clients to influence this choice through discretionaryEscaper.
        See Also:
        HTML_ESCAPER, SHORT_ESCAPER

      • toString

        public java.lang.String toString​(java.util.function.Function<? super java.lang.String,​java.lang.String> discretionaryEscaper)
        Generates a CSS snippet representing this node. This may differ in semantically unimportant ways from the snippet from which this node was originally parsed.

        You might reasonably n.setConcreteValue(n.toString(ESC)) because that will not change what you get from n.getValue(). But it is probably an error to write n.setValue(n.toString(ESC)); you can pump the string to unbounded length by putting the latter snippet in the body of a loop.

        Returns:
        a String corresponding to this node's abstract value, but suitable for inclusion in CSS.
        See Also:
        CssValueNode.getValue(), getConcreteValue()