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 * Configure how the paths of templates map to actual source resources.
011 *
012 * Order of path config lookup and precedence is as follows:
013 * <ol>
014 * <li>type annotated with JStache and this annotation.
015 * <li>enclosing class (of type annotated with JStache) with this annotation with inner to
016 * outer order.
017 * <li>package annotated with this annotation.
018 * <li>module annotated with this annotation.
019 * </ol>
020 * After this lookup is done then the lookup is repeated using
021 * {@link JStacheConfig#pathing()} thus using this annotation directly on an element takes
022 * precedence over {@link JStacheConfig}.
023 * <p>
024 * If multiple annotations are found the first one is picked and there is no combining of
025 * settings. See {@link JStacheConfig} for general config resultion.
026 * @author agentgt
027 * @see JStacheConfig
028 */
029@Retention(RetentionPolicy.RUNTIME)
030@Target({ ElementType.MODULE, ElementType.PACKAGE, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
031@Documented
032public @interface JStachePath {
033
034        /**
035         * Will prefix the path. If you are mapping to a directory remember to end the prefix
036         * with a "/".
037         * @return prefix of path by default {@link #UNSPECIFIED} which will resolve to
038         * {@link #DEFAULT_PREFIX} if not set elsewhere.
039         */
040        public String prefix() default UNSPECIFIED;
041
042        /**
043         * Suffix the path. A common use case is to suffix with ".mustache".
044         * @return suffix of path by default is {@link #UNSPECIFIED} which will resolve to
045         * {@link #DEFAULT_SUFFIX} if not set elsewhere.
046         */
047        public String suffix() default UNSPECIFIED;
048
049        /**
050         * The value to mean the suffix and prefix is not set.
051         * @apiNote The value is purposely not a possible valid prefix or suffix and is not
052         * the actual default.
053         */
054        public static final String UNSPECIFIED = "*";
055
056        /**
057         * The default prefix if {@link #UNSPECIFIED}.
058         */
059        public static final String DEFAULT_PREFIX = "";
060
061        /**
062         * The default suffix if {@link #UNSPECIFIED}.
063         */
064        public static final String DEFAULT_SUFFIX = "";
065
066        /**
067         * If a JStache path is empty and template is empty and suffix is unspecified the path
068         * will be generated from the class name and suffixed with this constant.
069         */
070        public static final String AUTO_SUFFIX = ".mustache";
071
072}