berns 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f544945cd9c43afe1ce6d3bdf6e7a3c026b6386925cbe7ac9a6ba36ba228b76
-  data.tar.gz: 21add20e6f88c5c56ba48a5b60d48c80e4f4be0b9b351540345479f2a5f94896
+  metadata.gz: 5f3c43fca25c02a106395d8c33d65c9779968e72884ae5896df28f37da58898e
+  data.tar.gz: 30ac41f9ffe37b4c8eb0cd7f4832592532329a17039a69c5e87dbfcfa7758ede
 SHA512:
-  metadata.gz: 40ac56793d022c1191c775aba8020221e6251b9c9be9f61485bd4e0ad3b90e3b46e2e1f4aa1070a3fadce6026b2f48f4b31da156bdba89930fe7c3d557fff06f
-  data.tar.gz: 1af75731f2ce07e6978653b45f077ff20784d950cecbfce74970185c3c2a487c306187d821fed30edba3f4e920a5a7741c9bd009c584f86c7e1c6a0a3d9272fe
+  metadata.gz: 7ca9b09af7d2762a106a2e4ec36165ba4cc48060adc0747823fe2a8ddefd1742c9a6bc1583a65339d13c0825c4f1232efd4f21845aa54393bfd347c0792d8825
+  data.tar.gz: 8caa05f369f2788d2d61ababb1ad1bf58005f98669a0dbe5c1cab229da195aece455ae3788e7305757cd1c7cd0c909b9f2a37a978deac310bce6bc4bbe0fa7aa

data/.editorconfig

@@ -0,0 +1,20 @@
+# http://EditorConfig.org
+# This is the top most config file.
+root = true
+
+# All files
+[*]
+
+# Unix-style newlines with a newline ending every file
+end_of_line = lf
+insert_final_newline = true
+
+# Character set
+charset = utf-8
+
+# Trim extra whitespace.
+trim_trailing_whitespace = true
+
+# Soft tabs and 2 spaces.
+indent_style = space
+indent_size = 2

data/.github/workflows/main.yml

@@ -0,0 +1,24 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        ruby-version: ['3.0', 2.7, 2.6, 2.5]
+
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        bundler-cache: true
+        ruby-version: ${{ matrix.ruby-version }}
+
+    - name: Run tests & lint
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,58 @@
+# http://rubocop.readthedocs.io
+# https://github.com/bbatsov/rubocop/blob/master/config/enabled.yml
+require:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+  ExtraDetails: true
+  NewCops: enable
+  TargetRubyVersion: 2.5
+
+Layout/ParameterAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/EmptyLineAfterMagicComment:
+  Enabled: false
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/MultilineOperationIndentation:
+  EnforcedStyle: indented
+
+Layout/SpaceInsideStringInterpolation:
+  EnforcedStyle: space
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/Next:
+  MinBodyLength: 8

data/CHANGELOG.org

@@ -0,0 +1,129 @@
+* Berns Changelog
+
+** 3.0.0
+
+Version 3.0 is another mostly API-compatible refactor of Berns, this time in
+blazing fast C! I debated simply calling this version 2.1.0 but because it's a
+complete rewrite it didn't seem right to do a simple point release and there may
+be corner cases that I've not accounted for in this new C-backed version.
+
+Running the same benchmarks as from 2.0 but pitting 2.0 against 3.0 yields some
+great speed improvements, particularly for the =empty= and =simple= cases.
+
+/These benchmarks were performed on a desktop with a AMD Ryzen 5 3600X 6-Core
+Processor running Linux Mint 20.1 and kernel 5.4./
+
+Before:
+
+#+begin_example
+ empty      1.668M (± 0.6%) i/s -      8.356M in   5.011099s
+simple    442.102k (± 1.3%) i/s -      2.214M in   5.008068s
+nested    267.716k (± 0.4%) i/s -      1.357M in   5.068747s
+#+end_example
+
+After:
+
+#+begin_example
+ empty      3.573M (± 1.2%) i/s -     17.881M in   5.005001s
+simple    840.631k (± 0.6%) i/s -      4.253M in   5.059771s
+nested    267.281k (± 0.5%) i/s -      1.347M in   5.037887s
+#+end_example
+
+With both empty and simple attributes we see performance effectively double, and
+with nested attributes performance remains more or less the same.
+
+This is another set of fairly contrived benchmarks, testing a singleton method,
+=void= call, and =element= call against each other.
+
+Before:
+
+#+begin_example
+            br      3.061M (± 0.8%) i/s -     15.613M in   5.100154s
+    void("br")      6.141M (± 1.4%) i/s -     30.990M in   5.047338s
+element("div")      2.789M (± 0.6%) i/s -     14.171M in   5.080626s
+#+end_example
+
+After:
+
+#+begin_example
+            br      8.155M (± 1.0%) i/s -     41.339M in   5.069681s
+    void("br")      9.782M (± 1.5%) i/s -     49.096M in   5.020114s
+element("div")      6.769M (± 1.1%) i/s -     33.983M in   5.021362s
+#+end_example
+
+Lastly, benchmarking =to_attributes= with the following hash as the only
+argument shows about double the performance with 3.0.
+
+#+begin_src ruby
+ATTRS = { this: 'tag', should: 'work', data: { foo: 'bar', bar: { baz: 'foo' } } }.freeze
+#+end_src
+
+Before:
+
+#+begin_example
+to_attributes    228.829k (± 1.3%) i/s -      1.159M in   5.065714s
+#+end_example
+
+After:
+
+#+begin_example
+to_attributes    457.387k (± 1.2%) i/s -      2.305M in   5.041036s
+#+end_example
+
+** 2.0.0
+
+Version 2.0 is a mostly API-compatible refactor of all of the core
+methods that make up Berns. The goal is to improve performance, mostly
+using mutable strings and inlining variables that were otherwise short
+lived.
+
+In addition, the target Ruby version has been raised to 2.5 or later.
+2.4 has reached its end of life.
+
+Running this benchmarking code:
+
+#+begin_src ruby
+Benchmark.ips do |x|
+  x.report('empty') { Berns.element(:a) { 'Link to something' } }
+  x.report('simple') { Berns.element(:a, { href: 'Something', class: 'my-class' }) { 'Link to something' } }
+  x.report('nested') { Berns.element(:a, { href: 'Something', class: 'my-class', data: { something: 'Else' } }) { 'Link to something' } }
+
+  x.compare!
+end
+#+end_src
+
+Before:
+
+#+begin_example
+ empty    993.521k (± 1.7%) i/s -      5.062M in   5.096368s
+simple    340.795k (± 0.4%) i/s -      1.729M in   5.074101s
+nested    215.160k (± 1.0%) i/s -      1.081M in   5.025324s
+#+end_example
+
+After:
+
+#+begin_example
+ empty      1.769M (± 1.9%) i/s -      9.012M in   5.094973s
+simple    441.020k (± 1.0%) i/s -      2.233M in   5.063326s
+nested    280.255k (± 3.0%) i/s -      1.400M in   5.001009s
+#+end_example
+
+With empty attributes we see ~ 100% increase in iterations per second,
+with simple attributes we see ~ 30% increase in the same, and with
+nested attributes we see ~ 30% increase as well.
+
+** 1.3.0
+
+With version 1.3, nested HTML attributes can be created with nil keys
+and boolean values to produce e.g. "data-foo data-foo-bar='whatever'"
+from =data: { foo: { nil => true, bar: 'whatever' } }=
+
+** 1.2.0 - 1.2.2
+
+Starting with version 1.2, Berns will now HTML-escape all attribute
+values using =CGI.escapeHTML=. This should prevent attribute values from
+escaping themselves and injecting HTML into the DOM.
+
+** 1.1.0
+
+- Add =#sanitize= method.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in berns.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Taylor Beck
+
+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 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

@@ -0,0 +1,117 @@
+* Berns
+
+[[https://badge.fury.io/rb/berns.svg]]
+
+A utility library for generating HTML strings.
+
+** Installation
+
+Add this line to your application's Gemfile:
+
+#+begin_src ruby
+gem 'berns'
+#+end_src
+
+And then execute:
+
+#+begin_src sh
+bundle
+#+end_src
+
+Or install it yourself as:
+
+#+begin_src sh
+gem install berns
+#+end_src
+
+** Usage
+
+All standard and void HTML elements are defined as methods on Berns, so you can
+create e.g. a link with =Berns.a=. In addition, there are methods to sanitize
+strings i.e. remove HTML from them, convert hashes into a string of HTML
+attributes, and more.
+
+*** =void(tag, attributes)=
+
+The =void= method generates a void HTML element i.e. one without any content. It
+takes either a symbol or a string and an optional hash of HTML attributes.
+
+#+begin_src ruby
+Berns.void('br') # => '<br>'
+Berns.void('br', class: 'br-class') # => '<br class="br-class">'
+#+end_src
+
+*** =element(tag, attributes) { content }=
+
+The =element= method generates a standard HTML element i.e. one with optional
+content. It takes either a symbol or a string, an optional hash of HTML
+attributes, and an optional block of content. If provided, the block should
+return a string.
+
+#+begin_src ruby
+Berns.element('div') # => '<div></div>'
+Berns.element('div', class: 'div-class') # => '<div class="div-class"></div>'
+Berns.element('div', class: 'div-class') { 'Content' } # => '<div class="div-class">Content</div>'
+#+end_src
+
+*** =to_attribute(attribute, value)=
+
+The =to_attribute= method generates an HTML attribute string. If the value is a
+hash then the attribute is treated as a prefix.
+
+#+begin_src ruby
+Berns.to_attribute('class', 'my-class another-class') # => 'class="my-class another-class"'
+Berns.to_attribute('data', { foo: 'bar' }) # => 'data-foo="bar"'
+#+end_src
+
+All attribute values are HTML-escaped using =CGI.escapeHTML=.
+
+*** =to_attributes(attributes)=
+
+The =to_attributes= method generates an HTML attribute string from a hash by
+calling =to_attribute= for each key/value pair.
+
+#+begin_src ruby
+Berns.to_attributes({ 'data' => { foo: 'bar' }, 'class' => 'my-class another-class' }) # => 'data-foo="bar" class="my-class another-class"'
+#+end_src
+
+*** =escape_html(string)=
+
+The =escape_html= method is a passthrough to =CGI.escapeHTML= and does what it
+says on the tin.
+
+#+begin_src ruby
+Berns.escape_html('<"tag"') # => '&lt;&quot;tag&quot;'
+#+end_src
+
+*** =sanitize(string)=
+
+The =sanitize= method strips HTML tags from strings.
+
+#+begin_src ruby
+Berns.sanitize('This <span>should be clean</span>') # => 'This should be clean'
+#+end_src
+
+*** Standard and void elements
+
+As mentioned above, all standard and void HTML elements are defined as singleton
+methods on the Berns module. Below is the full list of standard elements.
+
+#+begin_example
+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
+#+end_example
+
+
+Below is the full list of void elements that are defined as singleton methods on
+Berns.
+
+#+begin_example
+area base br col embed hr img input link menuitem meta param source track wbr
+#+end_example

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+require 'bundler/gem_tasks'
+require 'rake/extensiontask'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+Rake::ExtensionTask.new 'berns' do |ext|
+  ext.lib_dir = 'lib/berns'
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.deps = :compile
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/berns.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+require_relative 'lib/berns/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'berns'
+  spec.version = Berns::VERSION
+  spec.authors = ['Taylor Beck', 'Evan Lecklider']
+  spec.email = ['beck.taylorg@gmail.com', 'evan@lecklider.com']
+
+  spec.summary = 'A utility library for generating HTML strings.'
+  spec.description = 'A utility library for generating HTML strings.'
+  spec.homepage = 'https://github.com/evanleck/berns'
+  spec.license = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.require_paths = ['lib']
+  spec.extensions = %w[ext/berns/extconf.rb]
+
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/evanleck/berns/issues',
+    'source_code_uri' => 'https://github.com/evanleck/berns'
+  }
+
+  spec.add_dependency 'cgi'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rake-compiler'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-minitest'
+  spec.add_development_dependency 'rubocop-performance'
+  spec.add_development_dependency 'rubocop-rake'
+end