maveric 0.1.0 → 0.2.0

data/maveric.rb

@@ -1,11 +1,29 @@
 ##
 # = Maveric: A simple, non-magical, framework
 #
+# == Resources
+#
+# Maveric can normally be found on {rubyforge}[http://maveric.rubyforge.org/]
+# with it's project page {here}[http://rubyforge.org/projects/maveric/].
+#
+# Maveric is also listed at the RAA as
+# {maveric}[http://raa.ruby-lang.org/project/maveric/]. This page lags a bit
+# behind rubyforge.
+#
+# Maveric's home away from home is http://code.stadik.net which contains
+# many other things.
+#
 # == Version
 #
-# This is 0.1.0 th first real release of Maveric. It's rough around the edges
+# This is 0.1.0, the first real release of Maveric. It's rough around the edges
 # and several squishy bits in the middle. At the moment it's still operation
 # conceptualization over algorithm implementation. It's usable, but kinda.
+#
+# Ahh, 0.2.0, wherein we reevaluate ourselves and our ways and eliminate the
+# cruft and improve our efficiency. We have a new implementation of Routing
+# going on, they're now regexps. The ServerError class has been removed, now any subclass of Exception can be raised. One of the larger differences is greater
+# customization of Maveric and Controller instances through extending methods.
+# These are touched upon in their respective docs. Have fun!
 # 
 # == Authors
 # 
@@ -57,14 +75,22 @@
 # 
 # Because ehird from #ruby-lang was whining about it so much I removed its
 # dependancy on Mongrel sooner than later. Maveric should now be very maveric.
+#
+# Because Maveric 0.1.0 worked, but still didn't do things the way I wanted
+# I revised and refactored codes and algorithms into 0.2.0 which will hopefully
+# be all that I want. Everything beyond 1.0.0 will be improvements and
+# extensions.
 # 
 # = Features
-# * Sessions inherent (kept to each instance of Maveric)
+# * Optional sessions
 # * Flexible and strong route setup
 # * Sharing of a Controller between Maveric instances is facilitated
 # * Inheritance is highly respected
 # 
 # == Not so Maveric
+#
+# NOTE: Maveric 0.2.0 does not include extension enablers, further releases
+# should include them.
 # 
 # For these examples we will utilize the simplest functional Maveric possible
 #   require 'maveric'
@@ -101,25 +127,9 @@
 # pointless time checks in place. Anything greater than the WARN level on the
 # logging output tends to output a good deal of information. DEBUG is not for
 # the meek.
-
 require 'log4r'
-require 'benchmark'
 require 'stringio'
-
-class Module
-  protected
-  ##
-  # Decends through the heirarchy of classes and modules looking fot
-  # objects in constants that &test[const] == true
-  def nested_search d=0, &test
-    constants.map do |c| c, r = const_get(c), []
-      next if c == self
-      r << c if test[c]
-      r.concat c.nested_search(d+1, &test) if c.is_a? Class or c.is_a? Module
-      r
-    end.flatten.compact
-  end
-end
+require 'maveric/extensions'
 
 ##
 # = The Maveric: Yeargh.
@@ -130,6 +140,7 @@ end
 # 
 # = Usage
 # We could technically have a running Maveric with:
+#
 #   require 'maveric'
 #   class Maveric::Index < Maveric::Controller
 #     def get
@@ -137,46 +148,29 @@ end
 #     end
 #   end
 #   maveric = Maveric.new # I'm a real boy now!
-# But that's not very friendly or useful.
+#
+# but that's not very useful.
 class Maveric
+  ## Standard end of line for HTTP
   EOL="\r\n"
+  ## Group 1 wil contain a boundary for multipart/form-data bodies.
   MP_BOUND_REGEX = /\Amultipart\/form-data.*boundary=\"?([^\";, ]+)\"?/n
 
-  @log = Log4r::Logger.new 'mvc'
-  @log.outputters = Log4r::Outputter['stderr']
-  @log.level = Log4r::INFO
-  #@sessions = Hash.new {|h,k| s = Maveric::Session.new; h[s.id]=s; }
-  @@sessions = Hash.new {|h,k| s = Maveric::Session.new; h[s.id]=s; }
-
-  @log.info "#{self.class} integrated at #{Time.now}"
-
+  # I hate putting utility methods here, rather than in some module, but for
+  # somereason things aren't working as they should that way.
   class << self
-    ##
-    # Family is important.
-    #
-    # Sets up a new Maveric with everything it needs for normal
-    # operation. Many things are either copied or included from it's
-    # parent The logger is copied and Models and Views are included by
-    # their respective modules.
-    def inherited klass
-      Maveric.log.info "Maveric: #{klass} inherits from #{self}."
-      # By default a Maveric's logger is its parent's
-      klass.instance_variable_set :@log, @log
-      parent = self
-      klass.class_eval do
-        const_set(:Models, Module.new).
-          module_eval { include parent::Models }
-        const_set(:Views, Module.new).
-          module_eval { include parent::Views }
+    ## Builds a logging object if there's not one yet, then returns it.
+    def log
+      unless defined? @@maveric_logger
+        @@maveric_logger = Log4r::Logger.new 'mvc'
+        @@maveric_logger.outputters = Log4r::Outputter['stderr']
+        @@maveric_logger.level = Log4r::INFO
+        @@maveric_logger.info "#{self} integrated at #{Time.now}"
       end
+      @@maveric_logger
     end
 
-    attr_reader :log
-
-    def sessions; @@sessions; end
-
-    ##
-    # Performs URI escaping.
+    ## Performs URI escaping.
     def escape(s)
       s.to_s.gsub(/([^ a-zA-Z0-9_.-]+)/n) {
         '%'+$1.unpack('H2'*$1.size).join('%').upcase
@@ -194,21 +188,23 @@ class Maveric
     # Parses a query string by breaking it up around the
     # delimiting characters.  You can also use this to parse
     # cookies by changing the characters used in the second
-    # parameter (which defaults to ';,'.
+    # parameter (which defaults to ';,').
+    #
+    # This will return a hash of parameters, values being contained in an
+    # array. As a warning, the default value is an empty array, not nil.
     def query_parse(qs, delim = '&;')
-      (qs||'').split(/[#{delim}] */n).inject({}) { |h,p|
+      (qs||'').split(/[#{delim}] */n).inject(Hash.new([])) { |h,p|
         k, v = unescape(p).split('=',2)
-        if h.key? k
-          if h[k].is_a? Array then h[k] << v
-          else h[k] = [h[k], v] end
-        else h[k] = v end
+        (h[k]||=[]) << v
         h
       }
     end
 
     ##
     # Parse a multipart/form-data entity. Adapated from cgi.rb. The body
-    # argument may either be a StringIO or a IO of sublcass thereof.
+    # argument may either be a StringIO or a IO of subclass thereof.
+    #
+    # Might need to be rehauled to match query_parse's behaviour.
     def parse_multipart boundary, body
       ::Maveric.type_check :body, body, IO
       values = {}
@@ -239,12 +235,11 @@ class Maveric
       values
     end
 
-    ## Help us find our contained implicit Controller classes.
-    def contained_controllers
-      nested_search {|v| v.is_a? Class and v < ::Maveric::Controller }
-    end
-
-    ## So we don't have ginormous test+raise statements everywhere.
+    ##
+    # I have a penchant for static typing, but just as a general assertion
+    # and insurance that the correct types of data are being passed I created
+    # this little checking method. It will test value to be an instance of
+    # any of the trailing class, or if the block provided evalutates as true.
     def type_check name, value, *klasses, &test
       if klasses.any? {|klass| value.is_a? klass } then return true
       elsif test and test[value] then return true
@@ -253,517 +248,379 @@ class Maveric
           " got #{value.class}:#{value.inspect}."
       end
     end
-  end
 
-  ##
-  # When instantiated, the Maveric look search through its constants for
-  # nested Controllers. If It finds them, they will be asked if they have
-  # already chosen their routes. If they haven't, a default route will
-  # be derived from their name. AClassName would become '/a_class_name'
-  # and Maveric::BongleBing::ThisPage would become '/bongle_bing/this_page'.
-  #
-  # FIXME: Does not do nested paths for a nested Controller
-  def initialize *opts
-    klass = self.class
-    klass.log.info "#{self.class} instantiated at #{Time.now}"
-    # We have no where to go. populate me plz!
-    @routings = []
-    # By default we use a global session repository
-    @sessions = @@sessions
-
-    # defualt settings
-    @path_prefix = ''
-    # let's hande some options!
-    if (hopts = opts[-1]).is_a? Hash
-      # should not end with / !!!!!
-      @path_prefix = hopts[:path_prefix] if hopts.key? :path_prefix
+    ##################### Non-utility methods
+
+    ##
+    # A recursive method to hunt out subclasses of Controller nested
+    # within a Maveric subclass. Used in the setting up of autoroutes.
+    def nested_controllers realm=self, stk=[]
+      stk << realm #We don't need to visit the same thing twice.
+      realm.constants.map do |c|
+        next if stk.include?(c = realm.const_get(c)) or not c.is_a? Module
+        a = []
+        a << c if c < ::Maveric::Controller
+        a += nested_controllers c, stk
+      end.compact.flatten
     end
 
-    # auto population
-    unless (controllers = klass.contained_controllers).empty?
-      controllers.each do |c|
-        klass.log.info "Setting routes for #{c}."
-        r = if not c.routes.empty? then c.routes
-          elsif (s = c.to_s[/::(.*)/,1]) =~ /^index$/i then '/'
-          else # I see we want to be difficult
-            '/'+s.gsub(/([^A-Z_])([A-Z])/){$1+'_'+$2}.downcase
-          end
-        set_routes c, *r
+    ##
+    # Family is important.
+    #
+    # Sets up a new Maveric with everything it needs for normal
+    # operation. Many things are either copied or included from it's
+    # parent The logger is copied and Models and Views are included by
+    # their respective modules.
+    def inherited klass
+      ::Maveric.log.info "#{klass} inherits from #{self}."
+      super klass
+      parent = self
+      klass.class_eval do
+        const_set(:Models, Module.new).
+          module_eval { include parent::Models }
+        const_set(:Views, Module.new).
+          module_eval { include parent::Views }
       end
     end
   end
 
-  attr_reader :routings, :sessions
-  def log; self.class.log; end
-
   ##
-  # Creates a Route to the object c. The c argument should be a Proc or a 
-  # Maveric::Controller subclass.
-  def add_route  c, r
-    log.info "#{self}#add_route #{c} #{r.inspect}"
-    route = Route.new @path_prefix+r, c
-    @routings.delete_if{|e| e === route } << route
+  # When instantiated, the Maveric look search through its constants for
+  # nested Controllers and adds them by their roots. 
+  def initialize opts={}
+    ::Maveric.log.info "#{self.class} instantiated at #{Time.now}"
+    ::Maveric.type_check :opts, opts, Hash
+    @options = opts
+    @routings = Hash.new # should be an associative array or ordered hash.
+    self.class.nested_controllers.
+      each {|c| add_routes c, c.routes, {:maveric => self} }
   end
 
-  ## Creates routes to object c, via Maveric#add_route
-  def add_routes c, *r
-    r.flatten.map {|route| add_route c, route }
-  end
+  attr_reader :options, :routings
 
-  ##
-  # Removes all routes directed at c, and adds routes to the given object,
-  # viaa Maveric#add_routes 
-  def set_routes c, *r
-    log.info "#{self}#set_route #{c} #{r.inspect}"
-    @routings.delete_if{|e| e.run == c }
-    add_routes c, *r
+  ## Returns an array of controllers that are being routed to.
+  def controllers
+    @routings.values.uniq
   end
 
   ##
-  # The env argument should be a normal environment hash derived from HTTP.
-  #
-  # Determines session info then sets the Maveric and the session info into 
-  # the environment hash at the keys of :maveric and :session respectively.
-  # Parses the REQUEST_URI to determine the appropriate routing and compiles
-  # the route info. Checks the REQUEST_METHOD for the post method and tests
-  # for a multipart/form-data payload.
-  def prep_env env
-    ::Maveric.type_check :env, env, Hash
-    class << env; include HashGenOnKey; end
-    env[:maveric] = self
-
-    # determines the appropriate route and build the route info.
-    url = Maveric.unescape env['REQUEST_URI']
-    route, rinfo = routings.
-      find {|r| o = r.match_url(url) and break [r, o] }
-    env.update :route => route, :route_info => rinfo
-    #::Maveric.log.warn env.map{|k,v|"#{k}: #{v.inspect}"}*"\n"
-
-    # determine if there's a multipart boundary
-    if env['REQUEST_METHOD'] =~ /^post$/i \
-      and env['CONTENT_TYPE'] =~ MP_BOUND_REGEX
-      env[:multipart_boundary] = $1
-    end
+  # Places a route to a controller. Will generate a new Routing if route is a
+  # String.
+  def add_route controller, route, opts={}
+    ::Maveric.log.info "#{self.class}#add_route"+
+      " #{controller.inspect} #{route.inspect}"
+    route = ::Maveric::Routing.new route, opts if route.instance_of? String
+    ::Maveric.type_check :controller, controller, Class
+    ::Maveric.type_check :route, route, ::Maveric::Routing
+    @routings[route] = controller
+  end
 
-    env[:params]
-    # session data!
-    session_id = env[:cookies][Maveric::Session::COOKIE_NAME]
-    session_id = session_id[0] if session_id.is_a? Array
-    env[:session] = sessions[ session_id ]
-    env
+  ## Used for adding multiple routes via #add_route
+  def add_routes controller, routes, opts={}
+    routes.flatten.map {|route| add_route controller, route, opts }
   end
 
   ##
   # A Maveric's cue to start doing the heavy lifting. The env should be
   # a hash with the typical assignments from an HTTP environment or crying
-  # and whining will ensue. The req_body argument should be a String, StringIO,
-  # or an IO or subclass thereof instance.
-  def dispatch req_body=$stdin, env=ENV, *opts
-    log.info "#{self.class}#dispatch #{id=Integer(rand*10000)}\n  "+
+  # and whining will ensue. The req_body argument should be a StringIO.
+  # TODO: More doc! :P
+  def process req_body=$stdin, env=ENV, opts={}
+    ::Maveric.log.info "#{self.class}#process\n  "+
       "[#{Time.now}] #{env['REMOTE_ADDR']} => #{env['REQUEST_URI']}"
-    ::Maveric.type_check :req_body, req_body, IO, StringIO
+    ::Maveric.type_check :req_body, req_body, StringIO
     ::Maveric.type_check :env, env, Hash
-    response = ''
-    n = Benchmark.measure do
-      response = begin
-        prep_env env unless [:maveric, :route, :route_info].all?{|k|env.key? k}
-        raise ServerError, [404, "Page not found. Sorry!"] unless env[:route]
-
-        if env['REQUEST_METHOD'] =~ /^post$/i
-          qparams = env.key?(:multipart_boundary) ?
-            parse_multipart(env[:multipart_boundary], req_body) :
-            Maveric.query_parse(req_body.read)
-          env[:params].update qparams
-        end
-
-        env[:route].run[req_body, env, *opts]
-      rescue ServerError then $!
-      rescue 
-        log.fatal "#{Time.now}: #{$!.to_s}\n#{$!.backtrace*"\n"}"
-        # have a nice fail, then have a hard fail if something fails there.
-        begin
-          ServerError.new($!)
-        end
+    begin
+      prepare_environment env unless env.key? :maveric
+      raise RuntimeError, [404, "Page not found."] unless env[:route]
+
+      if env['REQUEST_METHOD'] =~ /^post$/i
+        env[:params].update env.key?(:multipart_boundary) ?
+          parse_multipart(env[:multipart_boundary], req_body) :
+          ::Maveric.query_parse(req_body.read)
       end
-    end
-    log.info "#{self.class}#dispatch #{id}\n#{n}".chomp
-    response
-  end
-end
 
-##
-# Conveniance class to build simple error responses. Raise it from within a
-# dispatch to attain a quick end to a possibly messy situation.
-#
-# TODO: Adapt it to be a subclass of Maveric::Controller
-class Maveric::ServerError < RuntimeError
-
-  class << self
-    ##
-    # If given an instance of the same class it shall return that class as
-    # doubling up is wasteful.
-    def new a
-      a.instance_of?(self) ? a : super(a)
-    end
-    alias_method :exception, :new
-  end
-
-  ##
-  # After a bit of experimenting with Exception and raise I determinee a fun
-  # and simple way to generate fast HTTP response error thingies. As long as
-  # you're within a call to dispatch (with no further rescue clauses) the
-  # ServerError will propogate up and be returned. As a ServerError has similar
-  # accessors as a Controller, they should be compatible with any outputting
-  # implimentation.
-  #
-  # If the status code is 5xx (500 by default) then a backtrace is appended to
-  # the response body.
-  #
-  #   raise ServerErrpr; # 500 error
-  #   raise ServerError, 'Crap!'; # 500 error with message set to 'Crap!'
-  #   raise ServerError, $!; # 500 error with same message and backtrace as
-  #     # $! with a note in the message as to  the original exception class
-  #   raise ServerError, [status, headers, body, *other_data] # Magic!
-  #
-  # In the final example line an Array is passed to raise as a second argument
-  # rather than a String. This only works as intended if the first element is
-  # an Integer. This is taken as the HTTP status code. The next element is
-  # tested to be a Hash, if so then it's values are merged into the HTTP
-  # headers. Then next item is tested to be a String, if so it is appended to
-  # the response body. All remaining elements are appended to the response
-  # body in inspect format.
-  def initialize data=nil
-    @status, @headers, @body = 500, {'Content-Type'=>'text/plain'}, ''
-    case msg = data
-    when Exception
-      msg = @body << data.class.to_s+" "+data.message
-      set_backtrace data.backtrace
-      @body << "\n\n"+data.backtrace*"\n"
-    when String
-      @body << msg
-    when Array
-      if data[0].is_a? Integer
-        # [status, headers, body, request]
-        @status = data.shift
-        @headers.update data.shift if data.first.is_a? Hash
-        @body.concat data.shift if data.first.is_a? String
-        msg = @body.dup
-        @body << "\n\n#{data.map{|e|e.inspect}*"\n"}" unless data.empty?
+      if (controller = env[:route][:controller]) < ::Maveric::Controller
+        controller.new req_body, env, opts
+      elsif controller.is_a? String
+        ::Maveric.log.warn "We have not implemented dynamic route dispatch "+
+          "just yet. Please explicitly state :controller."
+        raise "Dynamic dispatching failed."
+      else
+        raise TypeError, "Lapse in handling. Something fugly got dropped."+
+          " Notify Maveric coder please."
+      end
+    rescue # we catch exception.is_a? StandardError
+      ::Maveric.log.error "#{Time.now}:\n#{$!.inspect}\n#{$!.backtrace*"\n"}"
+      begin
+        raise $! # this makes sense in a certain context...
+        # Here is where we should have transformational stuffs for accessorizing
+        # or customizing error pages. As long as someone doesn't get stupid 
+        # about it.
+      rescue
+        return $!
       end
     end
-    if @status/100%10 == 5
-      @body << "\n\n#{$!}\n#{$@[0..10]*"\n"}"
-    end
-    super msg
-  end
-  attr_reader :status, :headers, :body
-
-  ## Allows fun with splat (*).
-  def to_a
-    [
-      (@status.dup.freeze rescue @status), 
-      @headers.dup.freeze, 
-      @body.dup.freeze, 
-      (@env.dup.freeze rescue @env)
-    ].freeze
-  end
-
-  ## Fun with raw output!
-  def to_s
-    status, headers, body, e, i = to_a
-    response = "Status: #{status}"+Maveric::EOL
-    response << headers.map{|(k,v)| "#{k}: #{v}" }*Maveric::EOL
-    response << Maveric::EOL*2
-    response << body
-  end
-end
-
-##
-# Contains session data and provides conveniance in generating an appropriate
-# cookie.
-class Maveric::Session
-  COOKIE_NAME = 'SESSIONID'
-  DURATION = 15*60
-  KEY_GRADE = 16
-  KEY_LENGTH = 16
-
-  ## Do you want to alter the duration of sessions? M'kay.
-  def initialize duration=DURATION
-    @id = Array.new(KEY_LENGTH){rand(KEY_GRADE).to_s(KEY_GRADE)}*''
-    @duration, @data = duration, {}
-    Maveric.log.debug self
   end
-  attr_reader :id, :expires, :duration, :data
-  attr_writer :duration
 
   ##
-  # Update the Session's lifetime by @duration seconds from the time this
-  # method is called. Returns self for chaining uses.
-  #
-  # NOTE: No bookeeping algorithms are implemented, so a Session will last
-  # forever (within the app, the client's cookie will expire) at this point.
-  def touch
-    @expires = Time.now.gmtime + Integer(@duration)
-    Maveric.log.info "#{self.class}#touch: #{self.inspect}"
-    self
+  # The env argument should be a normal environment hash derived from HTTP.
+  # Runs through a list of sorted methods, looking for methods beginning with
+  # 'env_' followed by a number followed by a '_' and then whatever descriptive
+  # ending the programmer gives the method. It passes the env hash to those
+  # methods for them to update and mess around with the env in appropriate
+  # ways. See default/included methods for example usage.
+  # NOTE: Override the defaults at your own risk!
+  def prepare_environment env
+    ::Maveric.type_check :env, env, Hash
+    env.update :maveric => self
+    methods.sort.each{|m| __send__ m, env if /^env_\d+_/=~m }
   end
 
-  ##
-  # Representation of the Session in cookie form. Session specific data 
-  # is not used in any way.
-  def to_s env=Hash.new{|h,k|"#{k} not defined"}
-    touch unless @expires
-    c = "#{COOKIE_NAME}=#{id};" #required
-    c << " expires=#{@expires.httpdate}" if @expires
-    c << " path=#{env['SCRIPT_NAME']};"
-    c << " domain=#{env['SERVER_NAME']};"
-    c << " secure" if false
-    c
+  ## Cookies!
+  def env_0_cookies env
+    env[:cookies] = ::Maveric.query_parse env['HTTP_COOKIE'], ';,'
   end
-end
-
-##
-# Instances of Route are used for determining how to act upon particular urls
-# in each Maveric instance. Routes should be defined in terms of / as the 
-# mount point of the Maveric. The following code would print the request
-# instance on the request of '/foo/'.
-#   Maveric.add_route '/', proc{p @request}
-#   mongrelserver.register('/foo', Maveric::MongrelHandler(Maveric))
-class Maveric::Route
-  ## Seperator characters.
-  URI_CHAR = '[^/?:,&#]'
-
-  ##
-  # Create a Route from the String route where varying parts of the url are
-  # represented as Symbol like sigils. The run argument should be a Proc or
-  # a Maveric::Controller subclass.
-  #   Route.new '/:page', proc{|request| p request.params[:params][:page] }
-  #   Route.new '/:page', MyController # MyController < Maveric::Controller
-  def initialize route, run
-    ::Maveric.type_check :route, route, String
-    ::Maveric.type_check :run, run, Proc, ::Maveric::Controller do |k|
-      k < ::Maveric::Controller
+  ## Params!
+  def env_0_params env
+    env[:params]  = ::Maveric.query_parse env['QUERY_STRING']
+  end
+  ## More Params!?
+  def env_0_multipart_detect env
+    if not env.key? :multipart_boundary \
+      and env['REQUEST_METHOD'] =~ /^post$/i \
+      and env['CONTENT_TYPE'] =~ MP_BOUND_REGEX
+      env[:multipart_boundary] = $1
     end
-    @run = run
-    @route = route.gsub /\/+/, '/'
-    @params = []
-    @regex = Regexp.new '^'+@route.gsub(/\/:(#{URI_CHAR}+)/){
-      @params << $1.to_sym
-      raise 'Duplicated parameters.' unless @params.uniq.size == @params.size
-      "/(#{URI_CHAR}+)"
-    }+'$'
-    Maveric.log.debug self
   end
-  attr_reader :route, :run, :regex, :params
-
-  ##
-  # Create a url from a Hash by replacing the Symbol like sigils of the route
-  # with the corresponding hash values. An incomplete url may be returned if
-  # not all values of @params do not have corresponding value in the given 
-  # Hash.
-  def build_url hsh
-    Maveric.log.debug "#{self.class}#build_url"+
-      " #{hsh.inspect} : #{self.inspect}"
-    #@params.inject(@route){|r,k| r.gsub(/#{k.inspect}/, hsh[k]) }
-    hsh.inject(@route){|r,(k,v)| r.gsub(/:#{k}/, v.to_s) }
+  ## What am I doing in this basket...
+  def env_0_route env
+    url = ::Maveric.unescape env['REQUEST_URI']
+    env[:route] = routings.eject do |(r,c)|
+      b=r.route(url) and {:controller=>c}.update b
+    end
   end
 
-  ##
-  # Build a Hash by picking out portions of the provided url that correspond
-  # to each sigil of the route. Returns nil if the url does not match.
-  def match_url url
-    Maveric.log.debug "#{self.class}#match_url"+
-      " #{url.inspect} : #{self.inspect}"
-    return nil unless md = @regex.match(url)
-    Hash[ *@params.zip(md.captures).flatten ]
+  ## Holds views related methods and helpers
+  module Views
+    def path_to c, a={}
+      ::Maveric.log.info "#{self.class}#path_to #{c} #{a.inspect}"
+      @env[:maveric].routings.eject{|(r,d)| r.build a if d == c }
+    end
   end
 
-  ##
-  # Provides comparisons with instances of Array, Hash, Strings or Proc, as
-  # well as subclasses of Maveric::Controller.
-  def === arg
-    Maveric.log.debug "#{self.class}#==="+
-      " #{arg.inspect} : #{self.inspect}"
-    case arg
-    when Array  then arg.size == @params.size and \
-      not arg.any?{|v|!@params.include?(v)}
-    when Hash   then self === arg.keys
-    when String then @regex.match(arg).nil?
-    when Proc   then @run == arg
-    when Class  then @run == arg if arg < Maveric::Controller
-    end
+  ## Repository for models. Still not realy utilized.
+  module Models
   end
 end
 
 ##
-# Controller instances are the work horses of Maveric instances, pulling them
-# around the wide prarie of the net, lashed by means of a Route.
-# 
-# They may be defined anywhere you want, being contained in a Maveric is not
-# needed, all that is needed is for that class to be a subclass of 
-# Maveric::Controller. While you may do everything to the all-father of
-# Maveric::Controller that you can do with a child, it is not recommended for
-# the great one are prone to pass down their weirding ways to their children
-# which will probably instigate a small war or other conflicts later on.
-# 
-# If the methods get, post, put, or delete are called (typically called in
-# Controller.new when setting the body of the response) and they haven't been
-# defined then a ServerError is thrown with a status of 503.
-# 
-# * Access to the raw request is provided through @request.
-# * Cookies are reflected in @cookies, alterations will be passed to the 
-#   client response.
-#   * Alteration of the session id cookie is not recommended.
-# * HTTP headers should be set in @headers. The HTTP status should be set 
-#   in @status. Cookies from @cookies are included at the end of processing.
+# Controllers are the classes that do the actual handling and processing of
+# requests. The number of normal methods is kept low to prevent clobbering by
+# user defined methods.
+#
+# They may be defined in any location, but if they are defined in a nested
+# location within the Maveric class being used to serve at a particular
+# location, on instantialization of the Maveric they will automatically
+# be added at either the routes specified in their class definition or
+# at the default route which is derived from their name and their nesting.
 class Maveric::Controller
-  REQUEST_METHODS = [:post, :get, :put, :delete, :head] # CRUD
+  REQUEST_METHODS = [:post, :get, :put, :delete, :head] # CRUDY
 
-  @routes = []
   class << self
-    ## Added to allow utilitilizing of Route#run[stuff]
-    alias_method :[], :new
-    def add_route r
+    ## All children should have routes.
+    def inherited klass
+      klass.class_eval{ @routes = [] }
+    end
+    ## Removes currently set routes and adds the stated ones.
+    def set_routes r, o={}
+      ::Maveric.type_check :r, r, String, Array
+      clear_routes
+      r = [r] unless r.is_a? Array
+      r.flatten.map{|e| add_route e }
+    end
+    ## Add a route to the Controller.
+    def add_route r, o={}
+      ::Maveric.type_check :r, r, String, ::Maveric::Routing
+      r = ::Maveric::Routing.new r, o if r.is_a? String
       @routes << r
     end
-    def set_routes *r
+    ## Removes all currently set routes.
+    def clear_routes
       @routes.clear
-      r.flatten.map{|e| add_route e }
     end
-    def inherited klass
-      klass.instance_variable_set :@routes, @routes.dup
+    ## Returns a default Routing based on the #nesting_path if no routes.
+    def routes
+      @routes.empty? ?
+        ::Maveric::Routing.new(nesting_path) :
+        @routes
     end
-    attr_reader :routes
   end
 
   ##
-  # Main processing method of Controller. After initial setup it will call
-  # its method with name equivalent to REQUEST_METHOD or 'get' in downcased
-  # form. The result of this method is used as the response body.
-  def initialize req_body, env, *opts
-    Maveric.log.warn "Provided env has not been properly processed, results "+
-      "may vary!" unless ([:maveric, :route, :route_info]-env.keys).empty?
+  # Main processing method of Controller.
+  #
+  # The response body is set with the result of the specified action method
+  # if the result is a String and @body has not been set to a String. The
+  # action method is determined by env[:route][:action], REQUEST_METHOD in
+  # downcased form, or 'get' by default.
+  #
+  # Directly before the action method is called, methods beginning with
+  # 'prepare_', a number, another '_', and an optional label are called.
+  # Similarly, after the action method is called, methods beginning with
+  # 'cleanup_', etc., are called.
+  #
+  # By the time the Controller is be instantiated, it should have @status,
+  # @headers, and @body set. @status should be an Integer matching the
+  # http status code, @headers a string keyed hash of http headers, and @body
+  # to a string of the http response body.
+  def initialize req_body, env, opts={}
+    ::Maveric.log.warn "Provided env has not been properly processed, results "+
+      "may vary!" unless ([:maveric, :route, :params, :cookies]-env.keys).empty?
     ::Maveric.type_check :req_body, req_body, IO, StringIO
-    Maveric.log.debug env
+    ::Maveric.type_check :env, env, Hash
+    ::Maveric.type_check :opts, opts, Hash
+
     @status, @headers = 200, {'Content-Type'=>'text/html'}
-    @env = env
-    @in = req_body
+    @env, @in = env, req_body
     @cookies = @env[:cookies].dup
-    method = (@env['REQUEST_METHOD'] || 'get').downcase
 
-    n = Benchmark.measure{@body = __send__(method)}
-    Maveric.log.info "#{self.class}@body\n#{n}".chomp
+    action = if @env.key? :route and @env[:route].key? :action
+               @env[:route][:action]
+             elsif @env.key? 'REQUEST_METHOD'
+               @env['REQUEST_METHOD'].downcase
+             else 'get' end
+    raise NoMethodError, [503, "#{action} not implemented.", nil, @env] if \
+      REQUEST_METHODS.include? action and not respond_to? action
 
-    @headers['Set-Cookie'] = [@env[:session].touch.to_s(@env)]
-    @cookies.each do |k,v|
-      next unless v != @env[:cookies][k]
-      @headers['Set-Cookie'] << \
-        "#{k}=#{Maveric.escape(v)}; path=#{@env['SCRIPT_NAME']}"
-    end
-    Maveric.log.debug self
+    methods.sort.each{|m| __send__ m if /^prepare_\d+_/=~m }
+    result = __send__(action)
+    @body = result unless @body.is_a? String or not result.is_a? String
+    methods.sort.each{|m| __send__ m if /^cleanup_\d+_/=~m }
+
+    ::Maveric.log.debug self # omg, masochistic.
   end
 
   attr_reader :status, :headers, :body
 
-  ##
-  # This is the new renderer. It uses nothing. Yay, configurability!
+  ## TODO: Doc me.
   def render view, s=''
-    Maveric.log.debug "#{self.class}#render"+
-      " #{view.inspect}, #{s}"
+    ::Maveric.log.debug "#{self.class}#render"+
+      " #{view.inspect}, #{s.inspect}" # s is painful to logs.
     ::Maveric.type_check :view, view, Symbol, String
-    extend @env[:maveric].class::Views
-    n = Benchmark.measure do
-      s = __send__ view, s if respond_to? view
-      s = __send__ :layout, s unless view.to_s[/^(_|layout$)/]
-    end
-    Maveric.log.info "#{self.class}#render #{view.inspect}\n#{n}".chomp
+    ::Maveric.type_check :s, s, String
+    s = yield s if block_given?
+    s = __send__ view, s if respond_to? view
+    s = render :layout, s unless view.to_s[/^(_|layout$)/] \
+      or caller.any?{|l|l=~/`render'/} # i don't like this 
     return s
   end
 
-  ## Allows fun with splat (8).
-  def to_a
-    [
-      (@status.dup.freeze rescue @status), 
-      @headers.dup.freeze, 
-      @body.dup.freeze, 
-      (@env.dup.freeze rescue @env)
-    ].freeze
+  ## For quick and raw response printing!
+  def to_http
+    response = "Status: #{@status}" + ::Maveric::EOL
+    response << @headers.map{|k,v| "#{k}: #{v}" }*::Maveric::EOL
+    response << ::Maveric::EOL*2 + @body
   end
 
-  ## Because simple output is sometimes needed
-  def to_s
-    response = "Status: #{@status}" + Maveric::EOL
-    response << @headers.map{|k,v| "#{k}: #{v}" }*Maveric::EOL
-    response << Maveric::EOL*2 + @body
+  ##
+  # Extends the Controller instance with the Views and Models modules of the
+  # pertinant Maveric instance.
+  def prepare_0_imports
+    extend @env[:maveric].class::Models
+    extend @env[:maveric].class::Views
   end
-
   ##
-  # If the method requested is a standard HTTP REQUEST_METHOD name then
-  # we've probably just requested something not implemented. So, we throw
-  # a 503 error!
-  def method_missing m, *a, &b
-    Maveric.log.debug "#{self.class}#missing_method"+
-      "( #{m.inspect}, #{a.inspect}, #{b.inspect}) "
-    raise ServerError, [503, "Method #{m} not implemented.", @env] if \
-      REQUEST_METHODS.include? m
-    super m, *a, &b
+  # Folds the datasets of @cookie to @headers if they have been altered or
+  # are new.
+  def cleanup_0_cookies
+    @cookies.each do |k,v|
+      next unless v != @env[:cookies][k]
+      @headers['Set-Cookie'] << "#{k}=#{::Maveric.escape(v)}"
+    end
   end
 end
 
 ##
-# Repository for global Views helpers and methods. For Maveric specific
-# views they should be defined in the Views module within the Maveric
-# subclass itself.
-#
-# NOTE: They really shouldn't be going here, but I cannot recall a better 
-# location to place helper methods. Truthfully, Views related helpers should
-# go here, while Controller related ones should be in their Controller.
-module Maveric::Views
-  def path_to c, a={}
-    path = ''
-    n = Benchmark.measure do
-      path = (@env['SCRIPT_NAME']+@env[:maveric].routings.find do |r|
-        r === a and u = r.build_url(a) and break u if r === c
-      end).gsub /\/+/, '/'
+# Instances of Route are used for determining how to act upon particular urls
+# in each Maveric instance. They are magical and simply complex creatures.
+class Maveric::Routing < Regexp
+  URI_CHAR = '[^/?:,&#]'
+  PARAM_MATCH= %r~:(#{URI_CHAR}+):?~
+  ##
+  # The String path is turned into a regex in a very straightforward manner. 
+  # Fragments of the path that begin with ':' followed by any number of
+  # characters that aren't a typical URI delimiter or reserved character, and
+  # optionally ending with another ':', are indicators of paramæters.
+  #
+  # Parameters are typically replaced with the regexp of /(#{URI_CHAR}+)/ in
+  # the Routing instance. If the parameter label matches a key in opts, the 
+  # associated value is placed into the Routing instead.
+  def initialize path, opts={}
+    ::Maveric.type_check :path, path, String
+    ::Maveric.type_check :opts, opts, Hash
+
+    @path = path.dup.freeze
+    @options = opts.dup.freeze
+
+    @params = []
+    regex = path.gsub PARAM_MATCH do
+      param = $1.to_sym
+      raise ArgumentError, "Duplicated parameters in path."+
+        " <#{param.inspect}>" if @params.include? param
+      @params << param
+      "(#{opts[param] || URI_CHAR+'+'})"
     end
-    Maveric.log.info "#{self.class}#path_to #{c} #{a.inspect}\n#{n}".chomp
-    path
+    @params.freeze
+    super %r~^#{regex}$~iu.freeze
+
+    ::Maveric.log.debug self.inspect
   end
-end
 
-## Container module for Models. Akin to Maveric::Views
-module Maveric::Models
-end
+  attr_reader :path, :params
 
-##
-# Utilizes a hash in @@gen_on_key, with Symbol keys and Proc values, to
-# generate default values for keys that don't exist.
-#
-# Used to extend the environment hash to automatically build the
-# data hashes for cookies and query parameters (limited to those gathered from
-# QUERY_STRING). Each data hash is triggered and accessable from the keys of 
-# :cookies and :params, respectively.
-module HashGenOnKey
-  # Store procs for generating data sets on the look up of a particular key
-  @@gen_on_key = Hash[
-    :cookies,
-    proc{|h| Maveric.query_parse(h['HTTP_COOKIE'], ';,') },
-    :params,
-    proc{|h| Maveric.query_parse(h['QUERY_STRING']) }
-  ]
-
-  ## If a key has no assigned value then test to see if there's a generator.
-  def default k
-    unless @@gen_on_key.key? k then super k
-    else store k, @@gen_on_key[k][self]
+  ##
+  # If given a hash that contains all of and only contains keys matching its
+  # parameters then a path will be built by interpolating the hash values for
+  # their corresponding parameters.
+  # NOTE: Should I or should I not test the result against itself to ensure
+  # the generation of a matching path?
+  def build arg
+    ::Maveric.log.debug "#{self.class}#build"+
+      " #{arg.inspect} : #{self.inspect}"
+    ::Maveric.type_check :arg, arg, Hash
+    if @params.sort == arg.keys.sort
+      path = arg.inject(@path){|r,(k,v)| r.sub /:#{k}:?/, v }
     end
   end
 
-  ## If there's a symbol key or corresponding generator, then return the value.
-  def method_missing m, *a, &b
-    if key? m then self[m]
-    elsif @@gen_on_key.key? m then default m
-    else super m, *a, &b
+  ##
+  # When given a path that matches the Routing itself, a hash is returned with
+  # keys being parameters and values being the associated value gathered from
+  # the path.
+  def route path
+    ::Maveric.log.debug "#{self.class}#route"+
+      " #{path.inspect} : #{self.inspect}"
+    ::Maveric.type_check :path, path, String
+    if self =~ path
+      Hash[ *@params.zip($~.captures).flatten ].update(nil => self)
     end
   end
+
+  ##
+  # This is an attempt as path correction. Root is treated as a prefix to the
+  # generating path to be removed, from which a new Routing will be spawned.
+  def adjust root, opts={}
+    ::Maveric.type_check :root, root, String
+    self.class.new @path.sub(/^#{root}/,'/'), @options.merge(opts)
+  end
+
+  ##
+  # As Routing is a subclass of a corelib class, the inspect isn't as
+  # informative as we'd like. So we override it.
+  def inspect
+    v = [object_id<<1].pack('i').unpack('I')[0] # faster
+    "#<#{self.class}:0x#{v.to_s(16)} #{super}"+
+      " #{@path.inspect} #{@params.inspect}>"
+  end
 end