001package io.jstach.jstache;
002
003/**
004 * Tells the annotation processor what kind of code to generate namely whether to generate
005 * full fledged jstachio templates (default {@link JStacheType#JSTACHIO}) or zero
006 * dependency templates ({@link #STACHE}).
007 * <p>
008 * JStachio will guarantee to generate the following methods for this specific major
009 * version (this will only change on major version changes):
010 *
011 * <table border="1">
012 * <caption><strong>Guaranteed Generated Methods</strong></caption>
013 * <tr>
014 * <th>Type</th>
015 * <th>Method</th>
016 * <th>Description</th>
017 * </tr>
018 * <tr>
019 * <td>{@link JStacheType#JSTACHIO}<br/>
020 * {@link JStacheType#STACHE}</td>
021 * <td>{@code <T extends Model> void execute(T model, Appendable appendable)}</td>
022 * <td>Executes model</td>
023 * </tr>
024 * <tr>
025 * <td>{@link JStacheType#JSTACHIO}</td>
026 * <td>{@code <T extends Model> void execute(T model, Appendable appendable, Formatter formatter, Escaper escaper)}</td>
027 * <td>Executes model with supplied formatter and escaper</td>
028 * </tr>
029 * <tr>
030 * <td>{@link JStacheType#JSTACHIO}<br/>
031 * {@link JStacheType#STACHE}</td>
032 * <td>{@code Class<?> modelClass()}</td>
033 * <td>Return the model class (root context class annotated with JStache) that generated
034 * this template.</td>
035 * </tr>
036 * <tr>
037 * <td>{@link JStacheType#JSTACHIO}<br/>
038 * {@link JStacheType#STACHE}</td>
039 * <td>{@code this()}</td>
040 * <td>No arg constructor that will resolve the formatter and escaper based on
041 * configuration.</td>
042 * </tr>
043 * <tr>
044 * <td>{@link JStacheType#JSTACHIO}<br/>
045 * {@link JStacheType#STACHE}</td>
046 * <td>{@code this(Function<@Nullable Object,String> formatter, Function<String,String> escaper)}</td>
047 * <td>Constructor that uses the supplied formatter and escaper for
048 * {@code execute(T model, Appendable appendable)}.</td>
049 * </tr>
050 * <tr>
051 * <td>{@link JStacheType#JSTACHIO}</td>
052 * <td>{@code this(TemplateConfig templateConfig)}</td>
053 * <td>Constructor that configures a JStachio template based on configuration.</td>
054 * </tr>
055 * <tr>
056 * <td>{@link JStacheType#JSTACHIO}<br/>
057 * {@link JStacheType#STACHE}</td>
058 * <td>{@code public static GENERATED_CLASS of()}</td>
059 * <td>Similar to the no arg constructor but reuses a single static singleton.</td>
060 * </tr>
061 * </table>
062 * <br/>
063 * Class that are generated with type {@link JStacheType#JSTACHIO} will implement
064 * {@code io.jstach.jstachio.Template} interface and thus all methods on that interface
065 * (and parent interfaces) will be generated if needed (ie no default method).
066 *
067 * @author agentgt
068 * @see JStacheConfig#type()
069 */
070public enum JStacheType {
071
072        /**
073         * This effectively means not set and to let other {@link JStacheConfig} determine the
074         * setting.
075         */
076        UNSPECIFIED,
077
078        /**
079         * The default code generation which allows reflective access to templates and
080         * requires the jstachio runtime (io.jstach.jstachio).
081         */
082        JSTACHIO,
083        /**
084         * Zero runtime dependency renderers are generated if this is selected. Code will not
085         * have a single reference to JStachio runtime interfaces.
086         * <p>
087         * Because there is no reference to the JStachio runtime the escaper and formatter are
088         * inline implementations that passthrough the result of
089         * <code>Object.toString()</code> directly to the appendable. Just like JStachios
090         * default formatter a <code>null</code> variable will fail fast with a null pointer
091         * exception. <em>If you need different escaping or formatting you will have to
092         * provide your own implementation!</em>
093         * <p>
094         * If all templates in a project are generated this way then you can and ideally
095         * should set:
096         * <ul>
097         * <li>The <code>jstachio-annotation</code> dependency as an optional dependency (e.g.
098         * in Maven {@code <optional>true</optional>})</li>
099         * <li>as well as set in your module-info
100         * <code>requires static io.jstach.jstache</code>.</li>
101         * </ul>
102         * The above will minimize your deployed footprint and downstream dependencies will
103         * not transitively need jstachio. <strong>N.B if you go this route you will not be
104         * able to use jstachio runtime extensions.</strong>
105         *
106         *
107         * @apiNote if this is selected jstachio runtime extensions will not work for the
108         * generated renderers.
109         */
110        STACHE;
111
112}