Allow passing IO to HTML.build (#24)

willhbr · web-flow · commit ebc888f3fc64 · 2026-02-09T11:01:48.000+01:00
diff --git a/spec/html_builder_spec.cr b/spec/html_builder_spec.cr
@@ -3,7 +3,7 @@ require "../src/html/builder"
 
 describe HTML::Builder do
   it "builds html" do
-    str = HTML::Builder.build do
+    str = HTML.build do
       doctype
       html do
         head do
@@ -20,8 +20,18 @@ describe HTML::Builder do
     str.should eq %(<!DOCTYPE html><html><head><title>Crystal Programming Language</title></head><body><a href="http://crystal-lang.org">Crystal rocks!</a><form method="POST"><input name="name"></form></body></html>)
   end
 
+  it "builds html to IO" do
+    io = IO::Memory.new
+    HTML.build(io) do
+      doctype
+      html do
+      end
+    end
+    io.to_s.should eq %(<!DOCTYPE html><html></html>)
+  end
+
   it "builds html with some tag attributes" do
-    str = HTML::Builder.new.build do
+    str = HTML.build do
       a(href: "http://crystal-lang.org", class: "crystal", id: "main") do
         text "Crystal rocks!"
       end
@@ -30,7 +40,7 @@ describe HTML::Builder do
   end
 
   it "builds html with some tag attributes, using a hash" do
-    str = HTML::Builder.new.build do
+    str = HTML.build do
       a(href: "http://crystal-lang.org", class: "crystal", id: "main") do
         text "Crystal rocks!"
       end
@@ -39,7 +49,7 @@ describe HTML::Builder do
   end
 
   it "builds html with some tag attributes, using a named tuple" do
-    str = HTML::Builder.new.build do |builder|
+    str = HTML.build do |builder|
       builder.a({href: "http://crystal-lang.org", class: "crystal", id: "main"}) do
         text "Crystal rocks!"
       end
@@ -48,28 +58,28 @@ describe HTML::Builder do
   end
 
   it "builds html with an provided html string" do
-    str = HTML::Builder.new.build do
+    str = HTML.build do
       html "<section>Crystal rocks!</section>"
     end
     str.should eq %(<section>Crystal rocks!</section>)
   end
 
   it "builds html with a custom tag with attributes" do
-    str = HTML::Builder.new.build do
+    str = HTML.build do
       tag("section", class: "crystal") { text "Crystal rocks!" }
     end
     str.should eq %(<section class="crystal">Crystal rocks!</section>)
   end
 
   it "escapes attribute values" do
-    str = HTML::Builder.new.build do
+    str = HTML.build do
       a(href: "<>") { }
     end
     str.should eq %(<a href="&lt;&gt;"></a>)
   end
 
   it "escapes text" do
-    str = HTML::Builder.new.build do
+    str = HTML.build do
       a { text "<>" }
     end
     str.should eq %(<a>&lt;&gt;</a>)
diff --git a/src/html/builder/builder.cr b/src/html/builder/builder.cr
@@ -18,17 +18,35 @@ require "html"
 struct HTML::Builder
   # Creates a new HTML::Builder, yields with with `with ... yield`
   # and then returns the resulting string.
-  def self.build
-    new.build do |builder|
+  def self.build : String
+    String.build do |io|
+      build(io) do |builder|
+        with builder yield builder
+      end
+    end
+  end
+
+  def self.build(io : IO)
+    new(io).build_impl do |builder|
       with builder yield builder
     end
   end
 
-  def initialize
-    @buffer = String::Builder.new
+  @buffer : IO
+
+  def initialize(@buffer : IO)
+  end
+
+  @[Deprecated("Use HTML.build directly")]
+  def initialize(@buffer = String::Builder.new)
+  end
+
+  protected def build_impl
+    with self yield self
   end
 
-  def build
+  @[Deprecated("Use HTML.build directly")]
+  def build(&block)
     with self yield self
     @buffer.to_s
   end
@@ -179,9 +197,16 @@ end
 
 module HTML
   # Convenience method which invokes `HTML::Builder#build`.
-  def self.build
+  def self.build : String
     HTML::Builder.build do |builder|
       with builder yield builder
     end
   end
+
+  # Convenience method which invokes `HTML::Builder#build`.
+  def self.build(io : IO)
+    HTML::Builder.build(io) do |builder|
+      with builder yield builder
+    end
+  end
 end
