Repository: incubator-freemarker Updated Branches: refs/heads/3 4039577ae -> 4d00a845b
Forward-ported from 2.3-gae: JavaDoc: Added notes to prevent confusion between square bracket tag syntax and interpolation syntax. Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/4d00a845 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/4d00a845 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/4d00a845 Branch: refs/heads/3 Commit: 4d00a845bd2cd8ec655ce95187b863b2029b56a7 Parents: 4039577 Author: ddekany <[email protected]> Authored: Tue Mar 27 23:58:01 2018 +0200 Committer: ddekany <[email protected]> Committed: Tue Mar 27 23:58:01 2018 +0200 ---------------------------------------------------------------------- .../freemarker/core/InterpolationSyntax.java | 8 ++++++++ .../core/MutableProcessingConfiguration.java | 15 +++++++++++++-- .../freemarker/core/ParsingConfiguration.java | 17 ++++++++++++----- .../java/org/apache/freemarker/core/TagSyntax.java | 15 +++++++++++++-- 4 files changed, 46 insertions(+), 9 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4d00a845/freemarker-core/src/main/java/org/apache/freemarker/core/InterpolationSyntax.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/InterpolationSyntax.java b/freemarker-core/src/main/java/org/apache/freemarker/core/InterpolationSyntax.java index dc4ce88..7ea5fbe 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/InterpolationSyntax.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/InterpolationSyntax.java @@ -23,6 +23,14 @@ package org.apache.freemarker.core; * Used as the value of the {@link ParsingConfiguration#getInterpolationSyntax()} interpolationSyntax} setting. */ public enum InterpolationSyntax { + + /** <code>${expression}</code> */ DOLLAR, + + /** + * <code>[=expression]</code> instead of <code>${expression}</code>. + * It does <em>not</em> change {@code <#if x>} to {@code [#if x]}; that's square bracket <em>tag</em> syntax + * ({@link TagSyntax#SQUARE_BRACKET}). + */ SQUARE_BRACKET; } http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4d00a845/freemarker-core/src/main/java/org/apache/freemarker/core/MutableProcessingConfiguration.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/MutableProcessingConfiguration.java b/freemarker-core/src/main/java/org/apache/freemarker/core/MutableProcessingConfiguration.java index 2f2db0e..9373a07 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/MutableProcessingConfiguration.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/MutableProcessingConfiguration.java @@ -58,9 +58,9 @@ import org.apache.freemarker.core.templateresolver.OrMatcher; import org.apache.freemarker.core.templateresolver.PathGlobMatcher; import org.apache.freemarker.core.templateresolver.PathRegexMatcher; import org.apache.freemarker.core.templateresolver.impl.DefaultTemplateNameFormat; -import org.apache.freemarker.core.util.TemplateLanguageUtils; import org.apache.freemarker.core.util.GenericParseException; import org.apache.freemarker.core.util.OptInTemplateClassResolver; +import org.apache.freemarker.core.util.TemplateLanguageUtils; import org.apache.freemarker.core.util._ClassUtils; import org.apache.freemarker.core.util._CollectionUtils; import org.apache.freemarker.core.util._KeyValuePair; @@ -1518,7 +1518,18 @@ public abstract class MutableProcessingConfiguration<SelfT extends MutableProces * <li><p>{@code "tagSyntax"}: * See {@link ParsingConfiguration#getTagSyntax()}. * <br>String value: Must be one of - * {@code "autoDetect"}, {@code "squareBracket"}, and {@code "squareBracket"}. + * {@code "autoDetect"}, {@code "squareBracket"}, and {@code "squareBracket"} (like {@code [#if x]}). + * <br>Note that setting the {@code "tagSyntax"} to {@code "squareBracket"} does <em>not</em> change + * <code>${x}</code> to {@code [=...]}; that's <em>interpolation</em> syntax, so use the + * {@code "interpolationSyntax"} setting for that, not this setting.. + * + * <li><p>{@code "interpolationSyntax"}: + * See {@link ParsingConfiguration#getInterpolationSyntax()}. + * <br>String value: Must be one of + * {@code "legacy"}, {@code "dollar"}, and {@code "square_bracket"} (like {@code [=x]}). + * <br>Note that setting the {@code "interpolationSyntax"} to {@code "squareBracket"} does <em>not</em> change + * {@code <#if x>} to {@code [#if x]}; that's <em>tag</em> syntax, so use the + * {@code "tagSyntax"} setting for that, not this setting. * * <li><p>{@code "incompatibleImprovements"}: * See {@link Configuration#getIncompatibleImprovements()}. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4d00a845/freemarker-core/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java b/freemarker-core/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java index abfdf9e..66b237c 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/ParsingConfiguration.java @@ -47,16 +47,20 @@ public interface ParsingConfiguration { /** * Determines the syntax of the template files (angle bracket VS square bracket) - * that has no {@code #ftl} in it. The {@code tagSyntax} - * parameter must be one of: + * that has no {@code #ftl} in it. Don't confuse this with the interpolation syntax + * ({@link #getInterpolationSyntax()}); they are independent. + * + * <p>The {@code tagSyntax} parameter must be one of: * <ul> * <li>{@link TagSyntax#AUTO_DETECT}: - * use the syntax of the first FreeMarker tag (can be anything, like <tt>#list</tt>, + * Use the syntax of the first FreeMarker tag (can be anything, like <tt>#list</tt>, * <tt>#include</tt>, user defined, etc.) * <li>{@link TagSyntax#ANGLE_BRACKET}: - * use the angle bracket syntax (the normal syntax) + * Use the angle bracket tag syntax (the normal syntax), like {@code <#include ...>} * <li>{@link TagSyntax#SQUARE_BRACKET}: - * use the square bracket syntax + * Use the square bracket tag syntax, like {@code [#include ...]}. Note that this does <em>not</em> change + * <code>${x}</code> to {@code [=...]}; that's <em>interpolation</em> syntax, so there the relevant one is + * {@link #getInterpolationSyntax()}. * </ul> * * <p>In FreeMarker 2.3.x {@link TagSyntax#ANGLE_BRACKET} is the @@ -80,6 +84,9 @@ public interface ParsingConfiguration { /** * Determines the interpolation syntax (<code>${x}</code> VS <code>[=x]</code>) of the template files. + * Don't confuse this with the tag syntax ({@link #getTagSyntax()}); they are independent. + * Note that {@link InterpolationSyntax#SQUARE_BRACKET} does <em>not</em> change {@code <#if x>} to + * {@code [#if x]}; that's <em>tag</em> syntax, so there the relevant one is {@link #getTagSyntax()}. */ InterpolationSyntax getInterpolationSyntax(); http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4d00a845/freemarker-core/src/main/java/org/apache/freemarker/core/TagSyntax.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/TagSyntax.java b/freemarker-core/src/main/java/org/apache/freemarker/core/TagSyntax.java index 52a6aec..b841484 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/TagSyntax.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/TagSyntax.java @@ -23,11 +23,22 @@ package org.apache.freemarker.core; * Used as the value of the {@link ParsingConfiguration#getTagSyntax()} tagSyntax} setting. */ public enum TagSyntax { - /** The parser decides between {@link #ANGLE_BRACKET} and {@link #SQUARE_BRACKET} based on the first tag it mets. */ + + /** + * The parser decides between {@link #ANGLE_BRACKET} and {@link #SQUARE_BRACKET} based on the first tag (like + * {@code [#if x]} or {@code <#if x>}) it mets. Note that {@code [=...]} is <em>not</em> a tag, but + * an interpolation, so it's not used for tag syntax auto-detection. + */ // TODO [FM3] Get rid of this, as it's too hard for tooling. AUTO_DETECT, + /** For example {@code <#if x><@foo /></#if>} */ ANGLE_BRACKET, - /** For example {@code [#if x][@foo /][/#if]} */ + + /** + * For example {@code [#if x][@foo /][/#if]}. + * It does <em>not</em> change <code>${x}</code> to {@code [=x]}; that's square bracket <em>interpolation</em> + * syntax ({@link InterpolationSyntax#SQUARE_BRACKET}). + */ SQUARE_BRACKET }
