berns 3.2.1 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74e861ab5e3bfb8359f063dc7637b4f9c8f30ed60722b3f6cfec7aaf432915af
-  data.tar.gz: 17e884c022d55c44ad4ff080ec485d82688664529aee4d656b95d1d93a129e31
+  metadata.gz: bcded7fea247763fc7b27807c2c945943e0f08895b117ae086e4041bf1b08371
+  data.tar.gz: 965518819feb3eef689f19b7cc5470a973198b891e00f9d7f8ac7fd5b4620119
 SHA512:
-  metadata.gz: 17166b6a903fba75f3cf3984710735e92206892eec6310bb2144ff5e088694089326426baf2c8e7c1246e681d4887559f01f7364635bfc29006878a908b9912f
-  data.tar.gz: 9472135003033d1fdc6db413e44cf7ab69be6fa947b9e2a452d2bd24f316f0708055d03d6157adf292c5b9644d73dd08cad261c1b4c45588be18b8069e5366e2
+  metadata.gz: f023bfcde5d5b272477d2dd7e7c2d6de430c4ec544d6a10da75f7ff72b5980349d282710796a2ac5c4bede5e72df5456dd733828c7869f3f1231b26314f450e4
+  data.tar.gz: d606bdeed6b199fa467c4f80236d9dab40ef0db13e3105397bbe411caffa71c00274ea5902e1ce3f4764ab915cada0a9574d133905f07e28a348e2e28f9b7cfa

data/LICENSE.txt

@@ -1,21 +1,20 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Taylor Beck
+Copyright © 2021 Taylor Beck and Evan Lecklider
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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,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 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
+
 *** 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,10 +186,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]].

data/ext/berns/berns.c

@@ -64,7 +64,7 @@ static const size_t sllen = 1;
   static VALUE external_##element_name##_element(int argc, VALUE *argv, RB_UNUSED_VAR(VALUE self)) { \
     rb_check_arity(argc, 0, 1); \
     \
-    CONTENT_FROM_BLOCK; \
+    CONTENT_FROM_BLOCK \
     const char *tag = #element_name; \
     char *string = element(tag, strlen(tag), RSTRING_PTR(content), RSTRING_LEN(content), argv[0]); \
     VALUE rstring = rb_utf8_str_new_cstr(string); \
@@ -110,17 +110,24 @@ static VALUE external_sanitize(RB_UNUSED_VAR(VALUE self), VALUE string) {
   char *str = RSTRING_PTR(string);
 
   char dest[slen + 1];
-  int index = 0;
-  int open = 0;
-  int opened = 0;
+
+  unsigned int index = 0;
+  unsigned int open = 0;
+  unsigned int modified = 0;
+  unsigned int entity = 0;
 
   for (unsigned int i = 0; i < slen; i++) {
     if (str[i] == '<') {
       open = 1;
-      opened = 1;
+      modified = 1;
     } else if (str[i] == '>') {
       open = 0;
-    } else if (!open) {
+    } else if (str[i] == '&') {
+      entity = 1;
+      modified = 1;
+    } else if (str[i] == ';') {
+      entity = 0;
+    } else if (!open && !entity) {
       dest[index++] = str[i];
     }
   }
@@ -128,10 +135,10 @@ static VALUE external_sanitize(RB_UNUSED_VAR(VALUE self), VALUE string) {
   dest[index] = '\0';
 
   /*
-   * If a tag was never opened, return the original string, otherwise create a new
-   * string from our destination buffer.
+   * If the string was never modified, return the original string, otherwise
+   * create a new string from our destination buffer.
    */
-  if (opened) {
+  if (modified) {
     return rb_utf8_str_new_cstr(dest);
   } else {
     return string;
@@ -221,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("");
   }
 
@@ -432,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("");
   }
 
@@ -446,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;
+  }
+
+  char *dest = malloc(total);
+  char *ptr = NULL;
+  char *end = dest + total;
 
-    size_t total = tag_olen + tlen + splen + strlen(attrs) + tag_clen + 1;
-    char *string = malloc(total);
-    char *ptr;
-    char *end = string + total;
+  ptr = stecpy(dest, tag_open, end);
+  ptr = stecpy(ptr, tag, end);
 
-    ptr = stecpy(string, 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;
 }
 
 /*
@@ -571,7 +573,7 @@ static VALUE external_element(int argc, VALUE *arguments, RB_UNUSED_VAR(VALUE se
 
   StringValue(tag);
 
-  CONTENT_FROM_BLOCK;
+  CONTENT_FROM_BLOCK
 
   char *string = element(RSTRING_PTR(tag), RSTRING_LEN(tag), RSTRING_PTR(content), RSTRING_LEN(content), attributes);
   VALUE rstring = rb_utf8_str_new_cstr(string);

data/lib/berns/builder.rb

@@ -0,0 +1,59 @@
+# 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
+
+    # Append an arbitrary standard element to the buffer.
+    #
+    # @return [String]
+    def element(*args, **opts, &block)
+      content = Builder.new.instance_exec(*args, **opts, &block) if block
+      @buffer << Berns.element(*args, **opts) { content }
+    end
+
+    # Append an arbitrary void element to the buffer.
+    #
+    # @return [String]
+    def void(*args, **opts)
+      @buffer << Berns.void(*args, **opts)
+    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.2.1'
+  VERSION = '3.5.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,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: berns
 version: !ruby/object:Gem::Version
-  version: 3.2.1
+  version: 3.5.0
 platform: ruby
 authors:
 - Taylor Beck
 - Evan Lecklider
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-06-15 00:00:00.000000000 Z
+date: 2022-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -167,15 +167,17 @@ files:
 - ext/berns/hescape.c
 - ext/berns/hescape.h
 - lib/berns.rb
-- lib/berns/berns.so
+- lib/berns/berns.bundle
+- lib/berns/builder.rb
 - lib/berns/version.rb
 homepage: https://github.com/evanleck/berns
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/evanleck/berns/issues
+  rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/evanleck/berns
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -188,10 +190,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 requirements: []
-rubygems_version: 3.2.15
-signing_key: 
+rubygems_version: 3.3.3
+signing_key:
 specification_version: 4
 summary: A utility library for generating HTML strings.
 test_files: []