0
@@ -1,3 +1,13 @@
0
+0.7.5
0
+- Foundations and Layers
0
+- Sequel ORM is now a Layer, instead of being baked in
0
+- Almost all boilerplate code removed from generated app, by virtue of the Layers refactoring
0
+- Configuration attribute for selecting a Rack handler
0
+- Mapping#handle method to register blocks that handle exceptions (e.g. NotFoundError)
0
+- Blackboard, a very simple shared storaged usable during request processing.
0
+- Fixed waves script to work when installed as gem (regression)
0
+- Revised and extended documentation
0
+- Expanded spec coverage
0
 0.7.3:
0
 - Added explicit require for daemons gem
0
 - Added support for running off source

0
@@ -6,20 +6,6 @@ module Waves
0
 
0
       def attributes; params[model_name.singular.intern]; end
0
 
0
-      # def all; model.all; end
0
-      # 
0
-      # def find( name ); model[ :name => name ] or not_found; end
0
-      # 
0
-      # def create; model.create( attributes ); end
0
-      # 
0
-      # def update( name )
0
-      #   instance = find( name )
0
-      #   instance.set( attributes )
0
-      #   instance.save_changes
0
-      # end
0
-      # 
0
-      # def delete( name ); find( name ).destroy; end
0
-
0
     end
0
   end
0
 end
0
\ No newline at end of file

0
@@ -76,13 +76,12 @@ module Waves
0
   module Controllers
0
 
0
     #
0
-    # This mixin provides some handy methods for Waves controllers. You will probably
0
-    # want to include it in any controllers you define for your application. The controllers
0
-    # autocreated in the Default foundation already do this.
0
+    # Waves::Controllers::Mixin adapts a controller class for use in mappings and provides utility methods.     
0
+    # It is included in controllers autocreated by the Default foundation, so you do not need to include
0
+    # it in subclasses of the same. 
0
     #
0
-    # Basically, what the mixin does is adapt the class so that it can be used within
0
-    # mappings (see Waves::Mapping); add some simple reflection to allow controller methods
0
-    # to be written generically (i.e., without reference to a specific model); and provide
0
+    # The utility methods include simple reflection to allow controller methods
0
+    # to be written generically (i.e., without reference to a specific model) and
0
     # parameter destructuring for the request parameters.
0
     #
0
 
0
@@ -92,10 +91,10 @@ module Waves
0
 
0
       include Waves::ResponseMixin
0
 
0
-      # When you include this Mixin, a +process+ class method is added to your class,
0
-      # which accepts a request object and a block. The request object is used to initialize
0
-      # the controller and the block is evaluated using +instance_eval+. This allows the
0
-      # controller to be used within a mapping file.
0
+      # When this mixin is included it adds a class method named +process+,
0
+      # which accepts a request object and a block. The +process+ method initializes the
0
+      # controller with the request, then evaluates the block using +instance_eval+. This allows the
0
+      # controller to be used from within a mapping lambda (i.e. a ResponseProxy).
0
 
0
       def self.included( mod )
0
         def mod.process( request, &block )
0
@@ -105,7 +104,7 @@ module Waves
0
 
0
       def initialize( request )
0
         @request = request
0
-        end
0
+      end
0
 
0
       # The params variable is taken from the request object and "destructured", so that
0
       # a parameter named 'blog.title' becomes:
0
@@ -116,13 +115,13 @@ module Waves
0
       # +request.params+ instead of simply +params+.
0
       def params; @params ||= destructure(request.params); end
0
 
0
-      # You can access the name of the model related to this controller using this method.
0
-      # It simply takes the basename of the module and converts it to snake case, so if the
0
-      # model uses a different plurality, this won't, in fact, be the model name.
0
+      # Returns the name of the model corresponding to this controller by taking the basename
0
+      # of the module and converting it to snake case. If the model plurality is different than
0
+      # the controller, this will not, in fact, be the model name.
0
       def model_name; self.class.basename.snake_case; end
0
 
0
-      # This uses the model_name method to attempt to identify the model corresponding to this
0
-      # controller. This allows you to write generic controller methods such as:
0
+      # Returns the model corresponding to this controller by naively assuming that 
0
+      # +model_name+ must be correct. This allows you to write generic controller methods such as:
0
       #
0
       #   model.find( name )
0
       #

0
@@ -2,8 +2,14 @@ module Waves
0
 
0
   module Dispatchers
0
 
0
+    # A NotFoundError means what you think it means.  The dispatchers included with Waves do not
0
+    # natively intercept this exception.  Instead an exception handler must be registered in the application
0
+    # mappings.  The Simple foundation registers a minimal handler, while the Default foundation registers
0
+    # a slightly fleshier one.
0
     class NotFoundError < Exception ; end
0
 
0
+    # Redirect exceptions are rescued by the Waves dispatcher and used to set the 
0
+    # response status and location.
0
     class Redirect < Exception
0
       attr_reader :path, :status
0
       def initialize( path, status = '302' )
0
@@ -12,16 +18,16 @@ module Waves
0
       end
0
     end
0
 
0
-    # The Base dispatcher simply makes it easier to write dispatchers by inheriting
0
-    # from it. It creates a Waves request, ensures the request processing is done
0
-    # within a mutex, benchmarks the request processing, logs it, and handles common
0
-    # exceptions and redirects. Derived classes need only process the request within
0
-    # their +safe+ method, which takes a Waves::Request and returns a Waves::Response.
0
+    # Waves::Dispatchers::Base provides the basic request processing structure.
0
+    # All other Waves dispatchers should inherit from it.  It creates a Waves request, 
0
+    # determines whether to enclose the request processing in a mutex, benchmarks it, 
0
+    # logs it, and handles common exceptions and redirects. Derived classes need only 
0
+    # process the request within the +safe+ method, which must take a Waves::Request and return a Waves::Response.
0
 
0
     class Base
0
 
0
-      # Like any Rack application, Waves' dispatchers must provide a call method
0
-      # taking an +env+ parameter.
0
+      # As with any Rack application, a Waves dispatcher must provide a call method
0
+      # that takes an +env+ parameter.
0
       def call( env )
0
         if Waves.config.synchronize?
0
           Waves::Application.instance.synchronize { _call( env ) }
0
@@ -30,8 +36,9 @@ module Waves
0
         end
0
       end
0
 
0
-      # Called by event driven servers like thin and ebb. Return true if
0
-      # the server should run the request in a separate thread.
0
+      # Called by event driven servers like thin and ebb. Returns true if
0
+      # the server should run the request in a separate thread, as determined by
0
+      # Configurations::Mapping#threaded?
0
       def deferred?( env )
0
         Waves::Application.instance.mapping.threaded?( env )
0
       end

0
@@ -3,13 +3,14 @@ module Waves
0
   module Dispatchers
0
 
0
     #
0
-    # The default dispatcher essentially checks the application's mapping to see
0
-    # what to do with the request URL. It checks before and after filters (wrap
0
-    # filters are just a combination of both) as well as path and url mappings.
0
+    # Waves::Dispatchers::Default matches requests against an application's mappings to 
0
+    # determine what main action to take, as well as what before, after, always, and exception-handling
0
+    # blocks must run.
0
     #
0
     # The default dispatcher also attempts to set the content type based on the
0
-    # MIME type implied by any file extension used in the request URL using Mongrel's
0
-    # MIME types YAML file.
0
+    # file extension used in the request URL. It does this using the class defined in
0
+    # the current configuration's +mime_types+ attribute, which defaults to Mongrel's
0
+    # MIME type handler.
0
     #
0
     # You can write your own dispatcher and use it in your application's configuration
0
     # file. By default, they use the default dispatcher, like this:

0
@@ -1,5 +1,10 @@
0
 module Waves
0
   module Foundations
0
+# The Default foundation supports the common MVC development pattern, a la Rails and Merb. Models, controllers, views, templates, and helpers live in the corresponding directories. When your code calls for a specific M, V, C, or H, Waves tries to load it from a file matching the snake-case of the constant name.  If the file does not exist, Waves creates the constant from a sensible (and customizable) default.
0
+#
0
+# This foundation does not include any ORM configuration.  You can include Waves::Layers::ORM::Sequel or custom configure your model.
0
+
0
+    
0
     module Default
0
 
0
       def self.included( app )

0
@@ -1,8 +1,21 @@
0
 module Waves
0
+  
0
+  # A Waves Foundation provides enough functionality to allow a Waves application
0
+  # to run.  At the bare minimum, this means creating configuration classes in the Configurations
0
+  # namespace, as is done in the Simple foundation
0
+  #
0
+  # Typically, a Foundation will include several Layers, perform any necessary
0
+  # configuration, and register the application with the Waves module
0
   module Foundations
0
 
0
+    # The Simple foundation provides the bare minimum needed to run a Waves application.
0
+    # It is intended for use as the basis of more fully-featured foundations, but you can
0
+    # use it as a standalone where all the request processing is done directly in a 
0
+    # mapping lambda.
0
     module Simple
0
 
0
+      # On inclusion in a module, the Simple foundation includes Waves::Layers::Simple and 
0
+      # registers the module as a Waves application.
0
       def self.included( app )
0
 
0
         app.instance_eval do

0
@@ -1,4 +1,8 @@
0
 module Waves
0
+  
0
+  # Helper methods can be defined for any view template by simply defining them within the default Helper module in <tt>helpers/default.rb</tt> of the generated application. Helpers specific to a particular View class can be explicitly defined by creating a helper module that corresponds to the View class. For examples, for the +User+ View class, you would define a helper module in <tt>user.rb</tt> named +User+.
0
+  #
0
+  # The default helper class initially includes a wide-variety of helpers, including helpers for layouts, Textile formatting, rendering forms, and nested views, as well as helpers for accessing the request and response objects. More helpers will be added in future releases, but in many cases, there is no need to include all of them in your application.
0
   module Helpers
0
 
0
     # Common helpers are helpers that are needed for just about any Web page. For example,

0
@@ -15,6 +15,7 @@ module Waves
0
     # will invoke the +text+ form view (the template in +templates/form/text.mab+),
0
     # passing in the name ('blog.title') and the value (@blog.title) as instance variables.
0
     #
0
+    # These helpers are Markaby only.
0
     module Form
0
 
0
       # This method really is a place-holder for common wrappers around groups of

0
@@ -1,5 +1,7 @@
0
 module Waves
0
   module Layers
0
+    
0
+    # Configures Waves to use the templates in app/templates/errors for exception handling
0
     module DefaultErrors
0
 
0
       def self.included( app )

0
@@ -1,5 +1,9 @@
0
 module Waves
0
   module Layers
0
+    # The MVC layer establishes the Models, Views, Controllers, and Helpers namespaces inside 
0
+    # a Waves application.  In each namespace, undefined constants are handled by AutoCode, which
0
+    # loads the constant from the correct file in the appropriate directory if it exists, or creates
0
+    # from default otherwise.
0
     module MVC
0
 
0
       def self.included( app )

0
@@ -6,6 +6,7 @@ module Waves
0
   module Layers
0
     module ORM
0
       
0
+      # Work in Progress
0
       module DataMapper
0
         
0
         def self.included(app)

0
@@ -2,13 +2,14 @@ module Waves
0
   module Layers
0
     module ORM
0
       
0
+      # Work in Progress
0
       module Filebase
0
         
0
         def self.included(app)
0
           app.module_eval do
0
             auto_eval( :Models ) do
0
-          	  auto_eval( true ) { include Filebase::Model[ :db / self.name.snake_case ] }
0
-          	end
0
+              auto_eval( true ) { include Filebase::Model[ :db / self.name.snake_case ] }
0
+            end
0
           end
0
         end
0
         

0
@@ -1,5 +1,6 @@
0
 module Waves
0
-  module Orm
0
+  module Orm # :nodoc:
0
+    # Helper methods to establish an inter-ORM standard for migrations
0
     module Migration
0
 
0
       # stuff in this file largely lifted from Sequel.  Thanks, bro.

0
@@ -51,12 +51,23 @@ module Waves
0
             end
0
             
0
             Waves::Controllers::Base.module_eval do
0
-              def all; model.all; end
0
-              def find( name ); model[ :name => name ] or not_found; end
0
-              def create; model.create( attributes ); end
0
-              def delete( name ); find( name ).destroy; end
0
+              def all #:nodoc:
0
+                model.all
0
+              end
0
+              
0
+              def find( name ) #:nodoc:
0
+                model[ :name => name ] or not_found
0
+              end
0
+              
0
+              def create #:nodoc:
0
+                model.create( attributes )
0
+              end
0
+              
0
+              def delete( name ) #:nodoc:
0
+                find( name ).destroy
0
+              end
0
               
0
-              def update( name )
0
+              def update( name ) #:nodoc:
0
                 instance = find( name )
0
                 instance.update_with_params( attributes )
0
                 instance

0
@@ -1,11 +1,21 @@
0
 module Waves
0
+  
0
+  # Waves uses Layers to provide discrete, stackable, interchangeable bundles of functionality.
0
+  # 
0
+  # Developers can make use of Layers by including them directly in a Waves application:
0
+  # 
0
+  #   module MyApp
0
+  #     include SomeLayer
0
+  #   end
0
   module Layers
0
+    
0
+    # Creates the Configurations namespace and establishes the standard autoload-or-autocreate
0
+    # rules.
0
     module Simple
0
       def self.included( app )
0
 
0
         def app.config ; Waves.config ; end
0
         def app.configurations ; self::Configurations ; end
0
-        def app.paths ; configurations::Mapping.named; end
0
         
0
         app.instance_eval do
0
 

0
@@ -1,5 +1,10 @@
0
 module Waves
0
   module Layers
0
+    # Configures Waves for minimal exception handling.  
0
+    # 
0
+    # For example,
0
+    # a NotFoundError results in response status of 404, with body text
0
+    # of "404 Not Found".
0
     module SimpleErrors
0
 
0
       def self.included( app )

0
@@ -1,11 +1,33 @@
0
 module Waves
0
 
0
-  # Waves::Mapping is a mixin for defining Waves URI mappings (mapping a request to Ruby code).
0
-  # Mappings can work against the request url, path, and elements of the request (such as the
0
-  # request method or accept header). Mappings may also include before, after, or wrap filters
0
-  # to be run if they match the request. Mappings are created using an appropriate mapping method
0
-  # along with a URL pattern (a string or regular expression), a hash of constraint options, and
0
-  # a block, which is the code to run if the pattern matches.
0
+  # Mappings in Waves are the interface between the request dispatcher and your
0
+  # application code.  The dispatcher matches each request against the mappings
0
+  # to determine a primary action and to collect sets of before, after, wrap, 
0
+  # and always actions.  The dispatcher also looks for an exception handler 
0
+  # registered in the mappings when attempting a rescue.
0
+  # 
0
+  # Each mapping associates a block with a set of constraints.  Mappings can be
0
+  # one of several types:
0
+  # 
0
+  # - action (the actual request processing and response)
0
+  # - handle (exception handling)
0
+  # - before 
0
+  # - after
0
+  # - wrap (registers its block as both a before and after action)
0
+  # - always (like an "ensure" clause in a rescue)
0
+  # 
0
+  # Actions are registered using path, url, or map.  The other types may be 
0
+  # registered using methods named after the type.
0
+  # 
0
+  # 
0
+  # The available constraints are:
0
+  # 
0
+  # - a string or regexp that the path or url must match
0
+  # - parameters to match against the HTTP request headers and the Rack-specific variables (e.g. 'rack.url_scheme')
0
+  # - an additional hash reserved for settings not related to the Rack request (e.g. giving Rack handers special instructions for certain requests.  See threaded? )
0
+  # 
0
+  # The dispatcher evaluates mapping blocks in an instance of ResponseProxy, 
0
+  # which provides access to foundational classes of a Waves application (i.e. controllers and views)
0
   #
0
   # == Examples
0
   #

0
@@ -1,6 +1,6 @@
0
 require 'erubis'
0
 
0
-module Erubis
0
+module Erubis # :nodoc:
0
 
0
   # This is added to the Erubis Content class to allow the same helper methods
0
   # to be used with both Markaby and Erubis.

0
@@ -1,6 +1,6 @@
0
 module Waves
0
 
0
-  module Renderers
0
+  module Renderers # :nodoc:
0
 
0
     # The renderers mixin provides a number of methods to simplify writing new renderers.
0
     # Just include this in your Renderer class and write your render method.

0
@@ -30,7 +30,7 @@ module Waves
0
 
0
     class << self; attr_accessor :instance; end
0
 
0
-    # Accessor for options passed to the application. Valid options include
0
+    # Accessor for options passed to the application.
0
     attr_reader :options
0
 
0
     # Create a new Waves application instance.

0
@@ -1,12 +1,11 @@
0
 module Waves
0
 
0
-  # Waves configurations are simply Ruby code, meaning you can use an Ruby expression as
0
-  # a value for a configuration parameter, extend and inherit your configurations, and
0
-  # add your own configuration attributes. You can even use it as a configuration repository
0
-  # for your applications.
0
+  # Waves configurations are Ruby code.  This means you can use a Ruby expression as
0
+  # the value of a configuration attribute, extend and inherit your configurations, and
0
+  # add your own attributes. You can even use it as a repository
0
+  # for your application configuration.
0
   #
0
-  # The form for configuration parameters to use the parameter name as a method name. Passing
0
-  # in a parameter sets the value.
0
+  # You can access configuration attributes using the attribute name as a method, with the value as the argument.
0
   #
0
   # == Example
0
   #
0
@@ -25,28 +24,27 @@ module Waves
0
   #      end
0
   #    end
0
   #
0
-  # There are three forms for accessing parameters:
0
+  # There are three forms for accessing attributes:
0
   #
0
-  #   Waves.config.port                        # generic form - gets current config
0
-  #   Blog.configurations[:development]        # gets a value for a specific config
0
-  #   Blog::Configurations::Development.port   # Access config constant directly
0
+  #   Waves.config.port                        # generic form - gets the value for current config
0
+  #   Blog.configurations[:development].port   # gets the value for a specified config
0
+  #   Blog::Configurations::Development.port   # Access a specific config constant directly
0
   #
0
-  # You can inherit configurations, as is shown in the example above. Typically, you
0
-  # can use the application's "default" configuration to set shared configurations,
0
-  # and then inherit from it for specific variations.
0
+  # Configuration data is inheritable, as shown in the example above. Typically, you
0
+  # would set data common to all configurations in the Default class, from which
0
+  # your variations inherit.
0
   #
0
-  # To define your own attributes, and still make them inheritable, you should use
0
-  # the +attribute+ class method, like this:
0
+  # You may define your own heritable attributes using the +attribute+ class method:
0
   #
0
   #   class Default < Waves::Configurations::Default
0
-  #     attribute 'theme' # define a theme attribute
0
-  #     theme 'ultra'     # give it a default
0
+  #     attribute 'theme' # define an attribute named "theme"
0
+  #     theme 'ultra'     # set an inheritable default
0
   #   end
0
   #
0
-  # There are a number of reserved or built-in attributes. These are:
0
+  # Certain attributes are reserved for internal use by Waves:
0
   #
0
   # - application: configure the application for use with Rack
0
-  # - database: takes a hash of parameters used to initalize the database; see below
0
+  # - database: initialization parameters needed by the ORM layer
0
   # - reloadable: an array of module names to reload; see below for more
0
   # - log: takes a hash of parameters; see below for more
0
   # - host: the host to bind the server to (string)
0
@@ -58,7 +56,7 @@ module Waves
0
   #
0
   # One of the really nice features of Rack is the ability to install "middleware"
0
   # components to optimize the way you handle requests. Waves exposes this ability
0
-  # directly to the application developer via the +application+ configuration parameter.
0
+  # directly to the application developer via the +application+ configuration method.
0
   #
0
   # *Example*
0
   #
0
@@ -70,45 +68,45 @@ module Waves
0
   #
0
   # == Configuring Database Access
0
   #
0
-  # The database parameter takes a hash with the following elements:
0
-  #
0
-  # - hos