RubyGems - shaven - Versions diffs - 0.0.1 - Mend

shaven 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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