maveric 0.2.0 → 0.3.0

data/{maveric.rb → lib/maveric.rb}

@@ -20,59 +20,66 @@
 # 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
+# cruft and improve our efficiency. We have a new implementation of Route
+# 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!
-# 
+#
+# I was hoping for a 0.2.1 with refined documentation, updated plugins, and a
+# better execution path. Instead I got all of that as well as altering basic
+# implementation details and adding pre and post processors for Controller and
+# refinment of Maveric's. With the degree of changes we get 0.3.0! Nothing
+# but good stuff yo.
+#
 # == Authors
-# 
+#
 # Maveric is designed and coded by {blink}[mailto:blinketje@gmail.com]
 # of #ruby-lang on irc.freenode.net
-# 
+#
 # == Licence
-# 
+#
 # This software is licensed under the
 # {CC-GNU LGPL}[http://creativecommons.org/licenses/LGPL/2.1/]
-# 
+#
 # == Disclaimer
-# 
+#
 # This software is provided "as is" and without any express or
 # implied warranties, including, without limitation, the implied
 # warranties of merchantability and fitness for a particular purpose.
 # Authors are not responsible for any damages, direct or indirect.
-# 
+#
 # = Maveric: History
-# 
+#
 # Maveric was initially designed as a replacement for Camping in the style of a
-# Model-View-Controller framework. Early implementations aimed to reduce the 
+# Model-View-Controller framework. Early implementations aimed to reduce the
 # amount of "magic" to 0. Outstanding magic of Camping is that nothing is
 # related due to the reading, gsub-ing, and eval-ing of the Camping source file
 # Also, even the unobfuscated/unabridged version of Camping is a bit hard to
 # follow at times.
-# 
-# However, the result of this initial attempt was a spaghetti of winding code, 
+#
+# However, the result of this initial attempt was a spaghetti of winding code,
 # empty template modules, and rediculous inheritance paths between the template
-# modules and a plethora of dynamically generated classes and modules. I got 
+# modules and a plethora of dynamically generated classes and modules. I got
 # more complaints with that particular jumble of code than any other, evar.
-# 
-# The next iteration of Maveric was a seeking of simplification and departure 
-# from the concept of cloning Camping and its functionality and settling for 
+#
+# The next iteration of Maveric was a seeking of simplification and departure
+# from the concept of cloning Camping and its functionality and settling for
 # Camping-esqe. At this point, I started talking to ezmobius on #ruby-lang and
-# their Merb project. We talked a bit about merging and brainstorming but my 
+# their Merb project. We talked a bit about merging and brainstorming but my
 # lone wolf tendencies stirred me away from such an endeavour, but I came away
 # a compatriot and inspiration for a new routing methodology inspired by Merb's.
-# The result is the Route that's been stable since, only varying in method 
+# The result is the Route that's been stable since, only varying in method
 # placement and data management.
-# 
+#
 # After building to a version that stood on it's owned and was able to run a
 # variance of my website as functional as the Camping version. I noticed a few
 # tendncies of my coding and refactored. I also redesigned the concept from a
 # modules that included the Maveric module to that of subclassing Maveric, which
-# is a Mongrel::HttpHandlerPlugin. This allowed the running of Maveric apps 
+# is a Mongrel::HttpHandlerPlugin. This allowed the running of Maveric apps
 # without using Mongrel::CampingHandler as well as not worrying about namespace
 # clobbering.
-# 
+#
 # 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.
 #
@@ -80,50 +87,54 @@
 # 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
 # * 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.
-# 
+# Maveric has additional classes to allow you to run Maveric behind different
+# http server implementations. CGI, FastCGI, and Mongrel are supported. If
+# another service exists that you'd like to have supported please submit a
+# patch of a good reason why.
+#
+# NOTE: Beyond Maveric 0.1.0 extensions have not been touched, future releases
+# should include updates. AFAIK they should work.
+#
 # For these examples we will utilize the simplest functional Maveric possible
 #   require 'maveric'
-#   class Maveric::HelloWorld < Maveric::Controller
+#   class Maveric::Index < Maveric::Controller
 #     def get
-#       'Hello'
+#       'Hello, world!'
 #     end
 #   end
-# 
+#
+# To use CGI:
+#   Maveric.new.dispatch.to_s
+#
+# To use FastCGI:
+#   require 'maveric/fastcgi'
+#   ::Maveric::FCGI.new(MyMaveric)
+#
 # To use Mongrel:
 #   require 'maveric/mongrel'
 #   h = ::Mongrel::HttpHandler ip, port
 #   h.register mountpoint, ::Maveric::MongrelHandler.new(MyMaveric)
 #   h.join.run
-# 
-# To use FastCGI:
-#   require 'maveric/fastcgi'
-#   ::Maveric::FCGI.new(MyMaveric)
-# 
-# To use WEBrick, which I have come to loathe: 
-#   server = ::WEBrick::HTTPServer.new(:Port => 9090)
-#   trap('INT'){ puts "Shutting down server."; server.stop }
-#   server.mount '/', ::Maveric::WEBrickServlet, Maveric
-#   server.start
-# 
+#
 # However, if your script is mounted at a point other than /, use the
 # :path_prefix option to adjust your routes. This affects all routes generated
 # from MyMaveric.
-#   ::Maveric::FCGI.new(MyMaveric, :path_prefix => '/mount/point/here'
-# 
+#   ::Maveric::FCGI.new(MyMaveric, :path_prefix => mountpoint
+#   h.register mountpoint, ::Maveric::MongrelHandler.
+#     new(MyMaveric, :path_prefix => mountpoint)
+#
 # --------------------------------
-# 
-# NOTE: Due to rampant debugging and benchmarking there is a plethora of 
+#
+# NOTE: Due to rampant debugging and benchmarking there is a plethora of
 # 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.
@@ -135,29 +146,19 @@ require 'maveric/extensions'
 # = The Maveric: Yeargh.
 # The Maveric may be used alone or may be used in a cadre of loosely aligned
 # Maveric instances. The Maveric stands tall and proud, relying on it's fine
-# family and it's inventory of goods to get things done with little magic or 
+# family and it's inventory of goods to get things done with little magic or
 # trickery.
-# 
-# = Usage
-# We could technically have a running Maveric with:
-#
-#   require 'maveric'
-#   class Maveric::Index < Maveric::Controller
-#     def get
-#       'Hello, world!'
-#     end
-#   end
-#   maveric = Maveric.new # I'm a real boy now!
-#
-# but that's not very useful.
 class Maveric
+  ## Implementation details.
+  VERSION='0.3.0'
+
   ## 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
 
-  # I hate putting utility methods here, rather than in some module, but for
-  # somereason things aren't working as they should that way.
+  # I hate putting utility methods here, rather than in some module, but
+  # I don't see how to do it without getting messy.
   class << self
     ## Builds a logging object if there's not one yet, then returns it.
     def log
@@ -165,7 +166,8 @@ class Maveric
         @@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}"
+        @@maveric_logger.info "#{self} #{::Maveric::VERSION}"+
+          " integrated at #{Time.now}"
       end
       @@maveric_logger
     end
@@ -174,14 +176,14 @@ class Maveric
     def escape(s)
       s.to_s.gsub(/([^ a-zA-Z0-9_.-]+)/n) {
         '%'+$1.unpack('H2'*$1.size).join('%').upcase
-      }.tr(' ', '+') 
+      }.tr(' ', '+')
     end
 
     ## Unescapes a URI escaped string.
     def unescape(s)
       s.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n){
         [$1.delete('%')].pack('H*')
-      } 
+      }
     end
 
     ##
@@ -206,7 +208,7 @@ class Maveric
     #
     # Might need to be rehauled to match query_parse's behaviour.
     def parse_multipart boundary, body
-      ::Maveric.type_check :body, body, IO
+      ::Maveric.type_check :body, body, IO, StringIO
       values = {}
       bound = /(?:\r?\n|\A)#{Regexp::quote('--'+boundary)}(?:--)?\r$/
       until body.eof?
@@ -217,7 +219,7 @@ class Maveric
             fv[:type] = $1
           when /^Content-Disposition: form-data;/
             $'.scan(/(?:\s(\w+)="([^"]+)")/) {|w| fv[w[0].intern] = w[1] }
-          end 
+          end
         end
 
         o = unless fv[:filename] then ''
@@ -236,13 +238,15 @@ class Maveric
     end
 
     ##
-    # I have a penchant for static typing, but just as a general assertion
+    # I have a penchant for static typing, so 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
+      return unless $DEBUG
+      # order of speed: #include?, #index, #any?
+      if i = klasses.any?{|k|value.is_a? k} then return i
+      elsif test and r = test[value] then return r
       else
         raise TypeError, "Expected #{klasses*' or '} for #{name},"+
           " got #{value.class}:#{value.inspect}."
@@ -265,8 +269,6 @@ class Maveric
     end
 
     ##
-    # 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
@@ -280,51 +282,51 @@ class Maveric
           module_eval { include parent::Models }
         const_set(:Views, Module.new).
           module_eval { include parent::Views }
+        @adj_env = parent.adjust_env.dup
       end
     end
+
+    ##
+    # If no argument is given, the array of actions is returned.
+    # 
+    # If a Symbol or String is given with no block, in prepare_env, the
+    # corresponding method is called with the environment hash as an argument.
+    # If a block is given then, in prepare_env, that block will be called
+    # with the environment hash as the single argument.
+    #
+    # If you are specifying other options you must explicitly state 
+    # :name => <chosen label> as an argument.
+    # Additional arguments include :test, which should be a Proc that
+    # accepts a single argument. The argument will be the environment
+    # hash and the boolean result of the block will determine if the
+    # block will run.
+    def adjust_env act={}, &block
+      ::Maveric.type_check :act, act, Hash, Symbol, String
+      return @adj_env if act.is_a? Hash and act.empty?
+      act = {:name => act} unless act.is_a? Hash
+      act[:do] = block
+      @adj_env << act
+    end
   end
+    @adj_env = []
 
   ##
-  # When instantiated, the Maveric look search through its constants for
-  # nested Controllers and adds them by their roots. 
+  # When instantiated, the Maveric decends through its constants for
+  # nested Controllers and adds them by their routes.
   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} }
+    @options = {:path_prefix => '/'}.merge opts
+    @router = ::Maveric::Router.new
+    self.class.nested_controllers.each {|c| router.add c.routes, c }
   end
 
-  attr_reader :options, :routings
-
-  ## Returns an array of controllers that are being routed to.
-  def controllers
-    @routings.values.uniq
-  end
+  attr_reader :options, :router
 
   ##
-  # 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
-
-  ## 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
+  # 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 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']}"
@@ -334,28 +336,25 @@ class Maveric
       prepare_environment env unless env.key? :maveric
       raise RuntimeError, [404, "Page not found."] unless env[:route]
 
+      # If this is a POST request we need to load data from the body
       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
 
-      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."
+      unless env[:route][:controller] < ::Maveric::Controller
+        raise TypeError, "Route Controller of "+
+          "#{env[:route][:controller].class}. Expecting ::Maveric::Controller."
       end
+
+      env[:route][:controller].new req_body, env, opts
     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 
+        # or customizing error pages. As long as someone doesn't get stupid
         # about it.
       rescue
         return $!
@@ -365,51 +364,53 @@ class Maveric
 
   ##
   # 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 }
+    self.class.adjust_env.
+      select {|act| act[:test].nil? or act[:test][env] }.
+      each {|act| act[:do] ? act[:do][env] : __send__(act[:name], env) }
   end
 
-  ## Cookies!
-  def env_0_cookies env
-    env[:cookies] = ::Maveric.query_parse env['HTTP_COOKIE'], ';,'
+  ### Does this count as magic? No, just defaults.
+  adjust_env :route do |env|
+    url = ::Maveric.unescape env['REQUEST_URI']
+    env[:route] = env[:maveric].router[url]
   end
-  ## Params!
-  def env_0_params env
+
+  adjust_env :cookies do |env|
+    env[:cookies] = ::Maveric.query_parse env['HTTP_COOKIE'], ';,' 
+  end
+
+  adjust_env :params do |env|
     env[:params]  = ::Maveric.query_parse env['QUERY_STRING']
   end
-  ## More Params!?
-  def env_0_multipart_detect env
+
+  adjust_env :multipart_detect do |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
   end
-  ## 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
 
-  ## Holds views related methods and helpers
+  ##
+  # Holds views related methods and helpers
+  #
+  # As long as Controller#prepare_0_imports is not overridden, Views extends
+  # the Controller instance just before the action is called.
   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 }
+      @env[:maveric].router.to(c).eject{|r| r.build a }
     end
   end
 
-  ## Repository for models. Still not realy utilized.
+  ##
+  # Repository for models. Still not really utilized.
+  #
+  # As long as Controller#prepare_0_imports is not overridden, Models extends
+  # the Controller instance just before the action is called.
   module Models
   end
 end
@@ -419,19 +420,42 @@ end
 # requests. The number of normal methods is kept low to prevent clobbering by
 # user defined methods.
 #
+# === Placing a Controller
+#
 # 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.
+#
+# === Working in Controller
+#
+# Within an instance of Controller: @env contains the environment hash; @in
+# contains the request body, and @cookies contains a hash of cookie values.
+#
+# In addition @status, @header, and @body may be set to appropriate values
+# for the response. Note that @headers should be a Hash, @status should be an
+# Integer corresponding to a real HTTP status code, and @body should contain
+# a String.
+#
+# Those are the only instance variables you should be warned against playing
+# with frivously.
 class Maveric::Controller
   REQUEST_METHODS = [:post, :get, :put, :delete, :head] # CRUDY
+  @before = []
+  @after = []
 
   class << self
-    ## All children should have routes.
+    ## Family is important.
     def inherited klass
-      klass.class_eval{ @routes = [] }
+      parent = self
+      klass.class_eval do
+        @routes = []
+        @before = parent.before.dup
+        @after = parent.after.dup
+      end
     end
+    
     ## Removes currently set routes and adds the stated ones.
     def set_routes r, o={}
       ::Maveric.type_check :r, r, String, Array
@@ -439,22 +463,79 @@ class Maveric::Controller
       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
+      ::Maveric.type_check :r, r, String, ::Maveric::Route
+      r = ::Maveric::Route.new r, o if r.is_a? String
       @routes << r
     end
+
     ## Removes all currently set routes.
     def clear_routes
       @routes.clear
     end
-    ## Returns a default Routing based on the #nesting_path if no routes.
+    
+    ## Returns a default Route based on the #nesting_path if no routes.
     def routes
       @routes.empty? ?
-        ::Maveric::Routing.new(nesting_path) :
+        ::Maveric::Route.new(nesting_path) :
         @routes
     end
+
+    ##
+    # If no argument is given, the array of actions is returned.
+    # 
+    # If a Symbol or String is given with no block, during Controller 
+    # initialization before the action is called, the corresponding 
+    # method is called with the Controller instance as an argument.
+    # If a block is given, the block is called with the controller
+    # instance as an argument instead.
+    #
+    # If you are specifying other options, you must explicitly state 
+    # :name => <chosen label> as an argument.
+    # Additional arguments include :only and :exclude, whose values should
+    # be a Symbol or an Array of such that correspond with actions that
+    # they should only run on or not run on.
+    #
+    # NOTE: If you are referencing instance variables within the action,
+    # it is recommended that you create a method rather than a block.
+    def before act={}, &block
+      ::Maveric.type_check :act, act, Hash, Symbol, String
+      return @before if act.is_a? Hash and act.empty?
+      act = {:name => act} unless act.is_a? Hash
+      act[:do] = block
+      act[:only]=[*act[:only]] if act.key? :only
+      act[:exclude]=[*act[:exclude]] if act.key? :exclude
+      @before << act
+    end
+
+    ##
+    # If no argument is given, the array of actions is returned.
+    # 
+    # If a Symbol or String is given with no block, during Controller 
+    # initialization after the action is called, the corresponding 
+    # method is called with the Controller instance as an argument.
+    # If a block is given, the block is called with the controller
+    # instance as an argument instead.
+    #
+    # If you are specifying other options, you must explicitly state 
+    # :name => <chosen label> as an argument.
+    # Additional arguments include :only and :exclude, whose values should
+    # be a Symbol or an Array of such that correspond with actions that
+    # they should only run on or not run on.
+    #
+    # NOTE: If you are referencing instance variables within the action,
+    # it is recommended that you create a method rather than a block.
+    def after act={}, &block
+      ::Maveric.type_check :act, act, Hash, Symbol, String
+      return @after if act.is_a? Hash and act.empty?
+      act = {:name => act} unless act.is_a? Hash
+      act[:do] = block
+      act[:only]=[*act[:only]] if act.key? :only
+      act[:exclude]=[*act[:exclude]] if act.key? :exclude
+      @after << act
+    end
   end
 
   ##
@@ -462,22 +543,17 @@ class Maveric::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.
+  # action method is determined respectively 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,
+  # By the time the Controller.new is done running, 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={}
+  def initialize req_body=$stdin, env=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.type_check :req_body, req_body, StringIO, IO
     ::Maveric.type_check :env, env, Hash
     ::Maveric.type_check :opts, opts, Hash
 
@@ -485,25 +561,49 @@ class Maveric::Controller
     @env, @in = env, req_body
     @cookies = @env[:cookies].dup
 
-    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
+    action ||= @env[:route][:action] rescue nil
+    action ||= @env['REQUEST_METHOD'].downcase rescue nil
+    action ||= 'get'
+    action = action.to_sym
+
     raise NoMethodError, [503, "#{action} not implemented.", nil, @env] if \
       REQUEST_METHODS.include? action and not respond_to? action
 
-    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 }
+    self.class.before.select do |act|
+      (act[:only].nil? or act[:only].include? action) and \
+      (act[:exclude].nil? or not act[:exclude].include? action)
+    end.each do |act|
+      act[:do] ? act[:do][self] : __send__(act[:name], self)
+    end
+
+    @body = __send__ action
+
+    self.class.after.select do |act|
+      (act[:only].nil? or act[:only].include? action) and \
+      (act[:exclude].nil? or not act[:exclude].include? action)
+    end.each do |act|
+      act[:do] ? act[:do][self] : __send__(act[:name], self)
+    end
 
     ::Maveric.log.debug self # omg, masochistic.
   end
 
   attr_reader :status, :headers, :body
 
-  ## TODO: Doc me.
+  ## For quick and raw response outputting!
+  def to_http
+    response = "Status: #{@status}" + ::Maveric::EOL # Status message? :/
+    response << @headers.map{|k,v| "#{k}: #{v}" }*::Maveric::EOL
+    response << ::Maveric::EOL*2 + @body
+  end
+
+  private
+
+  ##
+  # TODO: Doc me. ehird is confused
+  #
+  # This is a simple method, really. The only confusing part is the expressions
+  # just above the return. Controller#render calls itself. That is all.
   def render view, s=''
     ::Maveric.log.debug "#{self.class}#render"+
       " #{view.inspect}, #{s.inspect}" # s is painful to logs.
@@ -512,50 +612,72 @@ class Maveric::Controller
     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 
+      or caller.any?{|l|l=~/`render'/} # i don't like this but it works
     return s
   end
 
-  ## 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
-
   ##
+  # Standard Controller setup.
+  #
   # 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
+  def setup controller
+    controller.extend @env[:maveric].class::Models
+    controller.extend @env[:maveric].class::Views
   end
+
   ##
+  # Standard Controller cleanup.
+  #
   # Folds the datasets of @cookie to @headers if they have been altered or
   # are new.
-  def cleanup_0_cookies
+  def cleanup controller
     @cookies.each do |k,v|
       next unless v != @env[:cookies][k]
       @headers['Set-Cookie'] << "#{k}=#{::Maveric.escape(v)}"
     end
   end
+
+  before :setup
+  after :cleanup
 end
 
 ##
 # 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
+# The Route class was inspired by Merb's implementation, which in turn were
+# inspired by Rails. One thing I think Rails has done nicely, to a point.
+#
+# The String path is turned into a Regexp in a very straight-forward 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. The
+# trailing ':' is useful if the parameter occurs within a string of similar
+# characters.
+#
+# Parameters are replaced by default with the regexp of /(#{URI_CHAR}+)/ in
+# the final Route. If a parameter symbol matches a key in the opts hash the
+# associated value is placed into the Route instead.
+#
+class Maveric::Route < Regexp
+  ## A negative class of URI delimiting and reserved characters.
   URI_CHAR = '[^/?:,&#]'
+  ## Standard pattern for finding parameters in provided paths.
   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.
+
+  # NOTE: The following examples shows a return value of the equivalent regexp
+  # and not the result of Route#inspect.
   #
-  # 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.
+  #   Route.new '/'
+  #     => /^\/$/                # with no groups or derived values
+  #   Route.new '/:value'
+  #     => /^\/([^/?:,&#]+)$/    # with group 1 assigned to :value
+  #   Route.new '/:val:ue'
+  #     => /^\/([^/?:,&#]+)ue$/ # with group 1 assigned to :val
+  #   Route.new '/:value', :value => 'print|find'
+  #     => /^\/(print|find)$/
+  #   Route.new '/:whtevr', :whtevr => '.*'
+  #     => /^\/(.*)$/            # if you want a real catch-all
   def initialize path, opts={}
     ::Maveric.type_check :path, path, String
     ::Maveric.type_check :opts, opts, Hash
@@ -563,31 +685,25 @@ class Maveric::Routing < Regexp
     @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
+    regex, @params = __compile path, opts
     @params.freeze
-    super %r~^#{regex}$~iu.freeze
+    super %r~^#{regex}$~iu
+    freeze
 
     ::Maveric.log.debug self.inspect
   end
 
-  attr_reader :path, :params
+  attr_reader :path, :params, :options
 
   ##
   # 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?
+  #
+  # NOTE: Should I or should I not pass the result to #route to ensure
+  # the generation of a compatible path?
   def build arg
-    ::Maveric.log.debug "#{self.class}#build"+
-      " #{arg.inspect} : #{self.inspect}"
+    ::Maveric.log.debug "#{self.class}#build #{arg.inspect} : #{@params}"
     ::Maveric.type_check :arg, arg, Hash
     if @params.sort == arg.keys.sort
       path = arg.inject(@path){|r,(k,v)| r.sub /:#{k}:?/, v }
@@ -595,12 +711,11 @@ class Maveric::Routing < Regexp
   end
 
   ##
-  # When given a path that matches the Routing itself, a hash is returned with
+  # When given a path that matches the Route 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.log.debug "#{self.class}#route #{path.inspect} : #{self}"
     ::Maveric.type_check :path, path, String
     if self =~ path
       Hash[ *@params.zip($~.captures).flatten ].update(nil => self)
@@ -608,19 +723,92 @@ class Maveric::Routing < Regexp
   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={}
+  # This is an attempt as path correction. The String root is treated as a
+  # prefix to the generating path to be removed, from which a new Route will
+  # be generated.
+  #
+  #   r = Route.new '/foo/bar/qux'
+  #   r.reroot('/foo') == Route.new('/bar/qux')
+  #     => true
+  def reroot root, opts={}
     ::Maveric.type_check :root, root, String
-    self.class.new @path.sub(/^#{root}/,'/'), @options.merge(opts)
+    self.class.new @path.sub(/^#{root}\/?/,'/'), @options.merge(opts)
   end
 
   ##
-  # As Routing is a subclass of a corelib class, the inspect isn't as
+  # As Route 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}>"
+    "#<%s:0x%x %s %s %s>" % [
+      self.class,
+      [object_id<<1].pack('i').unpack('I')[0],
+      super,
+      @params.inspect,
+      @path.inspect
+    ]
+  end
+
+  private
+
+  ##
+  # Builds a regex from path by parsing out fragments matching PARAM_MATCH
+  # and replacing them with either a corresponding symbol from the opts
+  # hash or the default regex.
+  def __compile path, opts
+    ::Maveric.type_check :path, path, String
+    ::Maveric.type_check :opts, opts, Hash
+    params = []
+    regex = path.gsub PARAM_MATCH do
+      param = $1.to_sym
+      raise ArgumentError, "Duplicated parameter in path."+
+        " <#{param.inspect}>" if params.include? param
+      params << param
+      "(#{opts[param] || URI_CHAR+'+'})"
+    end
+    [regex, params]
+  end
+end
+
+## Storage of routes and routing mechanisms.
+class Maveric::Router
+  def initialize opts={}
+    @routings = Hash.new
+  end
+  
+  ## Returns a list of the controllers with listed routes.
+  def controllers
+    @routings.values.uniq
+  end
+
+  ##
+  # Places one or more routes to a Controller. Will generate a new Route if
+  # a route is a String. Accepts an Array for routes to add several at a time.
+  def add routes, controller, opts={}
+    ::Maveric.log.info "#{self.class}#add"+
+      " #{routes.inspect} #{controller.inspect}"
+    ::Maveric.type_check :controller, controller, Class
+    ::Maveric.type_check :routes, routes, Array, String, ::Maveric::Route
+    routes = [routes] unless routes.is_a? Array
+    routes.flatten.map do |route|
+      ::Maveric.type_check :route, route, String, ::Maveric::Route
+      route = ::Maveric::Route.new route, opts if route.instance_of? String
+      @routings[route] = controller
+    end
+  end
+
+  ## Return an array of routes mapped to a controller.
+  def to controller
+    @routings.map{|(r,d)| r if d == controller }.compact
+  end
+
+  ##
+  # Matches the given path against the collection of routes.
+  # Returns nil the appropriate Route#route result with :controller
+  # mapped to the associated Controller.
+  def [] path
+    ::Maveric.type_check :path, path, String
+    @routings.eject do |(r,c)|
+      b=r.route(path) and {:controller=>c}.update b
+    end
   end
 end

data/{maveric → lib/maveric}/extensions.rb

@@ -1,13 +1,9 @@
 class Module
-  alias_method :__to_s, :to_s
-  private :__to_s
-  ## Prepends a :: to the string represendation of itself.
-  def to_s; "::#{__to_s}"; end
-  ## Build a string akin toa relative url of the nesting structure.
-  def nesting_path
-    self.to_s.
+  ## Build a string akin to the absolute path of the nesting structure.
+  def nesting_path 
+    ('::'+self.to_s). # '::' prepended for absolute path semantic
       gsub(/([a-z])([A-Z])/, '\1_\2').
-      gsub(/::/, '/').
+      gsub(/(::)+/, '/').
       downcase
   end
   # ::nodoc::

data/{maveric → lib/maveric}/sessions.rb

@@ -1,4 +1,4 @@
-module Maveric
+class Maveric
   ##
   # Contains session data and provides conveniance in generating an appropriate
   # cookie.

metadata

@@ -3,13 +3,13 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: maveric
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
-date: 2007-01-22 00:00:00 -07:00
+  version: 0.3.0
+date: 2007-01-26 00:00:00 -07:00
 summary: A simple, non-magical, framework.
 require_paths: 
-- .
+- lib/
 email: blinketje@gmail.com
-homepage: 
+homepage: http://maveric.rubyforge.org/
 rubyforge_project: 
 description: 
 autorequire: maveric
@@ -29,12 +29,12 @@ post_install_message:
 authors: 
 - blink
 files: 
-- maveric.rb
-- maveric/mongrel.rb
-- maveric/fastcgi.rb
-- maveric/webrick.rb
-- maveric/sessions.rb
-- maveric/extensions.rb
+- lib/maveric.rb
+- lib/maveric/mongrel.rb
+- lib/maveric/fastcgi.rb
+- lib/maveric/webrick.rb
+- lib/maveric/sessions.rb
+- lib/maveric/extensions.rb
 test_files: []
 
 rdoc_options: []