Introduce DefaultHtmlBuilder

obecker · obecker · commit c8e392ee2f9b · 2021-06-19T13:48:01.000+02:00
to have a central and easy to use entry point for configuring the HTML rendering, and to hide the details of FlatHtml and IndentedHtml. Adds static methods in Indenter for easy changing the indent depth. This commits also adds @deprecated annotations to some methods and fields that should be removed in a future version of the library, namely - some static fields of Config - the public visibility of FlatHtml and IndentedHtml
diff --git a/library/src/main/java/j2html/Config.java b/library/src/main/java/j2html/Config.java
@@ -7,14 +7,14 @@
 import j2html.utils.Minifier;
 import j2html.utils.TextEscaper;
 
-import java.util.Collections;
-
 public class Config {
 
     /**
      * Change this to configure text-escaping
      * For example, to disable escaping, do <code>{@code Config.textEscaper = text -> text;}</code>
+     * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withTextEscaper(TextEscaper)}
      */
+    @Deprecated
     public static TextEscaper textEscaper = EscapeUtil::escape;
     /**
      * Change this to configure css-minification.
@@ -29,14 +29,18 @@ public class Config {
     /**
      * Change this to configure enable/disable closing empty tags
      * The default is to NOT close them
+     * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withEmptyTagsClosed(boolean)}
      */
+    @Deprecated
     public static boolean closeEmptyTags = false;
-    private static String FOUR_SPACES = "    ";
+
     /**
      * Change this to configure indentation when rendering formatted html
      * The default is four spaces
+     * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withIndenter(Indenter)}
      */
-    public static Indenter indenter = (level, text) -> String.join("", Collections.nCopies(level, FOUR_SPACES)) + text;
+    @Deprecated
+    public static Indenter indenter = Indenter.defaults();
 
 
     private TextEscaper _textEscaper;
@@ -93,6 +97,10 @@ public Indenter indenter() {
         return _indenter;
     }
 
+    /**
+     * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withTextEscaper(TextEscaper)}
+     */
+    @Deprecated
     public Config withTextEscaper(TextEscaper textEscaper){
         Config copy = new Config(this);
         copy._textEscaper = textEscaper;
@@ -111,12 +119,20 @@ public Config withJsMinifier(Minifier jsMinifier){
         return copy;
     }
 
+    /**
+     * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withEmptyTagsClosed(boolean)}
+     */
+    @Deprecated
     public Config withEmptyTagsClosed(boolean closeEmptyTags){
         Config copy = new Config(this);
         copy._closeEmptyTags = closeEmptyTags;
         return copy;
     }
 
+    /**
+     * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withIndenter(Indenter)}
+     */
+    @Deprecated
     public Config withIndenter(Indenter indenter){
         Config copy = new Config(this);
         copy._indenter = indenter;
@@ -128,7 +144,7 @@ public Config withIndenter(Indenter indenter){
         CSSMin::compressCss,
         JSMin::compressJs,
         false,
-        (level, text) -> String.join("", Collections.nCopies(level, FOUR_SPACES)) + text
+        Indenter.defaults()
     );
 
     public static final Config defaults() {
diff --git a/library/src/main/java/j2html/rendering/DefaultHtmlBuilder.java b/library/src/main/java/j2html/rendering/DefaultHtmlBuilder.java
@@ -0,0 +1,125 @@
+package j2html.rendering;
+
+import j2html.Config;
+import j2html.utils.Indenter;
+import j2html.utils.TextEscaper;
+
+/**
+ * Default entry point for constructing an {@link HtmlBuilder} instance.
+ * Examples:
+ * 
+ * <pre>
+ * HtmlTag html = ...
+ * Appendable out = ...
+ * html.render(DefaultHtmlBuilder.into(out));
+ * </pre>
+ * 
+ * will write the HTML into {@code out} without any line breaks or indentation
+ * using the default settings of {@link Config#defaults()}.
+ * <p>
+ * 
+ * <pre>
+ * html.render(DefaultHtmlBuilder.indented(true).into(out));
+ * </pre>
+ * 
+ * will write the HTML into {@code out} with line breaks and indentation using
+ * the default settings and the indenter {@link Indenter#defaults()}.
+ * <p>
+ * 
+ * <pre>
+ * html.render(DefaultHtmlBuilder.indented(true).withIndenter(Indenter.with("\t")).into(out));
+ * </pre>
+ * 
+ * will use the tab character {@code \t} for indentation.
+ * <p>
+ * A different {@link TextEscaper} can be provided using
+ * {@link #withTextEscaper(TextEscaper)}, a different setting for the closing of
+ * empty tags can be applied with {@link #withEmptyTagsClosed(boolean)}.
+ * <p>
+ * There is also a convenience method {@link #inMemory()} for rendering the HTML
+ * into a String:
+ * 
+ * <pre>
+ * String text = html.render(DefaultHtmlBuilder.with...().inMemory()).toString();
+ * </pre>
+ */
+public class DefaultHtmlBuilder {
+
+    public static <A extends Appendable> HtmlBuilder<A> into(A out) {
+        return new Configurer().into(out);
+    }
+
+    public static HtmlBuilder<StringBuilder> inMemory() {
+        return into(new StringBuilder());
+    }
+
+    public static Configurer indented(boolean indented) {
+        return new Configurer().indented(indented);
+    }
+
+    public static Configurer withEmptyTagsClosed(boolean closeTags) {
+        return new Configurer().withEmptyTagsClosed(closeTags);
+    }
+
+    public static Configurer withTextEscaper(TextEscaper textEscaper) {
+        return new Configurer().withTextEscaper(textEscaper);
+    }
+
+    public static Configurer withIndenter(Indenter indenter) {
+        return new Configurer().withIndenter(indenter);
+    }
+
+    /**
+     * @deprecated will be removed in a future version
+     */
+    @Deprecated
+    public static Configurer withConfig(Config config) {
+        return new Configurer(config);
+    }
+
+    public static class Configurer {
+        private boolean indented;
+        private Config config;
+
+        private Configurer() {
+            this(Config.defaults());
+        }
+
+        private Configurer(Config config) {
+            this.config = config;
+            this.indented = false;
+        }
+
+        @SuppressWarnings("deprecation")
+        public <A extends Appendable> HtmlBuilder<A> into(A out) {
+            return this.indented ? IndentedHtml.into(out, this.config) : FlatHtml.into(out, this.config);
+        }
+
+        public HtmlBuilder<StringBuilder> inMemory() {
+            return into(new StringBuilder());
+        }
+
+        public Configurer indented(boolean indented) {
+            this.indented = indented;
+            return this;
+        }
+
+        @SuppressWarnings("deprecation")
+        public Configurer withEmptyTagsClosed(boolean closeTags) {
+            this.config = this.config.withEmptyTagsClosed(closeTags);
+            return this;
+        }
+
+        @SuppressWarnings("deprecation")
+        public Configurer withTextEscaper(TextEscaper textEscaper) {
+            this.config = this.config.withTextEscaper(textEscaper);
+            return this;
+        }
+
+        @SuppressWarnings("deprecation")
+        public Configurer withIndenter(Indenter indenter) {
+            this.config = this.config.withIndenter(indenter);
+            return this;
+        }
+    }
+}
diff --git a/library/src/main/java/j2html/rendering/FlatHtml.java b/library/src/main/java/j2html/rendering/FlatHtml.java
@@ -9,7 +9,10 @@
  * Composes HTML without any extra line breaks or indentation.
  *
  * @param <T> The type of the Appendable to which HTML will be appended.
+ *
+ * @deprecated in favor of {@link DefaultHtmlBuilder}
  */
+// should be made package private in 2.0
 public class FlatHtml<T extends Appendable> implements HtmlBuilder<T> {
 
     /**
@@ -20,6 +23,7 @@ public class FlatHtml<T extends Appendable> implements HtmlBuilder<T> {
      * @param <T> The type of the Appendable to which HTML will be appended.
      * @return An HtmlBuilder for flat HTML.
      */
+    @Deprecated
     public static final <T extends Appendable> FlatHtml<T> into(T out) {
         return new FlatHtml<>(out, Config.defaults());
     }
@@ -43,6 +47,7 @@ public static final <T extends Appendable> FlatHtml<T> into(T out, Config config
      *
      * @return An HtmlBuilder for flat HTML.
      */
+    @Deprecated
     public static final FlatHtml<StringBuilder> inMemory() {
         return into(new StringBuilder());
     }
@@ -53,6 +58,7 @@ public static final FlatHtml<StringBuilder> inMemory() {
      * @param config The Config which will specify text escapement, tag closing, etc.
      * @return An HtmlBuilder for flat HTML.
      */
+    @Deprecated
     public static final FlatHtml<StringBuilder> inMemory(Config config) {
         return into(new StringBuilder(), config);
     }
diff --git a/library/src/main/java/j2html/rendering/HtmlBuilder.java b/library/src/main/java/j2html/rendering/HtmlBuilder.java
@@ -7,6 +7,9 @@
  * Appendable, and support appending HTML-specific character
  * sequences to that Appendable.
  * <p>
+ * This library provides configurable implementations for flat and
+ * indented HTML, which can be obtained from the {@link DefaultHtmlBuilder}.
+ * <p>
  * Note:  HtmlBuilder extends Appendable for compatibility with
  * previous version of this library.  This extension will probably be
  * removed in the future, so avoid relying on the deprecated methods
diff --git a/library/src/main/java/j2html/rendering/IndentedHtml.java b/library/src/main/java/j2html/rendering/IndentedHtml.java
@@ -12,7 +12,10 @@
  * Composes HTML with lines breaks and indentation between tags and text.
  *
  * @param <T> The type of the Appendable to which HTML will be appended.
+ *
+ * @deprecated in favor of {@link DefaultHtmlBuilder}
  */
+// should be made package private in 2.0
 public class IndentedHtml<T extends Appendable> implements HtmlBuilder<T> {
 
     /**
@@ -23,6 +26,7 @@ public class IndentedHtml<T extends Appendable> implements HtmlBuilder<T> {
      * @param <T> The type of the Appendable to which HTML will be appended.
      * @return An HtmlBuilder for indented HTML.
      */
+    @Deprecated
     public static final <T extends Appendable> IndentedHtml<T> into(T out) {
         return new IndentedHtml<>(out, Config.defaults());
     }
@@ -46,6 +50,7 @@ public static final <T extends Appendable> IndentedHtml<T> into(T out, Config co
      *
      * @return An HtmlBuilder for indented HTML.
      */
+    @Deprecated
     public static final IndentedHtml<StringBuilder> inMemory() {
         return into(new StringBuilder());
     }
@@ -57,6 +62,7 @@ public static final IndentedHtml<StringBuilder> inMemory() {
      * @param config The Config which will specify indentation, text escapement, tag closing, etc.
      * @return An HtmlBuilder for indented HTML.
      */
+    @Deprecated
     public static final IndentedHtml<StringBuilder> inMemory(Config config) {
         return into(new StringBuilder(), config);
     }
diff --git a/library/src/main/java/j2html/tags/ContainerTag.java b/library/src/main/java/j2html/tags/ContainerTag.java
@@ -2,11 +2,9 @@
 
 import j2html.Config;
 import j2html.attributes.Attribute;
-import j2html.rendering.TagBuilder;
-import j2html.rendering.FlatHtml;
+import j2html.rendering.DefaultHtmlBuilder;
 import j2html.rendering.HtmlBuilder;
-import j2html.rendering.IndentedHtml;
-
+import j2html.rendering.TagBuilder;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
@@ -145,9 +143,10 @@ public int getNumChildren() {
      *
      * @return the rendered and formatted string
      */
+    @SuppressWarnings("deprecation")
     public String renderFormatted() {
         try {
-            return render(IndentedHtml.into(new StringBuilder(), Config.global())).toString();
+            return render(DefaultHtmlBuilder.withConfig(Config.global()).indented(true).inMemory()).toString();
         }catch (IOException e) {
             throw new RuntimeException(e.getMessage(), e);
         }
@@ -179,7 +178,7 @@ public <A extends Appendable> A render(HtmlBuilder<A> builder, Object model) thr
     public void renderModel(Appendable writer, Object model) throws IOException {
         HtmlBuilder<?> builder = (writer instanceof HtmlBuilder)
             ? (HtmlBuilder<?>) writer
-            : FlatHtml.into(writer, Config.global());
+            : DefaultHtmlBuilder.withConfig(Config.global()).into(writer);
 
         render(builder, model);
     }
diff --git a/library/src/main/java/j2html/tags/EmptyTag.java b/library/src/main/java/j2html/tags/EmptyTag.java
@@ -2,10 +2,9 @@
 
 import j2html.Config;
 import j2html.attributes.Attribute;
-import j2html.rendering.TagBuilder;
-import j2html.rendering.FlatHtml;
+import j2html.rendering.DefaultHtmlBuilder;
 import j2html.rendering.HtmlBuilder;
-
+import j2html.rendering.TagBuilder;
 import java.io.IOException;
 
 public class EmptyTag<T extends EmptyTag<T>> extends Tag<T> {
@@ -35,7 +34,7 @@ public <A extends Appendable> A render(HtmlBuilder<A> builder, Object model) thr
     public void renderModel(Appendable writer, Object model) throws IOException {
         HtmlBuilder<?> builder = (writer instanceof HtmlBuilder)
             ? (HtmlBuilder<?>) writer
-            : FlatHtml.into(writer, Config.global());
+            : DefaultHtmlBuilder.withConfig(Config.global()).into(writer);
 
         render(builder, model);
     }
diff --git a/library/src/main/java/j2html/tags/Renderable.java b/library/src/main/java/j2html/tags/Renderable.java
@@ -1,9 +1,8 @@
 package j2html.tags;
 
 import j2html.Config;
-import j2html.rendering.FlatHtml;
+import j2html.rendering.DefaultHtmlBuilder;
 import j2html.rendering.HtmlBuilder;
-
 import java.io.IOException;
 import java.io.UncheckedIOException;
 
@@ -42,9 +41,10 @@ default <T extends Appendable> T render(HtmlBuilder<T> builder) throws IOExcepti
      * Create a StringBuilder and use it to render the Renderable and it's
      * children
      */
+    @SuppressWarnings("deprecation")
     default String render() {
         try {
-            return render(FlatHtml.into(new StringBuilder(), Config.global())).toString();
+            return render(DefaultHtmlBuilder.withConfig(Config.global()).inMemory()).toString();
         } catch (IOException e) {
             throw new UncheckedIOException(e);
         }
@@ -60,7 +60,7 @@ default void render(Appendable writer) throws IOException {
         if (writer instanceof HtmlBuilder) {
             render((HtmlBuilder<? extends Appendable>) writer);
         } else {
-            render(FlatHtml.into(writer, Config.global()));
+            render(DefaultHtmlBuilder.withConfig(Config.global()).into(writer));
         }
     }
 
diff --git a/library/src/main/java/j2html/tags/Text.java b/library/src/main/java/j2html/tags/Text.java
@@ -1,9 +1,8 @@
 package j2html.tags;
 
 import j2html.Config;
-import j2html.rendering.FlatHtml;
+import j2html.rendering.DefaultHtmlBuilder;
 import j2html.rendering.HtmlBuilder;
-
 import java.io.IOException;
 
 public class Text extends DomContent {
@@ -25,7 +24,7 @@ public <T extends Appendable> T render(HtmlBuilder<T> builder, Object model) thr
     public void renderModel(Appendable writer, Object model) throws IOException {
         HtmlBuilder<?> builder = (writer instanceof HtmlBuilder)
             ? (HtmlBuilder<?>) writer
-            : FlatHtml.into(writer, Config.global());
+            : DefaultHtmlBuilder.withConfig(Config.global()).into(writer);
 
         render(builder, model);
     }
diff --git a/library/src/main/java/j2html/tags/UnescapedText.java b/library/src/main/java/j2html/tags/UnescapedText.java
diff --git a/library/src/main/java/j2html/utils/Indenter.java b/library/src/main/java/j2html/utils/Indenter.java
diff --git a/library/src/test/java/j2html/rendering/RenderingCompatabilityTest.java b/library/src/test/java/j2html/rendering/RenderingCompatabilityTest.java
diff --git a/library/src/test/java/j2html/tags/TextTest.java b/library/src/test/java/j2html/tags/TextTest.java
