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}<br/>
026 * {@link JStacheType#STACHE}</td>
027 * <td>{@code Class<?> modelClass()}</td>
028 * <td>Return the model class (root context class annotated with JStache) that generated
029 * this template.</td>
030 * </tr>
031 * <tr>
032 * <td>{@link JStacheType#JSTACHIO}<br/>
033 * {@link JStacheType#STACHE}</td>
034 * <td>{@code this()}</td>
035 * <td>No arg constructor that will resolve the formatter and escaper based on
036 * configuration.</td>
037 * </tr>
038 * <tr>
039 * <td>{@link JStacheType#JSTACHIO}<br/>
040 * {@link JStacheType#STACHE}</td>
041 * <td>{@code this(Function<@Nullable Object,String> formatter, Function<String,String> escaper)}</td>
042 * <td>Constructor that uses the supplied formatter and escaper for
043 * {@code execute(T model, Appendable appendable)}.</td>
044 * </tr>
045 * <tr>
046 * <td>{@link JStacheType#JSTACHIO}</td>
047 * <td>{@code this(TemplateConfig templateConfig)}</td>
048 * <td>Constructor that configures a JStachio template based on configuration.</td>
049 * </tr>
050 * <tr>
051 * <td>{@link JStacheType#JSTACHIO}<br/>
052 * {@link JStacheType#STACHE}</td>
053 * <td>{@code public static GENERATED_CLASS of()}</td>
054 * <td>Similar to the no arg constructor but reuses a single static singleton.</td>
055 * </tr>
056 * </table>
057 * <br/>
058 * Class that are generated with type {@link JStacheType#JSTACHIO} will implement
059 * {@code io.jstach.jstachio.Template} interface and thus all methods on that interface
060 * (and parent interfaces) will be generated if needed (ie no default method).
061 *
062 * @author agentgt
063 * @see JStacheConfig#type()
064 */
065public enum JStacheType {
066
067        /**
068         * This effectively means not set and to let other {@link JStacheConfig} determine the
069         * setting.
070         */
071        UNSPECIFIED,
072
073        /**
074         * The default code generation which allows reflective access to templates and
075         * requires the jstachio runtime (io.jstach.jstachio).
076         */
077        JSTACHIO,
078        /**
079         * Zero runtime dependency renderers are generated if this is selected. Code will not
080         * have a single reference to JStachio runtime interfaces.
081         * <p>
082         * Because there is no reference to the JStachio runtime the escaper and formatter are
083         * inline implementations that passthrough the result of
084         * <code>Object.toString()</code> directly to the appendable. Just like JStachios
085         * default formatter a <code>null</code> variable will fail fast with a null pointer
086         * exception. <em>If you need different escaping or formatting you will have to
087         * provide your own implementation!</em>
088         * <p>
089         * If all templates in a project are generated this way then you can and ideally
090         * should set:
091         * <ul>
092         * <li>The <code>jstachio-annotation</code> dependency as an optional dependency (e.g.
093         * in Maven {@code <optional>true</optional>})</li>
094         * <li>as well as set in your module-info
095         * <code>requires static io.jstach.jstache</code>.</li>
096         * </ul>
097         * The above will minimize your deployed footprint and downstream dependencies will
098         * not transitively need jstachio. <strong>N.B if you go this route you will not be
099         * able to use jstachio runtime extensions.</strong>
100         *
101         *
102         * @apiNote if this is selected jstachio runtime extensions will not work for the
103         * generated renderers.
104         */
105        STACHE;
106
107}