hom 1.0.0 → 1.1.0

data/README.md

@@ -1,5 +1,8 @@
-A straightforward API for generating HTML
-=========================================
+hom
+===
+
+
+A straightforward API for generating HTML.
 
 
 Motivation
@@ -26,12 +29,12 @@ puts HOM::Element.new(:h1, nil, 'hello world')
 ```
 
 
-Usage
------
+Using HOM::Element
+------------------
 
-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:
+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)
@@ -50,8 +53,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, '')
@@ -65,16 +68,35 @@ 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::Element.new(:span, nil, HOM::Entity.new(:nbsp))
+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::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.
+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.

data/hom.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'hom'
-  s.version = '1.0.0'
+  s.version = '1.1.0'
   s.platform = Gem::Platform::RUBY
   s.authors = ['Tim Craft']
   s.email = ['mail@timcraft.com']

data/lib/hom.rb

@@ -43,6 +43,38 @@ module HOM
     end
   end
 
+  class NodeList
+    def initialize(nodes)
+      @nodes = Array(nodes)
+    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)
+      Encoding.safe_encode(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
     def initialize
       @index = {}
@@ -80,6 +112,8 @@ 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_safe?) && object.html_safe?

data/spec/node_list_spec.rb

@@ -0,0 +1,48 @@
+require 'minitest/autorun'
+require 'active_support/core_ext/string/output_safety'
+require 'hom'
+
+describe 'HOM::NodeList' do
+  describe 'to_a method' do
+    it 'returns the array of nodes passed to the constructor' do
+      nodes = HOM::NodeList.new(%w(a b c))
+      nodes.to_a.must_equal(%w(a b c))
+    end
+  end
+
+  describe 'to_s method' do
+    it 'returns an html safe string containing the encoded nodes' do
+      nodes = HOM::NodeList.new(['Hello', HOM::Entity.new(:nbsp), HOM::Element.new(:b, nil, 'World')])
+
+      output = nodes.to_s
+      output.must_equal('Hello&nbsp;<b>World</b>')
+      output.html_safe?.must_equal(true)
+    end
+  end
+
+  describe 'addition of two node lists' do
+    it 'returns a new node list containing the items in each list' do
+      nodes = HOM::NodeList.new(['one']) + HOM::NodeList.new(['two'])
+      nodes.must_be_instance_of(HOM::NodeList)
+      nodes.to_a.must_equal(%w(one two))
+    end
+  end
+
+  describe 'addition of a node list with an element object' do
+    it 'returns a new node list containing the items in the list and the additional element' do
+      element = HOM::Element.new(:b, nil, 'World')
+
+      nodes = HOM::NodeList.new(['Hello', HOM::Entity.new(:nbsp)]) + element
+      nodes.must_be_instance_of(HOM::NodeList)
+      nodes.to_s.must_equal('Hello&nbsp;<b>World</b>')
+    end
+  end
+
+  describe 'join method' do
+    it 'returns an html safe string containing the encoded nodes seperated by the argument' do
+      output = HOM::NodeList.new(%w(a b c)).join(HOM::Entity.new(:nbsp))
+      output.html_safe?.must_equal(true)
+      output.must_equal('a&nbsp;b&nbsp;c')
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hom
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-16 00:00:00.000000000 Z
+date: 2013-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -70,6 +70,7 @@ files:
 - spec/element_spec.rb
 - spec/encoding_spec.rb
 - spec/entity_spec.rb
+- spec/node_list_spec.rb
 - Rakefile
 - README.md
 - hom.gemspec
@@ -93,8 +94,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: See description
 test_files: []
+has_rdoc: