hom 0.4.0 → 1.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80265a394bf1cecc27755bfcc583dbc81cb3ea51ffcb110fae6a61ecc3d0f0cd
+  data.tar.gz: 9ab3f813474864c3db170c4add2780309a2470f8bc4acca7c6daa2355bd27087
+SHA512:
+  metadata.gz: 1d7d556b5749cd886a0731f39734e32cd34dde6ee8ffc0c07294034d0554c0f9bc2f6c35c51bf1f206b50bd9f03a6c01fae28bab158590f1792782f1bee341d6
+  data.tar.gz: 6e27e6d36d7648c968c8bec6c45a99c263e056945eacab2b4de3538220a40f5ad881e5cf30974e5561c0645044eb3ea9968cda6c2ea0e4ab148e1f1d207206c7

data/CHANGES.md

@@ -0,0 +1,57 @@
+# 1.3.1
+
+* Added metadata to gemspec
+
+# 1.3.0
+
+* HOM::NodeList#join now returns a new node list
+
+* Added plus method to HOM::Element
+
+* Added plus method to HOM::Entity
+
+# 1.2.0
+
+* Added html_safe? methods to HOM::Element and HOM::NodeList for compatibility with [erubis-auto](https://github.com/timcraft/erubis-auto)
+
+# 1.1.0
+
+* Added HOM::NodeList class
+
+# 1.0.0
+
+* Ruby 1.8.7 compatibility
+
+* Removed support for rendering arbitrary objects by calling #html
+
+# 0.4.0
+
+* Deprecated support for rendering arbitrary objects by calling #html
+
+* Added notion of undefined content, changing how elements with nil content are rendered:
+
+  With an element like this: `HOM::Element.new(:h1, {}, nil)`
+
+  Pre v0.4.0 rendering: `<h1>`
+
+  Post v0.4.0 rendering: `<h1></h1>`
+
+# 0.3.0
+
+* Added notion of undefined attribute values, nil is now rendered as an empty value:
+
+  With an element like this: `HOM::Element.new(:input, {:value => nil})`
+
+  Pre v0.3.0 rendering: `<input value>`
+
+  Post v0.3.0 rendering: `<input value="">`
+
+* Removed Element#lookup method
+
+# 0.2.0
+
+* Replaced method missing attribute access with Element#lookup method
+
+# 0.1.0
+
+* First version!

data/LICENSE.txt

@@ -0,0 +1,4 @@
+Copyright (c) 2011-2020 TIMCRAFT
+
+This is an Open Source project licensed under the terms of the LGPLv3 license.
+Please see <http://www.gnu.org/licenses/lgpl-3.0.html> for license text.

data/README.md

@@ -1,19 +1,37 @@
-HOM: A straightforward API for generating HTML
-==============================================
+# hom
 
-Motivation
-----------
+[![Gem Version](https://badge.fury.io/rb/hom.svg)](https://badge.fury.io/rb/hom) [![Build Status](https://api.travis-ci.org/timcraft/hom.svg?branch=master)](https://travis-ci.org/timcraft/hom)
+
+
+A straightforward API for generating HTML.
+
+
+## Motivation
 
 HOM helps you implement HTML presentation logic in your code. Things like
 navigation links, select boxes, sets of checkboxes; anything with behaviour
 that is too complex for your templates.
 
-Usage
------
 
-Build up an object tree using `HOM::Element` objects. The first constuctor
-argument is a symbol representing the tag name. For example, here's how you'd
-represent a line break element:
+## Installation
+
+    $ gem install hom
+
+
+## Quick start
+
+```ruby
+require 'hom'
+
+puts HOM::Element.new(:h1, nil, 'hello world')
+```
+
+
+## Using HOM::Element
+
+Create instances of HOM::Element to represent DOM elements. The first
+constructor argument is a symbol representing the tag name. For example,
+you can represent a line break element like this:
 
 ```ruby
 HOM::Element.new(:br)
@@ -32,8 +50,8 @@ HOM::Element.new(:input, [{type: :text, size: 30}, :disabled])
 ```
 
 The third constructor argument is the inner content, which can be a string,
-another element object, or an array of child items. For example, here's how
-you can represent elements with attributes:
+another element object, or an array of child nodes. For example, here's how
+you can represent various elements with inner content:
 
 ```ruby
 span = HOM::Element.new(:span, nil, '')
@@ -47,16 +65,67 @@ link = HOM::Element.new(:a, {target: :_blank, href: '/'}, image)
 list = HOM::Element.new(:ul, nil, (1..3).map { |n| HOM::Element.new(:li, nil, n) })
 ```
 
-There's also a `HOM::Entity` class which you can use to represent HTML entities;
-integer values for numeric entities and symbol/string values for named entities,
+Calling #to_s on a HOM::Element object will return a string containing the
+generated HTML markup. HOM::Element objects are safe to use directly in Rails
+templates, all escaping is handled automatically.
+
+
+## Using HOM::Entity
+
+Create instances of HOM::Entity to represent HTML entities. Use an integer
+argument for numeric entities and a symbol/string argument for named entities,
 for example:
 
 ```ruby
-HOM::Element.new(:span, nil, HOM::Entity.new(160))
+HOM::Entity.new(160)
+
+HOM::Entity.new(:nbsp)
+```
+
+
+## Using HOM::NodeList
+
+Use HOM::NodeList to group nodes together without having to wrap them in an
+outer element. For example:
+
+```ruby
+HOM::NodeList.new(['This is a ', HOM::Element.new(:strong, nil, 'Contrived'), ' example'])
+```
+
+Calling #to_s on a HOM::NodeList object will return a string containing the
+generated HTML markup. Calling #join will insert separator nodes, a bit like
+Array#join, but returning HTML safe output.
+
+
+## XSS 101
+
+Do you have helper methods that look like this:
 
-HOM::Element.new(:span, nil, HOM::Entity.new(:nbsp))
+```ruby
+def user_name(user)
+  "<strong>#{user.name}</strong>".html_safe
+end
+```
+
+Bzzzt, that's a security vulnerability right there. If you're using Rails
+you should have code that looks like this:
+
+```ruby
+def user_name(user)
+  content_tag(:strong, user.name)
+end
+```
+
+The content_tag helper will automatically escape content not explicitly
+marked as safe. HOM will do very much the same thing, the equivalent helper
+method would look like this:
+
+```ruby
+def user_name(user)
+  HOM::Element.new(:strong, nil, user.name)
+end
 ```
 
-Calling `#to_s` on a `HOM::Element` object will return a string containing
-the generated markup. `HOM::Element` objects are safe to use directly in
-Rails templates, all escaping is handled automatically.
+Moral of the story: building up fragments of HTML using string interpolation
+and concatenation is highly error prone. Solution: use content_tag or HOM to
+safely build your content, and audit your usage of html_safe.

data/hom.gemspec

@@ -1,13 +1,20 @@
 Gem::Specification.new do |s|
   s.name = 'hom'
-  s.version = '0.4.0'
+  s.version = '1.3.1'
+  s.license = 'LGPL-3.0'
   s.platform = Gem::Platform::RUBY
   s.authors = ['Tim Craft']
   s.email = ['mail@timcraft.com']
-  s.homepage = 'http://github.com/timcraft/hom'
+  s.homepage = 'https://github.com/timcraft/hom'
   s.description = 'A straightforward API for generating HTML'
   s.summary = 'See description'
-  s.files = Dir.glob('{lib,spec}/**/*') + %w(Rakefile README.md hom.gemspec)
-  s.add_development_dependency('activesupport', ['>= 3.0.3'])
+  s.files = Dir.glob('lib/**/*.rb') + %w(LICENSE.txt README.md CHANGES.md hom.gemspec)
+  s.required_ruby_version = '>= 1.9.3'
   s.require_path = 'lib'
+  s.metadata = {
+    'homepage' => 'https://github.com/timcraft/hom',
+    'source_code_uri' => 'https://github.com/timcraft/hom',
+    'bug_tracker_uri' => 'https://github.com/timcraft/hom/issues',
+    'changelog_uri' => 'https://github.com/timcraft/hom/blob/main/CHANGES.md'
+  }
 end

data/lib/hom.rb

@@ -25,6 +25,10 @@ module HOM
     def html_safe?
       true
     end
+
+    def +(object)
+      NodeList.new([self, object])
+    end
   end
 
   class Element
@@ -38,9 +42,53 @@ module HOM
       @content != Undefined
     end
 
+    def html_safe?
+      true
+    end
+
+    def to_s
+      Encoding.safe_encode(self)
+    end
+
+    def +(object)
+      NodeList.new([self, object])
+    end
+  end
+
+  class NodeList
+    def initialize(nodes)
+      @nodes = Array(nodes)
+    end
+
+    def html_safe?
+      true
+    end
+
     def to_s
       Encoding.safe_encode(self)
     end
+
+    def to_a
+      @nodes
+    end
+
+    def +(object)
+      self.class.new(@nodes + Array(object))
+    end
+
+    def join(separator)
+      self.class.new(intersperse(separator, @nodes))
+    end
+
+    private
+
+    def intersperse(separator, array)
+      array.inject([]) do |tmp, item|
+        tmp << separator unless tmp.empty?
+        tmp << item
+        tmp
+      end
+    end
   end
 
   class AttributeList
@@ -80,12 +128,10 @@ module HOM
     def self.encode(object)
       if object.is_a?(Array)
         object.map { |item| encode(item) }.join
+      elsif object.is_a?(NodeList)
+        object.to_a.map { |item| encode(item) }.join
       elsif object.is_a?(Element)
         encode_element(object)
-      elsif object.respond_to?(:html) # TODO: REMOVE ME
-        Kernel.warn '[hom] defining #html on custom objects is deprecated, map the objects to elements instead'
-
-        object.html
       elsif object.respond_to?(:html_safe?) && object.html_safe?
         object.to_s
       else

metadata

@@ -1,32 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: hom
 version: !ruby/object:Gem::Version
-  version: 0.4.0
-  prerelease: 
+  version: 1.3.1
 platform: ruby
 authors:
 - Tim Craft
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2012-09-26 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 3.0.3
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 3.0.3
+date: 2020-11-03 00:00:00.000000000 Z
+dependencies: []
 description: A straightforward API for generating HTML
 email:
 - mail@timcraft.com
@@ -34,35 +17,36 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/hom.rb
-- spec/element_spec.rb
-- spec/entity_spec.rb
-- Rakefile
+- CHANGES.md
+- LICENSE.txt
 - README.md
 - hom.gemspec
-homepage: http://github.com/timcraft/hom
-licenses: []
-post_install_message: 
+- lib/hom.rb
+homepage: https://github.com/timcraft/hom
+licenses:
+- LGPL-3.0
+metadata:
+  homepage: https://github.com/timcraft/hom
+  source_code_uri: https://github.com/timcraft/hom
+  bug_tracker_uri: https://github.com/timcraft/hom/issues
+  changelog_uri: https://github.com/timcraft/hom/blob/main/CHANGES.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.24
-signing_key: 
-specification_version: 3
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
 summary: See description
 test_files: []
-has_rdoc: 

data/Rakefile

@@ -1,8 +0,0 @@
-require 'rake/testtask'
-
-task :default => :spec
-
-Rake::TestTask.new(:spec) do |t|
-  t.test_files = FileList['spec/*_spec.rb']
-  t.warning = true
-end

data/spec/element_spec.rb

@@ -1,71 +0,0 @@
-require 'minitest/autorun'
-require 'active_support/core_ext/string/output_safety'
-
-require_relative '../lib/hom'
-
-describe 'Element' do
-  before do
-    @br = HOM::Element.new(:br)
-    @i1 = HOM::Element.new(:input, :disabled)
-    @i2 = HOM::Element.new(:input, {type: :text, size: 30, value: nil})
-    @i3 = HOM::Element.new(:input, [{type: :text, size: 30}, :disabled])
-    @h1 = HOM::Element.new(:h1, nil, '')
-    @h2 = HOM::Element.new(:h2, nil, 'hello world')
-    @h3 = HOM::Element.new(:h3, nil, 'a && b, x > y')
-    @h4 = HOM::Element.new(:h4, nil, 1234567890)
-    @h5 = HOM::Element.new(:h5, nil, HOM::Element.new(:b, nil, 'how bold'))
-    @h6 = HOM::Element.new(:h6, nil, nil)
-    @ul = HOM::Element.new(:ul, nil, (1..3).map { |n| HOM::Element.new(:li, nil, n) })
-  end
-
-  describe 'content query method' do
-    it 'should return false if the content is undefined' do
-      @br.content?.must_equal(false)
-    end
-
-    it 'should return true otherwise' do
-      @h1.content?.must_equal(true)
-    end
-  end
-
-  describe 'to_s method' do
-    it 'should return a string containing the correct markup' do
-      @br.to_s.must_equal('<br>')
-      @i1.to_s.must_equal('<input disabled>')
-      @i2.to_s.must_equal('<input type="text" size="30" value="">')
-      @i3.to_s.must_equal('<input type="text" size="30" disabled>')
-      @h1.to_s.must_equal('<h1></h1>')
-      @h2.to_s.must_equal('<h2>hello world</h2>')
-      @h3.to_s.must_equal('<h3>a &amp;&amp; b, x &gt; y</h3>')
-      @h4.to_s.must_equal('<h4>1234567890</h4>')
-      @h5.to_s.must_equal('<h5><b>how bold</b></h5>')
-      @h6.to_s.must_equal('<h6></h6>')
-      @ul.to_s.must_equal('<ul><li>1</li><li>2</li><li>3</li></ul>')
-    end
-
-    it 'should not encode content that has been marked as html safe' do
-      HOM::Element.new(:span, nil, '<br>').to_s.must_equal('<span>&lt;br&gt;</span>')
-      HOM::Element.new(:span, nil, '<br>'.html_safe).to_s.must_equal('<span><br></span>')
-    end
-
-    it 'should return content that is marked as html safe' do
-      @br.to_s.html_safe?.must_equal(true)
-    end
-  end
-
-  describe 'encoding objects with an html method' do # TODO: REMOVE ME
-    it 'should emit a deprecation warning' do
-      require 'mocha'
-
-      object = Object.new
-
-      def object.html; HOM::Element.new(:span, nil, 'html') end
-
-      div = HOM::Element.new(:div, nil, object)
-
-      Kernel.expects(:warn).with(regexp_matches(/defining #html on custom objects is deprecated/))
-
-      div.to_s.must_equal('<div><span>html</span></div>')
-    end
-  end
-end

data/spec/entity_spec.rb

@@ -1,75 +0,0 @@
-require 'minitest/autorun'
-
-require_relative '../lib/hom'
-
-describe 'Named entity' do
-  before do
-    @entity = HOM::Entity.new(:nbsp)
-  end
-
-  describe 'value method' do
-    it 'should return the symbol value' do
-      @entity.value.must_equal(:nbsp)
-    end
-  end
-
-  describe 'numeric query method' do
-    it 'should return false' do
-      @entity.numeric?.must_equal(false)
-    end
-  end
-
-  describe 'named query method' do
-    it 'should return true' do
-      @entity.named?.must_equal(true)
-    end
-  end
-
-  describe 'to_s method' do
-    it 'should return the encoded html entity' do
-      @entity.to_s.must_equal(' ')
-    end
-  end
-
-  describe 'html_safe query method' do
-    it 'should return true' do
-      @entity.html_safe?.must_equal(true)
-    end
-  end
-end
-
-describe 'Numeric entity' do
-  before do
-    @entity = HOM::Entity.new(160)
-  end
-
-  describe 'value method' do
-    it 'should return the integer value' do
-      @entity.value.must_equal(160)
-    end
-  end
-
-  describe 'numeric query method' do
-    it 'should return true' do
-      @entity.numeric?.must_equal(true)
-    end
-  end
-
-  describe 'named query method' do
-    it 'should return false' do
-      @entity.named?.must_equal(false)
-    end
-  end
-
-  describe 'to_s method' do
-    it 'should return the encoded html entity' do
-      @entity.to_s.must_equal(' ')
-    end
-  end
-
-  describe 'html_safe query method' do
-    it 'should return true' do
-      @entity.html_safe?.must_equal(true)
-    end
-  end
-end