waves-stable 0.7.7

data/lib/controllers/base.rb

@@ -0,0 +1,11 @@
+module Waves
+  module Controllers
+    class Base
+
+      include Waves::Controllers::Mixin
+
+      def attributes; params[model_name.singular.intern]; end
+
+    end
+  end
+end

data/lib/controllers/mixin.rb

@@ -0,0 +1,165 @@
+module Waves
+
+  #
+  # Controllers in Waves are simply classes that provide a request / response
+  # context for operating on a model. While models are essentially just a way
+  # to manage data in an application, controllers manage data in response to
+  # a request. For example, a controller updates a model instance using
+  # parameters from the request.
+  #
+  # Public controller methods simply return data (a resource), if necessary, that
+  # can be then used by views to determine how to render that data.
+  # Controllers do not determine which view will be invoked. They are
+  # independent of the view; one controller method might be suitable for
+  # several different views. In some cases, controllers can choose to
+  # directly modify the response and possibly even short-circuit the view
+  # entirely. A good example of this is a redirect.
+  #
+  # Controllers, like Views and Mappings, use the Waves::ResponseMixin to
+  # provide a rich context for working with the request and response objects.
+  # They can even call other controllers or views using the controllers method.
+  # In addition, they provide some basic reflection (access to the model and
+  # model_name that corresponds to the class name for the given model) and
+  # automatic parameter destructuring. This allows controller methods to access
+  # the request parameters as a hash, so that a POST variable named
+  # <tt>entry.title</tt> is accessed as <tt>params[:entry][:title]</tt>.
+  #
+  # Controllers often do not have to be explicitly defined. Instead, one or more
+  # default controllers can be defined that are used as exemplars for a given
+  # model. By default, the +waves+ command generates a single default, placed in
+  # the application's <tt>controllers/default.rb</tt> file. This can be modified
+  # to change the default behavior for all controllers. Alternatively, the
+  # <tt>rake generate:controller</tt> command can be used to explicitly define a
+  # controller.
+  #
+  # As an example, the code for the default controller is below for the Blog application.
+  #
+  #   module Blog
+  #     module Controllers
+  #       class Default
+  #
+  #         # Pick up the default controller methods, like param, url, etc.
+  #         include Waves::Controllers::Mixin
+  #
+  #         # This gets me the parameters associated with this model
+  #         def attributes; params[model_name.singular.intern]; end
+  #
+  #         # A simple generic delegator to the model
+  #         def all; model.all; end
+  #
+  #         # Find a specific instance based on a name or raise a 404
+  #         def find( name ); model[ :name => name ] or not_found; end
+  #
+  #         # Create a new instance based on the request params
+  #         def create; model.create( attributes ); end
+  #
+  #         # Update an existing record. find will raise a 404 if not found.
+  #         def update( name )
+  #           instance = find( name )
+  #           instance.set( attributes )
+  #           instance.save_changes
+  #         end
+  #
+  #         # Find and delete - or will raise a 404 if it doesn't exist
+  #         def delete( name ); find( name ).destroy; end
+  #
+  #       end
+  #     end
+  #   end
+  #
+  # Since the mapping file handles "glueing" controllers to views, controllers
+  # don't have to be at all concerned with views. They don't have to set
+  # instance variables, layouts, or contain logic to select the appropriate
+  # view based on the request. All they do is worry about updating the model
+  # when necessary based on the request.
+
+  module Controllers
+
+    #
+    # Waves::Controllers::Mixin adapts a controller class for use in mappings and provides utility methods.     
+    # It is included in controllers autocreated by the Default foundation, so you do not need to include
+    # it in subclasses of the same. 
+    #
+    # The utility methods include simple reflection to allow controller methods
+    # to be written generically (i.e., without reference to a specific model) and
+    # parameter destructuring for the request parameters.
+    #
+
+    module Mixin
+
+      attr_reader :request
+
+      include Waves::ResponseMixin
+
+      # When this mixin is included it adds a class method named +process+,
+      # which accepts a request object and a block. The +process+ method initializes the
+      # controller with the request, then evaluates the block using +instance_eval+. This allows the
+      # controller to be used from within a mapping lambda (i.e. a ResponseProxy).
+
+      def self.included( mod )
+        def mod.process( request, &block )
+          self.new( request ).instance_eval( &block )
+        end
+      end
+
+      def initialize( request )
+        @request = request
+      end
+
+      # The params variable is taken from the request object and "destructured", so that
+      # a parameter named 'blog.title' becomes:
+      #
+      #   params['blog']['title']
+      #
+      # If you want to access the original parameters object, you can still do so using
+      # +request.params+ instead of simply +params+.
+      def params; @params ||= destructure(request.params); end
+
+      # Returns the name of the model corresponding to this controller by taking the basename
+      # of the module and converting it to snake case. If the model plurality is different than
+      # the controller, this will not, in fact, be the model name.
+      def model_name; self.class.basename.snake_case; end
+
+      # Returns the model corresponding to this controller by naively assuming that 
+      # +model_name+ must be correct. This allows you to write generic controller methods such as:
+      #
+      #   model.find( name )
+      #
+      # to find an instance of a given model. Again, the plurality of the controller and
+      # model must be the same for this to work.
+      def model; Waves.application.models[ model_name.intern ]; end
+
+      private
+
+      def destructure( hash )
+        destructured = {}
+        hash.keys.map { |key| key.split('.') }.each do |keys|
+          destructure_with_array_keys(hash, '', keys, destructured)
+        end
+        destructured
+      end
+
+      def destructure_with_array_keys( hash, prefix, keys, destructured )
+        if keys.length == 1
+          key = "#{prefix}#{keys.first}"
+          val = hash[key]
+          destructured[keys.first.intern] = case val
+          when String
+            val.strip
+          when Hash
+            val
+          when nil
+            raise key.inspect
+          end
+        else
+          destructured = ( destructured[keys.first.intern] ||= {} )
+          new_prefix = "#{prefix}#{keys.shift}."
+          destructure_with_array_keys( hash, new_prefix, keys, destructured )
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/dispatchers/base.rb

@@ -0,0 +1,67 @@
+module Waves
+
+  module Dispatchers
+
+    # A NotFoundError means what you think it means.  The dispatchers included with Waves do not
+    # natively intercept this exception.  Instead an exception handler must be registered in the application
+    # mappings.  The Simple foundation registers a minimal handler, while the Default foundation registers
+    # a slightly fleshier one.
+    class NotFoundError < Exception ; end
+
+    # Redirect exceptions are rescued by the Waves dispatcher and used to set the 
+    # response status and location.
+    class Redirect < Exception
+      attr_reader :path, :status
+      def initialize( path, status = '302' )
+        @path = path
+        @status = status
+      end
+    end
+
+    # Waves::Dispatchers::Base provides the basic request processing structure.
+    # All other Waves dispatchers should inherit from it.  It creates a Waves request, 
+    # determines whether to enclose the request processing in a mutex, benchmarks it, 
+    # logs it, and handles common exceptions and redirects. Derived classes need only 
+    # process the request within the +safe+ method, which must take a Waves::Request and return a Waves::Response.
+
+    class Base
+
+      # As with any Rack application, a Waves dispatcher must provide a call method
+      # that takes an +env+ parameter.
+      def call( env )
+        if Waves.config.synchronize?
+          Waves::Application.instance.synchronize { _call( env ) }
+        else
+          _call( env )
+        end
+      end
+
+      # Called by event driven servers like thin and ebb. Returns true if
+      # the server should run the request in a separate thread, as determined by
+      # Configurations::Mapping#threaded?
+      def deferred?( env )
+        Waves::Application.instance.mapping.threaded?( env )
+      end
+      
+      private
+      
+      def _call( env )
+        request = Waves::Request.new( env )
+        response = request.response
+        t = Benchmark.realtime do
+          begin
+            safe( request )
+          rescue Dispatchers::Redirect => redirect
+            response.status = redirect.status
+            response.location = redirect.path
+          end
+        end
+        Waves::Logger.info "#{request.method}: #{request.url} handled in #{(t*1000).round} ms."
+        response.finish
+      end
+
+    end
+
+  end
+
+end

data/lib/dispatchers/default.rb

@@ -0,0 +1,81 @@
+module Waves
+
+  module Dispatchers
+
+    #
+    # Waves::Dispatchers::Default matches requests against an application's mappings to 
+    # determine what main action to take, as well as what before, after, always, and exception-handling
+    # blocks must run.
+    #
+    # The default dispatcher also attempts to set the content type based on the
+    # file extension used in the request URL. It does this using the class defined in
+    # the current configuration's +mime_types+ attribute, which defaults to Mongrel's
+    # MIME type handler.
+    #
+    # You can write your own dispatcher and use it in your application's configuration
+    # file. By default, they use the default dispatcher, like this:
+    #
+    #   application do
+    #     use Rack::ShowExceptions
+    #     run Waves::Dispatchers::Default.new
+    #   end
+    #
+
+    class Default < Base
+
+      # All dispatchers using the Dispatchers::Base to provide thread-safety, logging, etc.
+      # must provide a +safe+ method to handle creating a response from a request.
+      # Takes a Waves::Request and returns a Waves::Reponse
+      def safe( request  )
+
+        response = request.response
+
+        Waves::Application.instance.reload if Waves::Application.instance.debug?
+        response.content_type = Waves::Application.instance.config.mime_types[ request.path ] || 'text/html'
+
+        mapping = Waves::Application.instance.mapping[ request ]
+
+        begin
+
+          mapping[:before].each do | block, args |
+            ResponseProxy.new(request).instance_exec(*args,&block)
+          end
+
+          request.not_found unless mapping[:action]
+
+          block, args = mapping[:action]
+          response.write( ResponseProxy.new(request).instance_exec(*args, &block) )
+          
+          mapping[:after].each do | block, args |
+            ResponseProxy.new(request).instance_exec(*args,&block)
+          end
+
+        rescue Exception => e
+          
+          handler = mapping[:handlers].detect do | exception, block, args |
+            e.is_a? exception
+          end
+          if handler
+            ResponseProxy.new(request).instance_exec(*handler[2], &handler[1])
+          else
+            raise e
+          end
+          
+        ensure
+          mapping[:always].each do | block, args |
+            begin
+              ResponseProxy.new(request).instance_exec(*args,&block) 
+            rescue Exception => e
+              Waves::Logger.info e.to_s
+            end
+          end
+          
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/foundations/default.rb

@@ -0,0 +1,27 @@
+module Waves
+  module Foundations
+# 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.
+#
+# This foundation does not include any ORM configuration.  You can include Waves::Layers::ORM::Sequel or custom configure your model.
+
+    
+    module Default
+
+      def self.included( app )
+
+        app.instance_eval do
+
+          include Waves::Layers::Inflect::English
+          include Waves::Layers::Simple
+          include Waves::Layers::MVC          
+          include Waves::Layers::DefaultErrors
+          
+        end
+        
+        Waves << app
+        
+      end
+    end
+  end
+end
+

data/lib/foundations/simple.rb

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

data/lib/helpers/asset_helper.rb

@@ -0,0 +1,67 @@
+module Waves
+  module Helpers
+    module AssetHelper
+      # Returns an html image tag for the +source+. The +source+ can be a full
+      # path or a file that exists in your public images directory. Note that 
+      # specifying a filename without the extension is now deprecated in Rails.
+      # You can add html attributes using the +options+. The +options+ supports
+      # two additional keys for convienence and conformance:
+      #
+      # * <tt>:alt</tt>  - If no alt text is given, the file name part of the 
+      #   +source+ is used (capitalized and without the extension)
+      # * <tt>:size</tt> - Supplied as "{Width}x{Height}", so "30x45" becomes 
+      #   width="30" and height="45". <tt>:size</tt> will be ignored if the
+      #   value is not in the correct format.
+      #
+      #  image_tag("icon.png")  # =>
+      #    <img src="/images/icon.png" alt="Icon" />
+      #  image_tag("icon.png", :size => "16x10", :alt => "Edit Entry")  # =>
+      #    <img src="/images/icon.png" width="16" height="10" alt="Edit Entry" />
+      #  image_tag("/icons/icon.gif", :size => "16x16")  # =>
+      #    <img src="/icons/icon.gif" width="16" height="16" alt="Icon" />
+      def image_tag(source, options = {})
+        options.symbolize_keys!
+          
+        options[:src] = image_path(source)
+        options[:alt] ||= File.basename(options[:src], '.*').split('.').first.capitalize
+  
+        if options[:size]
+          options[:width], options[:height] = options[:size].split("x") if options[:size] =~ %r{^\d+x\d+$}
+          options.delete(:size)
+        end
+
+        tag("img", options)
+      end
+
+      # Computes the path to an image asset in the public images directory.
+      # Full paths from the document root will be passed through.
+      # Used internally by image_tag to build the image path. Passing
+      # a filename without an extension is deprecated.
+      #
+      #   image_path("edit.png")  # => /images/edit.png
+      #   image_path("icons/edit.png")  # => /images/icons/edit.png
+      #   image_path("/icons/edit.png")  # => /icons/edit.png
+      def image_path(source)
+        compute_public_path(source, 'images', 'png')
+      end
+
+      private
+        def compute_public_path(source, dir, ext)
+          source = source.dup
+          source << ".#{ext}" if File.extname(source).blank?
+          unless source =~ %r{^[-a-z]+://}
+            source = "/#{dir}/#{source}" unless source[0] == ?/
+            asset_id = rails_asset_id(source)
+            source << '?' + asset_id if defined?(RAILS_ROOT) && !asset_id.blank?
+            # source = "#{ActionController::Base.asset_host}#{@controller.request.relative_url_root}#{source}"
+          end
+          source
+        end
+        
+        def rails_asset_id(source)
+          ENV["WAVES_ASSET_ID"] || File.mtime("public/#{source}").to_i.to_s rescue ""
+        end
+
+    end
+  end
+end