[WIP] updating readme to reflect latest library state (#289)

updating readme to reflect latest library state
bkiers · Feb 2, 2024 · 1f77a76 · 1f77a76
1 parent 445b09b
commit 1f77a76
Show file tree

Hide file tree

Showing 101 changed files with 510 additions and 407 deletions.
diff --git a/README.md b/README.md
diff --git a/src/main/java/liqp/Examples.java b/src/main/java/liqp/Examples.java
@@ -51,7 +51,7 @@ private static void demoCustomStrongFilter() {
         // first register your custom filter
         TemplateParser parser = new TemplateParser.Builder().withFilter(new Filter("b") {
             @Override
-            public Object apply(Object value, TemplateContext context, Object... params) {
+            public Object apply(TemplateContext context, Object value, Object... params) {
                 // create a string from the value
                 String text = super.asString(value, context);
 
@@ -69,7 +69,7 @@ public Object apply(Object value, TemplateContext context, Object... params) {
     private static void demoCustomRepeatFilter() {
         TemplateParser parser = new TemplateParser.Builder().withFilter(new Filter("repeat") {
             @Override
-            public Object apply(Object value, TemplateContext context, Object... params) {
+            public Object apply(TemplateContext context, Object value, Object... params) {
 
                 // check if an optional parameter is provided
                 int times = params.length == 0 ? 1 : super.asNumber(params[0]).intValue();
@@ -96,7 +96,7 @@ public Object apply(Object value, TemplateContext context, Object... params) {
     private static void demoCustomSumFilter() {
         TemplateParser parser = new TemplateParser.Builder().withFilter(new Filter("sum") {
             @Override
-            public Object apply(Object value, TemplateContext context, Object... params) {
+            public Object apply(TemplateContext context, Object value, Object... params) {
 
                 Object[] numbers = super.asArray(value, context);
 
@@ -117,7 +117,7 @@ public Object apply(Object value, TemplateContext context, Object... params) {
 
     private static void customLoopBlock() {
 
-        TemplateParser parser = new TemplateParser.Builder().withInsertion(new Block("loop") {
+        TemplateParser parser = new TemplateParser.Builder().withBlock(new Block("loop") {
             @Override
             public Object render(TemplateContext context, LNode... nodes) {
 
@@ -147,7 +147,7 @@ public static void instanceFilter() {
 
         TemplateParser parser = new TemplateParser.Builder().withFilter(new Filter("sum") {
             @Override
-            public Object apply(Object value, TemplateContext context, Object... params) {
+            public Object apply(TemplateContext context, Object value, Object... params) {
 
                 Object[] numbers = super.asArray(value, context);
 
@@ -181,7 +181,7 @@ public static void demoStrictVariables() {
     }
 
     public static void customRandomTag() {
-        TemplateParser parser = new TemplateParser.Builder().withInsertion(new Tag("rand") {
+        TemplateParser parser = new TemplateParser.Builder().withTag(new Tag("rand") {
             private final Random rand = new Random();
 
             @Override
@@ -199,7 +199,7 @@ public static void customFilter() {
 
         TemplateParser parser = new TemplateParser.Builder().withFilter(new Filter("sum") {
             @Override
-            public Object apply(Object value, TemplateContext context, Object... params) {
+            public Object apply(TemplateContext context, Object value, Object... params) {
 
                 Object[] numbers = super.asArray(value, context);
                 double sum = 0;

diff --git a/src/main/java/liqp/PlainBigDecimal.java b/src/main/java/liqp/PlainBigDecimal.java
@@ -11,6 +11,9 @@
 public final class PlainBigDecimal extends BigDecimal {
     private static final long serialVersionUID = 1L;
 
+    public PlainBigDecimal(BigDecimal val) {
+        super(val.toPlainString());
+    }
     public PlainBigDecimal(String val) {
         super(val);
     }

diff --git a/src/main/java/liqp/TemplateParser.java b/src/main/java/liqp/TemplateParser.java
@@ -5,10 +5,12 @@
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 import liqp.antlr.LocalFSNameResolver;
 import liqp.antlr.NameResolver;
+import liqp.blocks.Block;
 import liqp.filters.Filter;
 import liqp.filters.Filters;
 import liqp.parser.Flavor;
 import liqp.parser.LiquidSupport;
+import liqp.tags.Tag;
 import org.antlr.v4.runtime.CharStream;
 import org.antlr.v4.runtime.CharStreams;
 
@@ -127,7 +129,7 @@ public static class Builder {
 
         private Flavor flavor;
         private boolean stripSpacesAroundTags = false;
-        private boolean stripSingleLine;
+        private boolean stripSingleLine = false;
         private ObjectMapper mapper;
         private List<Insertion> insertions = new ArrayList<>();
         private List<Filter> filters = new ArrayList<>();
@@ -139,7 +141,7 @@ public static class Builder {
 
 
         private boolean strictVariables = false;
-        private boolean showExceptionsFromInclude;
+        private boolean showExceptionsFromInclude = true;
         private EvaluateMode evaluateMode = EvaluateMode.LAZY;
         private Locale locale = DEFAULT_LOCALE;
         private ZoneId defaultTimeZone;
@@ -221,8 +223,13 @@ public Builder withObjectMapper(ObjectMapper mapper) {
             return this;
         }
 
-        public Builder withInsertion(Insertion insertion) {
-            this.insertions.add(insertion);
+        public Builder withBlock(Block block) {
+            this.insertions.add(block);
+            return this;
+        }
+
+        public Builder withTag(Tag tag) {
+            this.insertions.add(tag);
             return this;
         }
 
@@ -319,6 +326,11 @@ public Builder withSnippetsFolderName(String snippetsFolderName) {
             return this;
         }
 
+        public Builder withNameResolver(NameResolver nameResolver) {
+            this.nameResolver = nameResolver;
+            return this;
+        }
+
         public Builder withMaxIterations(int maxIterations) {
             this.limitMaxIterations = maxIterations;
             return this;
@@ -345,10 +357,6 @@ public Builder withErrorMode(ErrorMode errorMode) {
             return this;
         }
 
-        public Builder withNameResolver(NameResolver nameResolver) {
-            this.nameResolver = nameResolver;
-            return this;
-        }
 
         @SuppressWarnings("hiding")
         public TemplateParser build() {
@@ -409,6 +417,9 @@ public TemplateParser build() {
         }
     }
 
+    /**
+     * Private constructor. Use: <code>new TemplateParser.Builder().build()</code> instead.
+     */
     TemplateParser(boolean strictVariables, boolean showExceptionsFromInclude, EvaluateMode evaluateMode,
                    RenderTransformer renderTransformer, Locale locale, ZoneId defaultTimeZone,
                    Consumer<Map<String, Object>> environmentMapConfigurator, ErrorMode errorMode, Flavor flavor, boolean stripSpacesAroundTags, boolean stripSingleLine,
@@ -453,21 +464,21 @@ public Template parse(File file) throws IOException {
     }
 
     public Template parse(String input) {
-        return new Template(this, CharStreams.fromString(input), pwd());
+        return new Template(this, CharStreams.fromString(input), Paths.get(".").toAbsolutePath());
     }
 
     public Template parse(InputStream input) throws IOException {
         Path location = getLocationFromInputStream(input);
-        return new Template(this, CharStreams.fromStream(input), Optional.ofNullable(location).orElseGet(TemplateParser::pwd));
+        return new Template(this, CharStreams.fromStream(input), Optional.ofNullable(location).orElseGet(() -> Paths.get(".").toAbsolutePath()));
     }
 
     public Template parse(Reader reader) throws IOException {
-        return new Template(this, CharStreams.fromReader(reader), pwd());
+        return new Template(this, CharStreams.fromReader(reader), Paths.get(".").toAbsolutePath());
     }
 
     public Template parse(CharStream input) {
         Path location = NameResolver.getLocationFromCharStream(input);
-        return new Template(this, input, Optional.ofNullable(location).orElseGet(TemplateParser::pwd));
+        return new Template(this, input, Optional.ofNullable(location).orElseGet(() -> Paths.get(".").toAbsolutePath()));
     }
 
 
@@ -525,11 +536,4 @@ private Path getLocationFromInputStream(InputStream input) {
             return null;
         }
     }
-
-
-    public static Path pwd() {
-        return Paths.get(".").toAbsolutePath();
-    }
-
-
 }
diff --git a/src/main/java/liqp/filters/Abs.java b/src/main/java/liqp/filters/Abs.java
@@ -1,6 +1,8 @@
 package liqp.filters;
 
 import liqp.PlainBigDecimal;
+import liqp.TemplateContext;
+
 
 public class Abs extends Filter {
 
@@ -22,7 +24,7 @@ public class Abs extends Filter {
       end
      */
     @Override
-    public Object apply(Object value, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         if (super.isInteger(value) || super.canBeInteger(value)) {
             return Math.abs(super.asNumber(value).longValue());

diff --git a/src/main/java/liqp/filters/Absolute_Url.java b/src/main/java/liqp/filters/Absolute_Url.java
@@ -27,7 +27,7 @@ def compute_absolute_url(input)
      */
 
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
         String valAsString = asString(value, context);
         if (isValidAbsoluteUrl(valAsString)) {
             return valAsString;

diff --git a/src/main/java/liqp/filters/Append.java b/src/main/java/liqp/filters/Append.java
@@ -10,7 +10,7 @@ public class Append extends Filter {
      * add one string to another
      */
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         return super.asString(value, context) + super.asString(super.get(0, params), context);
     }

diff --git a/src/main/java/liqp/filters/At_Least.java b/src/main/java/liqp/filters/At_Least.java
@@ -1,9 +1,11 @@
 package liqp.filters;
 
+import liqp.TemplateContext;
+
 public class At_Least extends Filter {
 
     @Override
-    public Object apply(Object value, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         if (params == null || params.length == 0) {
             return value;

diff --git a/src/main/java/liqp/filters/At_Most.java b/src/main/java/liqp/filters/At_Most.java
@@ -1,9 +1,11 @@
 package liqp.filters;
 
+import liqp.TemplateContext;
+
 public class At_Most extends Filter {
 
     @Override
-    public Object apply(Object value, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         if (params == null || params.length == 0) {
             return value;

diff --git a/src/main/java/liqp/filters/Capitalize.java b/src/main/java/liqp/filters/Capitalize.java
@@ -10,7 +10,7 @@ public class Capitalize extends Filter {
      * capitalize words in the input sentence
      */
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         String original = super.asString(value, context);
 

diff --git a/src/main/java/liqp/filters/Ceil.java b/src/main/java/liqp/filters/Ceil.java
@@ -1,9 +1,11 @@
 package liqp.filters;
 
+import liqp.TemplateContext;
+
 public class Ceil extends Filter {
 
     @Override
-    public Object apply(Object value, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         if (!super.isNumber(value)) {
             return value;

diff --git a/src/main/java/liqp/filters/Compact.java b/src/main/java/liqp/filters/Compact.java
@@ -8,7 +8,7 @@
 public class Compact extends Filter {
 
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         if (!super.isArray(value)) {
             return value;

diff --git a/src/main/java/liqp/filters/Concat.java b/src/main/java/liqp/filters/Concat.java
@@ -9,7 +9,7 @@
 public class Concat extends Filter {
 
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         super.checkParams(params, 1);
 

diff --git a/src/main/java/liqp/filters/Date.java b/src/main/java/liqp/filters/Date.java
@@ -28,7 +28,7 @@ protected Date(CustomDateFormatSupport<?> typeSupport) {
 
 
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
         Locale locale = context.getParser().locale;
 
         if (isArray(value) && asArray(value, context).length ==1) {

diff --git a/src/main/java/liqp/filters/Default.java b/src/main/java/liqp/filters/Default.java
@@ -5,7 +5,7 @@
 public class Default extends Filter {
 
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         if (params == null || params.length == 0) {
             return value;

diff --git a/src/main/java/liqp/filters/Divided_By.java b/src/main/java/liqp/filters/Divided_By.java
@@ -1,5 +1,7 @@
 package liqp.filters;
 
+import liqp.TemplateContext;
+
 public class Divided_By extends Filter {
 
     /*
@@ -8,7 +10,7 @@ public class Divided_By extends Filter {
      * division
      */
     @Override
-    public Object apply(Object value, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         if(value == null) {
             value = 0L;

diff --git a/src/main/java/liqp/filters/Downcase.java b/src/main/java/liqp/filters/Downcase.java
@@ -10,7 +10,7 @@ public class Downcase extends Filter {
      * convert a input string to DOWNCASE
      */
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         return super.asString(value, context).toLowerCase();
     }

diff --git a/src/main/java/liqp/filters/Escape.java b/src/main/java/liqp/filters/Escape.java
@@ -10,7 +10,7 @@ public class Escape extends Filter {
      * escape a string
      */
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         String str = super.asString(value, context);
 

diff --git a/src/main/java/liqp/filters/Escape_Once.java b/src/main/java/liqp/filters/Escape_Once.java
@@ -11,7 +11,7 @@ public class Escape_Once extends Filter {
      * existing escaped entities
      */
     @Override
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
         String str = super.asString(value, context);
 

diff --git a/src/main/java/liqp/filters/Filter.java b/src/main/java/liqp/filters/Filter.java
@@ -47,39 +47,17 @@ public String getName() {
         return name;
     }
 
-    /**
-     * Applies the filter on the 'value'.
-     *
-     * @param value
-     *            the string value `AAA` in: `{{ 'AAA' | f:1,2,3 }}`
-     * @param params
-     *            the values [1, 2, 3] in: `{{ 'AAA' | f:1,2,3 }}`
-     *
-     * @deprecated use {@link #apply(Object, TemplateContext, Object...)}
-     * @return the result of the filter.
-     */
-    @Deprecated
-    public Object apply(Object value, Object... params) {
-
-        // Default "no-op" filter.
-        return value;
-    }
-
     /**
      * Applies the filter on the 'value', with the given 'context'.
      *
-     * @param value
-     *            the string value `AAA` in: `{{ 'AAA' | f:1,2,3 }}`
-     * @param context
-     *            the template context.
-     * @param params
-     *            the values [1, 2, 3] in: `{{ 'AAA' | f:1,2,3 }}`
-     *
+     * @param context the template context.
+     * @param value   the string value `AAA` in: `{{ 'AAA' | f:1,2,3 }}`
+     * @param params  the values [1, 2, 3] in: `{{ 'AAA' | f:1,2,3 }}`
      * @return the result of the filter.
      */
-    public Object apply(Object value, TemplateContext context, Object... params) {
+    public Object apply(TemplateContext context, Object value, Object... params) {
 
-        return apply(value, params);
+        return value;
     }
 
     /**