Module io.jstach.jstachio

Package io.jstach.jstachio

Interface Escaper

All Superinterfaces:

Appender, Function<String,String>

public non-sealed interface Escaper
extends Appender, Function<String,String>

An Escaper is an Appender used to escape content such as HTML. A Formatter is usually what will call the Escaper and like a formatter it should be singleton like and expect reuse.

When a template outputs an escaped variable the callstack is as follows:

 formatter --> escaper --> appendable
 

Escapers are also a Function<String,String> to allow compatibility with zero dependency generated code that expects Escapers to be of type Function<String,String>.

If escaping is not needed one can use PlainText.of() which will just pass the strings and primitives downstream without altering them. The default escaper unless in zero dependency mode is provided by Html.of().

For context specific escaping like for example XML attributes consider using a JStacheLambda as the escaper is not passed information where in the template escaping is requested.

Implementing

If performance is not a concern an easier way to create an implementation is to adapt a function by using of(Function).

To implement a custom escaper:

1. Implement this interface or use of(Function).
2. Register the custom escaper. See JStacheContentType.
3. Set JStacheConfig.contentType() to the class that has the JStacheContentType.

Author:

agentgt

See Also:

• JStacheContentType
• PlainText.of()
• Html.of()

API Note

Implementations should be threadsafe and expect reuse!

Method Summary

Modifier and Type	Method	Description
default <A extends Output<E>, E extends Exception> void	append(A a, boolean b)	Escapes the character if it needs escaping.
<A extends Output<E>, E extends Exception> void	append(A a, char c)	Escapes the character if it needs escaping.
default <A extends Output<E>, E extends Exception> void	append(A a, double d)	Escapes the character if it needs escaping.
default <A extends Output<E>, E extends Exception> void	append(A a, int i)	Escapes the character if it needs escaping.
default <A extends Output<E>, E extends Exception> void	append(A a, long l)	Escapes the character if it needs escaping.
default <A extends Output<E>, E extends Exception> void	append(A a, short s)	Escapes the character if it needs escaping.
<A extends Output<E>, E extends Exception> void	append(A a, CharSequence s)	Escapes the characters if it needs it.
<A extends Output<E>, E extends Exception> void	append(A a, CharSequence csq, int start, int end)	Escapes the characters if it needs it.
default String	apply(String t)	Escapes a String by using StringBuilder and calling append(Output, CharSequence).
static Escaper	of(Function<String,String> escapeFunction)	Adapts a function to an Escaper.

Methods inherited from interface java.util.function.Function

andThen, compose

Method Details

apply

default String apply(String t)
              throws UncheckedIOException

Escapes a String by using StringBuilder and calling append(Output, CharSequence).

This method is to make Escaper implementations compatible with zero dependency generated code that expects Escapers to be Function<String,String>.

Specified by:

apply in interface Function<String,String>

Parameters:

t - String to ge escaped.

Returns:

escaped content

Throws:

UncheckedIOException - if the appender or appendable throw an IOException

append

<A extends Output<E>,
E extends Exception> void append(A a,
 CharSequence s)
                                               throws E

Escapes the characters if it needs it. Analogous to Appendable.append(CharSequence).

Specified by:

append in interface Appender

Type Parameters:

A - output type

E - exception type

Parameters:

a - appendable to write to. Always non null.

s - unlike appendable always non null.

Throws:

E - if an error happens while writting to the appendable

append

<A extends Output<E>,
E extends Exception> void append(A a,
 CharSequence csq,
 int start,
 int end)
                                               throws E

Escapes the characters if it needs it. Analogous to Appendable.append(CharSequence, int, int).

Specified by:

append in interface Appender

Type Parameters:

A - output type

E - exception type

Parameters:

a - appendable to write to. Never null.

csq - Unlike appendable never null.

start - start inclusive

end - end exclusive

Throws:

E - if an error happens while writting to the appendable

append

<A extends Output<E>,
E extends Exception> void append(A a,
 char c)
                                               throws E

Escapes the character if it needs escaping. Appends a character to the output.

Specified by:

append in interface Appender

Type Parameters:

A - output type

E - exception type

Parameters:

a - appendable to write to. Never null.

c - character

Throws:

E - if an error happens while writting to the appendable

append

default <A extends Output<E>,
E extends Exception>
void append(A a,
 short s)
     throws E

Escapes the character if it needs escaping. The default implementation will String.valueOf(short) and call append(Output, CharSequence). Appends a short to the output.

Specified by:

append in interface Appender

Type Parameters:

A - output type

E - exception type

Parameters:

a - appendable to write to. Never null.

s - short

Throws:

E - if an error happens while writting to the appendable

append

default <A extends Output<E>,
E extends Exception>
void append(A a,
 int i)
     throws E

Escapes the character if it needs escaping. The default implementation will String.valueOf(int) and call append(Output, CharSequence). Appends an int to the output.

Implementations should override if they want different behavior or able to support appendables that can write the native type.

Specified by:

append in interface Appender

Type Parameters:

A - output type

E - exception type

Parameters:

a - appendable to write to. Never null.

i - int

Throws:

E - if an error happens while writting to the appendable

append

default <A extends Output<E>,
E extends Exception>
void append(A a,
 long l)
     throws E

Escapes the character if it needs escaping. The default implementation will String.valueOf(long) and call append(Output, CharSequence). Appends a long to the output.

Implementations should override if they want different behavior or able to support appendables that can write the native type.

Specified by:

append in interface Appender

Type Parameters:

A - output type

E - exception type

Parameters:

a - appendable to write to. Never null.

l - long

Throws:

E - if an error happens while writting to the appendable

append

default <A extends Output<E>,
E extends Exception>
void append(A a,
 double d)
     throws E

Escapes the character if it needs escaping. The default implementation will String.valueOf(double) and call append(Output, CharSequence). Appends a double to the output.

Implementations should override if they want different behavior or able to support appendables that can write the native type.

Specified by:

append in interface Appender

Type Parameters:

A - output type

E - exception type

Parameters:

a - appendable to write to. Never null.

d - double

Throws:

E - if an error happens while writting to the appendable

append

default <A extends Output<E>,
E extends Exception>
void append(A a,
 boolean b)
     throws E

Escapes the character if it needs escaping. The default implementation will String.valueOf(boolean) and call append(Output, CharSequence). Appends a boolean to the output.

Implementations should override if they want different behavior or able to support appendables that can write the native type.

Specified by:

append in interface Appender

Type Parameters:

A - output type

E - exception type

Parameters:

a - appendable to write to. Never null.

b - boolean

Throws:

E - if an error happens while writting to the appendable

of

static Escaper of(Function<String,String> escapeFunction)

Adapts a function to an Escaper. If the function is already an Escaper then it is simply returned (noop). Thus it is safe to repeatedly call this on an Escaper. If the function is adapted the returned adapted Escaper will convert native types with String.valueOf first and then apply the escape function.

Parameters:

escapeFunction - returned if it is already an escaper

Returns:

adapted Escaper