manveru-innate 2009.02.06 → 2009.02.21

data/lib/innate/action.rb

@@ -3,16 +3,20 @@ module Innate
                      :wish, :options, :variables, :value, :view_value, :name ]
 
   class Action < Struct.new(*ACTION_MEMBERS)
+    DEFAULT = {:options => {}, :variables => {}, :params => []}
+
     # Create a new Action instance.
     #
-    # @param [Hash, #values_at] hash used to seed new Action instance
+    # @param [Hash, #to_hash] hash used to seed new Action instance
     # @return [Action] action with the given defaults from hash
     # @author manveru
     def self.create(hash = {})
-      new(*hash.values_at(*ACTION_MEMBERS))
+      new(*DEFAULT.merge(hash.to_hash).values_at(*ACTION_MEMBERS))
     end
 
-    # Call the Action instance, will insert itself temporarily into Current.actions during the render operation so even in nested calls one can still access all other Action instances.
+    # Call the Action instance, will insert itself temporarily into
+    # Current.actions during the render operation so even in nested calls one
+    # can still access all other Action instances.
     # Will initialize the assigned node and call Action#render
     #
     # @return [String] The rendition of all nested calls
@@ -20,8 +24,6 @@ module Innate
     # @author manveru
     def call
       Current.actions << self
-      self.instance = node.new
-      self.variables[:content] ||= nil
       render
     ensure
       Current.actions.delete(self)
@@ -54,6 +56,11 @@ module Innate
       from_action
     end
 
+    COPY_VARIABLES = '
+      STATE[:action_variables].each do |iv, value|
+        instance_variable_set("@#{iv}", value)
+      end'.strip.freeze
+
     # Copy Action#variables as instance variables into the given binding.
     #
     # This relies on Innate::STATE, so should be thread-safe and doesn't depend
@@ -71,25 +78,26 @@ module Innate
       STATE.sync do
         STATE[:action_variables] = self.variables
 
-        binding.eval('
-          STATE[:action_variables].each do |iv, value|
-            instance_variable_set("@#{iv}", value)
-          end')
+        eval(COPY_VARIABLES, binding)
 
         STATE[:action_variables] = nil
       end
     end
 
     def render
+      self.instance = node.new
+      self.variables[:content] ||= nil
+
       instance.wrap_action_call(self) do
         self.value = instance.__send__(method, *params) if method
         self.view_value = File.read(view) if view
-      end
 
-      content_type, body = send(Innate.options.action.wish[wish] || :as_html)
-      Current.response['Content-Type'] ||= content_type
+        content_type, body = send(Innate.options.action.wish[wish] || :as_html)
+        response = Current.response
+        response['Content-Type'] ||= content_type if response
 
-      body
+        body
+      end
     end
 
     # @return [Array] Content-Type and rendered action

data/lib/innate/cache.rb

@@ -92,8 +92,8 @@ module Innate
       self.send("#{key}=", cache)
     end
 
-    def self.add(name)
-      register(new(name))
+    def self.add(*names)
+      names.each{|name| register(new(name)) }
     end
 
     def clear

data/lib/innate/cache/api.rb

@@ -29,17 +29,18 @@ module Innate
       # Some parameters identifying the current process will be passed so
       # caches that act in one global name-space can use them as a prefix.
       #
-      # Treat all arguments as Strings.
-      #
-      # +hostname+  the hostname of the machine.
-      # +username+  user executing this process.
-      # +appname+   identifier for the application being executed.
-      # +cachename+ name-space of the cache, like 'session' or 'action'
+      # @param [String #to_s] hostname  the hostname of the machine
+      # @param [String #to_s] username  user executing the process
+      # @param [String #to_s] appname   identifier for the application
+      # @param [String #to_s] cachename namespace, like 'session' or 'action'
+      # @author manveru
       def cache_setup(hostname, username, appname, cachename)
       end
 
       # Remove all key/value pairs from the cache.
       # Should behave as if #delete had been called with all +keys+ as argument.
+      #
+      # @author manveru
       def cache_clear
         clear
       end
@@ -49,6 +50,16 @@ module Innate
       #
       # If only one key was deleted, answer with the corresponding value.
       # If multiple keys were deleted, answer with an Array containing the values.
+      #
+      # NOTE: Due to differences in the underlying implementation in the
+      #       caches, some may not return the deleted value as it would mean
+      #       another lookup before deletion. This is the case for caches on
+      #       memcached or any database system.
+      #
+      # @param [Object] key the key for the value to delete
+      # @param [Object] keys any other keys to delete as well
+      # @return [Object Array nil]
+      # @author manveru
       def cache_delete(key, *keys)
         if keys.empty?
           if value = yield(key)
@@ -61,6 +72,12 @@ module Innate
 
       # Answer with the value associated with the +key+, +nil+ if not found or
       # expired.
+      #
+      # @param [Object] key     the key for which to fetch the value
+      # @param [Object] default will return this if no value was found
+      # @return [Object]
+      # @see Innate::Cache#fetch Innate::Cache#[]
+      # @author manveru
       def cache_fetch(key, default = nil)
         value = default
 
@@ -91,6 +108,11 @@ module Innate
       #   sleep 21
       #   Cache.value.fetch(:num) # => nil
       #
+      # @param [Object] key     the value is stored with this key
+      # @param [Object] value   the key points to this value
+      # @param [Hash]   options for now, only :ttl => Fixnum is used.
+      # @see Innate::Cache#store Innate::Cache#[]=
+      # @author manveru
       def cache_store(key, value, options = {})
         ttl = options[:ttl]
 

data/lib/innate/dynamap.rb

@@ -9,11 +9,11 @@ module Innate
 
     # Delegate the call to the current Rack::URLMap instance.
     #
-    # NOTE: Currently Rack::URLMap will destructively modify PATH_INFO and
-    #       SCRIPT_NAME, which leads to incorrect routing as parts of the
-    #       PATH_INFO are cut out if they matched once.
-    #       Here I repair this damage and hope that my patch to rack will be
-    #       accepted.
+    # @note Currently Rack::URLMap will destructively modify PATH_INFO and
+    #   SCRIPT_NAME, which leads to incorrect routing as parts of the PATH_INFO
+    #   are cut out if they matched once. Here I repair this damage and hope
+    #   that my patch to rack will be accepted.
+    #   Update: patch was accepted, will remove it on next rack release
     def self.call(env)
       if app = CACHE[:map]
         script_name, path_info = env['SCRIPT_NAME'], env['PATH_INFO']
@@ -33,49 +33,49 @@ module Innate
     end
   end
 
-  module_function
-
-  # Maps the given +object+ or +block+ to +location+, +object+ must respond to
-  # #call in order to be of any use.
-  #
-  # Usage with passed +object+:
-  #
-  #   Innate.map('/', lambda{|env| [200, {}, "Hello, World"] })
-  #   Innate.at('/').call({}) # => [200, {}, "Hello, World"]
-  #
-  # Usage with passed +block+:
-  #
-  #   Innate.map('/'){|env| [200, {}, ['Hello, World!']] }
-  #   Innate.at('/').call({})
-  def map(location, object = nil, &block)
-    DynaMap.map(location, object || block)
-  end
+  module SingletonMethods
+    # Maps the given +object+ or +block+ to +location+, +object+ must respond to
+    # #call in order to be of any use.
+    #
+    # @example with passed +object+
+    #
+    #   Innate.map('/', lambda{|env| [200, {}, "Hello, World"] })
+    #   Innate.at('/').call({}) # => [200, {}, "Hello, World"]
+    #
+    # @example with passed +block+
+    #
+    #   Innate.map('/'){|env| [200, {}, ['Hello, World!']] }
+    #   Innate.at('/').call({})
+    def map(location, object = nil, &block)
+      DynaMap.map(location, object || block)
+    end
 
-  # Answer with object at +location+.
-  #
-  # Usage:
-  #
-  #   class Hello
-  #     include Innate::Node
-  #     map '/'
-  #   end
-  #
-  #   Innate.at('/') # => Hello
-  def at(location)
-    DynaMap::MAP[location.to_s]
-  end
+    # Answer with object at +location+.
+    #
+    # @example
+    #
+    #   class Hello
+    #     include Innate::Node
+    #     map '/'
+    #   end
+    #
+    #   Innate.at('/') # => Hello
+    def at(location)
+      DynaMap::MAP[location.to_s]
+    end
 
-  # Returns one of the paths the given +object+ is mapped to.
-  #
-  # Usage:
-  #
-  #   class Hello
-  #     include Innate::Node
-  #     map '/'
-  #   end
-  #
-  #   Innate.to(Hello) # => '/'
-  def to(object)
-    DynaMap::MAP.invert[object]
+    # Returns one of the paths the given +object+ is mapped to.
+    #
+    # @example
+    #
+    #   class Hello
+    #     include Innate::Node
+    #     map '/'
+    #   end
+    #
+    #   Innate.to(Hello) # => '/'
+    def to(object)
+      DynaMap::MAP.invert[object]
+    end
   end
 end

data/lib/innate/helper/aspect.rb

@@ -27,12 +27,14 @@ module Innate
 
       def aspect_wrap(action)
         return yield unless method = action.name
-        
+
         aspect_call(:before_all, method)
         aspect_call(:before, method)
-        yield
+        result = yield
         aspect_call(:after, method)
         aspect_call(:after_all, method)
+
+        result
       end
 
       module SingletonMethods

data/lib/innate/helper/link.rb

@@ -21,13 +21,16 @@ module Innate
       #   Users.r(:foo, :bar)           # => URI('/users/foo/bar')
       #   Users.r(:foo, :a => :b)       # => URI('/users/foo?a=b')
       #   Users.r(:foo, :bar, :a => :b) # => URI('/users/foo/bar?a=b')
+      #
+      # @return [URI] to the location
       def route(name = '/', *args)
         hash = {}
         hashes, names = args.partition{|arg| arg.respond_to?(:merge!) }
         hashes.each{|to_merge| hash.merge!(to_merge) }
 
+        prefix = Innate.options.app.prefix
         location = Innate.to(self) || Innate.to(self.class)
-        front = Array[location, name, *names].join('/').squeeze('/')
+        front = Array[prefix, location, name, *names].join('/').squeeze('/')
 
         if hash.empty?
           URI(front)
@@ -39,11 +42,15 @@ module Innate
       end
       alias r route
 
+      # Create a link tag
+      #
       # Usage, given Wiki is mapped to `/wiki`:
       #   Wiki.a(:home)                   # => '<a href="/wiki/home">home</a>'
       #   Wiki.a('home', :home)           # => '<a href="/wiki/home">home</a>'
       #   Wiki.a('home', :/)              # => '<a href="/wiki/">home</a>'
       #   Wiki.a('foo', :/, :foo => :bar) # => '<a href="/wiki/?foo=bar">foo</a>'
+      #
+      # @return [String]
       def anchor(text, *args)
         href = args.empty? ? r(text) : r(*args)
         text = Rack::Utils.escape_html(text)

data/lib/innate/helper/partial.rb

@@ -55,30 +55,32 @@ module Innate
       # current controller.
       #
       # TODO:
+      # * Doesn't work for absolute paths, but there are no specs for that yet.
       # * the local variable hack isn't working because innate allocates a new
-      #   binding
+      #   binding.
       #   For now one can simply use instance variables, which I prefer anyway.
-      # * Doesn't work for absolute paths, but there are no specs for that yet.
+      #
+      # the local binding hack:
+      #
+      #   variables.each do |key, value|
+      #     value = "ObjectSpace._id2ref(#{value.object_id})"
+      #     eval "#{key} = #{value}", action.binding
+      #   end
+
       def render_template(path, variables = {})
         path = path.to_s
 
         ext = File.extname(path)
         basename = File.basename(path, ext)
-        ext = ext[1..-1]
-
+        ext = ext[1..-1] || action.node.provide[action.wish].to_s
+        
         action = Innate::Current.action.dup
-        action.view   = action.node.find_view(basename, ext)
-        action.method = action.node.find_method(basename, action.params)
+        action.layout    = nil
+        action.view      = action.node.find_view(basename, ext)
+        action.method    = action.node.find_method(basename, action.params)
+        action.variables = action.variables.merge(variables)
         action.sync_variables(action)
-        action.variables.merge!(variables)
-
-=begin
-        variables.each do |key, value|
-          value = "ObjectSpace._id2ref(#{value.object_id})"
-          eval "#{key} = #{value}", action.binding
-        end
-=end
-
+        
         action.call
       end
 

data/lib/innate/node.rb

@@ -1,33 +1,34 @@
 module Innate
 
-  # The nervous system of Innate, so you can relax.
+  # The nervous system of {Innate}, so you can relax.
   #
   # Node may be included into any class to make it a valid responder to
   # requests.
   #
-  # The major difference between this and the Ramaze controller is that every
-  # Node acts as a standalone application with its own dispatcher.
+  # The major difference between this and the old Ramaze controller is that
+  # every Node acts as a standalone application with its own dispatcher.
   #
-  # What's also an important difference is the fact that Node is a module, so
+  # What's also an important difference is the fact that {Node} is a module, so
   # we don't have to spend a lot of time designing the perfect subclassing
   # scheme.
   #
   # This makes dispatching more fun, avoids a lot of processing that is done by
-  # Rack anyway and lets you tailor your application down to the last action
+  # {Rack} anyway and lets you tailor your application down to the last action
   # exactly the way you want without worrying about side-effects to other
-  # nodes.
+  # {Node}s.
   #
-  # Upon inclusion, it will also include Innate::Trinity and Innate::Helper to
-  # provide you with request/response objects, a session and all the standard
-  # helper methods as well as the ability to simply add other helpers.
+  # Upon inclusion, it will also include {Innate::Trinity} and {Innate::Helper}
+  # to provide you with {Innate::Request}, {Innate::Response},
+  # {Innate::Session} instances, and all the standard helper methods as well as
+  # the ability to simply add other helpers.
   #
   # NOTE:
   #   * Although I tried to minimize the amount of code in here there is still
   #     quite a number of methods left in order to do ramaze-style lookups.
   #     Those methods, and all other methods occurring in the ancestors after
-  #     Innate::Node will not be considered valid action methods and will be
+  #     {Innate::Node} will not be considered valid action methods and will be
   #     ignored.
-  #   * This also means that method_missing will not see any of the requests
+  #   * This also means that {method_missing} will not see any of the requests
   #     coming in.
   #   * If you want an action to act as a catch-all, use `def index(*args)`.
 
@@ -59,6 +60,7 @@ module Innate
       Log.debug("Mapped Nodes: %p" % DynaMap::MAP)
     end
 
+    # @return [String] the relative path to the node
     def mapping
       mapped = Innate.to(self)
       return mapped if mapped
@@ -67,7 +69,7 @@ module Innate
     end
 
     # Shortcut to map or remap this Node
-
+    # @param [#to_s] location
     def map(location)
       Innate.map(location, self)
     end
@@ -75,7 +77,7 @@ module Innate
     # This little piece of nasty looking code enables you to provide different
     # content from a single action.
     #
-    # Usage:
+    # @example
     #
     #   class Feeds
     #     include Innate::Node
@@ -127,8 +129,9 @@ module Innate
     def provide(formats = {})
       return ancestral_trait[:provide] if formats.empty?
 
-      trait[:provide] ||= {}
-      formats.each{|pr, as| trait[:provide][pr.to_s] = as.to_s }
+      hash = {}
+      formats.each{|pr, as| hash[pr.to_s] = Array[*as].map{|a| a.to_s } }
+      trait(:provide => hash)
 
       ancestral_trait[:provide]
     end
@@ -168,17 +171,20 @@ module Innate
     end
 
     # Let's try to find some valid action for given +path+.
-    # Otherwise we dispatch to action_not_found
-
+    # Otherwise we dispatch to action_missing
+    #
+    # @param [String] path from request['REQUEST_PATH']
     def try_resolve(path)
       action = resolve(path)
-      action ? action_found(action) : action_not_found(path)
+      action ? action_found(action) : action_missing(path)
     end
 
     # Executed once an Action has been found.
-    # Reset the Response instance, catch :respond and :redirect.
-    # Action#call has to return a String.
-
+    # Reset the {Innate::Response} instance, catch :respond and :redirect.
+    # {Action#call} has to return a String.
+    #
+    # @param [Innate::Action] action
+    # @return [Innate::Response]
     def action_found(action)
       result = catch(:respond){ catch(:redirect){ action.call }}
 
@@ -197,16 +203,18 @@ module Innate
     # * We are doing this is in order to avoid tons of special error handling
     #   code that would impact runtime and make the overall API more
     #   complicated.
-    # * This cannot be a normal action is that methods defined in Innate::Node
-    #   will never be considered for actions.
+    # * This cannot be a normal action is that methods defined in
+    #   {Innate::Node} will never be considered for actions.
     #
     # To use a normal action with template do following:
     #
+    # @example
+    #
     #   class Hi
     #     include Innate::Node
     #     map '/'
     #
-    #     def action_not_found(path)
+    #     def self.action_missing(path)
     #       return if path == '/not_found'
     #       # No normal action, runs on bare metal
     #       try_resolve('/not_found')
@@ -217,11 +225,13 @@ module Innate
     #       "Sorry, I do not exist"
     #     end
     #   end
-
-    def action_not_found(path)
+    #
+    # @param [String] path
+    # @see Innate::Response Node::try_resolve
+    def action_missing(path)
       response.status = 404
       response['Content-Type'] = 'text/plain'
-      response.write("Action not found at: %p" % path)
+      response.write("No action found at: %p" % path)
 
       response
     end
@@ -229,13 +239,21 @@ module Innate
     # Let's get down to business, first check if we got any wishes regarding
     # the representation from the client, otherwise we will assume he wants
     # html.
-
+    #
+    # @param [String] path
+    # @return [nil Action]
+    # @see Node::find_provide Node::update_method_arities Node::find_action
+    # @author manveru
     def resolve(path)
       name, wish = find_provide(path)
       update_method_arities
       find_action(name, wish)
     end
 
+    # @param [String] path
+    # @return [Array] with name and wish
+    # @see Node::provide
+    # @author manveru
     def find_provide(path)
       name, wish = path, 'html'
 
@@ -251,31 +269,38 @@ module Innate
     # if we can't find either we go to the next pattern, otherwise we answer
     # with an Action with everything we know so far about the demands of the
     # client.
-
+    #
+    # @param [String] given_name the name extracted from REQUEST_PATH
+    # @param [String] wish
+    # @author manveru
     def find_action(given_name, wish)
+      needs_method = Innate.options.action.needs_method
+
       patterns_for(given_name) do |name, params|
-        view = find_view(name, wish)
         method = find_method(name, params)
+        view = find_view(name, wish)
 
         next unless view or method
+        next unless method if needs_method
 
         layout = find_layout(name, wish)
+        params ||= []
 
-        Action.create(
-          :node => self, :params => params, :wish => wish, :method => method,
-          :view => view, :options => {}, :variables => {}, :layout => layout)
+        Action.create(:method => method, :params => params, :layout => layout,
+                      :node => self, :view => view, :wish => wish)
       end
     end
 
-    # TODO: allow layouts combined of method and view... hairy :)
+    # @todo allow layouts combined of method and view... hairy :)
     def find_layout(name, wish)
-      return unless found_layout = layout
+      return unless layout = ancestral_trait[:layout]
+      return unless layout = layout.call(name, wish) if layout.respond_to?(:call)
 
-      if found = to_layout(found_layout, wish)
+      if found = to_layout(layout, wish)
         [:layout, found]
-      elsif found = find_view(found_layout, wish)
+      elsif found = find_view(layout, wish)
         [:view, found]
-      elsif found = find_method(found_layout, [])
+      elsif found = find_method(layout, [])
         [:method, found]
       end
     end
@@ -310,31 +335,31 @@ module Innate
     #   def index(a = :a, b = :b)     # => -1
     #   def index(a = :a, b = :b, *r) # => -1
     #
-    # NOTE: Once 1.9 is mainstream we can use Method#parameters to do accurate
+    # @todo Once 1.9 is mainstream we can use Method#parameters to do accurate
     #       prediction
     def find_method(name, params)
       return unless arity = trait[:method_arities][name]
       name if arity == params.size or arity < 0
     end
 
-    # Answer with and set the @method_arities Hash, keys are method names,
-    # values are method arities.
-    #
-    # Usually called from Node::resolve
+    # Answer with a hash, keys are method names, values are method arities.
     #
-    # NOTE:
-    #   * This will be executed once for every request, once we have settled
-    #     things down a bit more we can switch to update based on Reloader
-    #     hooks and update once on startup.
-    #     However, that may cause problems with dynamically created methods, so
-    #     let's play it safe for now.
+    # Note that this will be executed once for every request, once we have
+    # settled things down a bit more we can switch to update based on Reloader
+    # hooks and update once on startup.
+    # However, that may cause problems with dynamically created methods, so
+    # let's play it safe for now.
     #
-    # Example:
+    # @example
     #
     #   Hi.update_method_arities
     #   # => {'index' => 0, 'foo' => -1, 'bar => 2}
+    #
+    # @see Node::resolve
+    # @return [Hash] mapping the name of the methods to their arity
     def update_method_arities
-      arities = trait[:method_arities] = {}
+      arities = {}
+      trait(:method_arities => arities)
 
       exposed = ancestors & Helper::EXPOSE.to_a
       higher = ancestors.select{|a| a < Innate::Node }
@@ -351,6 +376,9 @@ module Innate
     # Try to find the best template for the given basename and wish.
     # Also, having extraordinarily much fun with globs.
     def find_view(file, wish)
+      aliased = find_aliased_view(file, wish)
+      return aliased if aliased
+
       path = [Innate.options.app.root, Innate.options.app.view, view_root, file]
       to_template(path, wish)
     end
@@ -363,38 +391,105 @@ module Innate
       @view_root ||= Innate.to(self)
     end
 
-    def alias_view(to, from)
-      (trait[:alias_view] ||= {})[to] = from
+    # Aliasing one view from another.
+    # The aliases are inherited, and the optional third +node+ parameter
+    # indicates the Node to take the view from.
+    #
+    # The argument order is identical with `alias` and `alias_method`, which
+    # quite honestly confuses me, but at least we stay consistent.
+    #
+    # @example
+    #   class Foo
+    #     include Innate::Node
+    #
+    #     # Use the 'foo' view when calling 'bar'
+    #     alias_view 'bar', 'foo'
+    #
+    #     # Use the 'foo' view from FooBar node when calling 'bar'
+    #     alias_view 'bar', 'foo', FooBar
+    #   end
+    #
+    # Note that the parameters have been simplified in comparision with
+    # Ramaze::Controller::template where the second parameter may be a
+    # Controller or the name of the template.  We take that now as an optional
+    # third parameter.
+    #
+    # @param [#to_s]      to   view that should be replaced
+    # @param [#to_s]      from view to use or Node.
+    # @param [#nil? Node] node optionally obtain view from this Node
+    # @see Node::find_aliased_view
+    # @author manveru
+    def alias_view(to, from, node = nil)
+      trait[:alias_view] || trait(:alias_view => {})
+      trait[:alias_view][to.to_s] = node ? [from.to_s, node] : from.to_s
+    end
+
+    # @param [String] file
+    # @param [String] wish
+    # @return [nil String] the absolute path to the aliased template or nil
+    # @see Node::alias_view Node::find_view
+    # @author manveru
+    def find_aliased_view(file, wish)
+      aliased_file, aliased_node = ancestral_trait[:alias_view][file]
+      aliased_node ||= self
+      aliased_node.find_view(aliased_file, wish) if aliased_file
     end
 
     # Find the best matching file for the layout, if any.
+    #
+    # @param [String] file
+    # @param [String] wish
+    # @return [nil String] the absolute path to the template or nil
+    # @see Node::to_template
+    # @author manveru
     def to_layout(file, wish)
       path = [Innate.options.app.root, Innate.options.app.layout, file]
       to_template(path, wish)
     end
 
+    # @param [String] file
+    # @param [String] wish
+    # @return [nil String] the absolute path to the template or nil
+    # @see Node::find_view Node::to_layout Node::find_aliased_view
+    # @author manveru
     def to_template(path, wish)
       return unless path.all?
 
-      path = File.join(*path.map{|pa| pa.to_s })
-      exts = [provide[wish], *provide.keys].flatten.compact.uniq.join(',')
-      found = Dir["#{path}.{#{wish}.,#{wish},}{#{exts},}"].uniq
+      path = File.join(*path.map{|pa| pa.to_s.split('__') }.flatten)
+      exts = (Array[provide[wish]] + provide.keys).flatten.compact.uniq.join(',')
+      glob = "#{path}.{#{wish}.,#{wish},}{#{exts},}"
+      found = Dir[glob].uniq
 
       if found.size > 1
         Log.warn("%d views found for %p | %p" % [found.size, path, wish])
       end
 
-      template = found.first
-      ancestral_trait[:alias_view][template] || template
+      found.first
     end
 
-    # Set the +name+ of the layout you want, this takes only the basename
-    # without any filename-extension or directory.
-    def layout(name = nil)
-      name ? trait(:layout => name) : ancestral_trait[:layout]
+    # Define a layout to use on this Node.
+    #
+    # @param [String #to_s] name basename without extension of the layout to use
+    # @param [Proc #call] block called on every dispatch if no name given
+    # @return [Proc String] The assigned name or block
+    #
+    # @note The behaviour of Node#layout changed significantly from Ramaze,
+    #   instead of multitudes of obscure options and methods like deny_layout
+    #   we simply take a block and use the returned value as the name for the
+    #   layout. No layout will be used if the block returns nil.
+    def layout(name = nil, &block)
+      if name and block
+        trait(:layout => lambda{|n, w| name if block.call(n, w) })
+      elsif name
+        trait(:layout => name.to_s)
+      elsif block
+        trait(:layout => block)
+      end
+
+      return ancestral_trait[:layout]
     end
 
-    # The innate beauty in Nitro, Ramaze, and Innate.
+    # The innate beauty in Nitro, Ramaze, and {Innate}.
     #
     # Will yield the name of the action and parameter for the action method in
     # order of significance.
@@ -407,23 +502,22 @@ module Innate
     # The last fallback will always be the index action with all of the path
     # turned into parameters.
     #
-    # Samples:
-    #
+    # @usage
     #   class Foo; include Innate::Node; map '/'; end
     #
     #   Foo.patterns_for('/'){|action, params| p action => params }
-    #   {"index"=>[]}
+    #   # => {"index"=>[]}
     #
     #   Foo.patterns_for('/foo/bar'){|action, params| p action => params }
-    #   {"foo__bar"=>[]}
-    #   {"foo"=>["bar"]}
-    #   {"index"=>["foo", "bar"]}
+    #   # => {"foo__bar"=>[]}
+    #   # => {"foo"=>["bar"]}
+    #   # => {"index"=>["foo", "bar"]}
     #
     #   Foo.patterns_for('/foo/bar/baz'){|action, params| p action => params }
-    #   {"foo__bar__baz"=>[]}
-    #   {"foo__bar"=>["baz"]}
-    #   {"foo"=>["bar", "baz"]}
-    #   {"index"=>["foo", "bar", "baz"]}
+    #   # => {"foo__bar__baz"=>[]}
+    #   # => {"foo__bar"=>["baz"]}
+    #   # => {"foo"=>["bar", "baz"]}
+    #   # => {"index"=>["foo", "bar", "baz"]}
     def patterns_for(path)
       atoms = path.split('/')
       atoms.delete('')
@@ -452,7 +546,6 @@ module Innate
     # @param [Proc] block contains the instructions to call the action method if any
     # @see Action#render
     # @author manveru
-
     def wrap_action_call(action, &block)
       wrap = ancestral_trait[:wrap]
 
@@ -468,4 +561,40 @@ module Innate
     # @author manveru
     def binding; super; end
   end
+
+  module SingletonMethods
+    # Convenience method to include the Node module into +node+ and map to a
+    # +location+.
+    #
+    # @param [#to_s]    location where the node is mapped to
+    # @param [Node nil] node     the class that will be a node, will try to look it
+    #                            up if not given
+    # @return [Class] the node argument or detected class will be returned
+    # @see Innate::node_from_backtrace
+    # @author manveru
+    def node(location, node = nil)
+      node ||= node_from_backtrace(caller)
+      node.__send__(:include, Node)
+      node.map(location)
+      node
+    end
+
+    # Cheap hack that works reasonably well to avoid passing self all the time
+    # to Innate::node
+    # We simply search the file that Innate::node was called in for the first
+    # class definition above the line that Innate::node was called and look up
+    # the constant.
+    # If there are any problems with this (filenames containing ':' or
+    # metaprogramming) just pass the node parameter explicitly to Innate::node
+    #
+    # @param [Array #[]] backtrace
+    # @see Innate::node
+    # @author manveru
+    def node_from_backtrace(backtrace)
+      file, line = backtrace[0].split(':', 2)
+      line = line.to_i
+      File.readlines(file)[0..line].reverse.find{|line| line =~ /^\s*class\s+(\S+)/ }
+      const_get($1)
+    end
+  end
 end