berns 3.3.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8befdd27a627569fd4d81d583c107e97af40e9b8f29423c4178fffa1decb92e9
-  data.tar.gz: e268d19c3fafd596d310fefddcda6e9ca2393f06f668d52c3d92a7d748e41c77
+  metadata.gz: 5cfbcf19e2450ffa23b283ad0bb24717cde0bf6191bd8db538bf2cbb3936f205
+  data.tar.gz: f2639cdade9f1a3ee7b55a66666d23ce9843f5988567d3a630fc7403476825e8
 SHA512:
-  metadata.gz: d14dbff87be26716aa466fab088ac036e25e27e72fd2893c4fb67f02422560c88d8bd2d15c08b176c6c9b4fa706ed3a4098edcfe54af273a43eef5cacd295142
-  data.tar.gz: 34c7b95ee33095ea4e8712e280ad90cfe7d79d983996c72c0c245bb63ee9c10c28150a8bfbc3da0f56236ec5ac7df35f61a11f1f4a5e5f0255c167896e4bae5c
+  metadata.gz: f36bec9a6378fa664cc254a24700c63fc4a44720cfd5aad2b7e882dc6aa6ffa523031ec165270cb50d792c85dbcf0e1c0942d3ad22b64b4ec47ee29572170c03
+  data.tar.gz: a520befecc81e00cb2ae6c4a8b973965ee10cbdca0adb003d49ee6464478302ac97391651412f3945a5e6d92f76eaa2f5b51c5d5ef186a3c463c5b6928de564c

data/README.org

@@ -1,6 +1,7 @@
 * Berns
 
 [[https://badge.fury.io/rb/berns][https://badge.fury.io/rb/berns.svg]]
+[[https://github.com/evanleck/berns/actions/workflows/main.yml][https://github.com/evanleck/berns/actions/workflows/main.yml/badge.svg]]
 
 A utility library for generating HTML strings.
 
@@ -95,10 +96,102 @@ 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 element method,
+void element method, =#element=, and =#void= are available as methods 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
+
+Lastly, the block provided to =Berns::Builder.new= can take both positional and
+keyword arguments.
+
+#+begin_src ruby
+template = Berns::Builder.new do |content, title:|
+  h1 { title }
+  p(class: 'paragraph') { content }
+end
+
+template.call('Some text.', title: 'The title') # =>
+# <h1>
+#   The title
+# </h1>
+# <p>
+#   Some text.
+# </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 +204,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/ext/berns/berns.c

@@ -228,7 +228,7 @@ static char * hash_value_to_attribute(const char *attr, const size_t attrlen, VA
 
   Check_Type(value, T_HASH);
 
-  if (rb_hash_size(value) == 1) {
+  if (RHASH_SIZE(value) == 0) {
     return strdup("");
   }
 
@@ -439,7 +439,7 @@ static VALUE external_to_attribute(RB_UNUSED_VAR(VALUE self), VALUE attr, VALUE
 static VALUE external_to_attributes(RB_UNUSED_VAR(VALUE self), VALUE attributes) {
   Check_Type(attributes, T_HASH);
 
-  if (rb_hash_size(attributes) == 1) {
+  if (RHASH_SIZE(attributes) == 0) {
     return rb_utf8_str_new_cstr("");
   }
 
@@ -453,37 +453,32 @@ static VALUE external_to_attributes(RB_UNUSED_VAR(VALUE self), VALUE attributes)
 }
 
 static char * void_element(const char *tag, size_t tlen, VALUE attributes) {
-  /* T_IMEMO is what we get if an optional argument was not passed. */
-  if (TYPE(attributes) == T_IMEMO) {
-    size_t total = tag_olen + tlen + tag_clen + 1;
-    char *string = malloc(total);
-    char *ptr;
-    char *end = string + total;
+  const char *empty = "";
+  char *attrs = hash_value_to_attribute(empty, 0, attributes);
+  size_t alen = strlen(attrs);
 
-    ptr = stecpy(string, tag_open, end);
-    ptr = stecpy(ptr, tag, end);
-    ptr = stecpy(ptr, tag_close, end);
+  size_t total = tag_olen + tlen + tag_clen + 1;
 
-    return string;
-  } else {
-    const char *empty = "";
-    char *attrs = hash_value_to_attribute(empty, 0, attributes);
+  /* If we have some attributes, add a space and the attributes' length. */
+  if (alen > 0) {
+    total += splen + alen;
+  }
 
-    size_t total = tag_olen + tlen + splen + strlen(attrs) + tag_clen + 1;
-    char *string = malloc(total);
-    char *ptr;
-    char *end = string + total;
+  char *dest = malloc(total);
+  char *ptr = NULL;
+  char *end = dest + total;
 
-    ptr = stecpy(string, tag_open, end);
-    ptr = stecpy(ptr, tag, end);
+  ptr = stecpy(dest, tag_open, end);
+  ptr = stecpy(ptr, tag, end);
+
+  if (alen > 0) {
     ptr = stecpy(ptr, space, end);
     ptr = stecpy(ptr, attrs, end);
-    ptr = stecpy(ptr, tag_close, end);
+  }
 
-    free(attrs);
+  ptr = stecpy(ptr, tag_close, end);
 
-    return string;
-  }
+  return dest;
 }
 
 /*

data/ext/berns/extconf.rb

@@ -9,5 +9,6 @@ append_cflags '-Wstrict-overflow'
 append_cflags '-flto'
 append_cflags '-fno-strict-aliasing'
 append_cflags '-msse4'
+append_cflags '-std=c99'
 
 create_makefile 'berns/berns'