waves 0.6.7 → 0.6.9

data/lib/renderers/erubis.rb

@@ -2,6 +2,8 @@ require 'erubis'
 
 module Erubis
   
+  # This is added to the Erubis Content class to allow the same helper methods
+  # to be used with both Markaby and Erubis.
   class Context
     def <<(s) ; s ; end
   end
@@ -11,7 +13,7 @@ end
 module Waves
 
 	module Renderers
-	
+	  
 		class Erubis
 			
 			include Renderers::Mixin

data/lib/renderers/markaby.rb

@@ -11,17 +11,19 @@ module Waves
 			include Renderers::Mixin
 			
 			extension :mab
+			
 			# capture needed here for content fragments, otherwise
 			# you'll just get the last tag's output ...
-			def self.capture( template )
-			  "capture { #{template} }"
-			end
+			# def self.capture( template )
+			#  "capture { #{template} }"
+			# end
 			
 			def self.render( path, assigns )
 				builder = ::Markaby::Builder.new( assigns )
 				helper = helper( path )
 				builder.meta_eval { include( helper ) }
-				builder.instance_eval( capture( template( path ) ) ).to_s
+				builder.instance_eval( template( path ) )
+				builder.to_s
 			end
 		
 		end

data/lib/renderers/mixin.rb

@@ -5,8 +5,20 @@ module Waves
 		extend Autoload
 		autoload :renderers
 	
+	  # The renderers mixin provides a number of methods to simplify writing new renderers.
+	  # Just include this in your Renderer class and write your render method.
 		module Mixin
 		
+		  # Adds the following methods to the target class:
+		  #
+		  # - extension: allows you to set or get the extension used by this renderer.
+		  # 
+		  #     Renderers::Markaby.extension 'foo' # tell Waves to use .foo as Markaby extension
+		  #
+		  # - filename: generate a filename for the template based on a logical path.
+		  # - template: read the template from the file corresponding to the given logical path.
+		  # - helper: return a helper module that corresponds to the given logical path.
+		  #
 			def self.included(target)
 				class << target
 					

data/lib/runtime/application.rb

@@ -1,43 +1,53 @@
+# See the README for an overview.
 module Waves
 
 	class << self
 		
+		# Access the principal Waves application.
 		attr_reader :application
 		
-		# give us the root namespace for the application
+		# Register a module as a Waves application.		
+		# Also, initialize the database connection if necessary.
 		def << ( app )
-			@application = app if Module === app
+		  @application = app if Module === app
+		  app.database if app.respond_to? 'database'
 		end
 		
 	end
 	
+	# An application in Waves is anything that provides access to the Waves
+	# runtime and the registered Waves applications. This includes both
+	# Waves::Server and Waves::Console. Waves::Application is *not* the actual
+	# application module(s) registered as Waves applications. To access the
+	# main Waves application, you can use +Waves+.+application+.
 	class Application
-		
-		def initialize( mode = :development )
-			@mode = mode
-		end
-		
-		def debug? ; @mode == :development ; end
 
-		# now we can get the configuration, based on the mode
-		# we must specify global scope to avoid picking up Waves::Configurations::*
-		# and / or Waves::Application::* ... because the configuration may be
-		# loaded via autoload ....
-		def config
-			Waves.application.configurations[ @mode ]
-		end
+	  # Accessor for options passed to the application. Valid options include
+		attr_reader :options
 
-		# and, similarly, the url mapping ...
-		def mapping
-			Waves.application.configurations[ :mapping ]
+		# Create a new Waves application instance.
+		def initialize( options={} )
+		  @options = options
+		  Dir.chdir options[:directory] if options[:directory]
 		end
 
-		# the config then tells us whether to unload any namespaces
-		# after each request ...
-		def reset
-			config.reloadable.each { |mod| mod.reload }
-		end
+		# The 'mode' of the application determines which configuration it will run under.
+		def mode ; @mode ||= @options[:mode]||:development ; end
 
+		# Debug is true if debug is set to true in the current configuration.
+		def debug? ; config.debug ; end
+		
+		# Access the current configuration. *Example:* +Waves::Server.config+
+		def config ; Waves.application.configurations[ mode ] ; end
+		
+		# Access the mappings for the application.
+		def mapping ; Waves.application.configurations[ :mapping ] ; end
+		
+		# Reload the modules specified in the current configuration.
+		def reload ; config.reloadable.each { |mod| mod.reload } ; end
+		
+		# Returns the cache set for the current configuration
+    def cache ; config.cache ; end
 	end
 
 end

data/lib/runtime/configuration.rb

@@ -1,15 +1,131 @@
 module Waves
+  
+  # Waves configurations are simply Ruby code, meaning you can use an Ruby expression as
+  # a value for a configuration parameter, extend and inherit your configurations, and 
+  # add your own configuration attributes. You can even use it as a configuration repository
+  # for your applications.
+  #
+  # The form for configuration parameters to use the parameter name as a method name. Passing
+  # in a parameter sets the value.
+  #
+  # == Example 
+  #
+  #    module Blog
+  #      module Configurations
+  #        class Development < Default
+  #          host '127.0.0.1'
+  #          port 2000
+  #          reloadable [ Blog ]
+  #          log :level => :debug	
+  #          application do
+  #            use Rack::ShowExceptions
+  #            run Waves::Dispatchers::Default.new
+  #          end				
+  #        end
+  #      end
+  #    end
+  #
+  # There are three forms for accessing parameters:
+  #
+  #   Waves.config.port                        # generic form - gets current config
+  #   Blog.configurations[:development]        # gets a value for a specific config
+  #   Blog::Configurations::Development.port   # Access config constant directly
+  #
+  # You can inherit configurations, as is shown in the example above. Typically, you
+  # can use the application's "default" configuration to set shared configurations,
+  # and then inherit from it for specific variations.
+  # 
+  # To define your own attributes, and still make them inheritable, you should use
+  # the +attribute+ class method, like this:
+  #
+  #   class Default < Waves::Configurations::Default
+  #     attribute 'theme' # define a theme attribute
+  #     theme 'ultra'     # give it a default
+  #   end
+  #
+  # There are a number of reserved or built-in attributes. These are:
+  #
+  # - application: configure the application for use with Rack
+  # - database: takes a hash of parameters used to initalize the database; see below
+  # - reloadable: an array of module names to reload; see below for more
+  # - log: takes a hash of parameters; see below for more
+  # - host: the host to bind the server to (string)
+  # - port: the port for the server to listen on (number)
+  # - ports: used by the cluster:start task for clustering servers (array of numbers)
+  # - debug: true if running in "debug" mode, which automatically reloads code
+  #
+  # == Configuring The Rack Application
+  #
+  # One of the really nice features of Rack is the ability to install "middleware"
+  # components to optimize the way you handle requests. Waves exposes this ability
+  # directly to the application developer via the +application+ configuration parameter.
+  # 
+  # *Example*
+  # 
+  #   # Typical debugging configuration
+  #   application do
+	#   	use Rack::ShowExceptions
+	#   	run Waves::Dispatchers::Default.new
+	#   end				
+  #
+  # == Configuring Database Access
+  #
+  # The database parameter takes a hash with the following elements:
+  #
+  # - host: which host the database is running on
+  # - adapter: which adapter is being used to access the database (mysql, postgres, etc.)
+  # - database: the name of the database the application is connecting to
+  # - user: the user for authentication
+  # - password: password for authentication
+  #
+  # *Example*
+  #
+  #   database :host => host, :adapter => 'mysql', :database => 'blog',
+  #     :user => 'root', :password => 'guess'
+  #
+  # 
+  # == Configuring Code Reloading 
+  #
+  # You can specify a list of modules to reload on each request using the +reloadable+ 
+  # configuration parameter. The Waves server will call +reload+ on each module to trigger
+  # the reloading. Typically, your modules will use the Autocode gem to set parameters for
+  # reloading. This is done for you when you generate an application using the +waves+ 
+  # command, but you can change the default settings. See the documentation for Autocode
+  # for more information. Typically, you will set this parameter to just include your
+  # main application:
+  #
+  #   reloadable [ Blog ]
+  #
+  # although you could do this with several modules just as easily (say, your primary 
+  # application and several helper applications).
+  #
+  # == Configuring Logging 
+  #
+  # The +log+ configuration parameter takes the following options (as a hash):
+  # - level: The level to filter logging at. Uses Ruby's built in Logger class.
+  # - output: A filename or IO object. Should be a filename if running as a daemon.
+  #
+  # *Examples*
+  #
+  # log :level => :info, :output => $stderr
+  # log :level => :error, :output => 'log/blog.log'
+  #
 
 	module Configurations
 
 		class Base
 
+      # Set the given attribute with the given value. Typically, you wouldn't
+      # use this directly.
 			def self.[]=( name, val )
 				meta_def("_#{name}") { val }
 			end
 
+      # Get the value of the given attribute. Typically, you wouldn't
+      # use this directly.
 			def self.[]( name ) ; send "_#{name}" ; end
 
+      # Define a new attribute. After calling this, you can get and set the value.
 			def self.attribute( name )
 				meta_def(name) do |*args|
 					raise ArgumentError.new('Too many arguments.') if args.length > 1
@@ -17,18 +133,23 @@ module Waves
 				end
 				self[ name ] = nil
 			end
-
-			def self.mime_types
-				Waves::MimeTypes
-			end
 			
 		end
 	
+	  # The Default configuration provides a good starting point for your applications,
+	  # defining a number of attributes that are required by Waves.
 		class Default < Base
 		  
-			%w( host port ports log reloadable server database session ).
+			%w( host port ports log reloadable database session debug ).
 			each { |name| attribute(name) }
 			
+			# Provide access to the Waves::MimeTypes class via the configuration. You
+			# could potentially point this to your own MIME types repository class.
+			def self.mime_types
+				Waves::MimeTypes
+			end
+
+      # Defines the application for use with Rack.
 			def self.application( &block )
 			  if block_given? 
   			  self['application'] = Rack::Builder.new( &block )
@@ -36,10 +157,11 @@ module Waves
   			  self['application']
   			end
 			end
-			
-			session :duration => 30.minutes, 
-			  :path => :tmp / :sessions
-
+      
+      debug true
+			session :duration => 30.minutes, :path => '/tmp/sessions'
+    	log :level => :info, :output => $stderr	
+  	
 		end
 	end
 end

data/lib/runtime/console.rb

@@ -6,8 +6,8 @@ module Waves
 
 			attr_reader :console
 
-			def load(mode=:development)
-				@console ||= Waves::Console.new(mode)
+			def load( options={} )
+				@console ||= Waves::Console.new( options )
 				Kernel.load( :lib / 'startup.rb' )
 			end
 			

data/lib/runtime/logger.rb

@@ -1,26 +1,50 @@
 require 'logger'
 module Waves
 	
+	# Waves::Logger is based on Ruby's built-in Logger. It uses the same filtering approach
+	# (debug, info, warn, error, fatal), although the interface is slightly different.
+	# You won't typically instantiate this class directly; instead, you will specify the
+	# logging configuration you want in your configuration files. See Waves::Configurations
+	# for more information on this. 
+	#
+	# To use the logger for output, you can usually just call +log+, since the Waves::ResponseHelper
+	# mixin defines it (meaning it is available in the mapping file, controllers, views, and
+	# templates). Or, you can access Waves::Logger directly. Either way, the logger provides five
+	# methods for output corresponding to the log levels.
+	#
+	# *Examples*
+	#   # log the value of foo
+	#   log.info "Value of foo: #{foo}"
+	#
+	#   # fatal error!
+	#   Waves::Logger.fatal "She can't hold up any longer, cap'n!"
+	#
 	module Logger
-
-		# Initializes the logger based on the config, and then adds Waves#log.
-
-		def self.start
-			config = Waves::Server.config
-			output = ( config.log[:output] || $stderr )
-			level = ::Logger.const_get( config.log[:level].to_s.upcase || 'INFO' )
-			@log = if config.log(:rotation)
-  			::Logger.new( output, config.log[:rotation].intern ); 
-  		else
-  			::Logger.new( output ); 
+    
+    class << self
+      
+      # Returns the object being used for output by the logger.
+      def output
+        @output ||= ( config[:output] ? File.expand_path( config[:output] ) : $stderr )
+      end
+      # Returns the active configuration for the logger.
+      def config ; @config ||= Waves::Server.config.log ; end
+      # Returns the logging level used to filter logging events.
+      def level ; @level ||= ::Logger.const_get( config[:level].to_s.upcase || 'INFO' ) ; end
+      # Starts the logger, using the active configuration to initialize it.
+  		def start
+  			@log = config[:rotation] ? 
+    			::Logger.new( output, config[:rotation].intern ) : 
+    			::Logger.new( output )
+  			@log.level = level
+  			self  
   		end
-			@log.level = level
-		end
-		
-		# delegate everything to the logger
-		def self.method_missing(name,*args,&block)
-		  @log.send name,*args, &block
-		end
+  		# Forwards logging methods to the logger.
+  		def method_missing(name,*args,&block)
+  		  @log.send name,*args, &block
+  		end
+
+  	end
 		
 	end
 

data/lib/runtime/mime_types.rb

@@ -1,14 +1,18 @@
 module Waves
+  
+  # Waves::MimeTypes defines an interface for adding MIME types used in mapping requests
+  # to content types. Mongrel's MIME_TYPES hash is used as the baseline MIME map.
+  
 	module MimeTypes
 	  
 		def self.[]( path )
 		  mapping[ File.extname( path ) ]
 		end
 		
-		# TODO: why isn't this working?
-		# def self.<<( mapping )
-		#  mapping.merge!( mapping )
-		# end
+		# TODO: This does not seem to be working.
+		def self.<<( mapping )
+		  mapping.merge!( mapping )
+		end
 		
 		def self.mapping
 		  @mapping ||= Mongrel::DirHandler::MIME_TYPES

data/lib/runtime/request.rb

@@ -1,39 +1,48 @@
 module Waves
+  # Waves::Request represents an HTTP request and has methods for accessing anything
+  # relating to the request. See Rack::Request for more information, since many methods
+  # are actually delegated to Rack::Request.
 	class Request
 		
 		class ParseError < Exception ; end
 		
 		attr_reader :response, :session
 		
-		def initialize( env ) # Rack::Request
+		# Create a new request. Takes a env parameter representing the request passed in from Rack.
+		# You shouldn't need to call this directly.
+		def initialize( env )
 			@request = Rack::Request.new( env )
 			@response = Waves::Response.new( self )
 			@session = Waves::Session.new( self )
 		end
 				
-		# if we haven't overridden it, give it to Rack
+		# Accessor not explicitly defined by Waves::Request are delegated to Rack::Request. 
+		# Check the Rack documentation for more information.
 		def method_missing(name,*args)
 			@request.send(name,*args)
 		end
 		
-		# TODO: should / does this exclude the query_string?
-		# Is there a Rack API that is more appropos
+		# The request path (PATH_INFO). Ex: +/entry/2008-01-17+
 		def path
 			@request.path_info
 		end
-		
+
+		# The request domain. Ex: +www.fubar.com+
     def domain
       @request.host
     end
     
+    # The request method: GET, PUT, POST, or DELETE.
 		def method
 			@request.request_method.downcase.intern
 		end	
 		
+		# Raise a not found exception.
 		def not_found
   		raise Waves::Dispatchers::NotFoundError.new( @request.url + ' not found.')
   	end
 
+    # Issue a redirect for the given path.
 		def redirect( path )
 			raise Waves::Dispatchers::Redirect.new( path )
 		end