001package io.jstach.jstache;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Retention;
006import java.lang.annotation.RetentionPolicy;
007import java.lang.annotation.Target;
008
009/**
010 * Compiler flags that are subject to change. Use at your own risk.
011 * <p>
012 * <strong>Flags maybe added without a major version change unlike the rest of the
013 * API.</strong>
014 * <p>
015 * Order of flag lookup and precedence is as follows:
016 * <ol>
017 * <li>type annotated with JStache and this annotation.
018 * <li>enclosing class (of type annotated with JStache) with this annotation with inner to
019 * outer order.
020 * <li>package annotated with this annotation.
021 * <li>module annotated with this annotation.
022 * </ol>
023 * <em>The flags are NOT combined but rather the first found dictates the flags set or not
024 * (including empty)</em>
025 *
026 * @author agentgt
027 * @apiNote the retention policy is purposely {@link RetentionPolicy#SOURCE} as these
028 * flags only impact compiling of the template.
029 */
030@Retention(RetentionPolicy.SOURCE)
031@Target({ ElementType.MODULE, ElementType.PACKAGE, ElementType.TYPE })
032@Documented
033public @interface JStacheFlags {
034
035        /**
036         * Compiler flags that will be used on for this model.
037         * @return flags
038         */
039        Flag[] flags();
040
041        /**
042         * Compiler flags.
043         *
044         * @apiNote SUBJECT TO CHANGE!
045         * @author agentgt
046         *
047         */
048        public enum Flag {
049
050                /**
051                 * This will produce additional logging that is sent to standard out while the
052                 * annotation processor runs (not during runtime).
053                 */
054                DEBUG,
055                /**
056                 * Per mustache spec dotted names can actually not exist at all for inverted
057                 * sections. This flag disables that so that a compiler failure will happen if the
058                 * fields are missing.
059                 *
060                 * For example assume "missing" is not present on "data" as in data has no field
061                 * or method called "missing".
062                 *
063                 * <pre>
064                 * {{^data.missing}}
065                 * {{/data.missing}}
066                 * </pre>
067                 *
068                 * Normally the above will compile just fine per the spec but this can lead to
069                 * bugs. To not allow what the spec calls "dotted broken chains" you can use this
070                 * flag.
071                 */
072                NO_INVERTED_BROKEN_CHAIN
073
074        }
075
076}