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 * Tag a method to be used as a mustache lambda section.
011 *
012 * Lambda sections look something like: <pre>
013 * {{#context}}
014 * {{#lambda}}body{{/lambda}}
015 * {{/context}}
016 * </pre> Where in the above example a lambda is named "lambda" and optionally has access
017 * to the object called "context" and the raw body passed to the lambda is "body".
018 * <p>
019 * JStachio lambdas just like normal method calls do not have to be directly enclosed on
020 * the context objects but can be on implemented interfaces or inherited and thus models
021 * can be "mixed in" with interfaces to achieve sharing of lambdas. However there is
022 * currently no support for static methods to be used as lambdas.
023 * <p>
024 * JStachio lambdas work in basically two modes for <strong>parameters</strong>:
025 * <ul>
026 * <li><strong>Context aware:</strong> The default. The top of the stack is passed if an
027 * argument is present and is not annotated with {@link Raw}.
028 * <li><strong>Raw:</strong> If a string parameter is annoated with {@link Raw} it will be
029 * passed the contents of the lambda section call. <em>While this mode is the default for
030 * the spec it is not for JStachio!</em>. <em>n.b. the contents may not be valid mustache
031 * as the spec does not define that it has to be.</em>
032 * </ul>
033 * <p>
034 * Similarly JStachio works in two modes for <strong>return types</strong>:
035 * <ul>
036 * <li><strong>Model: </strong> The default. The returned model forms its own isolated
037 * context stack and the contents of the lambda section call are used as an inline
038 * template and rendered against the returned context.
039 * <li><strong>Raw: </strong> If the return type is a {@link String} and the method is
040 * annotated with {@link Raw} the contents of the string are directly written
041 * <em>unescaped</em>.
042 * </ul>
043 * <p>
044 * Due to the static nature of JStachio, JStachio does not support returning dynamic
045 * templates which is the optional lambda spec default if a {@link String} is returned.
046 * <p>
047 * JStachio is very similar to the JMustache model and does not have an analog in
048 * mustache.java. JStachio currently does not support returning closures of
049 * {@code Function<String,String> } like mustache.java but models can be like
050 * {@code Supplier<String>} for that use case.
051 *
052 * @see Raw
053 * @see JStacheInterfaces
054 * @author agentgt
055 *
056 */
057@Retention(RetentionPolicy.RUNTIME)
058@Target(ElementType.METHOD)
059@Documented
060public @interface JStacheLambda {
061
062        /**
063         * The logical name of the lambda. If blank the method name will be used.
064         * @return lambda name
065         */
066        String name() default "";
067
068        /**
069         * Tag a method return type of String or parameter of String to be used as a raw
070         * unprocessed string.
071         * @author agentgt
072         * @see JStacheLambda
073         */
074        @Retention(RetentionPolicy.RUNTIME)
075        @Target({ ElementType.PARAMETER, ElementType.METHOD })
076        @Documented
077        public @interface Raw {
078
079        }
080
081}