addressive 0.1.0.alpha

data/addressive.gemspec

@@ -0,0 +1,22 @@
+Gem::Specification.new do |s|
+  s.name = 'addressive'
+  s.version = '0.1.0.alpha'
+  s.date = '2011-11-23'
+  s.authors = ["HannesG"]
+  s.email = %q{hannes.georg@googlemail.com}
+  s.summary = 'A system which should help bringing different Rack applications together.'
+  s.homepage = 'https://github.com/hannesg/addressive'
+  s.description = ''
+  
+  s.require_paths = ['lib']
+  
+  s.files = Dir.glob('lib/**/**/*.rb') + ['addressive.gemspec']
+  
+  s.add_dependency 'uri_template', '~> 0.1.4'
+  
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'rack'
+  
+end

data/lib/addressive/graph.rb

@@ -0,0 +1,229 @@
+# -*- encoding : utf-8 -*-
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the Affero GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#    (c) 2011 by Hannes Georg
+#
+
+module Addressive
+
+  # A graph is basically a hash of nodes and some builder methods.
+  # Graphs are only used to generate nodes and their relations.
+  # They will be GCed when they are done.
+  class Graph
+    
+    # An app builder is used to add uris for a certain app to a node.
+    class AppBuilder
+    
+      # @private
+      def initialize(node, factory, app)
+        @node = node
+        @app = app
+        @spec_factory = factory
+      end
+      
+      # Sets a default value for an option.
+      def default(name, value)
+        @spec_factory.defaults[name] = value
+      end
+      
+      # Adds one or more uri specs for a given name. It uses the current app as the default app for all specs.
+      def uri(name,*args)
+        specs = @node.uri_spec(name)
+        specs << @spec_factory.convert(*args)
+        return specs
+      end
+    
+    end
+    
+    # A NodeBuilder is used to build a Node inside a Graph.
+    # This class should not be generated directly, it's created for you by {Builder#node}.
+    class NodeBuilder
+  
+      attr_reader :node
+      
+      # @private
+      def initialize(network,node)
+        @network = network
+        @node = node
+        @spec_factory = network.spec_factory.derive({})
+      end
+      
+      # Adds an edge from the current node to a node with the given name.
+      # 
+      # @example
+      #   nw = Addressive::Graph.new{
+      #     #create a node named :app_a
+      #     node :app_a do
+      #       # Creates an edge to the node named :app_b. The name of the edge will be :app_b, too.
+      #       edge :app_b 
+      #
+      #       # Creates another edge to the node named :app_b with edge name :app_c.
+      #       edge :app_c, :app_b
+      #
+      #       # Edge takes a block. Same behavior as Builder#node.
+      #       edge :app_d do
+      #         
+      #         edge :app_a
+      #       
+      #       end
+      #     end
+      #   }
+      #   # :app_a now references :app_b twice, :app_d once and is referenced only by :app_d.
+      #
+      # @yield BlockBuilder
+      #
+      def edge(as , name = as, &block)
+        @node.edges[as] = @network.build.node(name,&block).node
+        return self
+      end
+      
+      alias ref edge
+      
+      # Sets a default value for an option.
+      def default(name, value)
+        @spec_factory.defaults[name] = value
+      end
+      
+      # Adds one or more uri specs for a given name.
+      def uri(name,*args)
+        @node.uri_spec(name) << @spec_factory.convert(args)
+        return @node.uri_spec(name)
+      end
+      
+      # Adds an rack-application to this node.
+      #
+      # @example
+      #
+      #   Addressive::Graph.new{
+      #     
+      #     node :a_node do
+      #       
+      #       app lambda{|env| [200,{},['App 1']]} do
+      #         uri :show, '/a_node/app1'
+      #       end
+      #       
+      #       app lambda{|env| [200,{},['App 2']]} do
+      #         uri :show, '/a_node/app2'
+      #       end
+      #     
+      #     end
+      #   
+      #   }
+      #
+      # @yield {AppBuilder}
+      # @return {AppBuilder}
+      def app(app, options = {}, &block)
+        app = app.to_app if app.respond_to? :to_app
+        sf = @spec_factory.derive(options.merge(:app=>app))
+        builder = AppBuilder.new(@node,sf,app)
+        if block
+          if block.arity == 1
+            yield builder
+          else
+            builder.instance_eval(&block)
+          end
+        end
+        unless @node.apps.include? app
+          @node.apps << app
+          if app.respond_to? :generate_uri_specs
+            app.generate_uri_specs(builder)
+          end
+        end
+        return builder
+      end
+      
+    end
+  
+    # A Builder is used to construct a network.
+    # It's here so that a {Graph} can have only read methods, while a {Builder} does the heavy lifting.
+    # This class should not be generated directly, it's created for you by {Graph#build} and {Graph#initialize}.
+    class Builder
+      
+      # @private
+      def initialize(network)
+        @network = network
+      end
+    
+      # Creates or edits the node with the given name in the current network and yields and returns a NodeBuilder.
+      # This NodeBuilder can then be use to actually describe the node.
+      #
+      # @yield {NodeBuilder}
+      # @return {NodeBuilder}
+      def node(name, &block)
+        n = @network.node(name)
+        if block
+          if block.arity == 1
+            yield @network.node_builder_class.new(@network, n)
+          else
+            @network.node_builder_class.new(@network, n).instance_eval(&block)
+          end
+        end
+        return @network.node_builder_class.new(@network, n)
+      end
+      
+      # Sets a network-wide default.
+      # @note
+      #   Only nodes created after this default has been set will receive this value.
+      #
+      def default(name,value)
+        @network.spec_factory.defaults[name]=value
+      end
+    
+    end
+    
+    # @private
+    def configure(node)
+      return node
+    end
+
+    # @private
+    attr_reader :node_class, :node_builder_class, :spec_factory
+    
+    # Creates a new Graph.
+    # @yield {Builder}
+    def initialize(&block)
+      @defaults = {}
+      @node_class = Class.new(Node)
+      @node_builder_class = Class.new(NodeBuilder)
+      @spec_factory = URISpecFactory.new({})
+      @nodes = Hash.new{|hsh, name| hsh[name] = configure(node_class.new) }
+      build(&block)
+    end
+    
+    # Creates, yields and returns a {Builder} for this network.
+    #
+    # @yield {Builder}
+    # @return {Builder}
+    def build(&block)
+      if block
+        if block.arity == 1
+          yield Builder.new(self)
+        else
+          Builder.new(self).instance_eval(&block)
+        end
+      end
+      return Builder.new(self)
+    end
+    
+    # Return the node with the given name.
+    # @note
+    #   A Graph will automatically create nodes if they don't exists.
+    def [](name)
+      return @nodes[name]
+    end
+  
+    alias node []
+  
+  end
+end

data/lib/addressive/graphviz.rb

@@ -0,0 +1,21 @@
+# -*- encoding : utf-8 -*-
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the Affero GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#    (c) 2011 by Hannes Georg
+#
+
+module Addressive
+
+  # A module to visualize 
+  module Graphviz

data/lib/addressive/request.rb

@@ -0,0 +1,43 @@
+# -*- encoding : utf-8 -*-
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the Affero GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#    (c) 2011 by Hannes Georg
+#
+
+require 'rack/request'
+
+module Addressive
+
+  # A patched rack-request, which uses the addressive data if for the GET and uri methods.
+  class Request < Rack::Request
+  
+    def GET
+      if @env[ADDRESSIVE_ENV_KEY]
+        return @env[ADDRESSIVE_ENV_KEY].variables
+      else
+        super
+      end
+    end
+    
+    def uri(*args)
+      if @env[ADDRESSIVE_ENV_KEY]
+        @env[ADDRESSIVE_ENV_KEY].uri(*args)
+      else
+        self.url
+      end
+    end
+    
+  end
+
+end

data/lib/addressive/router.rb

@@ -0,0 +1,337 @@
+# -*- encoding : utf-8 -*-
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the Affero GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#    (c) 2011 by Hannes Georg
+#
+
+require 'rack/request'
+require 'thread'
+
+module Addressive
+
+  class Match < Struct.new(:node,:action,:variables, :spec, :data)
+  
+    include URIBuilder
+  
+  end
+
+  # A router which can be used as a rack application and routes requests to nodes and their apps.
+  #
+  class Router
+  
+    # @private
+    class Tree
+    
+      # @private
+      class Direct < self
+      
+        class EachingProc < Proc
+        
+          def initialize(routes)
+            @routes = routes
+          end
+        
+          alias each call
+          
+          def size
+            @routes.size
+          end
+        
+        end
+      
+        def initialize
+          @routes = []
+        end
+      
+        def preroute(path, uri)
+          return self
+        end
+        
+        def <<(spec)
+          @routes << spec
+        end
+        
+        def clear!
+          @routes = []
+        end
+        
+        def size
+          @routes.size
+        end
+        
+        def done!
+          # compile *gnihihi*
+          code = ['def each(path,uri); routes = Enumerator.new(@routes);',
+            *@routes.each_with_index.map{|r,i|
+              "route = routes.next
+              vars = route.template.extract(#{r.template.absolute? ? 'uri' : 'path'})
+              if vars
+                yield( route, vars, #{i} )
+              end
+              "
+            } ,'; end'].join
+          instance_eval(code)
+        end
+        
+        def each(path,uri)
+          @routes.each_with_index do |route,i|
+            vars = route.template.extract(route.template.absolute? ? uri : path)
+            if vars
+              yield( route, vars, i )
+            end
+          end
+        end
+      
+      end
+      
+      # @private
+      class SubstringSplit < self
+      
+        def initialize(substring, *partitions)
+          @substring = substring
+          @partitions = partitions
+        end
+        
+        def preroute(path,uri)
+          @partitions[ uri.include?(@substring) ? 0 : 1 ].preroute(uri,path)
+        end
+        
+        def <<(spec)
+          if spec.template.send(:tokens).select(&:literal?).none?{|tk| tk.string.include? @substring }
+            # okay, this template does not require the substring.
+            # so it can be matched, even when the substring is missing
+            @partitions[1] << spec
+          end
+          @partitions[0] << spec
+        end
+        
+        
+        def clear!
+          @partitions[0].clear!
+          @partitions[1].clear!
+        end
+        
+        def done!
+          @partitions[0].done!
+          @partitions[1].done!
+        end
+      
+      end
+      
+      # @private
+      class PrefixSplit < self
+      
+        def initialize(prefix, *partitions)
+          @prefix = prefix
+          @partitions = partitions
+        end
+        
+        def preroute(path,uri)
+          @partitions[ path.start_with?(@prefix) ? 0 : 1 ].preroute(uri,path)
+        end
+        
+        def <<(spec)
+          if spec.template.absolute?
+            @partitions[0] << spec
+            @partitions[1] << spec
+          else
+            tkns = spec.template.send(:tokens)
+            if tkns.empty?
+              # emtpy uri, no problem?!
+              @partitions[0] << spec
+              @partitions[1] << spec
+              return
+            end
+            tk = tkns.first
+            if tk.literal?
+              if tk.string.start_with?(@prefix)
+                @partitions[0] << spec
+              elsif @prefix.start_with?(tk.string) and tkns[1]
+                @partitions[0] << spec
+                @partitions[1] << spec
+              else
+                @partitions[1] << spec
+              end
+            else
+              @partitions[0] << spec
+              @partitions[1] << spec
+            end
+          end
+          
+        end
+        
+        
+        def clear!
+          @partitions[0].clear!
+          @partitions[1].clear!
+        end
+        
+        def done!
+          @partitions[0].done!
+          @partitions[1].done!
+        end
+      
+      end
+    
+    end
+  
+    DEBUG_NAME = 'addressive-router'.freeze
+    DEBUG_NULL = lambda{|_| nil}
+  
+    attr_reader :routes, :actions
+  
+    def initialize(tree = Tree::Direct.new)
+      @routes = []
+      @actions = {}
+      @tree = tree
+      @immaterial = true
+      @mutex = Mutex.new
+      @sealed = false
+    end
+    
+    # Add a nodes specs to this router.
+    def add(*nodes)
+      @mutex.synchronize do
+        raise "Trying to add nodes to a sealed router!" if @sealed 
+        nodes.each do |node|
+          node.uri_specs.each do |action, specs|
+            specs.each do |spec|
+              if spec.valid? and spec.app and spec.route != false
+                @routes << spec
+                @actions[spec] = [node, action]
+              end
+            end
+          end
+        end
+        @immaterial = true
+      end
+      return self
+    end
+    
+    # Routes the env to an app and it's node.
+    def call(env)
+      rr = Rack::Request.new(env)
+      l = env['rack.logger']
+      db = l ? l.method(:debug) : DEBUG_NULL
+      db.call(DEBUG_NAME) do
+        "[ ? ] #{rr.url.inspect}"
+      end
+      matches = routes_for(rr.path, rr.url)
+      result = nil
+      matches.each do |addressive|
+        env[ADDRESSIVE_ENV_KEY] = addressive
+        begin
+          result = addressive.spec.app.call(env)
+          db.call(DEBUG_NAME) do
+            "[#{result[0]}] #{addressive.spec.template.pattern} with #{addressive.variables.inspect} on #{addressive.spec.app} ( route #{addressive.data[:'routes.scanned']} / #{addressive.data[:'routes.total']} ) after #{'%.6f' % addressive.data[:duration]}"
+          end
+        rescue
+          db.call(DEBUG_NAME) do
+            "[!!!] #{addressive.spec.template.pattern} with #{addressive.variables.inspect} on #{addressive.spec.app} ( route #{addressive.data[:'routes.scanned']} / #{addressive.data[:'routes.total']} ) after #{'%.6f' % addressive.data[:duration]}"
+          end
+          raise
+        end
+        if result[0] != 404
+          break
+        end
+      end
+      if result.nil?
+        db.call(DEBUG_NAME) do
+          "[404] Nothing found"
+        end
+        return not_found(env)
+      end
+      return result
+    end
+    
+    class RouteEnumerator
+    
+      include Enumerable
+    
+      # @private
+      def initialize(routes,path,url,actions)
+        @routes,@path,@url,@actions = routes, path, url, actions
+      end
+      
+      # @yield {Addressive::Match}
+      def each
+        total = @routes.size
+        scan_time = Time.now
+        @routes.each(@path,@url) do |spec, vars, scanned|
+          node, action = @actions[spec];
+          t = Time.now
+          yield Match.new(node, action, vars, spec, {:'routes.scanned'=>scanned,:'routes.total'=>total,:duration => (t - scan_time)})
+          # still here?, the passed time should be added
+          scan_time += (Time.now - t)
+        end
+      
+      end
+    
+    end
+    
+    #
+    # @param path String the path to look for
+    # @param uri String the full uri
+    # @return {RouteEnumerator} an enumerator which yields the requested routes
+    def routes_for(path, uri)
+      materialize!
+      return RouteEnumerator.new(@tree.preroute(path,uri),path,uri,@actions)
+    end
+    
+    # @private
+    def to_app
+      return self
+    end
+    
+    # Prevents further editing of this router.
+    # This is not mandatory, but encouraged if later changes are not required.
+    #
+    # @example
+    #   rtr = Addressive::Router.new
+    #   rtr.add( Addressive.node ) # okay
+    #   rtr.seal!
+    #   rtr.add( Addressive.node ) #!> Exception
+    #
+    def seal!
+      @mutex.synchronize do
+        @sealed = true
+      end
+      materialize!
+    end
+    
+  protected
+    
+    # This method is called when no route was found.
+    def not_found(env)
+      [404,{'Content-Type'=>'text/plain','X-Cascade'=>'pass'},['Ooooopppps 404!']]
+    end
+    
+  private
+  
+    def materialize!
+      return unless @immaterial
+      @mutex.synchronize do
+        return unless @immaterial
+        @routes.sort_by!{|spec| spec.template.static_characters }.reverse!
+        @tree.clear!
+        @routes.each do |spec|
+          @tree << spec
+        end
+        @tree.done!
+        @immaterial = false
+      end
+    end
+  
+  end
+end

data/lib/addressive/static.rb

@@ -0,0 +1,71 @@
+# -*- encoding : utf-8 -*-
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the Affero GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#    (c) 2011 by Hannes Georg
+#
+
+require 'rack/file'
+
+module Addressive
+
+  # Similiar to Rack::Static but lives happily on a node.
+  # Emits just one uri-spec with name ":get" and a simple catch-all uri.
+  #
+  # @example
+  #   node = Addressive.node{
+  #     app Addressive::Static.new(:root=>'/tmp')
+  #   }
+  #   node.uri(:get,'file'=>'baz').to_s #=> "/baz"
+  #   
+  #   # Create a file, so this won't be a 404:
+  #   File.new('/tmp/baz','w').close
+  #   router = Addressive::Router.new.add(node)
+  #   status,headers,body = router.call('rack.url_scheme'=>'http','PATH_INFO'=>'/baz','HTTP_HOST'=>'example.example')
+  #   body.class #=> Rack::File
+  #   body.path #=> "/tmp/baz"
+  #
+  class Static
+  
+    def generate_uri_specs(builder)
+    
+      builder.uri :get, '/{+file}'
+    
+    end
+    
+    def call(env)
+      env['PATH_INFO'] = env['addressive'].variables['file']
+      return @file_server.call(env)
+    end
+    
+    # @param [Hash] options
+    # @option options [#call,Rack::File] :file_server A class compatible to Rack::File. If supplied this will be used instead of the default rack file server
+    # @option options [String] :root The directory to search files in. Same as for Rack::File.
+    # @option options [Obect] :cache_control Same as for Rack::File.
+    def initialize(options={})
+      unless options.key? :file_server
+        root = options[:root] || Dir.pwd
+        cache_control = options[:cache_control]
+        @file_server = Rack::File.new(root, cache_control)
+      else
+        @file_server = options[:file_server]
+      end
+    end
+    
+    def to_s
+      "Static[#{@file_server.inspect}]"
+    end
+  
+  end
+
+end

data/lib/addressive.rb

@@ -0,0 +1,404 @@
+# -*- encoding : utf-8 -*-
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the Affero GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#    (c) 2011 by Hannes Georg
+#
+
+$LOAD_PATH << File.expand_path('../../uri_template7/lib/',File.dirname(__FILE__))
+require File.expand_path('../../uri_template7/lib/uri_template',File.dirname(__FILE__))
+require 'ostruct'
+
+# Addressive is library which should make it possible for different rack-applications to live together on the same server.
+# To accomplish this, addressive supplies you with:
+#   - A model for a graph in which each node is one application.
+#   - A template-based uri-builder which is aware of the network and can generate uri for any reachable application.
+#   - A router which can route rack-requests based on the known templates.
+#
+# What needs to be done by the apps:
+#   - Provide uri templates.
+#
+module Addressive
+
+  autoload :Static, 'addressive/static'
+  autoload :Request, 'addressive/request'
+  autoload :Router, 'addressive/router'
+  autoload :Graph, 'addressive/graph'
+
+  ADDRESSIVE_ENV_KEY = 'addressive'.freeze
+
+  class Error < StandardError
+  
+  end
+
+  # This error is raised whenever no uri spec could be found.
+  class NoURISpecFound < Error
+    
+    attr_reader :builder
+    
+    def initialize(builder)
+      @builder = builder
+      super("No URISpec found for #{builder.inspect}. Only got: #{builder.node.uri_specs.keys.join(', ')}")
+    end
+  
+  end
+  
+  class NoEdgeFound < Error
+  
+    attr_reader :node, :edge
+    
+    def initialize(node, edge)
+      @node, @edge = node, edge
+      super("No Edge '#{edge.inspect}' found, only got '#{node.edges.keys.map(&:inspect).join('\', \'')}'")
+    end
+  
+  end
+
+  # A module for any class, which can create uris.
+  module URIBuilder
+  
+    def self.new(*args)
+      URIBuilderClass.new(*args)
+    end
+  
+    def derive_uri_builder(action, variables, node)
+      origin = self.origin rescue nil
+      return URIBuilderClass.new( origin, action, variables, node )
+    end
+    
+    protected :derive_uri_builder
+  
+    # Creates a new URIBuilder with the given arguments.
+    # Given Hashes are merged into the variables. The last symbol is used to determine the action. Everything else is used to traverse the node graph.
+    # 
+    # @example
+    #   node = Addressive::Node.new
+    #   node.uri_spec(:show) << Addressive::URISpec.new( URITemplate.new('/an/uri/with/{var}') )
+    #   bldr = Addressive::URIBuilder.new(node)
+    #   bldr.uri(:show, 'var'=>'VAR!').to_s #=> '/an/uri/with/VAR%21'
+    #
+    # @return URIBuilder
+    def uri(*args)
+      return uri_builder_delegate.uri(*args) if uri_builder_delegate
+      hashes, path = args.collect_concat{|a| a.respond_to?(:to_addressive) ? a.to_addressive : [a] }.partition{|x| x.kind_of? Hash}
+      node = self.node
+      action = self.action
+      if path.size >= 1
+        node = node.traverse(*path[0..-2])
+        action = path.last
+      end
+      derive_uri_builder(action, hashes.inject(self.variables || {}, &:merge), node)
+    end
+    
+    private
+    
+    def uri_builder_delegate
+      nil
+    end
+  
+  end
+
+  # A builder which creates uri based on a Node an action and some variables.
+  class URIBuilderClass
+  
+    include URIBuilder
+
+    attr_reader :origin,:node,:variables,:action
+
+    # @private
+    def initialize(origin, action=:default, vars={}, node=origin)
+      @origin = origin
+      @node = node
+      @action = action
+      @variables = vars
+    end
+    
+    # @private
+    def inspect
+      '<URIBuilder '+self.action.inspect+' '+self.variables.inspect+'>'
+    end
+    
+    # Actually creates the URI as a string
+    #
+    # @return String
+    def to_s
+      return uri_builder_delegate.to_s if uri_builder_delegate
+      specs = uri_builder_specs
+      # if a.none? ????
+      if specs.none?
+        raise NoURISpecFound.new(self)
+      end
+      return specs.first.template.expand(self.variables || {}).to_s
+    end
+    
+    def humanization_key
+      specs = uri_builder_specs
+      if specs.none?
+        return super
+      else
+        return specs.first.app._(:action,self.action,self.variables || {} )
+      end
+    end
+  private
+    def uri_builder_specs
+      return @specs ||= begin
+        varnames = (self.variables || {} ).keys
+        self.node.uri_spec(self.action).select{|s| s.valid? and (s.variables - varnames).none? }.sort_by{|s| (varnames - s.variables).size }
+      end
+    end
+  end
+  
+  # A specification is a combination of an URI template and some meta-data ( like the app this spec belongs to ).
+  class URISpec < OpenStruct
+    
+    attr_accessor :template
+    
+    def valid?
+      !!@template
+    end
+    
+    def variables
+      @template ? @template.variables : []
+    end
+    
+    def initialize(template, *args)
+      @template = template
+      super(*args)
+    end
+    
+    def inspect
+      ['#<',self.class.name,': ',template.inspect,*@table.map{|k,v| " #{k}=#{v.inspect}"},'>'].join
+    end
+    
+  end
+  
+  # A URISpecFactory contains all information necessary to create a URISpec.
+  # This class exists because it's annoying to pass around default values by hand and
+  # a factory makes it possible to apply post-processing options.
+  class URISpecFactory
+  
+    def converter(defaults = self.all_defaults)
+      lambda{|spec|
+        if spec.kind_of? URISpec
+          [ normalize( spec.dup, defaults ) ]
+        elsif spec.kind_of? URITemplate
+          [ normalize( URISpec.new( spec ) , defaults) ]
+        elsif spec.kind_of? String
+          [ normalize( URISpec.new( URITemplate.new(spec) ) , defaults) ]
+        elsif spec.kind_of? Array
+          spec.map(&self.converter(defaults))
+        elsif spec.kind_of? Hash
+          nd = defaults.merge(spec)
+          self.converter(nd).call(nd[:template])
+        else
+          []
+        end
+      }
+    end
+    
+    protected :converter
+  
+    def normalize( spec, defaults = self.all_defaults )
+      if defaults.key? :app 
+        spec.app = defaults[:app]
+      end
+      unless spec.template.absolute?
+        if defaults[:prefix]
+          spec.template = URITemplate.apply( defaults[:prefix] , :/ ,  spec.template)
+        end
+      end
+      return spec
+    end
+  
+    attr_reader :defaults
+    
+    def initialize(defaults, parent = nil)
+      @defaults = defaults
+      @parent = parent
+    end
+    
+    def convert(*args)
+      args.map(&converter).flatten
+    end
+    
+    alias << convert
+    
+    def all_defaults
+      @parent ? @parent.all_defaults.merge(defaults) : defaults
+    end
+    
+    def derive(nu_defaults)
+      self.class.new(nu_defaults, self)
+    end
+  
+  end
+  
+  # A list of {URISpec}s. Useful because it checks the input.
+  class URISpecList
+  
+    include Enumerable
+  
+    def initialize(factory, source = [])
+      @specs = [] 
+      self.<<(*source)
+    end
+    
+    def each(&block)
+      @specs.each(&block)
+    end
+    
+    def <<(*args)
+      args = args.flatten
+      fails = args.select{|a| !a.kind_of? URISpec }
+      raise ArgumentError, "Expected to receive only URISpecs but, got #{fails.map(&:inspect).join(', ')}" if fails.size != 0
+      @specs.push( *args )
+    end
+    
+    alias push <<
+  
+  end
+  
+  # The node is the most important class. A node bundles informations about all uri specs for a certain application.
+  # Furthermore nodes can reference each other so that one can traverse them.
+  #
+  # @example
+  #   node1 = Addressive::Node.new
+  #   node2 = Addressive::Node.new
+  #   node1.edges[:another_node] = node2
+  #   node1.traverse(:another_node) #=> node2
+  #
+  class Node
+  
+    attr_reader :edges, :meta, :uri_specs
+    attr_reader :apps
+    attr_accessor :defaults
+    
+    include URIBuilder
+  
+    def initialize
+      @edges = {}
+      @meta = {}
+      @apps = []
+      @uri_specs = Hash.new{|hsh,name| hsh[name]=URISpecList.new(@defaults) }
+      @uri_builder_delegate = URIBuilder.new(self)
+    end
+    
+    # Traverses some edges to another ( or the same ) node.
+    # 
+    # @example
+    #   node1 = Addressive::Node.new
+    #   node2 = Addressive::Node.new
+    #   node3 = Addressive::Node.new
+    #   node1.edges[:n2] = node2
+    #   node2.edges[:n3] = node3
+    #   node3.edges[:n1] = node1
+    #   node1.traverse() #=> node1
+    #   node1.traverse(:n2) #=> node2
+    #   node1.traverse(:n2,:n3,:n1) #=> node1
+    #
+    def traverse(*args)
+      return self if args.none?
+      if edges[args.first].kind_of? Addressive::Node
+        return edges[args.first].traverse(*args[1..-1])
+      else
+        raise NoEdgeFound.new(self, args.first)
+      end
+    end
+    
+    def uri_spec(name)
+      @uri_specs[name]
+    end
+    
+    def inspect
+      if @meta['name']
+        return "<#{self.class.name}: #{@meta['name']}>"
+      else
+        super
+      end 
+    end
+    
+  private
+    def uri_builder_delegate
+      @uri_builder_delegate
+    end
+  
+  end
+  
+  # Creates a new node and yields a builder for it
+  #
+  # This method makes it easy to create a tree-like structur by implictly creating and returning a root node ( by default called :root ). This should be used in most cases, as you will likely have just one connected component in an addressive graph. For complexer graphs you can use {Addressive#graph}.
+  #
+  # @example
+  #   node = Addressive.node do 
+  #     edge( :another ) do
+  #       default :prefix, '/another'
+  #       uri :default ,'/'
+  #     end
+  #     uri :default ,'/'
+  #   end
+  #   
+  #   node.uri.to_s #=> '/'
+  #   node.uri(:another,:default).to_s #=> '/another/'
+  #
+  # @param name [Symbol] a name for this node
+  # @yield {NodeBuilder}
+  # @return {Graph}
+  #
+  def self.node(name=:root,&block)
+    Graph.new{ |bldr|
+      bldr.node name, &block
+    }[name]
+  end
+  
+  # Creates a new graph and yields a builder for it
+  #
+  # This is good, if you want to create a graph with disconnected nodes or multiple root-nodes.
+  #
+  # @example
+  #   graph = Addressive.graph do
+  #     
+  #     node :shared do
+  #       uri :default, '/shared'
+  #     end
+  #     
+  #     node :foo do
+  #       uri :default ,'/foo'
+  #       edge :shared
+  #     end
+  #     
+  #     node :bar do
+  #       uri :default, '/bar'
+  #       edge :shared
+  #     end
+  #     
+  #   end
+  #   
+  #   # You can then get the nodes with {Addressive::Graph.[]}
+  #   graph[:foo].uri.to_s #=> '/foo'
+  #   graph[:bar].uri.to_s #=> '/bar'
+  #   # :foo and :bar can both reach :shared, but not each other.
+  #   # Neither can :shared reach any other node.
+  #   graph[:foo].traverse(:shared) #=> graph[:shared]
+  #   graph[:bar].traverse(:shared) #=> graph[:shared]
+  #   graph[:foo].traverse(:bar) #!> Addressive::NoEdgeFound
+  #   graph[:shared].traverse(:bar) #!> Addressive::NoEdgeFound
+  #
+  # @yield {Builder}
+  # @return {Node}
+  #
+  def self.graph(&block)
+    Graph.new(&block)
+  end
+
+end
+

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: addressive
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha
+  prerelease: 6
+platform: ruby
+authors:
+- HannesG
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: uri_template
+  requirement: &7411800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: *7411800
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &7408500 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *7408500
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &7407760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *7407760
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &7460580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *7460580
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: &7459920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *7459920
+description: ''
+email: hannes.georg@googlemail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/addressive/request.rb
+- lib/addressive/graphviz.rb
+- lib/addressive/graph.rb
+- lib/addressive/router.rb
+- lib/addressive/static.rb
+- lib/addressive.rb
+- addressive.gemspec
+homepage: https://github.com/hannesg/addressive
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A system which should help bringing different Rack applications together.
+test_files: []
+has_rdoc: