waves 0.6.7 → 0.6.9

data/lib/runtime/response.rb

@@ -1,8 +1,14 @@
 module Waves
+  # Waves::Response represents an HTTP response and has methods for constructing a response.
+  # These include setters for +content_type+, +content_length+, +location+, and +expires+ 
+  # headers. You may also set the headers directly using the [] operator. If you don't find
+  # what you are looking for here, check the documentation for Rack::Response since many
+  # methods for this class are delegated to Rack::Response.
 	class Response
 		
 		attr_reader :request
 		
+		# Create a new response. Takes the request object. You shouldn't need to call this directly.
 		def initialize( request )
 			@request = request
 			@response = Rack::Response.new
@@ -10,14 +16,22 @@ module Waves
 				
 		%w( Content-Type Content-Length Location Expires ).each do |header|
 			define_method( header.downcase.gsub('-','_')+ '=' ) do | val |
-				@response.headers[header] = val
+				@response[header] = val
 			end
 		end
 				
+		# Returns the sessions associated with the request, allowing you to set values within it.
+		# The session will be created if necessary and saved when the response is complete.
 		def session ; request.session ; end
 		
+		# Finish the response. This will send the response back to the client, so you shouldn't
+		# attempt to further modify the response once this method is called. You don't usually
+		# need to call it yourself, since it is called by the dispatcher once request processing
+		# is finished.
 		def finish ; request.session.save ; @response.finish ; end
 				
+		# Methods not explicitly defined by Waves::Response are delegated to Rack::Response. 
+		# Check the Rack documentation for more informations
 		def method_missing(name,*args)
 			@response.send(name,*args)
 		end

data/lib/runtime/response_mixin.rb

@@ -1,53 +1,35 @@
 module Waves
   
+  # Defines a set of methods that simplify accessing common request and response methods.
+  # These include methods not necessarily associated with the Waves::Request and Waves::Response
+  # objects, but which may still be useful for constructing a response.
+  #
+  # This mixin assumes that a @request@ accessor already exists.
   module ResponseMixin
-    
-    # assumes request method
-    
-    def response
-      request.response
-    end
-    
-    def params
-			request.params
-		end
-		
-		def session
-			request.session
-		end
-		
-		def path
-		  request.path
-		end
-		
-		def url
-		  request.url
-		end
-		
-		def domain
-		  request.domain
-		end
-		
-		def redirect(location)
-		  request.redirect(location)
-		end
-		
-		def models
-		  Waves.application.models
-		end
-		
-		def views
-		  Waves.application.views
-		end
-		
-		def controllers
-		  Waves.application.controllers
-		end
-		
-		def not_found
-		  request.not_found
-		end
-		
+    # Access the response.
+    def response; request.response; end
+    # Access the request parameters.
+    def params; request.params; end
+    # Access the request session.
+		def session; request.session; end
+		# Access the request path.
+		def path; request.path; end
+		# Access the request url.
+		def url; request.url; end
+		# Access the request domain.
+		def domain; request.domain; end
+		# Issue a redirect for the given location.
+		def redirect(location); request.redirect(location); end
+		# Access the primary application's models
+		def models; Waves.application.models; end
+		# Access the primary application's views
+		def views; Waves.application.views; end
+		# Access the primary application's controllers
+		def controllers; Waves.application.controllers; end
+		# Raise a "not found" exception.
+		def not_found; request.not_found; end
+		# Access the Waves::Logger.
+		def log; Waves::Logger; end
 	end
 	
 end

data/lib/runtime/server.rb

@@ -1,58 +1,83 @@
 module Waves
-	
+	# You can run the Waves::Server via the +waves-server+ command or via <tt>rake cluster:start</tt>. Run <tt>waves-server --help</tt> for options on the <tt>waves-server</tt> command. The <tt>cluster.start</tt> task use the +mode+ environment parameter to determine which configuration to use. You can define +port+ to run on a single port, or +ports+ (taking an array) to run on multiple ports.
+	#
+	# *Example*
+	#
+	# Assume that +ports+ is set in the development configuration like this:
+	#
+	#   ports [ 2020, 2021, 2022 ]
+	#
+	# Then you could start up instances on all three ports using:
+	#
+	#   rake cluster:start mode=development
+	#
+	# This is the equivalent of running:
+	#
+	#   waves-server -c development -p 2020 -d
+	#   waves-server -c development -p 2021 -d
+	#   waves-server -c development -p 2022 -d
+	#  
 	class Server < Application
-				
+		
+		# Access the server thread.		
 		attr_reader :thread
 		
+		# Access the host we're binding to (set via the configuration).
+		def host ; options[:host] || config.host ; end
+		# Access the port we're listening on (set via the configuration).
+		def port ; options[:port] || config.port ; end
+		# Run the server as a daemon. Corresponds to the -d switch on +waves-server+.
+		def daemonize
+		  pwd = Dir.pwd
+		  Daemonize.daemonize( Waves::Logger.output )
+		  Dir.chdir(pwd)
+		  File.write( :log / $$+'.pid', '' )
+		end
+		# Start and / or access the Waves::Logger instance.
+		def log ; @log ||= Waves::Logger.start ; end
+		# Start the server.
 		def start
 			load( :lib / 'startup.rb' )
-			Waves::Logger.start
+		  daemonize if options[:daemon]
 			log.info "** Waves Server Starting ..."
-			
-			t = Benchmark.realtime do
-				app = config.application.to_app				
-				@server = ::Mongrel::HttpServer.new( config.host, config.port )
-				@server.register('/', Rack::Handler::Mongrel.new( app ) )
-				trap('INT') { puts; stop }
-				@thread = @server.run
-			end
-			log.info "** Waves Server Running on #{config.host}:#{config.port}"
-			log.info "Server started in #{(t*1000).round} milliseconds."
+			t = real_start
+			log.info "** Waves Server Running on #{host}:#{port}"
+			log.info "Server started in #{(t*1000).round} ms."
 			@thread.join
 		end
-		
+		# Stop the server.
 		def stop
 			log.info "** Waves Server Stopping ..."
+			pid_file = :log / $$ + '.pid'
+			FileUtils.rm( pid_file ) if options[:daemon] and File.exist?( pid_file )
 			@server.stop 
 			log.info "** Waves Server Stopped"
 		end
-		
-		def synchronize( &block )
-			( @mutex ||= Mutex.new ).synchronize( &block )
-		end
-		
-		def cache
-			#@cache ||= MemCache::new '127.0.0.1'
-		end
-		
-		# make this a singleton ... we don't use Ruby's std lib
-		# singleton module because it doesn't do quite what we
-		# want - need a run method and implicit instance method
+		# Provides access to the server mutex for thread-safe operation.
+		def synchronize( &block ) ; ( @mutex ||= Mutex.new ).synchronize( &block ) ; end
+
 		class << self
-			
 			private :new, :dup, :clone
-			
-			def run( mode = :development )
-				@server.stop if @server; @server = new( mode ); @server.start
+			# Start or restart the server.
+			def run( options={} )
+				@server.stop if @server; @server = new( options ); @server.start
 			end
-			
-			# allow Waves::Server to act as The Server Instance
+			# Allows us to access the Waves::Server instance.
 			def method_missing(*args); @server.send(*args); end
-			
+			# Probably wouldn't need this if I added a block parameter to method_missing.
 			def synchronize(&block) ; @server.synchronize(&block) ; end
-			
+		end
+		
+		private
+		
+		def real_start
+		  Benchmark.realtime do
+				@server = ::Mongrel::HttpServer.new( host, port )
+				@server.register('/', Rack::Handler::Mongrel.new( config.application.to_app	 ) )
+				trap('INT') { puts; stop }; @thread = @server.run
+			end
 		end
 
 	end
 	
-end
+end

data/lib/runtime/session.rb

@@ -1,11 +1,22 @@
 module Waves
+  
+  # Encapsulates the session associated with a given request. A session has an expiration
+  # and path. You must set these in your configuration file. See Waves::Configuration for
+  # more information. 
+  #
 	class Session
 		
+		# Create a new session object using the given request. This is not necessarily the
+		# same as constructing a new session. The session_id cookie for the request domain
+		# is used to store a session id. The actual session data will be stored in a directory
+		# specified by the application's configuration file.
 		def initialize( request )
 			@request = request
 			@data ||= ( File.exist?( session_path  ) ? load_session : {} )
 		end
 		
+		# Save the session data. You shouldn't typically have to call this directly, since it
+		# is called by Waves::Response#finish.
 		def save
 			if @data && @data.length > 0
 				File.write( session_path, @data.to_yaml )
@@ -15,13 +26,15 @@ module Waves
 			end
 		end
 		
+		# Access a given data element of the session using the given key.
 		def [](key) ; @data[key] ; end
+		# Set the given data element of the session using the given key and value.
 		def []=(key,val) ; @data[key] = val ; end
 		
 		private
 		
 		def session_id
-			@request.cookies['session_id'] || generate_session_id 
+			@session_id ||= ( @request.cookies['session_id'] || generate_session_id )
 		end
 		
 		def generate_session_id # from Camping ...

data/lib/utilities/integer.rb

@@ -1,8 +1,14 @@
+# Added methods to Integer for commonly used "numeric phrases" like 6.days or 30.megabytes.
 class Integer
 	def seconds ; self ; end
 	def minutes ; self * 60 ; end
 	def hours ; self * 60.minutes ; end
 	def days ; self * 24.hours ; end
 	def weeks ; self * 7.days ; end
-	# months and years are not precise
+	def bytes ; self ; end
+	def kilobytes ; self * 1024 ; end
+	def megabytes ; self * 1024.kilobytes ; end
+	def gigabytes ; self * 1024.megabytes ; end
+	def terabytes ; self * 1024.gigabytes ; end
+	def petabytes ; self * 1024.gigabytes ; end
 end

data/lib/utilities/kernel.rb

@@ -1,8 +1,34 @@
 module Kernel
-	
-	# inspired by similar function in rails ...
+	#
+	# From Rails. This comes in handy when you want to return a value that you need to modify. 
+	# So instead of the awkward:
+	#
+	#   foo = Foo.new
+	#   foo.bar = 'bar'
+	#   foo
+	#
+	# You can just say
+	# 
+	#   returning Foo.new { |foo| foo.bar = 'bar' }
+	#
 	def returning( object, &block )
 		yield object; object
 	end
+	
+	#
+	# Inspired by a question on comp.lang.ruby. Sort of like returning, except
+	# you don't need to pass in the returnee as an argument. The drawback is that,
+	# since this relies on instance_eval, you can't access in methods in the local
+	# scope. You can work around this by assigning values to variables, but in that
+	# case, you might be better off using returning.
+	#
+	# Our above example would look like this:
+	#
+	#   with( Foo.new ) { bar = 'bar' }
+	#
+	def with( object, &block )
+	  object.instance_eval(&block); object
+	end
+	
 
 end

data/lib/utilities/module.rb

@@ -1,5 +1,8 @@
 class Module
 
+  # This comes in handy when you are trying to do meta-programming with modules / classes
+  # that may be nested within other modules / classes. I think I've seen it defined in 
+  # facets, but I'm not relying on facets just for this one method.
 	def basename
 		self.name.split('::').last || ''
 	end

data/lib/utilities/object.rb

@@ -1,5 +1,9 @@
 class Object
-	# this code from mauricio fernandez via ruby-talk
+	# This is an extremely powerful little function that will be built-in to Ruby 1.9.
+	# This version is from Mauricio Fernandez via ruby-talk. Works like instance_eval
+	# except that you can pass parameters to the block. This means you can define a block
+	# intended for use with instance_eval, pass it to another method, which can then
+	# invoke with parameters. This is used quite a bit by the Waves::Mapping code.
   def instance_exec(*args, &block)
     mname = "__instance_exec_#{Thread.current.object_id.abs}"
     class << self; self end.class_eval{ define_method(mname, &block) }

data/lib/utilities/string.rb

@@ -1,13 +1,18 @@
+# Waves extends String with a variety of methods for changing from singular to plural and back, and switching to different types of case and word separators. These methods are similar to those found in Rails and other frameworks, but some (all?) of the names are different. The names here were chosen for increased clarity and are hopefully easy to adjust to ...
+#
+# Notably, the inflector code here is not as comprehensive as the Rails code. This will be fixed in a future version of Waves.
+
 class String
 	
+	# Does a File.join on the two arguments joined by the /. Very handy
+	# for doing platform-safe paths without having to use File.join.
+	#
 	# I unfortunately don't recall where i first saw this ... see
 	# Symbol extension as well, allowing for :files / 'afilename.txt'
 	
 	def / ( string )
 		File.join(self,string.to_s)
 	end
-
-	# inspired by the inflector code in rails ...
 	
 	def singular
 		gsub(/ies$/,'y').gsub(/es$/,'').gsub(/s$/,'')

data/lib/utilities/symbol.rb

@@ -1,4 +1,6 @@
 class Symbol
+  # Does File.join on self and string, converting self to string before invocation.
+  # See String#/ for more.
 	def / ( string )
 		self.to_s / string
 	end

data/lib/views/mixin.rb

@@ -1,9 +1,63 @@
 module Waves
 	
+	# Views in Waves are ultimately responsible for generating the response body. Views mirror controllers - both have full access to the request and response, and both may modify the response and even short-circuit the request processing and return a result by calling redirect or calling Response#finish.
+	#
+	# Views, like controllers, are classes with methods that are invoked by a mapping block (see Waves::Mapping). View instance methods take an assigns hash that are typically converted into instance variables accesible from within a template. 
+	#
+	# Like controllers, a default implementation is provided by the +waves+ command when you first create your application. This default can be overridden to change the behaviors for all views, or you can explicitly define a View class to provide specific behavior for one view. 
+	#
+	# The default implementation simply determines which template to render and renders it, returning the result as a string. This machinery is provided by the View mixin, so it is easy to create your own View implementations.
+	#
+	# = Templates
+	#
+	# Although you won't typically need to modify or define View classes, you will often create and modify templates. Templates can be evaluated using any registered Renderer. Two are presently packaged with Waves: Markaby and Erubis. Templates have access to the assigns hash passed to the view method as instance variables. These can be explicitly defined by the mapping file or whomever is invoking the view.
+	#
+	# *Example*
+	#
+	#   # Find the story named 'home' and pass it into the view template as @story
+	#   use( :story ) | controller { find( 'home' ) } | view { |x| show( :story => x ) }
+	#
+	# = Helpers
+	#
+	# 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+.
+	#
+	# 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.
+	#
+	# = Layouts
+	#
+	# Layouts are defined using the +Layout+ view class, and layout templates are placed in the +layout+ directory of the +templates+ directory. Layouts are explicitly set within a template using the +layout+ method.
+	#
+	# *Example*
+	#
+	#   layout :default, :title => @story.title do
+	#     h1 @story.title
+	#     textile @story.content
+	#   end
+	#
+	#
+	# The layout method takes a name and an assigns hash that will be available within the layout template as instance variables. In this example, <tt>@title</tt> will be defined as <tt>@story.title</tt> within the layout template named 'default.' 
+	#
+	# Any number of layouts may be included within a single view, and layouts may even be nested within layouts. This makes it possible to create large numbers of highly structured views that can be easily changed with minimal effort. For example, you might a specific layout associated with form elements. By incorporating this into your views as a +layout+ template, you can make changes across all your forms by changing this single template.
+	#
+  # = Nested Views
+  #
+  # It is easy to include one view inside another. A common use for this is to define one set of templates for reusable content 'fragments' (somewhat akin to partials in Rails) and another set that incorporate these fragments into specific layouts. Including a view from within another view is done, logically enough, using the +view+ method.
+  #
+  # *Example*
+  #
+  #   # include the summary view for Story
+  #   view :story, :summary, :story => @story
+  #
+  # = Request And Response Objects
+  #
+  # As always, the request and response objects, and a wide-variety of short-cut methods, are available within view templates via the Waves::ResponseMixin.
+  #
+  	
 	module Views
 
 		class NoTemplateError < Exception ; end
 	
+	  # A class method that returns the known Renderers, which is any module that is defined within Waves::Renderers and includes the Renderers::Mixin. You can define new Renderers simply be reopening Waves::Renderers and defining a module that mixes in Renderers::Mixin.
 		def Views.renderers
 			return [] if Renderers.constants.nil?
 			Renderers.constants.inject([]) do |rx,cname|
@@ -12,7 +66,7 @@ module Waves
 			end
 		end
 
-	
+	  # The View mixin simply sets up the machinery for invoking a template, along with methods for accessing the request context and the standard interface for invoking a view method.
 		module Mixin
 				
 			attr_reader :request