JavaDoc: Added notes to prevent confusion between square bracket tag syntax and interpolation syntax.
Project: http://git-wip-us.apache.org/repos/asf/freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/freemarker/commit/b7410b92 Tree: http://git-wip-us.apache.org/repos/asf/freemarker/tree/b7410b92 Diff: http://git-wip-us.apache.org/repos/asf/freemarker/diff/b7410b92 Branch: refs/heads/2.3 Commit: b7410b92119bcd2bb0dc9280d242f5872c65cca1 Parents: fe37fe5 Author: ddekany <[email protected]> Authored: Tue Mar 27 23:57:21 2018 +0200 Committer: ddekany <[email protected]> Committed: Tue Mar 27 23:57:21 2018 +0200 ---------------------------------------------------------------------- src/main/java/freemarker/core/Configurable.java | 10 ++++- .../java/freemarker/template/Configuration.java | 44 ++++++++++++++++---- 2 files changed, 45 insertions(+), 9 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/freemarker/blob/b7410b92/src/main/java/freemarker/core/Configurable.java ---------------------------------------------------------------------- diff --git a/src/main/java/freemarker/core/Configurable.java b/src/main/java/freemarker/core/Configurable.java index a2b5d29..3c83e94 100644 --- a/src/main/java/freemarker/core/Configurable.java +++ b/src/main/java/freemarker/core/Configurable.java @@ -2365,12 +2365,18 @@ public class Configurable { * <li><p>{@code "tag_syntax"}: * See {@link Configuration#setTagSyntax(int)}. * <br>String value: Must be one of - * {@code "auto_detect"}, {@code "angle_bracket"}, and {@code "square_bracket"}. + * {@code "auto_detect"}, {@code "angle_bracket"}, and {@code "square_bracket"} (like {@code [#if x]}). + * <br>Note that setting the {@code "tagSyntax"} to {@code "square_bracket"} does <em>not</em> change + * <code>${x}</code> to {@code [=...]}; that's <em>interpolation</em> syntax, so use the + * {@code "interpolation_syntax"} setting for that, not this setting. * * <li><p>{@code "interpolation_syntax"} (since 2.3.28): * See {@link Configuration#setInterpolationSyntax(int)}. * <br>String value: Must be one of - * {@code "legacy"}, {@code "dollar"}, and {@code "square_bracket"}. + * {@code "legacy"}, {@code "dollar"}, and {@code "square_bracket"} (like {@code [=x]}). + * <br>Note that setting the {@code "interpolation_syntax"} to {@code "square_bracket"} does <em>not</em> + * change {@code <#if x>} to {@code [#if x]}; that's <em>tag</em> syntax, so use the + * {@code "tag_syntax"} setting for that, not this setting. * * <li><p>{@code "naming_convention"}: * See {@link Configuration#setNamingConvention(int)}. http://git-wip-us.apache.org/repos/asf/freemarker/blob/b7410b92/src/main/java/freemarker/template/Configuration.java ---------------------------------------------------------------------- diff --git a/src/main/java/freemarker/template/Configuration.java b/src/main/java/freemarker/template/Configuration.java index f0c6a0d..0785d21 100644 --- a/src/main/java/freemarker/template/Configuration.java +++ b/src/main/java/freemarker/template/Configuration.java @@ -376,15 +376,35 @@ public class Configuration extends Configurable implements Cloneable, ParserConf STANDARD_OUTPUT_FORMATS.put(JSONOutputFormat.INSTANCE.getName(), JSONOutputFormat.INSTANCE); } + /** + * The parser decides between {@link #ANGLE_BRACKET_TAG_SYNTAX} and {@link #SQUARE_BRACKET_TAG_SYNTAX} 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. + */ public static final int AUTO_DETECT_TAG_SYNTAX = 0; + + /** For example {@code <#if x><@foo /></#if>} */ public static final int ANGLE_BRACKET_TAG_SYNTAX = 1; + + /** + * 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 #SQUARE_BRACKET_INTERPOLATION_SYNTAX}). + */ public static final int SQUARE_BRACKET_TAG_SYNTAX = 2; /** <code>${expression}</code> and the deprecated <code>#{expression; numFormat}</code> @since 2.3.28 */ public static final int LEGACY_INTERPOLATION_SYNTAX = 20; + /** <code>${expression}</code> only (not <code>#{expression; numFormat}</code>) @since 2.3.28 */ public static final int DOLLAR_INTERPOLATION_SYNTAX = 21; - /** <code>[=expression]</code> @since 2.3.28 */ + + /** + * <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 #SQUARE_BRACKET_TAG_SYNTAX}). + * @since 2.3.28 + */ public static final int SQUARE_BRACKET_INTERPOLATION_SYNTAX = 22; public static final int AUTO_DETECT_NAMING_CONVENTION = 10; @@ -2378,15 +2398,20 @@ public class Configuration extends Configurable implements Cloneable, ParserConf /** * Determines the tag syntax (like {@code <#if x>} VS {@code [#if x]}) of the template files - * that has no {@code #ftl} header to decide that. The {@code tagSyntax} parameter must be one of: + * that has no {@code #ftl} header to decide that. Don't confuse this with the interpolation syntax + * ({@link #setInterpolationSyntax(int)}); they are independent. + * + * <p>The {@code tagSyntax} parameter must be one of: * <ul> * <li>{@link Configuration#AUTO_DETECT_TAG_SYNTAX}: - * 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 Configuration#ANGLE_BRACKET_TAG_SYNTAX}: - * use the angle bracket syntax (the normal syntax) + * Use the angle bracket tag syntax (the normal syntax), like {@code <#include ...>} * <li>{@link Configuration#SQUARE_BRACKET_TAG_SYNTAX}: - * 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 use + * {@link #setInterpolationSyntax(int)} for that. * </ul> * * <p>In FreeMarker 2.3.x {@link Configuration#ANGLE_BRACKET_TAG_SYNTAX} is the @@ -2413,9 +2438,14 @@ public class Configuration extends Configurable implements Cloneable, ParserConf } /** - * Determines the interpolation syntax (like <code>${x}</code> VS <code>[=x]</code>) of the template files. The - * {@code interpolationSyntax} parameter must be one of {@link Configuration#LEGACY_INTERPOLATION_SYNTAX}, + * Determines the interpolation syntax (like <code>${x}</code> VS <code>[=x]</code>) of the template files. Don't + * confuse this with the tag syntax ({@link #setTagSyntax(int)}); they are independent. + * + * <p> + * The {@code interpolationSyntax} parameter must be one of {@link Configuration#LEGACY_INTERPOLATION_SYNTAX}, * {@link Configuration#DOLLAR_INTERPOLATION_SYNTAX}, and {@link Configuration#SQUARE_BRACKET_INTERPOLATION_SYNTAX}. + * Note that {@link Configuration#SQUARE_BRACKET_INTERPOLATION_SYNTAX} does <em>not</em> change {@code <#if x>} to + * {@code [#if x]}; that's <em>tag</em> syntax, so use {@link #setTagSyntax(int)} for that. * * @see #setTagSyntax(int) *
