hom 0.3.0 → 0.4.0

data/README.md

@@ -0,0 +1,62 @@
+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:
+
+```ruby
+HOM::Element.new(:br)
+```
+
+The second constructor argument represents the element attributes, and can be
+nil, a single symbol/string, a hash, or an array of hashes and symbols/strings.
+For example, here's how you'd represent some input elements:
+
+```ruby
+HOM::Element.new(:input, :disabled)
+
+HOM::Element.new(:input, {type: :text, size: 30})
+
+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:
+
+```ruby
+span = HOM::Element.new(:span, nil, '')
+
+h1 = HOM::Element.new(:h1, {}, 'hello world')
+
+image = HOM::Element.new(:img, {src: 'image.png', width: 100, height: 30})
+
+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,
+for example:
+
+```ruby
+HOM::Element.new(:span, nil, HOM::Entity.new(160))
+
+HOM::Element.new(:span, nil, HOM::Entity.new(:nbsp))
+```
+
+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.

data/Rakefile

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

data/hom.gemspec

@@ -1,13 +1,13 @@
 Gem::Specification.new do |s|
   s.name = 'hom'
-  s.version = '0.3.0'
+  s.version = '0.4.0'
   s.platform = Gem::Platform::RUBY
   s.authors = ['Tim Craft']
   s.email = ['mail@timcraft.com']
   s.homepage = 'http://github.com/timcraft/hom'
-  s.description = 'A straightforward API for generating HTML programmatically'
+  s.description = 'A straightforward API for generating HTML'
   s.summary = 'See description'
-  s.files = Dir.glob('{lib,test}/**/*') + %w(README.txt hom.gemspec)
+  s.files = Dir.glob('{lib,spec}/**/*') + %w(Rakefile README.md hom.gemspec)
   s.add_development_dependency('activesupport', ['>= 3.0.3'])
   s.require_path = 'lib'
 end

data/lib/hom.rb

@@ -1,6 +1,8 @@
 require 'cgi'
 
 module HOM
+  Undefined = Class.new
+
   class Entity
     attr_reader :value
 
@@ -8,7 +10,7 @@ module HOM
       @value = value
     end
 
-    def html
+    def to_s
       numeric? ? "&\##{value};" : "&#{value};"
     end
 
@@ -19,41 +21,25 @@ module HOM
     def named?
       !numeric?
     end
+
+    def html_safe?
+      true
+    end
   end
 
   class Element
-    def initialize(tag_name, attributes = nil, content = nil)
+    attr_reader :tag_name, :attributes, :content
+
+    def initialize(tag_name, attributes = nil, content = Undefined)
       @tag_name, @attributes, @content = tag_name, AttributeList.new.update(attributes), content
     end
 
-    def html
-      @content.nil? ? start_tag : "#{start_tag}#{encode(@content)}</#{@tag_name}>"
+    def content?
+      @content != Undefined
     end
 
     def to_s
-      html_safe(html)
-    end
-
-    private
-
-    def html_safe(string)
-      string.respond_to?(:html_safe) ? string.html_safe : string
-    end
-
-    def encode(object)
-      if object.is_a?(Array)
-        object.map { |item| encode(item) }.join
-      elsif object.respond_to?(:html)
-        object.html
-      elsif object.respond_to?(:html_safe?) && object.html_safe?
-        object.to_s
-      else
-        HOM.escape(object)
-      end
-    end
-
-    def start_tag
-      "<#{@tag_name}#{@attributes.html}>"
+      Encoding.safe_encode(self)
     end
   end
 
@@ -62,16 +48,14 @@ module HOM
       @index = {}
     end
 
-    def html
-      @index.map { |name, value| attribute_html(name, value) }.join
-    end
-
-    Undefined = Class.new
-
     def set(name, value = Undefined)
       @index[name.to_s] = value
     end
 
+    def to_hash
+      @index
+    end
+
     def update(object)
       case object
       when NilClass
@@ -86,15 +70,51 @@ module HOM
 
       return self
     end
+  end
+
+  module Encoding
+    def self.safe_encode(object)
+      safe(encode(object))
+    end
 
-    private
+    def self.encode(object)
+      if object.is_a?(Array)
+        object.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'
 
-    def attribute_html(name, value)
-      value == Undefined ? " #{name}" : %( #{name}="#{HOM.escape value}")
+        object.html
+      elsif object.respond_to?(:html_safe?) && object.html_safe?
+        object.to_s
+      else
+        escape(object)
+      end
     end
-  end
 
-  def self.escape(object)
-    CGI.escapeHTML(object.to_s)
+    def self.encode_element(object)
+      object.content? ? "#{start_tag(object)}#{encode(object.content)}</#{object.tag_name}>" : start_tag(object)
+    end
+
+    def self.start_tag(element)
+      "<#{element.tag_name}#{encode_attributes(element)}>"
+    end
+
+    def self.encode_attributes(element)
+      element.attributes.to_hash.map { |name, value| encode_attribute(name, value) }.join
+    end
+
+    def self.encode_attribute(name, value)
+      value == Undefined ? " #{name}" : %( #{name}="#{escape value}")
+    end
+
+    def self.safe(string)
+      string.respond_to?(:html_safe) ? string.html_safe : string
+    end
+
+    def self.escape(object)
+      CGI.escapeHTML(object.to_s)
+    end
   end
 end

data/spec/element_spec.rb

@@ -0,0 +1,71 @@
+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

@@ -0,0 +1,75 @@
+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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hom
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-23 00:00:00.000000000Z
+date: 2012-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &10113880 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,8 +21,13 @@ dependencies:
         version: 3.0.3
   type: :development
   prerelease: false
-  version_requirements: *10113880
-description: A straightforward API for generating HTML programmatically
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+description: A straightforward API for generating HTML
 email:
 - mail@timcraft.com
 executables: []
@@ -30,7 +35,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/hom.rb
-- README.txt
+- spec/element_spec.rb
+- spec/entity_spec.rb
+- Rakefile
+- README.md
 - hom.gemspec
 homepage: http://github.com/timcraft/hom
 licenses: []
@@ -52,8 +60,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: See description
 test_files: []
+has_rdoc: 

data/README.txt

@@ -1,50 +0,0 @@
-A straightforward API for generating HTML programmatically.
-
-Install via rubygems (no dependencies):
-
-  gem install hom
-
-Either require it, or add it to your Rails Gemfile:
-
-  require 'hom'
-
-  gem 'hom'
-
-Generate HTML using HOM::Element objects. The first constuctor argument is
-a symbol representing the tag name, for example:
-
-  HOM::Element.new(:br)
-
-The second constructor argument represents the element attributes, and can be
-nil, a single symbol/string, a hash, or an array of hashes and symbols/strings.
-For example:
-
-  HOM::Element.new(:input, :disabled)
-
-  HOM::Element.new(:input, {type: :text, size: 30})
-
-  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:
-
-  span = HOM::Element.new(:span, nil, '')
-
-  h1 = HOM::Element.new(:h1, {}, 'hello world')
-
-  image = HOM::Element.new(:img, {src: 'image.png', width: 100, height: 30})
-
-  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) })
-
-Use HOM::Entity objects for HTML entities; integer values for numeric entities
-and symbol/string values for named entities, for example:
-
-  HOM::Element.new(:span, nil, HOM::Entity.new(160))
-
-  HOM::Element.new(:span, nil, HOM::Entity.new(:nbsp))
-
-Call #to_s or #html on a HOM::Element object to return a string containing
-the generated HTML. HOM::Element objects are safe to use directly in Rails
-templates, all escaping is handled automatically.