derailleur 0.0.5

data/Rakefile

@@ -0,0 +1,69 @@
+
+require 'rubygems'
+require 'rake/gempackagetask'
+
+$LOAD_PATH.unshift('lib')
+require 'derailleur'
+
+spec = Gem::Specification.new do |s|
+
+        s.name = 'derailleur'
+        s.rubyforge_project = 'derailleur'
+        s.version = Derailleur::VERSION
+        s.author = Derailleur::AUTHORS.first
+        s.homepage = Derailleur::WEBSITE
+        s.summary = "A super-fast Rack web framework"
+        s.email = "crapooze@gmail.com"
+        s.platform = Gem::Platform::RUBY
+
+        s.files = [
+          'Rakefile', 
+          'TODO', 
+          'lib/derailleur.rb',
+          'lib/derailleur/base/application.rb',
+          'lib/derailleur/base/grease.rb',
+          'lib/derailleur/base/context.rb',
+          'lib/derailleur/base/handler_generator.rb',
+          'lib/derailleur/core/application.rb',
+          'lib/derailleur/core/array_trie.rb',
+          'lib/derailleur/core/dispatcher.rb',
+          'lib/derailleur/core/errors.rb',
+          'lib/derailleur/core/handler.rb',
+          'lib/derailleur/core/hash_trie.rb',
+          'lib/derailleur/core/trie.rb',
+        ]
+
+        s.require_path = 'lib'
+        s.bindir = 'bin'
+        s.executables = []
+        s.has_rdoc = true
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+        pkg.need_tar = true
+end
+
+task :gem => ["pkg/#{spec.name}-#{spec.version}.gem"] do
+        puts "generated #{spec.version}"
+end
+
+
+desc "run an example"
+task :example, :ex, :server, :port do |t, params|
+  path = "./example/#{params[:ex]}.rb"
+  servername = params[:server] || 'thin' 
+  port = params[:port] || '3000' 
+  if File.file? path
+    require path
+    require 'rack'
+    app = Rack::Builder.new {
+      run ExampleApplication
+    }
+    server = Rack::Handler.get(servername)
+    server.run(app, :Port => port.to_i)
+  else
+    puts "no such example: #{path}
+    use ls example to see the possibilities"
+   
+  end
+end

data/TODO

@@ -0,0 +1 @@
+* separate classes to hold handoff and grafting logic in trienodes

data/lib/derailleur.rb

@@ -0,0 +1,9 @@
+
+module Derailleur
+  VERSION = "0.0.5"
+  AUTHORS = ['crapooze']
+  WEBSITE = "http://github.com/crapooze/derailleur"
+  LICENCE = "MIT"
+  autoload :Application, 'derailleur/base/application'
+  autoload :Grease, 'derailleur/base/grease'
+end

data/lib/derailleur/base/application.rb

@@ -0,0 +1,66 @@
+
+require 'derailleur/core/application'
+
+module Derailleur
+  module Application
+    # registers a handler for the GET HTTP method
+    # the handler is either content OR the passed block
+    # if content is true and there is a block, then the handler will be the content
+    # params is a hash of parameters, the only parameter supported is:
+    # * :overwrite , if true, then you can rewrite a handler
+    def get(path, content=nil, params={}, &blk)
+      register_route(path, :GET, content, params, &blk)
+    end
+
+    # removes a handler for the GET HTTP method
+    def unget(path)
+      unregister_route(path, :GET)
+    end
+
+    # registers a handler for the HEAD HTTP method
+    # see get for the use of parameters
+    def head(path, content=nil, params={}, &blk)
+      register_route(path, :HEAD, content, params, &blk)
+    end
+
+    # removes a handler for the HEAD HTTP method
+    def unhead(path)
+      unregister_route(path, :HEAD)
+    end
+
+    # registers a handler for the POST HTTP method
+    # see get for the use of parameters
+    def post(path, content=nil, params={}, &blk)
+      register_route(path, :POST, content, params, &blk)
+    end
+
+    # removes a handler for the POST HTTP method
+    def unpost(path)
+      unregister_route(path, :POST)
+    end
+
+    # registers a handler for the PUT HTTP method
+    # see get for the use of parameters
+    def put(path, content=nil, params={}, &blk)
+      register_route(path, :PUT, content, params, &blk)
+    end
+
+    # removes a handler for the PUT HTTP method
+    def unput(path)
+      unregister_route(path, :PUT)
+    end
+
+    # registers a handler for the DELETE HTTP method
+    # see get for the use of parameters
+    def delete(path, content=nil, params={}, &blk)
+      register_route(path, :DELETE, content, params, &blk)
+    end
+
+    # removes a handler for the DELETE HTTP method
+    def undelete(path)
+      unregister_route(path, :DELETE)
+    end
+
+    #no TRACE CONNECT
+  end
+end

data/lib/derailleur/base/context.rb

@@ -0,0 +1,63 @@
+
+module Derailleur
+  # A context is the place where we handle an incoming HTTP Request.
+  # much like a Rack application, it has an env and the result must
+  # be an array of three items: [status, headers, content]
+  # The content is just an instance_evaluation of a callback passed during
+  # initialization.
+  class Context
+    # The Rack environment
+    attr_reader :env
+
+    # The Derailleur context
+    attr_reader :ctx
+
+    # A hash representing the HTTP response's headers
+    attr_reader :headers
+
+    # The HTTP response's status
+    attr_accessor :status
+
+    # The body of the HTTP response, must comply with Rack's specification
+    attr_accessor :content
+
+    # The block of code that will be instance_evaled to produce the HTTP
+    # response's body
+    attr_reader :blk
+
+    def initialize(env, ctx, &blk)
+      @status = 200
+      @env = env
+      @ctx = ctx
+      @blk = blk
+      @content = nil
+      @headers = {'Content-Type' => 'text/plain'}
+    end
+
+    # Simply instance_evaluates the block blk in the context of self
+    def evaluate!
+      @content = instance_eval &blk
+    end
+
+    # The Derailleur::Application for this context
+    def app
+      ctx['derailleur']
+    end
+
+    # The parameters as parsed from the URL/HTTP-path chunks
+    def params
+      ctx['derailleur.params']
+    end
+
+    # Method that wraps the status, headers and content into an array
+    # for Rack specification.
+    def result
+      [status, headers, content]
+    end
+
+    # Returns the extension name of the HTTP path
+    def extname
+      File.extname(env['PATH_INFO'])
+    end
+  end
+end

data/lib/derailleur/base/grease.rb

@@ -0,0 +1,108 @@
+
+require 'derailleur/base/application'
+
+module Derailleur
+  autoload :HandlerGenerator, 'derailleur/base/handler_generator'
+  # The Grease is the module that helps you code at a high level,
+  # with blocks.
+  # Basically, including this method in a class makes the HTTP 
+  # methods definition available as registrations.
+  # Then, instanciating the class, it will actually register the routes
+  # in the objects. Including Grease will redefine the "initialize method",
+  # do do not include Grease after defining it. Do the opposite.
+  # See also Grease#initialize_HTTP (you should call it if you don't use 
+  # Grease's initialize method.
+  module Grease
+    include Derailleur::Application
+
+    Registration = Struct.new(:sym, :path, :handler)
+
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+    # Transform registration definitions into actual registrations.
+    def register_registrations_of(obj)
+      obj.registrations.each do |reg|
+        send(reg.sym, reg.path, reg.handler)
+      end
+    end
+
+    # Initialiazes HTTP routes by transforming all the registration definitions
+    # in the class of the object into itself.
+    def initialize_HTTP
+      register_registrations_of(self.class)
+    end
+
+    # If there is no initializer, will create one.
+    # If there is one, then it will try to call super.
+    # As a result include this module into classes *before* defining initialize,
+    # or in classes in which you don't care about initialize.
+    def initialize(*args, &blk)
+      super
+      initialize_HTTP
+    end
+
+    module ClassMethods
+      # Copies the registrations of an object.
+      # no check is done on duplicate registrations.
+      def inherit_HTTP_method(mod)
+        mod.registrations.each do |reg|
+          registrations << reg.dup
+        end
+      end
+
+      # Includes a module and then copies its registrations with
+      # inherit_HTTP_method
+      def include_and_inherit_HTTP_method(mod)
+        include mod
+        inherit_HTTP_method(mod)
+      end
+
+      # Returns (and create if needed) the list of registrations
+      def registrations
+        @registrations ||= []
+      end
+
+      attr_writer :handler_generator
+
+      # The class to use to create handlers that will catch requests.
+      def handler_generator
+        @handler_generator ||= Derailleur::HandlerGenerator
+      end
+
+      # Sets a specification to registers a handler at the given path and HTTP
+      # request "GET".  For the default handler_generator
+      # (Derailleur::HandlerGenerator), the block blk will be evaluated in a
+      # Derailleur::Context .
+      def get(path, params=nil, &blk) 
+        registrations << Registration.new(:get, path, 
+                                          handler_generator.for(params, &blk))
+      end
+
+      # Same as get but for HEAD
+      def head(path, params=nil, &blk)
+        registrations << Registration.new(:head, path, params,
+                                          handler_generator.for(params, &blk))
+      end
+
+      # Same as get but for POST
+      def post(path, params=nil, &blk)
+        registrations <<  Registration.new(:post, path, params,
+                                           handler_generator.for(params, &blk))
+      end
+
+      # Same as get but for PUT
+      def put(path, params=nil, &blk)
+        registrations <<  Registration.new(:put, path, params,
+                                           handler_generator.for(params, &blk))
+      end
+
+      # Same as get but for DELETE
+      def delete(path, params=nil, &blk)
+        registrations <<  Registration.new(:delete, path, params,
+                                           handler_generator.for(params, &blk))
+      end
+    end
+  end
+end

data/lib/derailleur/base/handler_generator.rb

@@ -0,0 +1,22 @@
+
+require 'derailleur/core/handler'
+require 'derailleur/base/context'
+
+module Derailleur
+  module HandlerGenerator
+    # Creates a new subclass of Derailleur::Handler that will create a
+    # Derailleur::Context which in turn will evaluate the block.
+    # The dummy_params parameter is not used, but we need it because
+    # it is the interface for Derailleur.Grease (in case you want to use
+    # a custom HandlerGenerator)
+    def self.for(dummy_params={}, &blk)
+      handler = Class.new(Derailleur::Handler) 
+      handler.send(:define_method, :to_rack_output) do
+        context = Context.new(env, ctx, &blk)
+        context.evaluate!
+        context.result
+      end
+      handler
+    end
+  end
+end

data/lib/derailleur/core/application.rb

@@ -0,0 +1,200 @@
+
+require 'derailleur/core/errors'
+
+module Derailleur
+  autoload :InternalErrorHandler, 'derailleur/core/handler'
+  autoload :DefaultRackHandler, 'derailleur/core/handler'
+  autoload :ArrayTrie, 'derailleur/core/array_trie'
+  autoload :Dispatcher, 'derailleur/core/dispatcher'
+
+  # In Derailleur, an application is an object extending the Application
+  # module.  It will have routes which hold handlers.  By default, we use
+  # Derailleur's components, but you can easily modify your application to use
+  # custom routes' node, HTTP methods dispatcher, and handlers.
+  module Application
+
+    attr_writer :default_handler, :default_root_node_type, :default_dispatcher,
+      :default_internal_error_handler
+
+    # The default error handler ( Derailleur::InternalErrorHandler )
+    def default_internal_error_handler
+      @default_internal_error_handler ||= InternalErrorHandler
+    end
+
+    # The default root node type ( Derailleur::ArrayTrie )
+    # You could change it to ( Derailleur::HashTrie ) for better performance.
+    # The rule of thumb is: benchmark your application with both and pick the 
+    # best one.
+    def default_root_node_type
+      @default_root_node_type ||= ArrayTrie
+    end
+
+    # The default node type (is the node_type of the default_root_node_type )
+    def default_node_type
+      default_root_node_type.node_type
+    end
+
+    # The default handler ( Derailleur::DefaultRackHandler )
+    # See Derailleur::Handler to understand how to build your own
+    def default_handler
+      @default_handler ||= DefaultRackHandler
+    end
+
+    # The default HTTP method dispatcher ( Derailleur::Dispatcher )
+    # See Derailleur::Dispatcher if you want a personal one
+    def default_dispatcher
+      @default_dispatcher ||= Dispatcher
+    end
+
+    # An object representing the routes. Usually, it is the root of a Trie
+    def routes
+      @routes ||= default_root_node_type.new
+    end
+
+    # Normalize a path by making sure it starts with '/'
+    def normalize(path)
+      File.join('/', path)
+    end
+
+    # Chunks a path, splitting around '/' separators
+    # there always is an empty name
+    # 'foo/bar' => ['', 'foo', 'bar']
+    def chunk_path(path)
+      normalize(path).split('/')
+    end
+
+    # Builds a route by appending nodes on the path.
+    # The implementation of nodes should create missing nodes on the path.
+    # See ArrayTrieNode#<< or HashTrieNode#<<
+    # Returns the last node for this path
+    def build_route(path)
+      current_node = routes
+      chunk_path(path).each do |chunk|
+        current_node = current_node << chunk
+      end
+      current_node
+    end
+
+    # Return the node corresponding to a given path.  
+    # Will (optionally) consecutively yield all the [node, chunk_name]
+    # this is useful when you want to interpret the members of the path
+    # as a parameter.
+    def get_route(path)
+      current_node = routes
+      chunk_path(path).each do |chunk|
+        unless current_node.absorbent?
+          current_node = current_node.child_for_name(chunk)
+          raise NoSuchRoute, "no such path #{path}" unless current_node
+        end
+        yield current_node, chunk if block_given?
+      end
+      current_node
+    end
+
+
+    # Registers an handler for a given path.
+    # The path will be interpreted as an absolute path prefixed by '/' .
+    #
+    # Usually you will not use this method but a method from the 
+    # base/application.rb code (with the name of the 
+    # HTTP method: e.g. get post put)
+    #
+    # The method argument is the HTTP method name as a symbol (e.g. :GET)
+    # (handler || blk) is the handler set. i.e., if there's both a handler
+    # and a block, the block will be ignored.
+    #
+    # Params is hash of parameters, currently, the only key 
+    # looked at is :overwrite to overwrite an handler for an 
+    # existing path/method pair.
+    #
+    # Internally, the path will be created node by node when nodes for this
+    # path are missing.
+    # A default_dispatcher will be here to map the various HTTP methods for the
+    # same path to their respective handlers.
+    def register_route(path, method=:default, handler=nil, params={}, &blk)
+      if path == '*'
+        raise ArgumentError.new("Cannot register on #{path} because of ambiguity, in Derailleur, '*' translated'/*' would not catch the path '/' like '/foo/*' doesn't catch '/foo'")
+      end
+      handler = handler || blk
+      node = build_route(path)
+      node.content ||= default_dispatcher.new
+      if (params[:overwrite]) or (not node.content.has_handler?(method))
+        node.content.set_handler(method, handler)
+      else
+        raise RouteObjectAlreadyPresent, "could not overwrite #{method} handler at path #{path}"
+      end
+      node
+    end
+
+    # Removes an handler for a path/method pair.
+    # The path will be interpreted as an absolute path prefixed with '/'
+    def unregister_route(path, method=:default)
+      node = get_route(normalize(path))
+      if node.children.empty?
+        if node.content.no_handler?
+          node.prune! 
+        else
+          node.content.set_handler(method, nil)
+        end
+      else
+        node.hand_off_to! default_node_type.new(node.name)
+      end
+    end
+
+    # Split a whole branch of the application at the given path, and graft the
+    # branch to the app in second parameter.
+    # This method does NOT prevents you from cancelling handlers in the second
+    # app if any. Because it does not check for handlers in the receiving
+    # branch. Use with care.  See ArrayNode#graft!
+    def split_to!(path, app)
+      app_node = app.build_route(path)
+
+      split_node = get_route(normalize(path))
+      split_node.prune!
+
+      app_node.graft!(split_node)
+    end
+
+    # Method implemented to comply to the Rack specification.  see
+    # http://rack.rubyforge.org/doc/files/SPEC.html to understand what to
+    # return.
+    #
+    # If everything goes right, an instance of default_handler will serve
+    # the request.
+    #
+    # The routing handler will be created with three params
+    # - the application handler contained in the dispatcher
+    # - the Rack env
+    # - a context hash with three keys:
+    #   * 'derailleur' at self, i.e., a reference to the application
+    #   * 'derailleur.params' with the parameters/spalt in the path
+    #   * 'derailleur.node' the node responsible for handling this path
+    # 
+    # If there is any exception during this, it will be catched and the 
+    # default_internal_error_handler will be called.
+    def call(env)
+      begin
+        path = env['PATH_INFO'].sub(/\.\w+$/,'') #ignores the extension if any
+        ctx = {}
+        params = {:splat => []}
+        route = get_route(path) do |node, val|
+          if node.wildcard?
+            params[node.name] = val 
+          elsif node.absorbent?
+            params[:splat] << val 
+          end
+        end
+        ctx['derailleur.node'] = route
+        ctx['derailleur.params'] = params
+        ctx['derailleur'] = self
+        dispatcher = route.content
+        raise NoSuchRoute, "no dispatcher for #{path}" if dispatcher.nil?
+        handler = dispatcher.send(env['REQUEST_METHOD'])
+        raise NoSuchRoute, "no handler for valid path: #{path}" if handler.nil?
+        default_handler.new(handler, env, ctx).to_rack_output
+      rescue Exception => err
+        default_internal_error_handler.new(err, env, ctx).to_rack_output
+      end
+    end
+  end
+end

data/lib/derailleur/core/array_trie.rb

@@ -0,0 +1,179 @@
+
+require 'derailleur/core/trie'
+
+module Derailleur
+  class ArrayTrieNode < TrieNode
+    # A fallback children, in case there is no child matching, this
+    # one is found.
+    attr_accessor :fallback_child
+
+    # An array of normal chidrens
+    attr_reader :normal_children
+
+    def initialize(name, parent=nil)
+      super
+      @normal_children = []
+    end
+
+    # List the children, including the fallback_child (in last position) if any
+    def children
+      ary = normal_children.dup
+      ary << fallback_child if fallback_child
+      ary
+    end
+
+    # Tries adding a new children built from the name
+    # * if the name is for a normal child
+    #   * if there already is a normal_children node with this name, returns it
+    #   * otherwise creates one
+    # * if the name is for a fallback child
+    #   * if there is no fallback child, creates one
+    #   * otherwise
+    #     * if the wording are identical, will just return the existing one
+    #     * if the wording are different, will raise an ArgumentError
+    def << name
+      node = child_with_exact_name(name)
+      if node
+        node
+      else
+        new_node = ArrayTrieNode.new(name, self)
+        ret = if new_node.normal?
+                normal_children << new_node
+                new_node
+              elsif fallback_child
+                raise ArgumentError, "there already is a fallback child in #{self}" unless fallback_child.name == new_node.name
+                fallback_child
+              else
+                @fallback_child = new_node
+              end
+        ret
+      end
+    end
+
+    # Returns the normal child with the name passed in parameter
+    # or nil if there is no such child
+    def child_with_exact_name(name)
+      normal_children.find{|n| n.name == name}
+    end
+
+    # Returns the child whose name match the parameter, 
+    # or the fallback one, or nil if there is no such child
+    def child_for_name(name)
+      child = child_with_exact_name(name)
+      if child
+        child
+      else
+        fallback_child
+      end
+    end
+
+    # Like Enumerable#map, but recursively creates a new array per child
+    # it looks like this:
+    # [root, [child1, [child11, child12]], [child2]]
+    def tree_map(&blk)
+      children.inject([yield(self)]) do |trunk, child| 
+        trunk << child.tree_map(&blk)
+      end
+    end
+
+    # Pruning the node means cutting the tree by removing the link between this
+    # node and its parent.  The pruned node thus becomes a root and could be
+    # placed somewhere else.  References to this node in the former parent node
+    # are cleaned during the process.  The process of pruning is recursive and
+    # stops whenever it encounters a not useless node (see useless?)
+    def prune!
+      return if root? #you cannot prune the root
+      if normal?
+        parent.normal_children.delete(self)
+      else
+        parent.fallback_child = nil
+      end
+      old_parent = parent
+      @parent = nil
+      old_parent.prune! if old_parent.useless?
+    end
+
+    # Hands off the role of this node to another, single, independent, simple,
+    # and useless node (as opposed to useful and complex ones, e.g., a complete
+    # branch of the tree). This is mainly useful for doing a sort of reset on
+    # the node's state without caring much about the content of the current
+    # node, but you only care about the state of the new node. You can see it
+    # like (or actually perform) "changing the class" of the node on the fly.
+    #
+    # To avoid weird situations, hand off must be licit:
+    # - the other node must be useless to avoid losing its useful content
+    # - the nodes must be compatible to prevent weird situations (see
+    # compatible_handoff?)
+    #
+    # Otherwise, an error explaining why the handoff is not licit will be
+    # raised.
+    #
+    # If the handoff can take place, it happens as follow:
+    # - the other node will copy current's children
+    # - this node will clear its references to its children
+    #
+    # Then, if there is a parent to current node, parent's reference will be modified
+    # to point to the replacing node. Finally, the other node will copy
+    # current's parent, and the reference to the parent will be cleared in this
+    # node.
+    def hand_off_to!(other)
+      verify_hand_off_to(other)
+
+      other.normal_children.replace normal_children
+      other.fallback_child = fallback_child
+      @normal_children = []
+      @fallback_child = nil
+      if parent
+        if normal?
+          parent.normal_children.delete(self)
+          parent.normal_children << other
+        else
+          parent.fallback_child = other
+        end
+        other.parent = parent
+        @parent = nil
+      end
+    end
+
+    # grafting another node means replacing this node in the tree by the other
+    # node, including its hierarchy (i.e., you can place branches).  this
+    # process works by replacing the reference to this node by the other node
+    # in this parent this process also updates the other node's parent
+    #
+    # one can only graft normal node in place of normal nodes, and vice versa,
+    # an incompatible grafting will raise an ArgumentError
+    # moreover, because of the semantics, grafting to a root will raise an error
+    #
+    # see-also compatible_graft?
+    def graft!(other)
+      verify_graft(other)
+
+      other.parent = parent
+      if other.normal?
+        parent.normal_children << other
+        parent.normal_children.delete(self)
+      else
+        parent.fallback_child = other
+      end
+    end
+  end
+
+  class ArrayTrie < ArrayTrieNode
+    def self.node_type
+      ArrayTrieNode
+    end
+
+    def initialize
+      @parent = nil
+      @normal_children = []
+    end
+
+    def name
+      nil
+    end
+
+    def prune!
+      nil
+    end
+  end
+end

data/lib/derailleur/core/dispatcher.rb

@@ -0,0 +1,41 @@
+
+module Derailleur
+  HTTP_METHODS = [:GET, :HEAD, :POST, :PUT, :DELETE, :default]
+  Dispatcher = Struct.new(*HTTP_METHODS) do
+    # returns the handler for an HTTP method, or, the default one
+    def get_handler(method)
+      send(method) || send(:default)
+    end
+
+    # returns true if a handler is set for the HTTP method in param
+    # it is an alternative to get_handler which would return a true value
+    # if there is a default handler
+    def has_handler?(method)
+      send(method) && true
+    end
+
+    # sets a handler for the HTTP method in param to val
+    def set_handler(method, val)
+      send("#{method}=", val)
+    end
+
+    # Returns an array of pairs of array with [HTTP-verbs, handler]
+    # an extra item is the :default handler
+    # NB: could also be a hash, but I'm fine with it
+    def handlers
+      HTTP_METHODS.map do |sym|
+        [sym, send(sym)]
+      end
+    end
+
+    # returns an array like handlers but restricted to the not nil values
+    def handlers_set
+      handlers.reject{|sym, handler| handler.nil?}
+    end
+
+    # Returns true if there is no handler set for this dispatcher
+    def no_handler?
+      handlers_set.empty?
+    end
+  end
+end

data/lib/derailleur/core/errors.rb

@@ -0,0 +1,31 @@
+
+module Derailleur
+  # Errors raising in Derailleur are subclasses of StandardError.
+  # Basically, they have an http_status code. This is useful for the various
+  # errors handlers people may write.
+  class ApplicationError < StandardError
+    def http_status
+      500
+    end
+  end
+
+  # This error is mainly for people implementing handlers wich instanciates
+  # other handlers.  The default handler uses it if it tries to instanciate
+  # another handler before forwarding to it.
+  class InvalidHandler < ApplicationError
+  end
+
+  #  A classical kind of not found error in HTTP.
+  class NoSuchRoute < ApplicationError
+    def http_status
+      404
+    end
+  end
+
+  # This errors shows up when you try to register twice on the same route
+  # (i.e., path + verb).
+  # Unless you modify the routing on the fly, you should not see this error
+  # very often.
+  class RouteObjectAlreadyPresent < ApplicationError
+  end
+end

data/lib/derailleur/core/handler.rb

@@ -0,0 +1,127 @@
+
+require 'derailleur/core/errors'
+
+module Derailleur
+  class Handler
+    attr_accessor :env, :ctx, :object
+    def initialize(obj=nil, env=nil, ctx=nil)
+      @env = env
+      @ctx = ctx
+      @object = obj
+    end
+
+    # Accessors, and to_rack_output for things behaving like RackHandler
+    module Rack
+      attr_accessor :status, :headers, :page
+
+      # Returns an status, headers, and page array conforming to the Rack
+      # specification
+      def to_rack_output
+        [status, headers, page]
+      end
+
+      # Sets to default values the Rack specification fields
+      # [200, {}, '']
+      def initialize_rack
+        @status = 200
+        @headers = {}
+        @page = ''
+      end
+    end
+  end
+
+  # The rack handler class instanciates the status, headers, and page to
+  # default values.
+  class RackHandler < Handler
+    include Handler::Rack
+
+    def initialize(obj=nil, env=nil, ctx=nil)
+      super
+      initialize_rack
+    end
+  end
+
+  # The default rack handler is a handler that does several default things:
+  # - if the object respond to to_rack_output (like, another handler)
+  #   it will set the handler's env to the current one (the handler must also 
+  #   respond to :env= and :ctx=) and call its to_rack_output method
+  # - if it's a Proc, it calls the proc passing the env and ctx as 
+  #   block parameters
+  # - if it's a subclass of Handler, it instantiates it 
+  #   (without object, and with the same env and ctx)
+  class DefaultRackHandler < RackHandler
+    def to_rack_output
+      if object.respond_to? :to_rack_output
+        do_forward_output
+      else
+        do_non_forward_output
+      end
+    end
+
+    def do_forward_output
+      object.env = env
+      object.ctx = ctx
+      object.to_rack_output 
+    end
+
+    def do_proc_output
+      object.call(env, ctx)
+    end
+
+    def do_handler_instantiation_output
+      object.new(nil, env, ctx).to_rack_output
+    end
+
+    def do_non_forward_output
+      ret = case object
+      when Proc
+        do_proc_output
+      when Class
+        if object.ancestors.include? RackHandler
+          do_handler_instantiation_output
+        else
+          raise InvalidHandler, "invalid handler: #{object}"
+        end
+      else
+        raise InvalidHandler, "invalid handler: #{object}"
+      end
+      ret
+    end
+  end
+
+  # This handler just call the result to a Rack-like application handler
+  # (the handler object must conform to the Rack specification)
+  # In that case, the Rack application has no view on the ctx variable anymore.
+  class RackApplicationHandler < RackHandler
+    # Simply delegates the method call to the enclosed object.
+    def to_rack_output
+      object.call(env)
+    end
+  end
+
+  # This handler returns the error as text/plain object
+  # If the error respond_to http_status, then it will modify the
+  # HTTP status code accordingly.
+  class InternalErrorHandler < RackHandler
+    alias :err :object
+
+    def initialize(err, env, ctx)
+      super
+      if err.respond_to? :http_status
+        @status = err.http_status
+      else
+        @status = 500
+      end
+    end
+
+    def headers
+      {'Content-Type' => 'text/plain'}
+    end
+
+    def page
+      [err.class.name,
+      err.message,
+      err.backtrace].join("\n")
+    end
+  end
+end

data/lib/derailleur/core/hash_trie.rb

@@ -0,0 +1,112 @@
+
+require 'derailleur/core/trie'
+
+module Derailleur
+  class HashTrieNode < TrieNode
+    attr_reader :children_hash
+
+    def initialize(name, parent=nil)
+      super
+      @children_hash = {}
+    end
+
+    def children
+      ret = @children_hash.values
+      ret << @children_hash.default if @children_hash.default
+      ret
+    end
+
+    def << name
+      node = exact_child_for_name(name)
+      if node
+        node
+      else
+        new_node = HashTrieNode.new(name, self)
+        ret = if new_node.normal?
+                children_hash[name] = new_node
+              elsif children_hash.default
+                raise ArgumentError, "there already is a fallback child in #{self}" unless children_hash.default.name == new_node.name
+                children_hash.default
+              else
+                children_hash.default = new_node
+              end
+        ret
+      end
+    end
+
+    def exact_child_for_name(name)
+      children_hash.values.find{|v| v.name == name}
+    end
+
+    def child_for_name(name)
+      children_hash[name]
+    end
+
+    def tree_map(&blk)
+      children_hash.values.inject([yield(self)]) do |trunk, child| 
+        trunk << child.tree_map(&blk)
+      end
+    end
+
+    # pruning an already pruned node will crash: it has no parent already
+    # also prunes recursively on useless parents
+    # will stop naturally on roots because they have an overloaded prune!
+    def prune!
+      return if root?
+      if normal?
+        parent.children_hash.delete(name)
+      else
+        parent.children_hash.default = nil
+      end
+      old_parent = parent
+      @parent = nil
+      old_parent.prune! if old_parent.useless?
+    end
+
+    def hand_off_to!(other)
+      verify_hand_off_to(other)
+
+      other.children_hash.replace @children_hash
+      @children_hash = {}
+      if parent
+        if normal?
+          parent.children_hash[name] = other
+        else
+          parent.children_hash.default = @children_hash.default
+        end
+        other.parent = parent
+        @parent = nil
+      end
+    end
+
+    def graft!(other)
+      verify_graft(other)
+
+      other.parent = parent
+      if other.normal?
+        parent.children_hash[name] = other
+      else
+        parent.children_hash.default = other
+      end
+    end
+  end
+
+  class HashTrie < HashTrieNode
+    def self.node_type
+      HashTrieNode
+    end
+
+    def initialize
+      @parent = nil
+      @children_hash = {}
+    end
+
+    def name
+      nil
+    end
+
+    def prune!
+      nil
+    end
+  end
+end

data/lib/derailleur/core/trie.rb

@@ -0,0 +1,172 @@
+
+module Derailleur
+  class TrieNode
+    # The name for this node
+    attr_reader :name
+
+    # The children of this node
+    attr_reader :children
+
+    # The children of this node
+    attr_accessor :content
+
+    # The parent of this node, or nil if this node is a root
+    attr_accessor :parent
+
+    # This is the default children for the TrieNode 
+    # (i.e., we record only the parent)
+    # That's why TrieNode is mainly a parent class and should be
+    # subclassed.
+    class EmptyClass
+      def self.empty?
+        true
+      end
+    end
+
+    # Creates a new node whose name and optional parent are set from 
+    # the parameters.
+    # There is a check wether the parent is absorbent (which disallow childrens)
+    # The children is set to EmptyClass, which is a placeholder for subclasses
+    # 
+    def initialize(name, parent=nil)
+      raise ArgumentError, "cannot be the child of #{parent} because it is an absorbent node" if parent and parent.absorbent?
+      @parent = parent
+      @children = EmptyClass
+      set_normal!
+      self.name = name
+    end
+
+    # sets the name of the node and also does other stuff with special names:
+    # - '*' means absorbent
+    # - /^:/ means wildcard
+    # - otherwise it's normal
+    def name=(val)
+      set_val = if val 
+                  case val
+                  when '*'
+                    set_absorbent!
+                  when /^:/
+                    set_wildcard!
+                  else
+                    set_normal!
+                  end
+                  val
+                else
+                  set_normal!
+                  nil
+                end
+      @name = set_val
+    end
+
+    private
+
+    # Set this node to be an absorbent one. 
+    # In the semantics, an absorbent node means that an
+    # entity traversing the trie should stop on this node and should not go any
+    # deeper (i.e., an absorbent node is generally a leaf in the tree, although
+    # no checking enforces this rule).
+    def set_absorbent!  
+      set_normal!  
+      @absorbent = true 
+    end
+
+    # Set this node to be a wildcard one. A wildcard node is a node whose name
+    # is an identifier local to the context of the application traversing it.
+    # The semantics often is "any name".
+    def set_wildcard!
+      set_normal!
+      @wildcard = true
+    end
+
+    # Set this node as normal. That is, cancel any wildcard or absorbent
+    # status.
+    def set_normal!
+      @wildcard = false
+      @absorbent = false
+    end
+
+    public
+
+    # A wildcard node is a node whose name was set with a trailing ':'
+    def wildcard?
+      @wildcard
+    end
+
+    # An absorbent node is a node which cannot be parent, its name is '*'.
+    def absorbent?
+      @absorbent
+    end
+
+    # A normal node is not absorbent and node wildcard
+    def normal?
+      (not wildcard?) and (not absorbent?)
+    end
+
+    # Compares a node with another, based on their name
+    def <=> other
+      name <=> other.name
+    end
+
+    # A useless node has no content and no children, basically
+    # arriving at this point, there's no handler you can ever find.
+    def useless?
+      content.nil? and children.empty?
+    end
+
+    # Returns the root of the tree structure (recursive)
+    def root
+      parent ? parent.root : self
+    end
+
+    # Returns wether or not this node is a root node (i.e., parent is nil)
+    def root?
+      parent.nil?
+    end
+
+    # Returns true wether this node could handoff its position to another one.
+    # It is the case if both nodes are normals or both are non-normal.
+    def compatible_handoff?(other)
+      (normal? and other.normal?) or
+      ((not normal?) and (not other.normal?))
+    end
+
+    # Raise argument errors if the handoff to other is not licit.
+    def verify_hand_off_to(other)
+      raise ArgumentError, "cannot hand off to node: #{other} because it is useful" unless other.useless?
+      raise ArgumentError, "uncompatible handoff between #{self} and #{other}" unless compatible_handoff?(other)
+    end
+
+    # Placeholder for the handoff logic, this method should be overridden by
+    # subclasses.
+    def hand_off_to!(other)
+      verify_hand_off_to(other)
+      other.children.replace children
+      other.parent = parent
+      @children = EmptyClass
+      @parent = nil
+    end
+
+    # Returns true wether the other node could be grafted over this one.
+    # It is the case if both nodes are normals or both are non-normal.
+    def compatible_graft?(other)
+      (normal? and other.normal?) or
+      ((not normal?) and (not other.normal?))
+    end
+
+    # Raise argument errors if the grafting of the other node is not licit.
+    def verify_graft(other)
+      raise ArgumentError, "incompatible grafting" unless compatible_graft?(other)
+      raise ArgumentError, "cannot graft a root" if root?
+    end
+
+    # Placeholder for the handoff logic, this method should be overridden by
+    # subclasses.
+    def graft!(other)
+      verify_graft(other)
+      other.parent = parent
+      parent.children.add other
+      parent.children.delete self
+    end
+
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: derailleur
+version: !ruby/object:Gem::Version 
+  hash: 21
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 5
+  version: 0.0.5
+platform: ruby
+authors: 
+- crapooze
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-12 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: 
+email: crapooze@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- TODO
+- lib/derailleur.rb
+- lib/derailleur/base/application.rb
+- lib/derailleur/base/grease.rb
+- lib/derailleur/base/context.rb
+- lib/derailleur/base/handler_generator.rb
+- lib/derailleur/core/application.rb
+- lib/derailleur/core/array_trie.rb
+- lib/derailleur/core/dispatcher.rb
+- lib/derailleur/core/errors.rb
+- lib/derailleur/core/handler.rb
+- lib/derailleur/core/hash_trie.rb
+- lib/derailleur/core/trie.rb
+has_rdoc: true
+homepage: http://github.com/crapooze/derailleur
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: derailleur
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A super-fast Rack web framework
+test_files: []
+