RubyGems - shaven - Versions diffs - 0.0.1 - Mend

shaven 0.0.1

Files changed (43) hide show

data/.gitignore +12 -0
data/.rspec +1 -0
data/Isolate +12 -0
data/README.md +183 -0
data/Rakefile +47 -0
data/lib/shaven.rb +27 -0
data/lib/shaven/core_ext/hash.rb +22 -0
data/lib/shaven/core_ext/object.rb +17 -0
data/lib/shaven/document.rb +9 -0
data/lib/shaven/helpers/html.rb +68 -0
data/lib/shaven/nokogiri_ext/node.rb +86 -0
data/lib/shaven/presenter.rb +90 -0
data/lib/shaven/scope.rb +50 -0
data/lib/shaven/transformer.rb +109 -0
data/lib/shaven/transformers/auto.rb +17 -0
data/lib/shaven/transformers/condition.rb +25 -0
data/lib/shaven/transformers/context.rb +35 -0
data/lib/shaven/transformers/dummy.rb +22 -0
data/lib/shaven/transformers/list.rb +51 -0
data/lib/shaven/transformers/reverse_condition.rb +25 -0
data/lib/shaven/transformers/text_or_node.rb +42 -0
data/lib/shaven/version.rb +13 -0
data/shaven.gemspec +20 -0
data/spec/benchmarks.rb +189 -0
data/spec/fixtures/condition.html +5 -0
data/spec/fixtures/context.html +7 -0
data/spec/fixtures/dummy.html +4 -0
data/spec/fixtures/list.html +6 -0
data/spec/fixtures/list_of_contexts.html +6 -0
data/spec/fixtures/reverse_condition.html +5 -0
data/spec/fixtures/text_or_node.html +4 -0
data/spec/helpers_html_spec.rb +54 -0
data/spec/nokogiri_node_spec.rb +55 -0
data/spec/presenter_spec.rb +36 -0
data/spec/spec_helper.rb +11 -0
data/spec/transformers/auto_spec.rb +34 -0
data/spec/transformers/condition_spec.rb +28 -0
data/spec/transformers/context_spec.rb +25 -0
data/spec/transformers/dummy_spec.rb +18 -0
data/spec/transformers/list_spec.rb +41 -0
data/spec/transformers/reverse_condition_spec.rb +28 -0
data/spec/transformers/text_or_node_spec.rb +65 -0
metadata +123 -0

data/lib/shaven/presenter.rb ADDED Viewed

@@ -0,0 +1,90 @@
+require 'shaven/scope'
+require 'shaven/document'
+require 'shaven/transformer'
+require 'shaven/helpers/html'
+module Shaven
+  # Presenters are placeholder for all logic which is going to fill in your html
+  # templates. Remember that presenters shouldn't contain any raw HTML code,
+  # you can generate it using html helpers (see <tt>Shaven::Helpers::HTML</tt>
+  # for details).
+  #
+  # ==== Simple example
+  #
+  #   class DummyPreseneter < Shaven::Presenter
+  #     def title
+  #       "Hello world!"
+  #     end
+  #   end
+  #
+  #   presenter = DummyPreseneter.feed("<!DOCTYPE html><html><body><h1 rb="title">Example...</h1></body><html>")
+  #   presenter.to_html # => ...
+  #
+  # ==== DOM Manipulation
+  #
+  # If your presenter method has one argument, then related DOM node will be passed
+  # to it while transformation process. You can use it to change its attributes or
+  # content, replace it with other node or text, remove it, etc.
+  #
+  #   class DummyPresenter < Shaven::Presenter
+  #     def title(node)
+  #       node.update!(:id => "title") { "Hello world!" }
+  #     end
+  #   end
+  #
+  # ==== HTML helpers
+  #
+  # Shaven's presenters provides set of helpers to generate extra html nodes. Take a look
+  # at example:
+  #
+  #   class DummyPresenter < Shaven::Presenter
+  #     def login_link
+  #       a(:href => login_path) { "Login to your account!" }
+  #     end
+  #
+  #     def title
+  #       tag(:h1, :id => "title") { "Hello world!" }
+  #     end
+  #   end
+  #
+  class Presenter
+    include Helpers::HTML
+    class << self
+      def feed(tpl)
+        new(Document.new(tpl))
+      end
+      def render(tpl, context={})
+        feed(tpl).render(context)
+      end
+    end
+    attr_reader :scope
+    def initialize(document)
+      @document = document
+      @scope    = Scope.new(self)
+    end
+    def render(context={})
+      unless compiled?
+        @scope.unshift(context.stringify_keys) unless context.empty?
+        Transformer.apply!(@scope.with(@document.root))
+        @compiled = true
+      end
+      @document.to_html
+    end
+    alias_method :to_html, :render
+    def compiled?
+      !!@compiled
+    end
+    # Some tricks to make presenter acts as array :)
+    alias_method :key?, :respond_to?
+    alias_method :[], :method
+  end # Presenter
+end # Shaven

data/lib/shaven/scope.rb ADDED Viewed

@@ -0,0 +1,50 @@
+module Shaven
+  # Special kind of array to fetch data from stack of context scopes.
+  #
+  # ==== Example
+  #
+  #   scope = Scope.new({:foo => nil})
+  #   scope["foo"] # => nil
+  #   scope.unshift({"foo" => "Bar!", "spam" => "Eggs!"})
+  #   scope["foo"] # => "Bar!"
+  #   scope.unshift({"foo" => "Foobar!"})
+  #   scope["foo"] # => "Foobar!"
+  #
+  class Scope < Array
+    # DOM node wrapped by this scope.
+    attr_reader :node
+    def initialize(*args)
+      super(args)
+    end
+    def [](key)
+      each { |scope|
+        if scope.key?(key = key.to_s)
+          value = scope[key]
+          if value.is_a?(Proc) or value.is_a?(Method)
+            args = [node, self]
+            return value.call(*args.take(value.arity))
+          else
+            return value
+          end
+        end
+      }
+    end
+    # Assigns given DOM node to this context and returns itself. This method will
+    # be used to fast switch from one node into another while transformation process.
+    #
+    # ==== Example
+    #
+    #   node_scope = scope.with(node)
+    #   node_scope.unshift({"foo" => proc { |node| node.update! :id => "hello-node" }})
+    #   node_scope["foo"] # => node
+    #
+    def with(node)
+      @node = node
+      return self
+    end
+  end # Scope
+end # Shaven

data/lib/shaven/transformer.rb ADDED Viewed

@@ -0,0 +1,109 @@
+module Shaven
+  class Transformer
+    # Just sugar to not using <tt>self</tt> in inheritance definition.
+    Base = self
+    # Load all built-in transformers
+    Dir[File.dirname(__FILE__)+"/transformers/*.rb"].each { |transformer|
+      require transformer
+    }
+    # This is chain containing list of DOM caller arguments and related transformers.
+    # All of them will be sequentially applied to each node in your template. Order is
+    # important because some of them allow to keep going with other transformations
+    # after they are applied, other doesn't allow that.
+    CALLERS = [
+      ['dummy',  Dummy],
+      ['if',     Condition],
+      ['unless', ReverseCondition],
+      [nil,      Auto]
+    ]
+    class << self
+      # Returns list of callers with full names. Names are combined with configuration
+      # setting in <tt>Shaven.caller_key</tt>.
+      def callers
+        @callers ||= CALLERS.map { |(name,trans)|
+          name = [Shaven.caller_key, name].compact.join(':')
+          [name,trans]
+        }
+      end
+      # Goes through callers chain and tries to apply all matching transformers within
+      # given scope. If scope for children should be combined/modified then it returns
+      # new scope for later usage, otherwise +nil+ will be returned.
+      def apply_each(scope, &block)
+        callers.each { |(name,trans)|
+          if key = scope.node.delete(name)
+            value = trans.find_value(scope, key).to_shaven
+            if trans.can_be_transformed?(value)
+              transformer = trans.new(key, value, scope)
+              extra_scope = transformer.transform!
+              return extra_scope unless transformer.allow_continue?
+            end
+          end
+        }
+        nil
+      end
+      # Applies each transformers within scope, to all children of represented document's
+      # node. Transformations are applied only for element nodes.
+      def apply!(scope)
+        scope.node.children.each { |child|
+          if child.elem?
+            extra_scope = apply_each(scope.with(child))
+            scope.unshift(extra_scope) if extra_scope
+            apply!(scope)
+            scope.shift if extra_scope
+          end
+        }
+        nil
+      end
+      # This method contains set of conditions which tells if given value can be
+      # used to transformation on current node. Each transformer should override
+      # this method if has such extra requirements.
+      def can_be_transformed?(value)
+        true
+      end
+      # Transformers can load values from scope in differen ways, so this method
+      # allows to define such own way within each trasformer. By default it just
+      # picks up specified key from given scope.
+      def find_value(scope, key)
+        scope[key]
+      end
+    end # self
+    # Name of the presenters method/key from which value has been extracted.
+    attr_reader :name
+    # Value extracted from presenter.
+    attr_reader :value
+    # Transformation context scope.
+    attr_reader :scope
+    def initialize(name, value, scope)
+      @name, @value, @scope = name, value, scope
+    end
+    # Just shortcut for <tt>scope.node</tt>.
+    def node
+      scope.node
+    end
+    # If this method returns +true+ then transformers left in chain gonna be applied
+    # to node within current scope, otherwise transformation chain will be broken.
+    # By default continuing after one transformation is not allowed.
+    def allow_continue?
+      false
+    end
+    # This method should contain all transformation directives. If scope for children
+    # nodes should be modified then method should return extra hash/scope which will
+    # be temporary combined with current one, otherwise returns +nil+.
+    def transform!
+      raise NotImplementedError, "You have to implement #transform! in your transformer"
+    end
+  end # Transformer
+end # Shaven

data/lib/shaven/transformers/auto.rb ADDED Viewed

@@ -0,0 +1,17 @@
+module Shaven
+  class Transformer
+    # Its job is to automatically recognize which transformer should be applied
+    # using specified settings. Regocnition is done by matching value type.
+    class Auto < Base
+      def self.new(name, value, scope)
+        if Context.can_be_transformed?(value)
+          Context.new(name, value, scope)
+        elsif List.can_be_transformed?(value)
+          List.new(name, value, scope)
+        else
+          TextOrNode.new(name, value, scope)
+        end
+      end
+    end # Auto
+  end # Transformer
+end # Shaven

data/lib/shaven/transformers/condition.rb ADDED Viewed

@@ -0,0 +1,25 @@
+module Shaven
+  class Transformer
+    # This transformer applies conditional operations to nodes. It applies to
+    # all nodes containing <tt>rb:if</tt> attribute.
+    #
+    # See Also: <tt>Shaven::Transformer::ReverseCondition</tt>
+    #
+    # ==== Example
+    #
+    #    <div rb:if="logged_in?">
+    #      Hello <span rb="user_name">John Doe</span>!
+    #    </div>
+    #
+    class Condition < Base
+      def allow_continue?
+        !!value
+      end
+      def transform!
+        node.remove unless value
+        nil
+      end
+    end # Condition
+  end # Transformer
+end # Shaven

data/lib/shaven/transformers/context.rb ADDED Viewed

@@ -0,0 +1,35 @@
+module Shaven
+  class Transformer
+    # This transformer Can be applied only when value is an instance of +Hash+,
+    # <tt>Shaven::Scope</tt>, or <tt>Shaven::Preseneter</tt>. It doesn't modify
+    # anything within given node, but modifies context for childrens.
+    #
+    # ==== Example
+    #
+    #   <div rb="user">
+    #     <div rb="name">John Doe</div>
+    #     <div rb="email">email@example.com</div>
+    #   </div>
+    #
+    # applied with given value:
+    #
+    #   { :name => "Marty Macfly", :email => "marty@macf.ly" }
+    #
+    # ... generates:
+    #
+    #   <div>
+    #     <div>Marty Macfly</div>
+    #     <div>marty@macf.ly</div>
+    #   </div>
+    #
+    class Context < Base
+      def self.can_be_transformed?(value)
+        value.is_a?(::Hash)
+      end
+      def transform!
+        value.stringify_keys
+      end
+    end # Context
+  end # Transformer
+end # Shaven

data/lib/shaven/transformers/dummy.rb ADDED Viewed

@@ -0,0 +1,22 @@
+module Shaven
+  class Transformer
+    # It removes all nodes containing <tt>rb:dummy</tt> attribute. It's very
+    # usefull when your template contains lot of example items. Instead of deleting
+    # them manualy you can mark them as dummy, so your designer can in the future
+    # edit templates directly in application.
+    #
+    # ==== Example
+    #
+    #   <ul id="emperors">
+    #     <li rb="emperors">Karol the Great</li>
+    #     <li rb:dummy="yes">Julius Cesar</li>
+    #     <li rb:dummy="yes">Alexander the Great</li>
+    #   <ul>
+    #
+    class Dummy < Base
+      def transform!
+        node.remove
+      end
+    end # Dummy
+  end # Transformer
+end # Shaven

data/lib/shaven/transformers/list.rb ADDED Viewed

@@ -0,0 +1,51 @@
+module Shaven
+  class Transformer
+    # This transformer can be applied when value can be iterated (responds to <tt>#each</tt>).
+    # It treats given node as template so generates sequence of clones for each list value,
+    # and finally removes original node.
+    #
+    # ==== Example
+    #
+    #   <ul id="users">
+    #     <li rb="users">John Doe</li>
+    #   </ul>
+    #
+    # applied with given value:
+    #
+    #   ["Emmet Brown", "Marty Macfly", "Biff Tannen"]
+    #
+    # ... generates:
+    #
+    #   <ul id="users">
+    #     <li>Emmet Brown</li>
+    #     <li>Marty Macfly</li>
+    #     <li>Biff Tannen</li>
+    #   </ul>
+    #
+    class List < Base
+      def self.can_be_transformed?(value)
+        value.is_a?(Array)
+      end
+      def transform!
+        array_scope = {}
+        parent = node.parent
+        id = 0
+        value.each { |item|
+          new_node = node.dup
+          array_scope["__shaven_list_item_#{id}"] = item
+          new_node['rb'] = "__shaven_list_item_#{id}"
+          parent.add_child(new_node)
+          id += 1
+        }
+        node.remove
+        array_scope = scope.dup.unshift(array_scope)
+        self.class.apply!(array_scope.with(parent))
+        nil
+      end
+    end # List
+  end # Transformer
+end # Shaven

data/lib/shaven/transformers/reverse_condition.rb ADDED Viewed

@@ -0,0 +1,25 @@
+module Shaven
+  class Transformer
+    # This transformer applies reverse conditional operations to nodes. It applies
+    # to all nodes containing <tt>rb:unless</tt> attribute.
+    #
+    # See Also: <tt>Shaven::Transformer::Condition</tt>
+    #
+    # ==== Example
+    #
+    #    <div rb:unless="logged_in?">
+    #      <a href="#" rb="login_link">Login to your account!</a>
+    #    </div>
+    #
+    class ReverseCondition < Base
+      def allow_continue?
+        !value
+      end
+      def transform!
+        node.remove if value
+        nil
+      end
+    end # ReverseCondition
+  end # Transformer
+end # Shaven

data/lib/shaven/transformers/text_or_node.rb ADDED Viewed

@@ -0,0 +1,42 @@
+module Shaven
+  class Transformer
+    # This transformers is applied to any kind of value which not applies to any
+    # other transformer. The only requirement is to node contains <tt>rb</tt> attribute.
+    # If result is different than current node object then will be assigned as its
+    # content, otherwise nothin will happen (any updates goes in presenter then).
+    #
+    # === Example
+    #
+    #   <h1 rb="title">Example</h1>
+    #   <p rb="description">Lorem ipsum dolor...</p>
+    #
+    # with given presenter:
+    #
+    #   class MyPresenter < Shaven::Presenter
+    #     def title
+    #       "Hello world!"
+    #     end
+    #
+    #     def description(node)
+    #       node.update!(:id => "description") { "World is beautiful!" }
+    #     end
+    #   end
+    #
+    # ... generates:
+    #
+    #   <h1>Hello world!</h1>
+    #   <p id="description">World is beautiful!</p>
+    #
+    class TextOrNode < Base
+      def transform!
+        if value.nokogiri_node?
+          node.inner_html = value unless value === node
+        else
+          node.content = value.to_s
+        end
+        nil
+      end
+    end # TextOrNode
+  end # Transformer
+end # Shaven