kiss 0.9.4 → 1.0

data/VERSION

@@ -1 +1 @@
-0.9.4
+1.0

data/lib/kiss.rb

@@ -31,6 +31,32 @@ module Rack
   autoload :ShowExceptions, 'kiss/rack/show_exceptions'
 end
 
+module Digest; end
+
+class Class
+  # adapted from Rails, re-written for speed (only one class_eval call)
+  def cattr_reader(*syms)
+    class_eval(
+      syms.flatten.map do |sym|
+        sym.is_a?(Hash) ? '' : %Q(
+          unless defined? @@#{sym}
+            @@#{sym} = nil
+          end
+
+          def self.#{sym}
+            @@#{sym}
+          end
+
+          def #{sym}
+            @@#{sym}
+          end
+        
+        )
+      end.join, __FILE__, __LINE__
+    )
+  end
+end
+
 # Kiss - An MVC web application framework for Ruby, built on:
 # * Erubis template engine
 # * Sequel database ORM library
@@ -40,523 +66,580 @@ class Kiss
   autoload :Mailer, 'kiss/mailer'
   autoload :Iterator, 'kiss/iterator'
   autoload :Form, 'kiss/form'
+  autoload :Format, 'kiss/format'
   autoload :SequelSession, 'kiss/sequel_session'
+  autoload :StaticFile, 'kiss/static_file'
+  autoload :Bench, 'kiss/bench'
+  autoload :Debug, 'kiss/debug'
+  
+  @@digest = {
+    :MD5 => "digest/md5",
+    :RMD160 => "digest/rmd160",
+    :SHA1 => "digest/sha1",
+    :SHA256 => "digest/sha2",
+    :SHA384 => "digest/sha2",
+    :SHA512 => "digest/sha2"
+  }
+  @@digest.each_pair do |type,path|
+    Digest.autoload type, path
+  end
   
-  attr_reader :action, :action_subdir, :action_path, :extension, :host, :template_dir,
-    :email_template_dir, :upload_dir, :evolution_dir, :asset_dir, :public_dir, :params, :args, :db,
-    :login, :request, :environment
+  # attributes below are application-wide
+  cattr_reader :action_dir, :template_dir, :email_template_dir, :model_dir, :upload_dir,
+    :evolution_dir, :asset_dir, :public_dir, :db, :environment, :options, :layout, :rack_file
   
-  @@default_action = 'index'
+  # attributes below are request-specific
+  attr_reader :params, :args, :action, :action_subdir, :action_path, :extension, :host, :request,
+    :session, :login
   
-  @@cookie_name = 'Kiss'
+  attr_accessor :last_sql
+  
+  @@default_action = 'index'
+  @@default_cookie_name = 'Kiss'
   
   # these supplement the mime types from Rack::File
   @@mime_types = {
     'rhtml' => 'text/html'
   }
   
-  # Purposely empty class.
-  # ActionDone exception is raised when render complete to abort execution.
-  # Could probably use throw...catch instead.
-  class ActionDone < Exception; end
-  
   ### Class Methods
   
-  # Creates a new Kiss instance and runs it.
-  def self.run(options = {})
-    new(options).run
-  end
-  
-  # Converts date strings from m/d/y to y/m/d. Useful for MySQL.
-  def self.mdy_to_ymd(date)
-    return '0000-00-00' unless date && date =~ /\S/
-    date.sub!(/\A\D+/,'')
-    date.sub!(/\D+\Z/,'')
-    
-    month, day, year = date.split(/\D+/,3).each {|s| s.to_i}
-    
-    return 0 unless month && day
-    
-    current_year = Time.now.year
-    if !year || year.length == 0
-      # use current year if year is missing.
-      year = current_year
-    else
-      # convert two-digit years to four-digit years
-      year = year.to_i
-      if year < 100
-        year += 1900
-        year += 100 if year < current_year - 95
-      end
+  class << self
+    # Creates new controller instance to handle Rack request.
+    def call(env)
+      new.call(env)
     end
     
-    return sprintf("%04d-%02d-%02d",year,month.to_i,day.to_i)
-  end
-  
-  # Returns regexp and error message for validating specified format.
-  # Will likely be rewritten in a future version of Kiss.
-  def self.format_details(format)
-    if format.is_a?(Regexp)
-      return format, 'invalid value'
-    end
+    # Runs Kiss application found at project_dir (default: '..'), with options 
+    # read from config files plus additional options if passed in.
+    def run(options = nil)
+      begin
+        if @@options
+          merge_options(options) if options
+        else
+          load(options)
+        end
     
-    case format
-    when :integer
-      return /\A\-?\d+\Z/,
-        'must be an integer'
+        # TODO: rewrite evolution file exists check for speed
+        check_evolution_number if @@db
+      
+        app = self
+        builder_options = @@options[:rack_builder] || []
+        rack = Rack::Builder.new do
+          builder_options.each do |builder_option|
+            if builder_option.is_a?(Array)
+              builder_args = builder_option
+              builder_option = builder_args.shift
+            else
+              builder_args = []
+            end
         
-    when :integer_positive, :positive_integer, :id
-      return /\A\d*[1-9]\d*\Z/,
-        'must be a positive integer'
-
-    when :integer_unsigned, :unsigned_integer, :id_or_zero, :id_zero
-      return /\A\d+\Z/,
-        'must be a positive integer or zero'
-
-    when :integer_negative, :negative_integer
-      return /\A\-\d*[1-9]\d*\Z/,
-        'must be a negative integer'
+            unless builder_option.is_a?(Class)
+              builder_option = Rack.const_get(builder_option.to_s)
+            end
         
-    when :decimal
-      return /\A\-?(\d+(\.\d*)?|\.\d+)\Z/,
-        'must be a decimal number'
+            use(builder_option,*builder_args)
+          end
 
-    when :alphanum
-      return /\A[a-z0-9]+\Z/,
-        'only letters and numbers'
-
-    when :word
-      return /\A\w+\Z/,
-        'only letters, numbers, and _'
-
-    when :email_address
-      return /\A[A-Z0-9._%+-]+\@([A-Z0-9-]+\.)+[A-Z]{2,4}\Z/i,
-        'must be a valid email address'
-
-    when :date
-      return /\A\d+\D\d+(\D\d+)?\Z/,
-        'must be a valid date'
-
-    when :time
-      return /\A\d+\:\d+\s*[ap]m\Z/i,
-        'must be a valid time'
-        
-    when :datetime
-      return /\A\d+\D\d+(\D\d+)?\s+\d{1,2}\:\d{2}\s*[ap]m\Z/i,
-        'must be a valid date and time'
+          run app
+        end
         
-    end
-  end
-  
-  # Validates value against specified format.
-  # If required is true, value must contain a non-whitespace character.
-  # If required is false, value need not match format if and only if value contains only whitespace.
-  def self.validate_value(value,format,required = false)
-    if required && (value !~ /\S/)
-      # value required
-      return 'required'
-    elsif format && (value =~ /\S/)
-      regexp,error = format_details(format)
-      return error unless value =~ regexp
+        handler = @@options[:rack_handler] || Rack::Handler::WEBrick
+        if !handler.is_a?(Class)
+          handler = Rack::Handler.const_get(handler.to_s)
+        end
+        handler.run(rack,@@options[:rack_handler_options] || {:Port => 4000})
+      rescue StandardError, LoadError, SyntaxError => e
+        if @@options[:rack_handler] == :CGI
+          print "Content-type: text/html\n\n"
+          print Kiss::ExceptionReport.generate(e)
+        else
+          print "Content-type: text/plain\n\n"
+          puts "exception:\n" + e.message
+          puts "\ntraceback:\n" + e.backtrace.join("\n")
+        end
+      end
     end
     
-    return nil
-  end
-  
-  # Generates string of random text of the specified length.
-  def self.random_text(length)
-    chars = ('A'..'Z').to_a + ('0'..'9').to_a  # array
-  
-    text = ''
-    size = chars.size
-    length.times { text += chars[rand(size)] }
+    # Load and set up Kiss application from config file options and
+    # any passed-in options.
+    def load(loader_options = nil)
+      # store cached files
+      @@file_cache = {}
+      @@directory_cache = {}
+      @@file_cache_time = {}
+      
+      loader_options ||= {}
+      # if loader_options is string, then it specifies environment
+      # else it should be a hash of config options
+      if loader_options.is_a?(String)
+        loader_options = { :environment => loader_options }
+      end
     
-    text
-  end
-  
-  # Returns exception cache, for use in Kiss::ExceptionReport.
-  def self.exception_cache
-    @@exception_cache
-  end
-  
-  ### Instance Methods
-  
-  # Adds specified data to exception cache, to be included in reports generated
-  # by Kiss::ExceptionReport in case of an exception.
-  def set_exception_cache(data)
-    @@exception_cache.merge!(data)
-  end
-  
-  # Clears exception cache.
-  def clear_exception_cache
-    @@exception_cache = {}
-  end
-  
-  # Generates string of random text of the specified length.
-  def random_text(*args)
-    self.class.random_text(*args)
-  end
-  
-  # Returns URL/URI of app root (corresponding to top level of action_dir).
-  def app(suffix = nil)
-    suffix ? @app_url + suffix : @app_url
-  end
-  
-  # Returns path of current action, under action_dir.
-  def action
-    @action
-  end
-  
-  # Kiss Model cache, used to invoke and store Kiss database models.
-  #
-  # Example:
-  # models[:users] : database model for `users' table
-  def models
-    @dbm
-  end
-  alias_method :dbm, :models
-  
-  # Returns URL/URI of app's static assets (asset_host or public_uri).
-  def assets(suffix = nil)
-    @pub ||= @options[:asset_host]
-    suffix ? @pub + '/' + suffix : @pub
-  end
-  alias_method :pub, :assets
-  
-  # Returns true if specified path is a directory.
-  # Cache result if file_cache_no_reload option is set; otherwise, always check filesystem.
-  def directory_exists?(dir)
-    @options[:file_cache_no_reload] ? (
-      @directory_cache.has_key?(path) ?
-        @directory_cache[dir] :
-        @directory_cache[dir] = File.directory?(dir)
-      ) : File.directory?(dir)
-  end
-  
-  # Caches the specified file and return its contents.
-  # If block given, executes block on contents, then cache and return block result.
-  # If fnf_file_type given, raises exception (of type fnf_exception_class) if file is not found.
-  def file_cache(path, fnf_file_type = nil, fnf_exception_class = Kiss::FileNotFound)
-    if (@options[:file_cache_no_reload] && @file_cache.has_key?(path)) || @files_cached_this_request[path]
-      return @file_cache[path]
-    end
+      # environment
+      @@environment = loader_options[:environment]
     
-    @files_cached_this_request[path] = true
+      # directories
+      script_dir = $0.sub(/[^\/]+\Z/,'')
+      script_dir = '' if script_dir == './'
+      @@project_dir = script_dir + (loader_options[:project_dir] || loader_options[:root_dir] || '..')
+      Dir.chdir(@@project_dir)
     
-    if !File.file?(path)
-      raise fnf_exception_class, "#{fnf_file_type} file missing: '#{path}'" if fnf_file_type
-      
-      @file_cache[path] = nil
-      contents = nil
-    else
-      # expire cache if file (or symlink) modified
-      # TODO: what about symlinks to symlinks?
-      if !@file_cache_time[path] ||
-        @file_cache_time[path] < File.mtime(path) ||
-        ( File.symlink?(path) && (@file_cache_time[path] < File.lstat(path).mtime) )
-      
-          @file_cache[path] = nil
-          @file_cache_time[path] = Time.now
-          contents = File.read(path)
-      end
-    end
-      
-    @file_cache[path] ||= begin
-      (block_given?) ? yield(contents) : contents
-    end
-  end
-  
-  # Merges specified options into previously defined/merged Kiss options.
-  def merge_options(config_options)
-    if config_options
-      if env_vars = config_options.delete(:ENV)
-        env_vars.each_pair {|k,v| ENV[k] = v }
-      end
-      if lib_dirs = config_options.delete(:lib_dirs)
-        @lib_dirs.push( lib_dirs )
+      @@config_dir = loader_options[:config_dir] || 'config'
+    
+      # get environment name from config/environment
+      if (@@environment.nil?) && File.file?(env_file = @@config_dir+'/environment')
+        @@environment = File.read(env_file).sub(/\s+\Z/,'')
       end
-      if gem_dirs = config_options.delete(:gem_dirs)
-        @gem_dirs.push( gem_dirs )
+    
+      # init options
+      @@options = {
+        :layout => '/_layout'
+      }
+      @@lib_dirs = ['lib']
+      @@gem_dirs = ['gems']
+      @@require = []
+    
+      # common (shared) config
+      if (File.file?(config_file = @@config_dir+'/common.yml'))
+        merge_options( YAML::load(File.read(config_file)) )
       end
-      if require_libs = config_options.delete(:require)
-        @require.push( require_libs )
+      # environment config
+      if (File.file?(config_file = "#{@@config_dir}/environments/#{@@environment}.yml"))
+        merge_options( YAML::load(File.read(config_file)) )
       end
     
-      @options.merge!( config_options )
-    end
-  end
-  
-  # Create a new Kiss application instance, based on specified options.
-  def initialize(loader_options = {})
-    # store cached files
-    @file_cache = {}
-    @directory_cache = {}
-    @file_cache_time = {}
-    
-    # if loader_options is string, then it specifies environment
-    # else it should be a hash of config options
-    if loader_options.is_a?(String)
-      loader_options = { :environment => loader_options }
-    end
-    
-    # environment
-    @environment = loader_options[:environment]
+      merge_options( loader_options )
     
-    # directories
-    script_dir = $0.sub(/[^\/]+\Z/,'')
-    script_dir = '' if script_dir == './'
-    @project_dir = script_dir + (loader_options[:project_dir] || loader_options[:root_dir] || '..')
-    Dir.chdir(@project_dir)
+      # set class vars from options
+      @@action_dir = @@options[:action_dir] || 'actions'
+      @@template_dir = @@options[:template_dir] ? @@options[:template_dir] : @@action_dir
     
-    @config_dir = loader_options[:config_dir] || 'config'
+      @@asset_dir = @@public_dir = @@options[:asset_dir] || @@options[:public_dir] || 'public_html'
     
-    # get environment name from config/environment
-    if (@environment.nil?) && File.file?(env_file = @config_dir+'/environment')
-      @environment = File.read(env_file).sub(/\s+\Z/,'')
-    end
+      @@model_dir = @@options[:model_dir] || 'models'
+      Kiss::ModelCache.model_dir = @@model_dir
+      
+      @@evolution_dir = @@options[:evolution_dir] || 'evolutions'
     
-    # init options
-    @options = {}
-    @lib_dirs = ['lib']
-    @gem_dirs = ['gems']
-    @require = []
+      @@email_template_dir = @@options[:email_template_dir] || 'email_templates'
+      @@upload_dir = @@options[:upload_dir] || 'uploads'
     
-    # common (shared) config
-    if (File.file?(config_file = @config_dir+'/common.yml'))
-      merge_options( YAML::load(File.read(config_file)) )
-    end
-    # environment config
-    if (File.file?(config_file = "#{@config_dir}/environments/#{@environment}.yml"))
-      merge_options( YAML::load(File.read(config_file)) )
-    end
+      @@cookie_name = @@options[:cookie_name] || @@default_cookie_name
+      @@default_action = @@options[:default_action] || @@default_action
+      @@action_root_class = @@options[:action_class] || Class.new(Kiss::Action)
+      
+      # exception log
+      @@exception_log_file = @@options[:exception_log] ? ::File.open(@@options[:exception_log],'a') : nil
+      
+      # default layout
+      @@layout = @@options[:layout]
     
-    merge_options( loader_options )
+      # public_uri: uri of requests to serve from public_dir
+      @@asset_uri = @@public_uri = @@options[:asset_uri] || @@options[:public_uri]
+      @@rack_file = Rack::File.new(@@asset_dir) if @@asset_uri
     
-    # set class vars from options
-    @action_dir = @options[:action_dir] || 'actions'
-    @template_dir = @options[:template_dir] ? @options[:template_dir] : @action_dir
+      # app_url: URL of the app actions root
+      @@app_host = @@options[:app_host] ? ('http://' + @@options[:app_host]) : ''
+      @@app_uri = @@options[:app_uri] || ''
+      @@app_url =  @@app_host + @@app_uri
     
-    @asset_dir = @public_dir = @options[:asset_dir] || @options[:public_dir] || 'public_html'
+      # include lib dirs
+      $LOAD_PATH.unshift(*( @@lib_dirs.flatten.select {|dir| File.directory?(dir) } ))
     
-    @model_dir = @options[:model_dir] || 'models'
-    @evolution_dir = @options[:evolution_dir] || 'evolutions'
+      # add gem dir to rubygems search path
+      Gem.path.unshift(*( @@gem_dirs.flatten.select {|dir| File.directory?(dir) } ))
     
-    @email_template_dir = @options[:email_template_dir] || 'email_templates'
-    @upload_dir = @options[:upload_dir] || 'uploads'
+      # require libs
+      @@require.flatten.each {|lib| require lib }
     
-    @cookie_name = @options[:cookie_name] || 'Kiss'
-    @default_action = @options[:default_action] || @@default_action
-    @action_root_class = @options[:action_class] || Class.new(Kiss::Action)
+      # session class
+      if (@@options[:session_class])
+        @@session_class = (@@options[:session_class].class == Class) ? @@options[:session_class] :
+          @@options[:session_class].to_const
+      end
     
-    # public_uri: uri of requests to serve from public_dir
-    @asset_uri = @public_uri = @options[:asset_uri] || @options[:public_uri]
-    @rack_file = Rack::File.new(@asset_dir) if @asset_uri
+      # load extensions to action class
+      action_extension_path = @@action_dir + '/_action.rb'
+      if File.file?(action_extension_path)
+        @@action_root_class.class_eval(File.read(action_extension_path),action_extension_path) rescue nil
+      end
     
-    # include lib dirs
-    $LOAD_PATH.unshift(*( @lib_dirs.flatten.select {|dir| File.directory?(dir) } ))
+      # database
+      if sequel = @@options[:database]
+        # open database connection (if not already open)
+        @@db = sequel.is_a?(String) ? (Sequel.open sequel) : sequel.is_a?(Hash) ? (Sequel.open sequel) : sequel
+      
+        if @@db.class.name == 'Sequel::MySQL::Database'
+          # add fetch_arrays, all_arrays methods
+          require 'kiss/sequel_mysql'
+          # turn off convert_tinyint_to_bool, unless options say otherwise
+          Sequel.convert_tinyint_to_bool = false unless @@options[:convert_tinyint_to_bool]
+        end
+      end
     
-    # add gem dir to rubygems search path
-    Gem.path.unshift(*( @gem_dirs.flatten.select {|dir| File.directory?(dir) } ))
+      # setup session storage, if session class specified in config
+      @@session_class.setup_storage(self) if @@session_class
     
-    # require libs
-    @require.flatten.each {|lib| require lib }
+      # prepare authenticate_exclude
+      if @@options[:authenticate_all]
+        if @@options[:authenticate_exclude].is_a?(Array)
+          @@options[:authenticate_exclude] = @@options[:authenticate_exclude].map do |action|
+            action = '/'+action unless action =~ /\A\//
+            action
+          end
+        else
+          @@options[:authenticate_exclude] = []
+        end
+      end
     
-    # session class
-    if (@options[:session_class])
-      @session_class = (@options[:session_class].class == Class) ? @options[:session_class] : @options[:session_class].to_const
+      self
     end
-    
-    # load extensions to action class
-    action_extension_path = @action_dir + '/_action.rb'
-    if File.file?(action_extension_path)
-      @action_root_class.class_eval(File.read(action_extension_path),action_extension_path) rescue nil
+  
+    # Returns URL/URI of app's static assets (asset_host or public_uri).
+    def assets(suffix = nil)
+      @@pub ||= @@options[:asset_host]
+      suffix ? @@pub + '/' + suffix : @@pub
+    end
+    alias_method :pub, :assets
+  
+    # Returns true if specified path is a directory.
+    # Cache result if file_cache_no_reload option is set; otherwise, always check filesystem.
+    def directory_exists?(dir)
+      @@options[:file_cache_no_reload] ? (
+        @@directory_cache.has_key?(path) ?
+          @@directory_cache[dir] :
+          @@directory_cache[dir] = File.directory?(dir)
+        ) : File.directory?(dir)
     end
-    
-    # set controller access variables
-    @action_root_class.set_controller(self)
-    Kiss::Model.set_controller(self)
-    Kiss::Mailer.set_controller(self)
-    
-    # database
-    if sequel = @options[:database]
-      # open database connection (if not already open)
-      @db = sequel.is_a?(String) ? (Sequel.open sequel) : sequel.is_a?(Hash) ? (Sequel.open sequel) : sequel
-      # add query logging to database class
-      @db.class.class_eval do
-        @@query = nil
-        def self.last_query
-          @@query
-        end
   
-        alias_method :execute_old, :execute
-        def execute(sql, *args, &block)
-          @@query = sql
-          execute_old(sql, *args, &block)
+    # Merges specified options into previously defined/merged Kiss options.
+    def merge_options(config_options)
+      if config_options
+        if env_vars = config_options.delete(:ENV)
+          env_vars.each_pair {|k,v| ENV[k] = v }
         end
+        if lib_dirs = config_options.delete(:lib_dirs)
+          @@lib_dirs.push( lib_dirs )
+        end
+        if gem_dirs = config_options.delete(:gem_dirs)
+          @@gem_dirs.push( gem_dirs )
+        end
+        if require_libs = config_options.delete(:require)
+          @@require.push( require_libs )
+        end
+    
+        @@options.merge!( config_options )
       end
-      
-      if @db.class.name == 'Sequel::MySQL::Database'
-        # fix sequel mysql bugs; add all_rows
-        require 'kiss/sequel_mysql'
-        Sequel.convert_tinyint_to_bool = false unless @options[:convert_tinyint_to_bool]
-      end
-      
-      # create models cache
-      @dbm = Kiss::ModelCache.new(self,@model_dir)
     end
     
-    # setup session storage, if session class specified in config
-    @session_class.setup_storage(self) if @session_class
+    # Converts passed-in filename to absolute path if it does not start with '/'.
+    def absolute_path(filename)
+      filename = ( filename =~ /\A\// ? '' : (Dir.pwd + '/') ) + filename
+    end
     
-    # prepare authenticate_exclude
-    if @options[:authenticate_all]
-      if @options[:authenticate_exclude].is_a?(Array)
-        @options[:authenticate_exclude] = @options[:authenticate_exclude].map do |action|
-          action = '/'+action unless action =~ /\A\//
-          action
-        end
+    # Returns string representation of object with HTML entities escaped.
+    def h(obj)
+      case obj
+      when String
+        Rack::Utils.escape_html(obj).gsub(/^(\s+)/) {'&nbsp;' * $1.length}
       else
-        @options[:authenticate_exclude] = []
+        Rack::Utils.escape_html(obj.inspect)
       end
     end
     
-    self
-  end
-  
-  # Sets up Rack builder options and begins Rack execution. 
-  def run(options = {})
-    merge_options(options)
-    
-    app = self
-    builder_options = @options[:rack_builder] || []
-    rack = Rack::Builder.new do
-      builder_options.each do |builder_option|
-        if builder_option.is_a?(Array)
-          builder_args = builder_option
-          builder_option = builder_args.shift
-        else
-          builder_args = []
+    # Returns MIME type corresponding to passed-in extension.
+    def mime_type(extension)
+      Rack::File::MIME_TYPES[extension] || @@mime_types[extension]
+    end
+    
+    # Returns Digest class used to generate digest of specified type.
+    def digest_class(type)
+      type = type.to_sym
+      @@digest[type] ? Digest.const_get(type) : nil
+    end
+    
+    # Converts date strings from m/d/y to y/m/d. Useful for MySQL.
+    def mdy_to_ymd(date)
+      return '0000-00-00' unless date && date =~ /\S/
+      date.sub!(/\A\D+/,'')
+      date.sub!(/\D+\Z/,'')
+    
+      month, day, year = date.split(/\D+/,3).each {|s| s.to_i}
+    
+      return 0 unless month && day
+      
+      current_year = Time.now.year
+      if !year || year.length == 0
+        # use current year if year is missing.
+        year = current_year
+      else
+        # convert two-digit years to four-digit years
+        year = year.to_i
+        if year < 100
+          year += 1900
+          year += 100 if year < current_year - 95
         end
-        
-        unless builder_option.is_a?(Class)
-          builder_option = Rack.const_get(builder_option.to_s)
+      end
+    
+      return sprintf("%04d-%02d-%02d",year,month.to_i,day.to_i)
+    end
+  
+    # Validates value against specified format.
+    # If required is true, value must contain a non-whitespace character.
+    # If required is false, value need not match format if and only if value contains only whitespace.
+    def validate_value(value, format, required = false, label = nil)
+      if required && (value !~ /\S/)
+        # value required
+        raise "#{label || 'value'} required"
+      elsif format && (value =~ /\S/)
+        format = Kiss::Format.lookup(format)
+      
+        begin
+          format.validate(value)
+        rescue Kiss::Format::ValidateError => e
+          raise e.class, "#{label} validation error: #{e.message}"
         end
-        
-        use(builder_option,*builder_args)
       end
-
-      run app
     end
+  
+    # Generates string of random text of the specified length.
+    def random_text(length)
+      chars = ('A'..'Z').to_a + ('0'..'9').to_a  # array
+  
+      text = ''
+      size = chars.size
+      length.times { text += chars[rand(size)] }
     
-    handler = @options[:rack_handler] || Rack::Handler::WEBrick
-    if !handler.is_a?(Class)
-      handler = Rack::Handler.const_get(handler.to_s)
+      text
     end
-    handler.run(rack,@options[:rack_handler_options] || {:Port => 4000})
-  end
   
-  # Processes and responds to requests received via Rack.
-  # Returns Rack::Response object.
-  def call(env)
-    clear_exception_cache
+    # Returns exception cache, for use in Kiss::ExceptionReport.
+    def exception_cache
+      @@exception_cache
+    end
+    
+    # Given a file path, caches or returns the file's contents or the return value of
+    # the passed block applied to the file's contents.
+    # If file is not found, raises exception of type fnf_exception_class.
+    def file_cache(path, fnf_file_type = nil, fnf_exception_class = Kiss::FileNotFound)
+      if (@@options[:file_cache_no_reload] && @@file_cache.has_key?(path))
+        return @@file_cache[path]
+      end
+      
+      if !File.file?(path)
+        raise fnf_exception_class, "#{fnf_file_type} file missing: '#{path}'" if fnf_file_type
     
-    if (env["PATH_INFO"] == '/favicon.ico') ||
-      (@asset_uri && env["PATH_INFO"].sub!(Regexp.new("\\A#{@asset_uri}"),''))
-        return @rack_file.call(env)
+        @@file_cache[path] = nil
+        contents = nil
+      else
+        # expire cache if file (or symlink) modified
+        # TODO: what about symlinks to symlinks?
+        if !@@file_cache_time[path] ||
+          @@file_cache_time[path] < File.mtime(path) ||
+          ( File.symlink?(path) && (@@file_cache_time[path] < File.lstat(path).mtime) )
+    
+            @@file_cache[path] = nil
+            @@file_cache_time[path] = Time.now
+            contents = File.read(path)
+        end
+      end
+      
+      @@file_cache[path] ||= begin
+        (block_given?) ? yield(contents) : contents
+      end
     end
     
-    check_evolution_number if @db
+    # Returns Sequel dataset to evolution_number table, which specifies app's current evolution number.
+    # Creates evolution_number table if it does not exist.
+    def evolution_number_table
+      unless db.table_exists?(:evolution_number)
+        db.create_table :evolution_number do
+          column :version, :integer, :null=> false
+        end
+        db[:evolution_number].insert(:version => 0)
+      end
+      db[:evolution_number]
+    end
+  
+    # Returns app's current evolution number.
+    def evolution_number
+      evolution_number_table.first.version
+    end
+  
+    # Sets app's current evolution number.
+    def evolution_number=(version)
+      load unless @@options
+      evolution_number_table.update(:version => version)
+    end
+  
+    # Check whether there exists a file in evolution_dir whose number is greater than app's
+    # current evolution number. If so, raise an error to indicate need to apply new evolutions.
+    def check_evolution_number
+      version = evolution_number
+      if Kiss.directory_exists?(@@evolution_dir) &&
+          Dir.entries(@@evolution_dir).select { |f| f =~ /\A0*#{version+1}_/ }.size > 0
+        raise "current evolution #{version} is outdated; apply evolutions or update evolution number"
+      end
+    end
+  end # end class methods
+  
+  ### Instance Methods
+  
+  # Creates a new controller instance, and also configures the application with the
+  # specified options.
+  def initialize(options = nil)
+    if @@options
+      self.class.merge_options(options) if options
+    else
+      self.class.load(options)
+    end
     
+    @exception_cache = {}
+    @debug_messages = []
+    @benchmarks = []
     @files_cached_this_request = {}
+  end
+  
+  # Caches the specified file and return its contents.  See Kiss.file_cache above.
+  def file_cache(path, fnf_file_type = nil, fnf_exception_class = Kiss::FileNotFound, &block)
+    return @@file_cache[path] if @files_cached_this_request[path]
+    @files_cached_this_request[path] = true
     
-    get_request(env)
-    
-    @response = Rack::Response.new
+    self.class.file_cache(path, fnf_file_type, fnf_exception_class, &block)
+  end
+  
+  # Processes and responds to a request received via Rack.  Should only be called once
+  # for each controller instance (i.e. each controller instance should handle at most 
+  # one request, then be discarded).  Returns array of response code, headers, and body.
+  def call(env)
+    if @@rack_file && (
+      (env["PATH_INFO"] == '/favicon.ico') ||
+       (env["PATH_INFO"].sub!(Regexp.new("\\A#{@@asset_uri}"),''))
+    )
+      return @@rack_file.call(env)
+    end
     
-    begin
-      parse_action_path(@path)
+    # catch and report exceptions in this block
     
-      setup_session
-      if login_session_valid?
-        load_from_login_session
-      elsif @options[:authenticate_all]
-        if (!@options[:authenticate_exclude].is_a?(Array) ||
-            @options[:authenticate_exclude].select {|action| action == @action}.size == 0)
-          authenticate
+    code, headers, body = begin
+      get_request(env)
+      @response = Rack::Response.new
+      
+      catch :kiss_action_done do
+        parse_action_path(@path)
+        env['kiss.parsed_action'] = @action
+        env['kiss.parsed_args'] = @args.inspect
+        
+        setup_session
+        if login_session_valid?
+          load_from_login_session
+        elsif @@options[:authenticate_all]
+          if (!@@options[:authenticate_exclude].is_a?(Array) ||
+              @@options[:authenticate_exclude].select {|action| action == @action}.size == 0)
+            authenticate
+          end
         end
+      
+        env['kiss.processed_action'] = @action
+        process.render
       end
-      process.render
-    rescue Kiss::ActionDone
+      finalize_session if @session
+      
+      @response.finish
+    rescue StandardError, LoadError, SyntaxError => e
+      body = Kiss::ExceptionReport.generate(e, env, @exception_cache, @last_sql)
+      if @@exception_log_file
+        @@exception_log_file.print(body + "\n--- End of exception report --- \n\n")
+      end
+      [500, {
+        "Content-Type" => "text/html",
+        "Content-Length" => body.length.to_s,
+        "X-Kiss-Error-Type" => e.class.name,
+        "X-Kiss-Error-Message" => e.message.sub(/\n.*/m,'')
+      }, body]
+    end
+    
+    if @debug_messages.size > 0
+      extend Kiss::Debug
+      body = prepend_debug(body)
+      headers['Content-Length'] = body.length.to_s
     end
-    finalize_session if @session
     
-    @response.finish
+    if @benchmarks.size > 0
+      stop_benchmark
+      extend Kiss::Bench
+      body = prepend_benchmarks(body)
+      headers['Content-Length'] = body.length.to_s
+    end
+    
+    [code,headers,body]
+  end
+  
+  # Adds debug message to inspect object.  Debug messages will be shown at top of
+  # application response body.
+  def debug(object, context = Kernel.caller[0])
+    @debug_messages.push( [object.inspect, context] )
+    object
+  end
+  
+  # Starts a new benchmark timer, with optional label.  Benchmark results will be shown 
+  # at top of application response body.
+  def bench(label = nil, context = Kernel.caller[0])
+    stop_benchmark(context)
+    @benchmarks.push(
+      :label => label,
+      :start_time => Time.now,
+      :start_context => context
+    )
+  end
+  
+  # Stops last benchmark timer, if still running.
+  def stop_benchmark(end_context = nil)
+    if @benchmarks[-1] && !@benchmarks[-1][:end_time]
+      @benchmarks[-1][:end_time] = Time.now
+      @benchmarks[-1][:end_context] = end_context
+    end
   end
   
   # Sets up request-specified variables based in request information received from Rack.
   def get_request(env)
     @request = Rack::Request.new(env)
     
-    @app_host = @options[:app_host] ? ('http://' + @options[:app_host]) : @request.server
-    @app_uri = @options[:app_uri] || @request.script_name || ''
+    @app_host = @@options[:app_host] ? ('http://' + @@options[:app_host]) : @request.server rescue ''
+    @app_uri = @@options[:app_uri] || @request.script_name || ''
     @app_url =  @app_host + @app_uri
     
     @path = @request.path_info || '/'
     @params = @request.params
     
-    @host ||= @request.host
+    @host ||= @request.host rescue ''
     @protocol = env['HTTPS'] == 'on' ? 'https' : 'http'
   end
   
-  # Returns Sequel dataset to evolution_number table, which specifies app's current evolution number.
-  # Creates evolution_number table if it does not exist.
-  def evolution_number_table
-    unless db.table_exists?(:evolution_number)
-      db.create_table :evolution_number do
-        column :version, :integer, :null=> false
-      end
-      db[:evolution_number].insert(:version => 0)
-    end
-    db[:evolution_number]
-  end
-  
-  # Returns app's current evolution number.
-  def evolution_number
-    evolution_number_table.first.version
-  end
-  
-  # Sets app's current evolution number.
-  def evolution_number=(version)
-    evolution_number_table.update(:version => version)
-  end
-  
-  # Check whether there exists a file in evolution_dir whose number is greater than app's
-  # current evolution number. If so, raise an error to indicate need to apply new evolutions.
-  def check_evolution_number
-    version = evolution_number
-    if directory_exists?(@evolution_dir) &&
-        Dir.entries(@evolution_dir).select { |f| f =~ /\A0*#{version+1}_/ }.size > 0
-      raise "current evolution #{version} is outdated; apply evolutions or update evolution number"
-    end
+  # Returns URL/URI of app root (corresponding to top level of action_dir).
+  def app_url(suffix = nil)
+    suffix ? @app_url + suffix : @app_url
   end
   
   # Loads session from session store (specified by session_class).
   def setup_session
     @login = {}
-    @session = @session_class ? begin
-      session = @session_class.persist(@request.cookies[@cookie_name])
-      @_fingerprint = Marshal.dump(session.data).hash
+    @session = @@session_class ? begin
+      session = @@session_class.persist(@request.cookies[@@cookie_name])
+      @session_fingerprint = Marshal.dump(session.data).hash
     
       cookie_vars = {
         :value => session.values[:session_id],
-        :path => @options[:cookie_path] || @app_uri,
-        :domain => @options[:cookie_domain] || @request.host
+        :path => @@options[:cookie_path] || @app_uri,
+        :domain => @@options[:cookie_domain] || @request.host
       }
-      cookie_vars[:expires] = Time.now + @options[:cookie_lifespan] if @options[:cookie_lifespan]
+      cookie_vars[:expires] = Time.now + @@options[:cookie_lifespan] if @@options[:cookie_lifespan]
     
       # set_cookie here or at render time
-      @response.set_cookie @cookie_name, cookie_vars
-      @login.merge!(session[:login]) if session[:login]
+      @response.set_cookie @@cookie_name, cookie_vars
+      @login.merge!(session[:login]) if session[:login] && session[:login][:expires_at] &&
+        session[:login][:expires_at] > Time.now
       
       session
     end : {}
@@ -564,11 +647,7 @@ class Kiss
   
   # Saves session to session store, if session data has changed since load.
   def finalize_session
-    @session.save if @_fingerprint != Marshal.dump(@session.data).hash
-  end
-  
-  def session
-    @session
+    @session.save if @session_fingerprint != Marshal.dump(@session.data).hash
   end
   
   ##### LOGIN SESSION #####
@@ -609,16 +688,16 @@ class Kiss
   
   # Calls login action's load_from_session method to populate request login hash.
   def load_from_login_session
-    klass = action_class('login')
+    klass = action_class('/login')
     raise 'load_from_login_session called, but no login action found' unless klass
     
-    action_handler = klass.new
+    action_handler = klass.new(self)
     action_handler.load_from_session
   end
   
   # Returns path to login action.
   def login_path
-    @action_dir + '/login.rb'
+    @@action_dir + '/login.rb'
   end
   
   # If valid login session exists, loads login action to populate request login hash data.
@@ -627,7 +706,7 @@ class Kiss
     if login_session_valid?
       load_from_login_session
     else
-      klass = action_class('login')
+      klass = action_class('/login')
       raise 'authenticate called, but no login action found' unless klass
       old_extension = @extension
       @extension = 'rhtml'
@@ -642,18 +721,14 @@ class Kiss
   
   ##### ACTION METHODS #####
   
-  def action_dir
-    @action_dir
-  end
-  
   # Creates and caches anonymous class with which to invoke specified (or current) action.
   def action_class(action = @action)
-    action_path = @action_dir + '/' + action.to_s + '.rb'
+    action_path = @@action_dir + action.to_s + '.rb'
     return nil unless action_path.is_a?(String) && action_path.length > 0
     
     file_cache(action_path) do |src|
       # create new action class, subclass of shared action parent class
-      klass = Class.new(@action_root_class)
+      klass = Class.new(@@action_root_class)
       klass.class_eval(src,action_path) if src
       klass
     end
@@ -664,17 +739,17 @@ class Kiss
     @action_subdir = ''
     @action = nil
     
-    redirect_url(app + '/') if path == ''
+    redirect_url(app_url + '/') if path == ''
     
-    path += @default_action if path =~ /\/\Z/
+    path += @@default_action if path =~ /\/\Z/
     
     parts = path.sub(/^\/*/,'').split('/')
     
     while part = parts.shift
       raise 'bad action' if part !~ /\A[a-z0-9][\w\-\.]*\Z/i
       
-      test_path = @action_dir + @action_subdir + '/' + part
-      if directory_exists?(test_path)
+      test_path = @@action_dir + @action_subdir + '/' + part
+      if Kiss.directory_exists?(test_path)
         @action_subdir += '/' + part
         next
       end
@@ -692,9 +767,9 @@ class Kiss
     
     # if no action, must have traversed all parts to a directory
     # add a trailing slash and try again
-    redirect_url(app + '/' + path + '/') unless @action
+    redirect_url(app_url + '/' + path + '/') unless @action
     
-    @action_path = @action_dir + '/' + @action + '.rb'
+    @action_path = @@action_dir + '/' + @action + '.rb'
     
     # keep rest of path_info in args
     @args = parts
@@ -703,28 +778,34 @@ class Kiss
   # Processes specified (or current) action, by instantiating its anonymous
   # action class and invoking `call' method on the instance.
   def process(klass = action_class, action_path = @action_path)
-    action_handler = klass.new
+    action_handler = klass.new(self)
     action_handler.call
     
     # return handler to follow with render
     action_handler
   end
   
-  ##### RACK OUTPUT METHODS #####
+  # Outputs a Kiss::StaticFile object as response to Rack.
+  # Used to return static files efficiently.
+  def send_file(path, mime_type = nil)
+    @response = Kiss::StaticFile.new(path,mime_type)
+    
+    throw :kiss_action_done
+  end
   
-  # Prepares Rack::Response object to be returned to Rack.
+  # Prepares Rack::Response object to return application response to Rack.
   # Raises Kiss::ActionDone exception to bypass caller stack and return directly 
   # to Kiss#call.
   def send_response(output = '',options = {})
-    content_type = options[:content_type] || @content_type || 
-      (extension ? Rack::File::MIME_TYPES[extension] || @@mime_types[extension] : nil)
+    content_type = options[:content_type] || 
+      (extension ? Kiss.mime_type(extension) : nil)
     document_encoding ||= 'utf-8'
     
     @response['Content-Type'] = "#{content_type}; #{document_encoding}" if content_type
     @response['Content-Length'] = output.length.to_s
     @response.body = output
     
-    raise Kiss::ActionDone
+    throw :kiss_action_done
     
     # back to Kiss#call, which finalizes session and returns @response
     # (throws exception if no @response set)
@@ -738,7 +819,25 @@ class Kiss
   end
   
   # Returns new Kiss::Mailer object using specified options.
-  def new_email(*options)
-    Kiss::Mailer.new(*options)
+  def new_email(options = {})
+    Kiss::Mailer.new(options)
+  end
+  
+  # Kiss Model cache, used to invoke and store Kiss database models.
+  #
+  # Example:
+  # models[:users] : database model for `users' table
+  def dbm
+    @dbm ||= Kiss::ModelCache.new(self)
+  end
+  alias_method :models, :dbm
+  
+  def h(*args)
+    self.class.h(*args)
+  end
+  
+  # Adds data to be displayed in "Cache" section of Kiss exception reports.
+  def set_exception_cache(data)
+    @exception_cache.merge!(data)
   end
 end