freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject incubator-freemarker git commit: Forward-ported from 2.3-gae: JavaDoc: Added notes to prevent confusion between square bracket tag syntax and interpolation syntax.
Date Tue, 27 Mar 2018 21:58:06 GMT
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 <ddekany@apache.org>
Authored: Tue Mar 27 23:58:01 2018 +0200
Committer: ddekany <ddekany@apache.org>
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
 }


Mime
View raw message