RubyGems - htmless - Versions diffs - 0.4 - Mend

htmless 0.4

Files changed (22) hide show

data/MIT-LICENSE +19 -0
data/README.md +7 -0
data/README_FULL.md +585 -0
data/lib/copy_to_doc.rb +43 -0
data/lib/htmless/abstract/abstract_double_tag.rb +144 -0
data/lib/htmless/abstract/abstract_single_tag.rb +18 -0
data/lib/htmless/abstract/abstract_tag.rb +246 -0
data/lib/htmless/abstract.rb +252 -0
data/lib/htmless/data/html5.rb +179 -0
data/lib/htmless/data.rb +11 -0
data/lib/htmless/doc.rb +394 -0
data/lib/htmless/dynamic_classes.rb +216 -0
data/lib/htmless/formatted.rb +43 -0
data/lib/htmless/helper.rb +24 -0
data/lib/htmless/pool.rb +72 -0
data/lib/htmless/rails.rb +40 -0
data/lib/htmless/standard.rb +48 -0
data/lib/htmless/strings_injector.rb +43 -0
data/lib/htmless.rb +3 -0
data/lib/js.rb +176 -0
data/spec/htmless_spec.rb +290 -0
metadata +279 -0

data/MIT-LICENSE ADDED Viewed

@@ -0,0 +1,19 @@
+Copyright (c) 2013 Petr Chalupa <git@pitr.ch>
+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.md ADDED Viewed

@@ -0,0 +1,7 @@
+## Htmless
+Fast extensible html5 builder in pure Ruby
+-   Documentation: <http://blog.pitr.ch/htmless>
+-   Source: <https://github.com/pitr-ch/htmless>
+-   Blog: <http://blog.pitr.ch/blog/categories/htmless/>

data/README_FULL.md ADDED Viewed

@@ -0,0 +1,585 @@
+# Htmless
+Fast extensible html5 builder in pure Ruby
+-   Documentation: <http://blog.pitr.ch/htmless>
+-   Source: <https://github.com/pitr-ch/htmless>
+-   Blog: <http://blog.pitr.ch/blog/categories/htmless/>
+## Why?
+I needed html builder with these characteristics:
+*   Ruby
+*   Fast
+*   Extensibility for each tag
+Disadvanteges of other options:
+*   Erector - quite high level, no tag extensibility
+*   Markaby - slow
+*   Wee::Brush - extensible but not a standalone gem
+*   Tagz - very slow
+*   Erubis - fast but temlate engine and no tag extensibility
+*   Tenjin - faster but temlate engine and no tag extensibility
+## Quick syntax example
+    !!!ruby
+    Htmless::Formatted.new.go_in do
+      html5
+      html do
+        head { title 'my_page' }
+        body do
+          div.content! do
+            p.centered "my page's content"
+          end
+        end
+      end
+    end.to_html
+returns
+    !!!html
+    <!DOCTYPE html>
+    <html xmlns="http://www.w3.org/1999/xhtml">
+      <head>
+        <title>my_page</title>
+      </head>
+      <body>
+        <div id="content">
+          <p class="centered">my page's content</p>
+        </div>
+      </body>
+    </html>
+## Chaining
+    !!!ruby
+    div.class('left').id('menu').class('border').onclick('run();').with do
+      text 'hello'
+    end
+prints
+    !!!html
+    <div class="left border" id="menu" onclick="run();">hello</div>
+Content block must be last in the chain. No other calls are allowed after block.
+    !!!ruby
+    div do
+      text 'content'
+    end.id('an_id') # won't work
+## Attributes
+    !!!ruby
+    div :id => 'menu', :class => 'left' # is shortcut for:
+    div.attributes :id => 'menu', :class => 'left'
+*   `#attributes` calls underlining methods `#id` and `#class`
+*   If you extend tag by a method, you can call it through `#attributes` or `#attribute`
+Any attribute method you call is immediately appended to output with exception of classes. They are acumulating
+until tag is closed.
+    !!!ruby
+    div(:class => 'left').class('center') # <div class='left center'></div>
+    div(:id => 1).id(2)                   # <div id="1" id="2"></div>
+Udefined attribute can be rendered with.
+    !!!ruby
+    html.attribute :xmlns, 'http://www.w3.org/1999/xhtml'
+    # => <html xmlns="http://www.w3.org/1999/xhtml"></html>
+If `#attribute` finds defined method for desired attribute, the method is called.
+    !!!ruby
+    div.attribute :class => 'left' # is equvivalent to:
+    div.class 'left'
+## Content, Boolean attributes
+    !!!ruby
+    div 'content'                       # <div>content</div>
+    div.content 'content'               # <div>content</div>
+    div :content => 'content'           # <div>content</div>
+    div { text 'content' }              # <div>content</div>
+    div.with { text 'content' }         # <div>content</div>
+    div 'content', :id => :id           # <div id="id">content</div>
+    div(:id => :id) { text 'content' }  # <div id="id">content</div>
+    div.id :id do
+      text 'content'
+    end                                 # <div id="id">content</div>
+### Boolean attributes
+Attributes like `checked` and `disabled` test value for true, if false they render nothing
+    !!!ruby
+    input.disabled am_i_disabled?
+    # => <input disabled="disabled" />
+    # or <input />
+## Id, class and mimic
+    !!!ruby
+    div.menu!.left.hidden # => <div id="menu" class="left hidden"></div>
+Content can be passed in the usual way:
+    !!!ruby
+    div.menu! 'content'       # => <div id="menu">content</div>
+    div.menu! { p 'content' } # => <div id="menu"><p>content</p></div>
+`#class` accepts an array, values are joined with spaces and `false`, `nil` values are ignored
+    !!!ruby
+    div.class('menu', 'big', hide? && 'hidden')
+    # => <div class="menu big hidden"></div>
+    # or <div class="menu big"></div>
+`#id` accepts also an array, values are joined with '-' and `false`, `nil` values are ignored
+    !!!ruby
+    div.id('menu', 'big', a_failing_test && 'useless') # => <div id="menu-big"></div>
+Object (model) can be used to set class and id
+    !!!ruby
+    user = User.new(:id => 1)
+    div(:class => 'model')[user].with { text 'data' }
+    # => <div id="user-1" class="model user">data</div>
+`#mimic` which is aliased as `#[]` looks for `.htmless_ref` or it uses the class name to render the class part.
+As id is used already determined class and `#htmless_ref`, `#id`, `#object_id` which one is found first.
+## Data attributes, Join
+### Data attributes
+    !!!ruby
+    div.data_secret("I won't tell.") # => <div data-secret="I won't tell."></div>
+    data :secret => "I won't tell."  # => <div data-secret="I won't tell."></div>
+### Join
+`#join` enables easy rendering of collections
+    !!!ruby
+    join([1, 1.2], ->{ text ', ' }) {|n| b "#{n}cm" }
+        # => "<b>1cm</b>, <b>1.2cm</b>"
+    join([1, 1.2], ', ') {|n| b "#{n}cm" }
+        # => "<b>1cm</b>, <b>1.2cm</b>"
+    join([1, ->{ text 'missing' }], ', ') {|n| b "#{n}cm" }
+        # => "<b>1cm</b>, missing"
+A block in the collection is rendered directly without iterator. This can be useful when menu with some delimiters
+is rendered based on collection of some objects and you need to add one or more untypical menu items.
+## '_' vs '-'
+'_' in attributes is transformed to '-'
+    !!!ruby
+    meta.http_equiv 'Content-Type' # => <meta http-equip="Content-Type" />
+'_' in class shortcut methods is transformed to '-'
+    !!!ruby
+    div.a_class.an_id! # => <div id="an-id" class="a-class"></div>
+Ids generated by Arrays are joined with '-'
+    !!!ruby
+    div.id('an', 'id') # => <div id="an-id"></div>
+## Tag's reprezentation
+Each tag has its own class.
+    !!!ruby
+    div.rclass # => #<Class:0x00000001d449b8(Htmless::Formatted.dc[:Div])>
+    li.rclass  # => #<Class:0x00000001d449b8(Htmless::Formatted.dc[:Li])>
+`#rclass` is original ruby method `#class`
+## Getting a builder
+Creating new builder is relatively expensive. There is a pool of builders implemented.
+    !!!ruby
+    if am_i_smart?
+      pool = Htmless::Pool.new Htmless::Formatted # store pool somewhere globalish for reuse
+      builder = pool.get # => new builder from pool if there is one, or a newlly created one
+      # ... do yours stuff
+      builder.release # resets builder and returns it to the pool
+    else
+      b = Htmless::Formatted.new
+      # ... do yours stuff
+      # later on builder gets garbage collected
+    end
+Be careful not to use builder after you have released it.
+    !!!ruby
+    if am_i_freaking_smart?
+      pool = Htmless::Pool.new Htmless::Formatted
+      xhtml = pool.get.go_in(your_data) do |data|
+        # render your data ...
+      end.to_html! # returns xhtml and releases the builder
+    end
+This way builder doesn't get stored anywhere.
+## How to use
+The idea is that any object intended to rendering will have methods which renders the object into builder.
+There is a `Htmless::Helper` and method `#render` (also aliased as `#r`) for that purpose.
+    !!!ruby
+    class User < Struct.new(:name, :login, :email)
+      extend Htmless::Helper
+      builder :detail do |user|
+        ul do
+          r user, :attribute, :name
+          r user, :attribute, :login
+          r user, :attribute, :email
+        end
+      end
+      def attribute(b, attribute)
+        b.li do
+          b.strong "#{attribute}: "
+          b.text self.send(attribute)
+        end
+      end
+    end
+`.builder` is just shortcut to define method `User#detail` like this:
+    !!!ruby
+    def detail(b)
+      b.go_in(self) do |user| # this block is the same as the one passed
+        ul do                 # above to .builder
+          r user, :attribute, :name
+          r user, :attribute, :login
+          r user, :attribute, :email
+        end
+      end
+    end
+is same as
+    !!!ruby
+    builder :detail do |user|
+      ul do
+        r user, :attribute, :name
+        r user, :attribute, :login
+        r user, :attribute, :email
+      end
+    end
+and
+    !!!ruby
+    user = User.new("Peter", "peter", "peter@example.com")
+    pool.get.dive do
+      r user, :detail
+    end.to_html!
+returns:
+    !!!html
+    <ul>
+      <li>
+        <strong>name: </strong>Peter
+      </li>
+      <li>
+        <strong>login: </strong>peter
+      </li>
+      <li>
+        <strong>email: </strong>peter@example.com
+      </li>
+    </ul>
+## Contexts
+Html can be rendered outside of builder's context
+    !!!ruby
+    class User
+      attr_reder :name, :age
+      def detail(b) # builder
+        b.ul { b.li name; b.li name }
+      end
+    end
+or `#go_in` (also aliased as `#dive`) can be used to get into builder's context
+    !!!ruby
+    class User
+      extend Htmless::Helper
+      attr_reder :name, :age
+      builder :detail do |user|
+        ul { li user.name; li user.age }
+      end
+    end
+    # => <ul><li>john Doe</li><li>25</li></ul>
+## Helpers
+If they are needed they can be mixed directly into Builder's instance
+    !!!ruby
+    Htmless::Formatted.new.go_in do
+      extend ActionView::Helpers::NumberHelper
+      div number_with_precision(Math::PI, :precision => 4)
+    end.to_html # => <div>3.1416</div>
+*Be careful when you are using this with `Pool`. Some instances may have helpers and some don't.*
+Or new builder descendant can be made.
+    !!!ruby
+    class MyBuilder < Hammer::FormattedBuilder
+      include ActionView::Helpers::NumberHelper
+    end
+    MyBuilder.new.go_in do
+      div number_with_precision(Math::PI, :precision => 4)
+    end.to_html # => <div>3.1416</div>
+## Implementation details - Tag's shared instances
+There are no multiple instances for each tag.
+Every tag of the same type share a same instance (unique within the instance of a builder).
+    !!!ruby
+    puts(pool.get.go_in do
+      puts div.object_id
+      puts div.object_id
+    end.to_html!)
+    # =>
+    # 10069200
+    # 10069200
+    # <div></div><div></div>
+`Htmless` creates what he can prior to rendering and uses heavily meta-programming, because of that instantiating
+the very first instance of builder triggers some magic staff taking about a one second. Creating new builders of the
+same class is than much faster and getting builder from a pool is instant.
+This won't work:
+    !!!ruby
+    puts(pool.get.go_in do
+      a = div 'a'
+      div 'b'
+      a.class 'class'
+    end.to_html!)
+    # => <div>a</div><div class="class">b</div>
+because when `#class` is called the second div is being built.
+## Implementation details - DynamicClasses
+    !!!ruby
+    class Parent
+      class LeftEye
+        def to_s
+          'left eye'
+        end
+      end
+      class RightEye < LeftEye
+        def to_s
+          'next to ' + super
+        end
+      end
+    end
+    class AChild < Parent
+    end
+    class AMutant
+      class LeftEye < superclass::LeftEye
+        def to_s
+          'laser ' + super
+        end
+      end
+    end
+How to define `AMutant::RihtEye` to return `"next to laser left eye"` ?
+    !!!ruby
+    class Parent
+      extend DynamicClasses
+      dynamic_classes do
+        def_class :LeftEye do
+          def to_s; 'left eye'; end
+        end
+        def_class :RightEye, :LeftEye do
+          class_eval <<-RUBYCODE, __FILE__, __LINE__+1
+            def to_s; 'next to ' + super; end
+          RUBYCODE
+        end
+      end
+    end
+    class AChild < Parent
+    end
+    class AMutant < Parent
+      dynamic_classes do
+        extend_class :LeftEye do
+          def to_s; 'laser ' + super; end
+        end
+      end
+    end
+Each class is a diferent object.
+    !!!ruby
+    Parent.dynamic_classes[:LeftEye] # => #<Class:0x00000001d449b8(A.dc[:LeftEye])>
+    AChild.dynamic_classes[:LeftEye] # => #<Class:0x00000001d42398(A.dc[:LeftEye])>
+`AMutant.dc[:RightEye]` automaticaly inherits from extended `AMutant.dc[:LeftEye]`
+    !!!ruby
+    Parent.dc[:LeftEye].new.to_s   # => 'left eye'
+    Parent.dc[:RightEye].new.to_s  # => 'next to left eye'
+    AChild.dc[:LeftEye].new.to_s   # => 'left eye'
+    AChild.dc[:RightEye].new.to_s  # => 'next to left eye'
+    AMutant.dc[:LeftEye].new.to_s  # => 'laser left eye'
+    AMutant.dc[:RightEye].new.to_s # => 'next to laser left eye'
+## Extensibility
+    !!!ruby
+    class MyBuilder < Htmless::Formatted
+      dynamic_classes do
+        # define new method to all tags
+        extend_class :AbstractTag do
+          def hide!
+            self.class 'hidden'
+          end
+        end
+        # add pseudo tag
+        def_class :Component, :Div do
+          class_eval <<-RUBYCODE, __FILE__, __LINE__ + 1
+            def open(id, attributes = nil, &block)
+              super(attributes, &nil).id(id).class('component')
+              block ? with(&block) : self
+            end
+          RUBYCODE
+        end
+      end
+      define_tag :component
+      # if the class is not needed same can be done this way
+      def simple_component(id, attributes = {}, &block)
+        div.id(id).attributes attributes, &block
+      end
+    end
+    MyBuilder.new.go_in do
+      div.content!.with do
+        span.secret!.class('left').hide!
+        component('component-1') do
+          strong 'something'
+        end
+        simple_component 'component-1'
+      end
+    end.to_html
+returns
+    !!!html
+    <div id="content">
+      <span id="secret" class="left hidden"></span>
+      <div id="component-1" class="component">
+        <strong>something</strong>
+      </div>
+      <div id="component-1"></div>
+    </div>
+## Benchmarks
+### Synthetic
+Benchmatk can be found on github. It renders simple page with two collections. 'reuse' means
+that template is precompiled and reused during benchmark.
+                                   user     system      total        real
+    tenjin-reuse               2.040000   0.000000   2.040000 (  2.055140)
+    Htmless::Standard          2.520000   0.000000   2.520000 (  2.519284)
+    fasterubis-reuse           2.580000   0.000000   2.580000 (  2.581407)
+    erubis-reuse               2.680000   0.000000   2.680000 (  2.690176)
+    Htmless::Formatted         2.780000   0.000000   2.780000 (  2.794307)
+    erubis                     5.180000   0.000000   5.180000 (  5.183333)
+    fasterubis                 5.210000   0.000000   5.210000 (  5.219176)
+    tenjin                     7.650000   0.160000   7.810000 (  7.820490)
+    erector                    9.450000   0.010000   9.460000 (  9.471654)
+    markaby                   14.300000   0.000000  14.300000 ( 14.318844)
+    tagz                      33.430000   0.000000  33.430000 ( 33.483693)
+### Rails 3
+Benchmatk can be found on github.
+Single page with or without a partial which is rendered 200 times. Partials make no diffrence for Htmless.
+    BenchTest#test_erubis_partials (3.34 sec warmup)
+               wall_time: 3.56 sec
+                 gc_runs: 15
+                 gc_time: 0.53 ms
+    BenchTest#test_erubis_single (552 ms warmup)
+               wall_time: 544 ms
+                 gc_runs: 4
+                 gc_time: 0.12 ms
+    BenchTest#test_htmless (2.33 sec warmup)
+               wall_time: 847 ms
+                 gc_runs: 5
+                 gc_time: 0.17 ms
+    BenchTest#test_tenjin_partial (942 ms warmup)
+               wall_time: 1.21 sec
+                 gc_runs: 7
+                 gc_time: 0.25 ms
+    BenchTest#test_tenjin_single (531 ms warmup)
+               wall_time: 532 ms
+                 gc_runs: 6
+                 gc_time: 0.20 ms
+## Why is it fast?
+*   Optimalization of garbage collecting.
+    *   10-15% improvment.
+    *   Preinicialization (tag's instances, even strings).
+    *   No string's `#+`, `#{}`. Just `#<<` to buffer.
+    *   Precomputed spaces for indentation.
+*   Doing as less as posible when rendering.
+*   Magic by metaprograming not by `method_missing`. Magic is run on inicialization not when rendering.
+*   Number of micro optimalization.
+    *   Data in constants or instance variables.
+    *   Buffer.
+    *   No `#define_method`.
+    *   Method inlining.
+    *   Probably no real effect :)
+## Future plans
+*   compile rendering methods on objects to javascript which will render html form json
+*   Helpers for Sinatra, Rails 3
+*   Helpers for fragment caching
+## Why use it?
+*   Its fast
+*   You can use inheritance (imposible with templates) and other goodness of Ruby
+*   You can use pure Ruby to write the html

data/lib/copy_to_doc.rb ADDED Viewed

@@ -0,0 +1,43 @@
+# This copies insides of dynamic classes into doc.rb for documenting purposes only
+require 'pp'
+root = File.expand_path File.dirname(__FILE__)
+$: << root
+require "#{root}/htmless"
+File.open "#{root}/htmless/doc.rb", 'w' do |out|
+  out.write "module Htmless\n"
+  out.write "  module StubBuilderForDocumentation\n"
+  files = ["#{root}/htmless/abstract/abstract_tag.rb",
+           "#{root}/htmless/abstract/abstract_single_tag.rb",
+           "#{root}/htmless/abstract/abstract_double_tag.rb"]
+  files.each do |file_path|
+    source = File.open(file_path, 'r') { |f| f.read }
+    source.scan(/def_class\s+(:\w+)(|,\s*(:\w+))\s+do\s+###import(([^#]|#[^#]|##[^#])*)end\s+###import/m) do |match|
+      klass   = match[0][1..-1]
+      parent  = match[2] ? match[2][1..-1] : nil
+      content = match[3]
+      #content = content.lines.delete_if { |l| l =~ /\#\#\# remove/ }.join("\n")
+      out << "    class #{klass}"
+      out << " < #{parent}" if parent
+      out << "\n"
+      out << content
+      out << "    end\n"
+    end
+  end
+  #out << "    class AbstractTag\n"   ff
+  #HammerBuilder::GLOBAL_ATTRIBUTES.each do |attr|
+  #  out << "    \#@method #{attr}(value)\n"
+  #  out << "    attribute :#{attr}\n"
+  #end
+  #out << "    end\n"
+  out << "  end\n"
+  out << "end\n"
+end