berns 4.1.2 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9332f5ed53d3722052cc33ff3796a47555a50586e89512df69ac2f314dec592c
-  data.tar.gz: 381ebd539a72cb79925554928cb11503104beae42b3ec5f4566e973ac4647409
+  metadata.gz: d21f3c4cd314834b56c13b9471da34320c996ecb526bcf13ea07728f8bf1d380
+  data.tar.gz: 8626b4f6b721d7f972d4436600d7264ca1e4cc4262af19a386ba95552f8bd944
 SHA512:
-  metadata.gz: 6001d1682311fffcddebb1d6cfefa7d9094386dae315d6d5b2d3a4a36a34ebdb97f9e5721c74b5f7dc4d8bfc1118fbf6c417f7bcc38f79c7158144729fe7909a
-  data.tar.gz: 7fce9c7ca12b3fec44c75902e3724ef6f4d6b11d77855e77864326bb4b1b3d8f53f47b45b99b59b70a37fe6f06199abf79cee317d2f28a0ff7931530f996cf87
+  metadata.gz: 06e239a9dceeeab18d0e5ec5255d6d587d4bfeb9c20ef3cd1605242da54de2b2ad448df8f60dbfb9b33c75ae54c08677cfc9b76c6e3b79f9a073913134a33621
+  data.tar.gz: c4d7991a61b3d2fce79b85bec27253ffefe380cbd7a4495934e8eff1ebec65e2e237e0a3f9e816f89754fd32ddcf819e1b859b88204fb33c1e2cf69029641fc0

data/{README.org → README.md}

@@ -1,117 +1,119 @@
-* Berns
+# 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]]
+[![](https://badge.fury.io/rb/berns.svg)](https://badge.fury.io/rb/berns)
+[![](https://github.com/evanleck/berns/actions/workflows/main.yml/badge.svg)](https://github.com/evanleck/berns/actions/workflows/main.yml)
 
 A utility library for generating HTML strings.
 
-** Installation
+## Installation
 
 Add this line to your application's Gemfile:
 
-#+begin_src ruby
+``` ruby
 gem 'berns'
-#+end_src
+```
 
 And then execute:
 
-#+begin_src sh
+``` sh
 bundle
-#+end_src
+```
 
 Or install it yourself as:
 
-#+begin_src sh
+``` sh
 gem install berns
-#+end_src
+```
 
-** Usage
+## Usage
 
 Note that all return string values will be UTF-8 encoded.
 
-*** =void(tag, attributes)=
+### `void(tag, attributes)`
 
-The =void= method generates a void HTML element i.e. one without any content. It
+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
+``` ruby
 Berns.void('br') # => '<br>'
 Berns.void('br', class: 'br-class') # => '<br class="br-class">'
-#+end_src
+```
 
-*** =element(tag, attributes) { content }=
+### `element(tag, attributes) { content }`
 
-The =element= method generates a standard HTML element i.e. one with optional
+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
+``` 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)=
+### `to_attribute(attribute, value)`
 
-The =to_attribute= method generates an HTML attribute string. If the value is a
+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
+``` 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 [[https://github.com/k0kubun/hescape][k0kubun/hescape]] written by Takashi
-Kokubun.
+All attribute values are HTML-escaped using [k0kubun/hescape](hescape) written
+by Takashi Kokubun.
 
-*** =to_attributes(attributes)=
+### `to_attributes(attributes)`
 
-The =to_attributes= method generates an HTML attribute string from a hash by
-calling =to_attribute= for each key/value pair.
+The `to_attributes` method generates an HTML attribute string from a hash by
+calling `to_attribute` for each key/value pair.
 
-#+begin_src ruby
+``` 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)=
+### `escape_html(string)`
 
-The =escape_html= method escapes HTML entities in strings using [[https://github.com/k0kubun/hescape][k0kubun/hescape]]
-written by Takashi Kokubun. As noted in the hescape repository, it should be the
-same as =CGI.escapeHTML=.
+The `escape_html` method escapes HTML entities in strings using
+[k0kubun/hescape](hescape) written by Takashi Kokubun. As noted in the hescape
+repository, it should be the same as `CGI.escapeHTML`.
 
-#+begin_src ruby
+``` ruby
 Berns.escape_html('<"tag"') # => '&lt;&quot;tag&quot;'
-#+end_src
+```
 
-*** =sanitize(string)=
+### `sanitize(string)`
 
-The =sanitize= method strips HTML tags from strings.
+The `sanitize` method strips HTML tags from strings.
 
-#+begin_src ruby
+``` ruby
 Berns.sanitize('This <span>should be clean</span>') # => 'This should be clean'
-#+end_src
+```
 
 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 }=
+### `build { content }`
 
-The =build= method uses =Berns::Builder= to let you create HTML strings using a DSL.
+The `build` method uses `Berns::Builder` to let you create HTML strings using a
+DSL.
 
-#+begin_src ruby
+``` ruby
 Berns.build { h1 { 'Heading' } } # => '<h1>Heading</h1>'
-#+end_src
+```
 
-See below for more on =Berns::Builder=.
+See below for more on `Berns::Builder`.
 
-*** =Berns::Builder= HTML DSL
+### `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.
+Added in version 3.4.0 and heavily inspired by the likes of
+[Papercraft](papercraft), [Markaby](markaby), and [Arbre](arbre), the
+`Berns::Builder` class lets you create HTML strings using a DSL.
 
-#+begin_src ruby
+``` ruby
 template = Berns::Builder.new do
   h1 { 'Heading' }
   p(class: 'paragraph') do
@@ -120,18 +122,18 @@ template = Berns::Builder.new do
     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
+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 appends HTML escaped text to the buffer and
-=#raw= appends text to the buffer without modification.
+In addition, the `#text` method appends HTML escaped text to the buffer and
+`#raw` appends text to the buffer without modification.
 
-The block provided to =Berns::Builder.new= can take both positional and keyword
+The block provided to `Berns::Builder.new` can take both positional and keyword
 arguments.
 
-#+begin_src ruby
+``` ruby
 template = Berns::Builder.new do |content, title:|
   h1 { title }
   p(class: 'paragraph') { content }
@@ -144,13 +146,13 @@ template.call('Some text.', title: 'The title') # =>
 # <p>
 #   Some text.
 # </p>
-#+end_src
+```
 
-Once initialized, the =#call= method will render the template to a string. Any
+Once initialized, the `#call` method will render the template to a string. Any
 arguments, positional or keyword, are passed through as-is to the block provided
-to =#new=.
+to `#new`.
 
-#+begin_src ruby
+``` ruby
 string = template.call # =>
 # <h1>
 #   Heading
@@ -161,12 +163,12 @@ string = template.call # =>
 #     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=.
+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
+``` ruby
 Berns.build do
   h1 { 'Heading' }
   p(class: 'paragraph') do
@@ -184,43 +186,41 @@ end # =>
 #     Bold text here.
 #   </b>
 # </p>
-#+end_src
+```
 
-
-*** Standard and void elements
+### 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
-which are also available in the constant =Berns::STANDARD= as an array of
+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
-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
+```
+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
+```
 
 Below is the full list of void elements that are defined as singleton methods on
-Berns which are also available in the constant =Berns::VOID= as an array of
+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
+## Performance
 
 Berns 3 was a total rewrite from a pure Ruby implementation to one powered by a
 C extension. That rewrite 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.
+implementation used in version 2. See the file
+[benchmarks/performance.rb](benchmarks/performance.rb) for the benchmark code.
 
-#+begin_example
+``` example
 Warming up --------------------------------------
                 ruby    27.521k i/100ms
                c-ext    74.915k i/100ms
@@ -231,9 +231,17 @@ Calculating -------------------------------------
 Comparison:
                c-ext:   813113.3 i/s
                 ruby:   275913.5 i/s - 2.95x  (± 0.00) slower
-#+end_example
+```
+
+## Trivia
 
-** Trivia
+The name "Berns" is taken from the name of [the inventor of HTML](html), [Sir
+Tim Berners-Lee](tim).
 
-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]].
+<!-- Links -->
+[arbre]: https://github.com/activeadmin/arbre
+[hescape]: https://github.com/k0kubun/hescape
+[html]: https://en.wikipedia.org/wiki/HTML#Development
+[markaby]: https://github.com/markaby/markaby
+[papercraft]: https://github.com/digital-fabric/papercraft
+[tim]: https://en.wikipedia.org/wiki/Tim_Berners-Lee