waves 0.7.3 → 0.7.5

data/lib/runtime/blackboard.rb

@@ -0,0 +1,57 @@
+module Waves
+
+  # Encapsulates the blackboard associated with a given request. The scope of the blackboard is
+  # the same as the request object it gets attached to.
+  #
+  # The Waves blackboard is a very simple shared storaged usable during the request processing.
+  # It is available within:
+  #    - mappings
+  #    - controllers
+  #    - helpers
+  #
+  # Adding a value:
+  #   blackboard.value1 = 1
+  #   blackboard[:value2] = 2
+  #
+  # Retrieving values
+  #   blackboard.value1
+  #   blackboard[:value2]
+  #
+  # see also blackboard_verify.rb  
+  
+  class Blackboard
+
+    # Create a new blackboard object using the given request.
+    def initialize( request )
+      @request = request
+      @data = {}
+    end
+
+    # Access a given data element of the blackboard using the given key.
+    def [](key)
+      @data[key]
+    end
+
+    # Set the given data element of the blackboard using the given key and value.
+    def []=(key,val)
+      @data[key] = val
+    end
+    
+    def each(&block)
+      @data.each(&block)
+    end
+
+    # also allow things like
+    # blackboard.test1 instead of blackboard[:test1]
+    # blackboard.test1 = 2 instead of blackboard[:test1] = 2
+    def method_missing(name,*args)
+      if (name.to_s =~ /=$/)
+        self[name.to_s.gsub('=', '')] = args[0]
+      else
+        self[name.to_s]
+      end
+    end
+
+  end
+  
+end

data/lib/runtime/configuration.rb

@@ -1,14 +1,13 @@
 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.
+
+  # Waves configurations are Ruby code.  This means you can use a Ruby expression as
+  # the value of a configuration attribute, extend and inherit your configurations, and
+  # add your own attributes. You can even use it as a repository
+  # for your application configuration.
   #
-  # The form for configuration parameters to use the parameter name as a method name. Passing
-  # in a parameter sets the value.
+  # You can access configuration attributes using the attribute name as a method, with the value as the argument.
   #
-  # == Example 
+  # == Example
   #
   #    module Blog
   #      module Configurations
@@ -16,37 +15,36 @@ module Waves
   #          host '127.0.0.1'
   #          port 2000
   #          reloadable [ Blog ]
-  #          log :level => :debug	
+  #          log :level => :debug
   #          application do
   #            use Rack::ShowExceptions
   #            run Waves::Dispatchers::Default.new
-  #          end				
+  #          end
   #        end
   #      end
   #    end
   #
-  # There are three forms for accessing parameters:
+  # There are three forms for accessing attributes:
   #
-  #   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
+  #   Waves.config.port                        # generic form - gets the value for current config
+  #   Blog.configurations[:development].port   # gets the value for a specified config
+  #   Blog::Configurations::Development.port   # Access a specific 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:
+  # Configuration data is inheritable, as shown in the example above. Typically, you
+  # would set data common to all configurations in the Default class, from which
+  # your variations inherit.
+  #
+  # You may define your own heritable attributes using the +attribute+ class method:
   #
   #   class Default < Waves::Configurations::Default
-  #     attribute 'theme' # define a theme attribute
-  #     theme 'ultra'     # give it a default
+  #     attribute 'theme' # define an attribute named "theme"
+  #     theme 'ultra'     # set an inheritable default
   #   end
   #
-  # There are a number of reserved or built-in attributes. These are:
+  # Certain attributes are reserved for internal use by Waves:
   #
   # - application: configure the application for use with Rack
-  # - database: takes a hash of parameters used to initalize the database; see below
+  # - database: initialization parameters needed by the ORM layer
   # - 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)
@@ -58,112 +56,130 @@ module Waves
   #
   # 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.
-  # 
+  # directly to the application developer via the +application+ configuration method.
+  #
   # *Example*
-  # 
+  #
   #   # Typical debugging configuration
   #   application do
-	#   	use Rack::ShowExceptions
-	#   	run Waves::Dispatchers::Default.new
-	#   end				
+  #     use Rack::ShowExceptions
+  #     run Waves::Dispatchers::Default.new
+  #   end
   #
   # == Configuring Database Access
   #
-  # The database parameter takes a hash with the following elements:
+  # The ORM layers provided with Waves use the +database+ attribute for connection initialization.
+  # Most ORMs take a hash for this purpose, with keys that may vary depending on the ORM and backend.
   #
-  # - 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
+  #   # Sequel with a MySQL db
+  #   database :host => 'localhost', :adapter => 'mysql', :database => 'blog',
+  #     :user => 'root', :password => 'guess'
   #
-  # *Example*
+  #   # Sequel with an SQLite db
+  #   database :adapter => 'sqlite', :database => 'blog'
   #
-  #   database :host => host, :adapter => 'mysql', :database => 'blog',
-  #     :user => 'root', :password => 'guess'
+  # See the documentation for each ORM layer for details.
   #
-  # 
-  # == Configuring Code Reloading 
+  # == Configuring Code Reloading
+  #
+  # The +reloadable+ attribute takes an array of modules. Before every request, the default Waves 
+  # dispatcher calls +reload+ on each listed module.  The module should remove any reloadable constants
+  # currently defined in its namespace.  
   #
-  # 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:
+  # In a Waves application built on the Default foundation, +reload+ functionality is provided
+  # by AutoCode for the Configurations, Controllers, Helpers, Models, and Views modules.
+  # 
+  # Listing only your application module will work in most cases:  
   #
   #   reloadable [ Blog ]
   #
-  # although you could do this with several modules just as easily (say, your primary 
-  # application and several helper applications).
+  # As an alternative, you could reload only some of the modules within your application:
   #
-  # == Configuring Logging 
+  #   reloadable [ Blog::Models, Blog::Controllers ]
   #
-  # 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.
+  # == Configuring Logging
+  #
+  # The +log+ configuration attribute takes hash with these keys:
+  # - :level - The log filter level. 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'
+  #  log :level => :info, :output => $stderr
+  #  log :level => :error, :output => 'log/blog.log'
   #
 
-	module Configurations
-
-		class Base
+  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
+      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
+      def self.[]( name ) ; send "_#{name}" ; end
+
+      # Define a new attribute. After calling this, you can get and set the value
+      # using the attribute name as the method
+      def self.attribute( name )
+        meta_def(name) do |*args|
+          raise ArgumentError.new('Too many arguments.') if args.length > 1
+          args.length == 1 ? self[ name ] = args.first : self[ name ]
+        end
+        self[ name ] = nil
+      end
+
+    end
+
+    # The Default configuration defines sensible defaults for attributes required by Waves.
+    #   debug true
+    #   synchronize? true
+    #   session :duration => 30.minutes, :path => '/tmp/sessions'
+    #   log :level => :info, :output => $stderr
+    #   reloadable []
+    class Default < Base
+
+      %w( host port ports log reloadable database session debug root synchronize? ).
+      each { |name| attribute(name) }
+
+      # Set the Rack handler, along with any specific options
+      # that need to be passed to the handler's #run method. 
+      #
+      # When accessing the value
+      # (calling with no arguments), returns an array of the handler and options.
+      def self.handler(*args)
+        if args.length > 0
+          @rack_handler, @rack_handler_options = args
+        else
+          [ @rack_handler, @rack_handler_options ]
+        end
+      end
+
+      # Provides access to the Waves::MimeTypes class via the configuration. You
+      # can override #mime_types to return your own MIME types repository class.
+      def self.mime_types
+        Waves::MimeTypes
+      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
-					args.length == 1 ? self[ name ] = args.first : self[ name ]
-				end
-				self[ name ] = nil
-			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 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.  Treat this method like an
+      # instance of Rack::Builder
+      def self.application( &block )
+        if block_given?
+          self['application'] = Rack::Builder.new( &block )
+        else
+          self['application']
+        end
+      end
 
-      # Defines the application for use with Rack.
-			def self.application( &block )
-			  if block_given? 
-  			  self['application'] = Rack::Builder.new( &block )
-  			else
-  			  self['application']
-  			end
-			end
-      
-      debug true
-			session :duration => 30.minutes, :path => '/tmp/sessions'
-    	log :level => :info, :output => $stderr	
-  	
-		end
-	end
+      debug true ; synchronize? true
+      session :duration => 30.minutes, :path => '/tmp/sessions'
+      log :level => :info, :output => $stderr
+      reloadable []
+    end
+  end
 end
 
 

data/lib/runtime/console.rb

@@ -1,21 +1,20 @@
 module Waves
-	
-	class Console < Application
-		
-		class << self
-
-			attr_reader :console
-
-			def load( options={} )
-				@console ||= Waves::Console.new( options )
-				Kernel.load( :lib / 'startup.rb' )
-			end
-			
-			# allow Waves::Console to act as The Console Instance
-			def method_missing(*args); @console.send(*args); end
-			
-		end
-	
-	end
-	
-end
+
+  class Console < Application
+
+    class << self
+
+      attr_reader :console
+
+      def load( options={} )
+        @console ||= Waves::Console.new( options )
+      end
+
+      # allow Waves::Console to act as The Console Instance
+      def method_missing(*args); @console.send(*args); end
+
+    end
+
+  end
+
+end

data/lib/runtime/debugger.rb

@@ -0,0 +1,9 @@
+module Kernel
+  unless respond_to?(:debugger)
+    # Starts a debugging session if ruby-debug has been loaded (call waves-server --debugger to do load it).
+    def debugger
+      puts "debugger called"
+      Waves::Logger.info "\n***** Debugger requested, but was not available: Start server with --debugger to enable *****\n"
+    end
+  end
+end

data/lib/runtime/logger.rb

@@ -1,52 +1,58 @@
 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
-    
+
+  # 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
+
     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
+      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
-  		# Forwards logging methods to the logger.
-  		def method_missing(name,*args,&block)
-  		  @log.send name,*args, &block
-  		end
+      def start
+        @log = config[:rotation] ?
+          ::Logger.new( output, config[:rotation].intern ) :
+          ::Logger.new( output )
+        @log.level = level
+        self
+      end
+      
+      # Forwards logging methods to the logger.
+      def method_missing(name,*args,&block)
+        @log.send name,*args, &block if @log
+      end
+
+    end
 
-  	end
-		
-	end
+  end
 
 end