001package io.jstach.jstachio;
002
003import io.jstach.jstachio.escapers.PlainText;
004
005/**
006 * A singleton like decorator for appendables that has additional methods for dealing with
007 * native types used to output variables that have been formatted. This interface is
008 * mostly an internal detail for performance and generally direct implementations are
009 * unnecessary.
010 *
011 * <p>
012 * When a template outputs an <strong>escaped</strong> variable the callstack is as
013 * follows:
014 *
015 * <pre>
016 * formatter --&gt; escaper --&gt; appendable
017 * </pre>
018 *
019 * When a template outputs an <strong>unescaped</strong> variable the callstack is as
020 * follows:
021 *
022 * <pre>
023 * formatter --&gt; appender --&gt; appendable
024 * </pre>
025 *
026 * When a template outputs anything else (e.g. HTML markup) it writes directly to the
027 * appendable.
028 *
029 * @apiNote <strong>Important:</strong> <em> The interface while public is currently
030 * sealed. If you would like to see it unsealed to allow control of intercepting unescaped
031 * variable output please file an issue.</em> Unlike an Appendable this class is expected
032 * to be reused so state should be avoided and implementations should be thread safe.
033 * @author agentgt
034 * @see Escaper
035 */
036public sealed interface Appender permits Escaper {
037
038        /**
039         * Analogous to {@link Appendable#append(CharSequence)}.
040         * @param <A> output type
041         * @param <E> exception type
042         * @param a appendable to write to. Always non null.
043         * @param s unlike appendable always non null.
044         * @throws E if an error happens while writting to the appendable
045         * @apiNote Implementations are required to implement this method.
046         */
047        public <A extends Output<E>, E extends Exception> void append(A a, CharSequence s) throws E;
048
049        /**
050         * Analogous to {@link Appendable#append(CharSequence, int, int)}.
051         * @param <A> output type
052         * @param <E> exception type
053         * @param a appendable to write to. Never null.
054         * @param csq Unlike appendable never null.
055         * @param start start inclusive
056         * @param end end exclusive
057         * @throws E if an error happens while writting to the appendable
058         * @apiNote Implementations are required to implement this method.
059         */
060        public <A extends Output<E>, E extends Exception> void append(A a, CharSequence csq, int start, int end) throws E;
061
062        /**
063         * Appends a character to the output.
064         * @param <A> output type
065         * @param <E> exception type
066         * @param a appendable to write to. Never null.
067         * @param c character
068         * @throws E if an error happens while writting to the appendable
069         * @apiNote Implementations are required to implement this method.
070         */
071        public <A extends Output<E>, E extends Exception> void append(A a, char c) throws E;
072
073        /**
074         * Appends a short to the output.
075         * @param <A> output type
076         * @param <E> exception type
077         * @param a appendable to write to. Never null.
078         * @param s short
079         * @throws E if an error happens while writting to the appendable
080         */
081        public <A extends Output<E>, E extends Exception> void append(A a, short s) throws E;
082
083        /**
084         * Appends an int to the output.
085         * <p>
086         * Implementations should override if they want different behavior or able to support
087         * appendables that can write the native type.
088         * @param <A> output type
089         * @param <E> exception type
090         * @param a appendable to write to. Never null.
091         * @param i int
092         * @throws E if an error happens while writting to the appendable
093         */
094        public <A extends Output<E>, E extends Exception> void append(A a, int i) throws E;
095
096        /**
097         * Appends a long to the output.
098         * <p>
099         * Implementations should override if they want different behavior or able to support
100         * appendables that can write the native type.
101         * @param <A> output type
102         * @param <E> exception type
103         * @param a appendable to write to. Never null.
104         * @param l long
105         * @throws E if an error happens while writting to the appendable
106         */
107        public <A extends Output<E>, E extends Exception> void append(A a, long l) throws E;
108
109        /**
110         * Appends a double to the output.
111         * <p>
112         * Implementations should override if they want different behavior or able to support
113         * appendables that can write the native type.
114         * @param <A> output type
115         * @param <E> exception type
116         * @param a appendable to write to. Never null.
117         * @param d double
118         * @throws E if an error happens while writting to the appendable
119         */
120        public <A extends Output<E>, E extends Exception> void append(A a, double d) throws E;
121
122        /**
123         * Appends a boolean to the output.
124         * <p>
125         * Implementations should override if they want different behavior or able to support
126         * appendables that can write the native type.
127         * @param <A> output type
128         * @param <E> exception type
129         * @param a appendable to write to. Never null.
130         * @param b boolean
131         * @throws E if an error happens while writting to the appendable
132         */
133        public <A extends Output<E>, E extends Exception> void append(A a, boolean b) throws E;
134
135        /**
136         * Default appender simply passes the contents unchanged to the Appendable.
137         * @return a passthrough appender
138         */
139        public static Appender defaultAppender() {
140                return PlainText.provider();
141        }
142
143}