berns 3.3.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8befdd27a627569fd4d81d583c107e97af40e9b8f29423c4178fffa1decb92e9
-  data.tar.gz: e268d19c3fafd596d310fefddcda6e9ca2393f06f668d52c3d92a7d748e41c77
+  metadata.gz: 844af14032659e36711f21b482d7e07ba1627cdca43045ec1fb30869171ee21a
+  data.tar.gz: 828da05830d2d5c1a516fe51bcc2a5c5c9c346359f9eedde4b3ee5bd60a6bf25
 SHA512:
-  metadata.gz: d14dbff87be26716aa466fab088ac036e25e27e72fd2893c4fb67f02422560c88d8bd2d15c08b176c6c9b4fa706ed3a4098edcfe54af273a43eef5cacd295142
-  data.tar.gz: 34c7b95ee33095ea4e8712e280ad90cfe7d79d983996c72c0c245bb63ee9c10c28150a8bfbc3da0f56236ec5ac7df35f61a11f1f4a5e5f0255c167896e4bae5c
+  metadata.gz: 93e0a7fc35666b0395d338cafc5a7aa9bb8aa3d1467158cdb1fc325640d275b3cfa0033921edfd62f0d6a52cbf8728842b45c31ea4d19552d18ee6440c135b59
+  data.tar.gz: 6bc2ea5f4749e09d8bbc4dacd2fac2981ad66dfdc649cb14f78a50ed21af5705d057228764edf6bdd32e4eb4dc8e848f6a42ffbab157ec9bf78f05c94899be6c

data/README.org

@@ -95,10 +95,84 @@ Note that this is an extremely naive implementation of HTML sanitization that
 literally just looks for "<" and ">" characters and removes the contents between
 them. This should probably only be used on trusted strings.
 
+*** =build { content }=
+
+The =build= method uses =Berns::Builder= to let you create HTML strings using a DSL.
+
+#+begin_src ruby
+Berns.build { h1 { 'Heading' } } # => '<h1>Heading</h1>'
+#+end_src
+
+See below for more on =Berns::Builder=.
+
+*** =Berns::Builder= HTML DSL
+
+Added in version 3.4.0 and heavily inspired by the likes of [[https://github.com/digital-fabric/papercraft][Papercraft]], [[https://github.com/markaby/markaby][Markaby]],
+and [[https://github.com/activeadmin/arbre][Arbre]], the =Berns::Builder= class lets you create HTML strings using a DSL.
+
+#+begin_src ruby
+template = Berns::Builder.new do
+  h1 { 'Heading' }
+  p(class: 'paragraph') do
+    text 'Bare text here.'
+
+    b { 'Bold text here' }
+  end
+end
+#+end_src
+
+Within the block provided to =Berns::Builder.new= every standard and void
+element is available as a method and each time you use one of those methods the
+result is appended to an internal buffer. In addition, the =#text= method can be
+used to append a plain text string to the buffer and that text will be HTML
+escaped, so it's good for untrusted content.
+
+Once initialized, rendering the template to a string can be done with the
+=#call= method and any arguments, positional or keyword, will be passed through
+as-is to the block provided to =#new=.
+
+#+begin_src ruby
+string = template.call # =>
+# <h1>
+#   Heading
+# </h1>
+# <p class='paragraph'>
+#   Bare text here.
+#   <b>
+#     Bold text here.
+#   </b>
+# </p>
+#+end_src
+
+In addition to initializing a new instance of =Berns::Builder=, you can
+construct and render a template to a string all at once with =Berns.build=.
+
+#+begin_src ruby
+Berns.build do
+  h1 { 'Heading' }
+  p(class: 'paragraph') do
+    text 'Bare text here.'
+
+    b { 'Bold text here' }
+  end
+end # =>
+# <h1>
+#   Heading
+# </h1>
+# <p class='paragraph'>
+#   Bare text here.
+#   <b>
+#     Bold text here.
+#   </b>
+# </p>
+#+end_src
+
 *** Standard and void elements
 
 All standard and void HTML elements are defined as methods on Berns, so you can
-create e.g. a link with =Berns.a=. Below is the full list of standard elements.
+create e.g. a link with =Berns.a=. Below is the full list of standard elements
+which are also available in the constant =Berns::STANDARD= as an array of
+symbols.
 
 #+begin_example
 a abbr address article aside audio b bdi bdo blockquote body button
@@ -111,15 +185,33 @@ table tbody td template textarea tfoot th thead time title tr u ul var
 video
 #+end_example
 
-
 Below is the full list of void elements that are defined as singleton methods on
-Berns.
+Berns which are also available in the constant =Berns::VOID= as an array of
+symbols.
 
 #+begin_example
 area base br col embed hr img input link menuitem meta param source track wbr
 #+end_example
 
+** Performance
+
+Berns 3 is about three times faster than the pure Ruby implementation used in
+version 2. See the file [[file:benchmarks/performance.rb][benchmarks/performance.rb]] for the benchmark code.
+
+#+begin_example
+Warming up --------------------------------------
+             element    27.373k i/100ms
+               berns    94.118k i/100ms
+Calculating -------------------------------------
+             element    314.078k (± 4.5%) i/s -      1.588M in   5.065539s
+               berns    935.528k (± 6.1%) i/s -      4.706M in   5.049718s
+
+Comparison:
+               berns:   935527.9 i/s
+             element:   314078.4 i/s - 2.98x  (± 0.00) slower
+#+end_example
+
 ** Trivia
 
-The name "Berns" is taken from the name of [[https://en.wikipedia.org/wiki/HTML#Development][the inventor of HTML]], [[https://en.wikipedia.org/wiki/Tim_Berners-Lee][Sir Tim
-Berners-Lee]].
+The name "Berns" is taken from the name of [[https://en.wikipedia.org/wiki/HTML#Development][the inventor of HTML]],
+[[https://en.wikipedia.org/wiki/Tim_Berners-Lee][Sir Tim Berners-Lee]].

data/lib/berns/builder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require 'berns'
+
+module Berns
+  # An HTML builder DSL using Berns' HTML methods.
+  class Builder
+    def initialize(&block)
+      @block = block
+      @buffer = +''
+    end
+
+    # @return [String]
+    def call(*args, **opts)
+      instance_exec(*args, **opts, &@block)
+      to_s
+    end
+
+    # @return [String]
+    def to_s
+      @buffer.freeze
+    end
+
+    # Append text to the buffer.
+    #
+    # @param string [String]
+    # @return [String]
+    def text(string)
+      @buffer << Berns.escape_html(string.to_s)
+    end
+
+    Berns::STANDARD.each do |meth|
+      define_method(meth) do |*args, **opts, &block|
+        content = Builder.new.instance_exec(*args, **opts, &block) if block
+        @buffer << Berns.send(meth, *args, **opts) { content }
+      end
+    end
+
+    Berns::VOID.each do |meth|
+      define_method(meth) do |*args, **opts|
+        @buffer << Berns.send(meth, *args, **opts)
+      end
+    end
+  end
+end

data/lib/berns/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Berns
-  VERSION = '3.3.1'
+  VERSION = '3.4.0'
 end

data/lib/berns.rb

@@ -1,3 +1,26 @@
 # frozen_string_literal: true
 require 'berns/berns'
 require 'berns/version'
+
+module Berns # :nodoc:
+  autoload :Builder, 'berns/builder'
+
+  STANDARD = %i[
+    a abbr address article aside audio b bdi bdo blockquote body button canvas
+    caption cite code colgroup datalist dd del details dfn dialog div dl dt em
+    fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 head header html i
+    iframe ins kbd label legend li main map mark menu meter nav noscript object
+    ol optgroup option output p picture pre progress q rp rt ruby s samp script
+    section select small span strong style sub summary table tbody td template
+    textarea tfoot th thead time title tr u ul var video
+  ].freeze
+
+  VOID = %i[
+    area base br col embed hr img input link menuitem meta param source track wbr
+  ].freeze
+
+  # @return [String]
+  def self.build(*args, **opts, &block)
+    Builder.new(&block).call(*args, **opts)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: berns
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: 3.4.0
 platform: ruby
 authors:
 - Taylor Beck
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-27 00:00:00.000000000 Z
+date: 2022-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -168,6 +168,7 @@ files:
 - ext/berns/hescape.h
 - lib/berns.rb
 - lib/berns/berns.bundle
+- lib/berns/builder.rb
 - lib/berns/version.rb
 homepage: https://github.com/evanleck/berns
 licenses: