freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [02/16] freemarker git commit: JavaDoc: Added notes to prevent confusion between square bracket tag syntax and interpolation syntax.
Date Fri, 30 Mar 2018 20:50:30 GMT
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 <ddekany@apache.org>
Authored: Tue Mar 27 23:57:21 2018 +0200
Committer: ddekany <ddekany@apache.org>
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)
      * 


Mime
View raw message