com.google.template.soy.shared.restricted

Class EscapingConventions.CrossLanguageStringXform

java.lang.Object

com.google.template.soy.shared.restricted.EscapingConventions.CrossLanguageStringXform

All Implemented Interfaces:

Escaper

Direct Known Subclasses:

EscapingConventions.EscapeCssString, EscapingConventions.EscapeHtml, EscapingConventions.EscapeHtmlNospace, EscapingConventions.EscapeJsRegex, EscapingConventions.EscapeJsString, EscapingConventions.EscapeUri, EscapingConventions.FilterCssValue, EscapingConventions.FilterHtmlAttributes, EscapingConventions.FilterHtmlElementName, EscapingConventions.FilterImageDataUri, EscapingConventions.FilterNormalizeUri, EscapingConventions.NormalizeHtml, EscapingConventions.NormalizeHtmlNospace, EscapingConventions.NormalizeUri

Enclosing class:

EscapingConventions

public abstract static class EscapingConventions.CrossLanguageStringXform
extends Object
implements Escaper

A transformation on strings that preserves some correctness or safety properties. Subclasses come in three varieties:

Escaper

A mapping from strings in an input language to strings in an output language that preserves the content. E.g. the plain text string 1 < 2 can be escaped to the equivalent HTML string 1 < 2.

Normalizer

A mapping from strings in a language to equivalent strings in the same language but that can be more easily embedded in another language. E.g. the URI http://www.google.com/search?q=O'Reilly is equivalent to http://www.google.com/search?q=O%27Reilly but the latter can be safely embedded in a single quoted HTML attribute.

Filter

A mapping from strings in a language to the same value or to an innocuous value. E.g. the string h1 might pass an html identifier filter but the string ><script>alert('evil')</script> should not and could be replaced by an innocuous value like zzz.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	CrossLanguageStringXform(Pattern valueFilter, String nonAsciiPrefix)

Method Summary

Modifier and Type	Method and Description
protected abstract com.google.common.collect.ImmutableList<EscapingConventions.Escape>	defineEscapes() Returns the escapes used for this escaper.
Appendable	escape(Appendable out) Returns an Appendable instance which automatically escapes all text appended to it before passing the resulting text to an underlying Appendable.
String	escape(String string) Returns the escaped form of a given literal string.
String	getDirectiveName() The name of the directive associated with this escaping function.
com.google.common.collect.ImmutableList<EscapingConventions.Escape>	getEscapes() The escapes need to translate the input language to the output language.
String	getInnocuousOutput() Returns an innocuous string in this context that can be used when filtering.
List<String>	getLangFunctionNames(EscapingConventions.EscapingLanguage language) The names of existing language builtins or available library functions (such as Google Closure) that implement the escaping convention.
String	getNonAsciiPrefix() An escaping prefix in "%", "\\u", "\\" which specifies how to escape non-ASCII code units not in the sparse mapping.
Pattern	getValueFilter() Null if the escaper accepts all strings as inputs, or otherwise a regular expression that accepts only strings that can be escaped by this escaper.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CrossLanguageStringXform

protected CrossLanguageStringXform(@Nullable
                                   Pattern valueFilter,
                                   @Nullable
                                   String nonAsciiPrefix)

Parameters:

valueFilter - null if the directive accepts all strings as inputs. Otherwise a regular expression that accepts only strings that can be escaped by this directive.

nonAsciiPrefix - An escaping prefix in "%", "\\u", "\\" which specifies how to escape non-ASCII code units not in the sparse mapping. If null, then non-ASCII code units outside the sparse map can appear unescaped.

Method Detail

defineEscapes

protected abstract com.google.common.collect.ImmutableList<EscapingConventions.Escape> defineEscapes()

Returns the escapes used for this escaper.

getDirectiveName

public String getDirectiveName()

The name of the directive associated with this escaping function.

Returns:

E.g. |escapeHtml

getNonAsciiPrefix

@Nullable
public final String getNonAsciiPrefix()

An escaping prefix in "%", "\\u", "\\" which specifies how to escape non-ASCII code units not in the sparse mapping. If null, then non-ASCII code units outside the sparse map can appear unescaped.

getValueFilter

@Nullable
public final Pattern getValueFilter()

Null if the escaper accepts all strings as inputs, or otherwise a regular expression that accepts only strings that can be escaped by this escaper.

getEscapes

public final com.google.common.collect.ImmutableList<EscapingConventions.Escape> getEscapes()

The escapes need to translate the input language to the output language.

getLangFunctionNames

public List<String> getLangFunctionNames(EscapingConventions.EscapingLanguage language)

The names of existing language builtins or available library functions (such as Google Closure) that implement the escaping convention.

Parameters:

language - The language being escaped.

Returns:

null if there is no such function.

getInnocuousOutput

public String getInnocuousOutput()

Returns an innocuous string in this context that can be used when filtering.

escape

public final String escape(String string)

Description copied from interface: Escaper

Returns the escaped form of a given literal string.

Note that this method may treat input characters differently depending on the specific escaper implementation.

• UnicodeEscaper handles UTF-16 correctly, including surrogate character pairs. If the input is badly formed the escaper should throw IllegalArgumentException.
• CharEscaper handles Java characters independently and does not verify the input for well formed characters. A CharEscaper should not be used in situations where input is not guaranteed to be restricted to the Basic Multilingual Plane (BMP).

Specified by:

escape in interface Escaper

Parameters:

string - the literal string to be escaped

Returns:

the escaped form of string

escape

public final Appendable escape(Appendable out)

Description copied from interface: Escaper

Returns an Appendable instance which automatically escapes all text appended to it before passing the resulting text to an underlying Appendable.

Note that the Appendable returned by this method may treat input characters differently depending on the specific escaper implementation.

• UnicodeEscaper handles UTF-16 correctly, including surrogate character pairs. If the input is badly formed the escaper should throw IllegalArgumentException.
• CharEscaper handles Java characters independently and does not verify the input for well formed characters. A CharEscaper should not be used in situations where input is not guaranteed to be restricted to the Basic Multilingual Plane (BMP).

In all implementations the escaped Appendable should throw NullPointerException if given a null CharSequence.

Specified by:

escape in interface Escaper

Parameters:

out - the underlying Appendable to append escaped output to

Returns:

an Appendable which passes text to out after escaping it.