halcyon 0.5.0 → 0.5.1

data/lib/halcyon/config/file.rb

@@ -0,0 +1,100 @@
+require 'erb'
+
+module Halcyon
+  class Config
+    
+    # Class to assist with loading configuration from a file.
+    # 
+    # Examples:
+    # 
+    #   Halcyon::Config::File.new(file_name_or_path).to_hash #=> {...}
+    # 
+    class File
+      
+      attr_accessor :path
+      attr_accessor :content
+      
+      # Creates a profile with the default paths.
+      # 
+      # * +file+ is the path to the file.
+      # * +filter_config+ specifies whether to filter the contents through ERB
+      #   before parsing it.
+      # 
+      def initialize(file, filter_config = true)
+        if ::File.exist?(file)
+          self.path = file
+        elsif ::File.exist?(Halcyon.paths.for(:config)/file)
+          self.path = Halcyon.paths.for(:config)/file
+        else
+          raise ArgumentError.new("Could not find #{self.path} (it does not exist).")
+        end
+        self.content = self.filter(::File.read(self.path), filter_config)
+      end
+      
+      # Returns the loaded configuration file's contents parsed by the
+      # marshal format loader (defaulting to YAML, also providing JSON).
+      # 
+      # Examples:
+      # 
+      #   p = Halcyon.paths.for(:config)/'config.yml'
+      #   c = Halcyon::Config::File.new(p)
+      #   c.to_hash #=> the contents of the config file parsed as YAML
+      #   c.to_hash(:from_json) #=> same as above only parsed as JSON
+      #   # parsing errors will happen if you try to use the wrong marshal
+      #   # load method
+      # 
+      def to_hash(from = :from_yaml)
+        case from
+        when :from_yaml
+          require 'yaml'
+          YAML.load(self.content)
+        when :from_json
+          JSON.parse(self.content)
+        end
+      end
+      
+      # Filters the contents through ERB.
+      # 
+      def filter(content, filter_through_erb)
+        content =  ERB.new(content).result if filter_through_erb
+        content
+      end
+      
+      def inspect
+        "#<Halcyon::Config::File #{self.path}>"
+      end
+      
+      class << self
+        
+        # Provides a convenient way to load the configuration and return the
+        # appropriate hash contents.
+        # 
+        def load(path)
+          file = File.new(path)
+          case path
+          when /\.(yaml|yml)/
+            file.to_hash
+          when /\.(json)/
+            file.to_hash(:from_json)
+          end
+        end
+        
+        # Loads the configuration file and parses it's contents as YAML.
+        # This is a shortcut method.
+        # 
+        def load_from_yaml(path)
+          self.new(path).to_hash
+        end
+        
+        # Loads the configuration file and parses it's contents as JSON.
+        # This is a shortcut method.
+        # 
+        def load_from_json(path)
+          self.new(path).to_hash(:from_json)
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/halcyon/config/helpers.rb

@@ -0,0 +1,180 @@
+module Halcyon
+  class Config
+    module Helpers
+      
+      # Extends the target class with the Configurable and Accessors helpers.
+      def self.included(target)
+        target.extend(Configurable)
+        target.extend(Accessors)
+      end
+      
+      # Provides several convenience accessors for configuration values,
+      # including these:
+      # * <tt>app</tt>: the app name
+      # * <tt>root</tt>: the application working directory
+      # * <tt>db</tt>: database configuration settings
+      # 
+      module Accessors
+        
+        # Accesses the <tt>app</tt> config value which is the constantized
+        # version of the application name (which can be set manually in the
+        # config file as <tt>app: NameOfApp</tt>, defaulting to a camel case
+        # version of the application directory name).
+        # 
+        def app
+          self.config[:app] || ::File.dirname(self.root).camel_case
+        end
+        
+        # Sets the application name.
+        # 
+        def app=(name)
+          self.config[:app] = name
+        end
+        
+        # Accesses the <tt>root</tt> config value which is the root of the
+        # current Halcyon application (usually <tt>Dir.pwd</tt>).
+        # 
+        # Defaults to <tt>Dir.pwd</tt>
+        # 
+        def root
+          self.config[:root] || Dir.pwd rescue Dir.pwd
+        end
+        
+        # Sets the application root.
+        # 
+        def root=(path)
+          self.config[:root] = path
+        end
+        
+        # Accesses the <tt>db</tt> config value. Intended to contain the
+        # database configuration values for whichever ORM is used.
+        # 
+        def db
+          self.config[:db]
+        end
+        
+        # Sets the database settings.
+        # 
+        def db=(config)
+          self.config[:db] = config
+        end
+        
+        # Accesses the <tt>environment</tt> config value. Intended to contain
+        # the environment the application is running in.
+        # 
+        # Defaults to the <tt>development</tt> environment.
+        # 
+        def environment
+          self.config[:environment] || :development
+        end
+        alias_method :env, :environment
+        
+        # Sets the environment config value.
+        # 
+        def environment=(env)
+          self.config[:environment] = env.to_sym
+        end
+        alias_method :env=, :environment=
+        
+        # Provides a proxy to the Halcyon::Config::Paths instance.
+        # 
+        def paths
+          self.config[:paths]
+        end
+        
+        # Provides a proxy to the hooks hash.
+        # 
+        def hooks
+          self.config[:hooks]
+        end
+        
+      end
+      
+      # Provides dynamic creation of configuration attribute accessors.
+      # 
+      module Configurable
+        
+        # Defines a dynamic accessor for configuration attributes.
+        # 
+        # Examples:
+        # 
+        #   Halcyon.configurable(:db)
+        #   Halcyon.db = {...}
+        #   Halcyon.config[:db] #=> {...}
+        #   Halcyon.config[:db] = true
+        #   Halcyon.db #=> true
+        # 
+        def configurable(attribute)
+          eval <<-"end;"
+            def #{attribute.to_s}
+              Halcyon.config[:#{attribute.to_s}]
+            end
+            def #{attribute.to_s}=(value)
+              value = value.to_mash if value.is_a?(Hash)
+              Halcyon.config[:#{attribute.to_s}] = value
+            end
+          end;
+        end
+        alias_method :configurable_attr, :configurable
+        
+        # Defines a dynamic reader for configuration attributes, accepting
+        # either a string or a block to perform the action.
+        # 
+        # Examples:
+        # 
+        #   Halcyon.configurable_reader(:foo) do
+        #     self.config[:foo].to_sym
+        #   end
+        # 
+        # OR
+        # 
+        #   Halcyon.configurable_reader(:foo, "Halcyon.config[%s].to_sym")
+        # 
+        def configurable_reader(attribute, code=nil, &block)
+          if block_given? and not code
+            Halcyon.class.send(:define_method, attribute.to_sym, block)
+          elsif code and not block_given?
+            Halcyon.class.send(:eval, <<-"end;")
+              def #{attribute.to_s}
+                #{code % [attribute.to_sym.inspect]}
+              end
+            end;
+          else
+            raise ArgumentError.new("Either a block or a code string should be supplied.")
+          end
+        end
+        alias_method :configurable_attr_reader, :configurable_reader
+        
+        # Defines a dynamic writer for configuration attributes, accepting
+        # either a string or a block to perform the action.
+        # 
+        # Examples:
+        # 
+        #   Halcyon.configurable_writer(:foo) do |val|
+        #     self.config[:foo] = val.to_sym
+        #   end
+        # 
+        # OR
+        # 
+        #   Halcyon.configurable_reader(:foo, "Halcyon.config[%s] = value.to_sym")
+        # 
+        def configurable_writer(attribute, code=nil, &block)
+          if block_given? and not code
+            Halcyon.class.send(:define_method, :"#{attribute}=", block)
+          elsif code and not block_given?
+            Halcyon.class.send(:eval, <<-"end;")
+              def #{attribute.to_s}=(value)
+                #{code % [attribute.to_sym.inspect]}
+              end
+            end;
+          else
+            raise ArgumentError.new("Either a block or a code string should be supplied.")
+          end
+        end
+        alias_method :configurable_attr_writer, :configurable_writer
+        
+      end
+      
+    end
+  end
+end

data/lib/halcyon/config/paths.rb

@@ -0,0 +1,73 @@
+module Halcyon
+  class Config
+    class Paths
+      
+      attr_accessor :paths
+      
+      # Creates a profile with the default paths.
+      def initialize(paths={})
+        self.paths = Mash.new(self.defaults.merge(paths))
+      end
+      
+      # Gets the path for the specified entity.
+      # 
+      # Examples:
+      # 
+      #   Halcyon.paths.for(:log) #=> "/path/to/app/log/"
+      # 
+      def for(key)
+        self.paths[key] or raise ArgumentError.new("Path is not defined")
+      end
+      
+      # Alias to <tt>for</tt>.
+      # 
+      def [](key)
+        self.for(key)
+      end
+      
+      # Defines a path for the specified entity.
+      # 
+      # Examples:
+      # 
+      #   Halcyon.paths.define(:tmp, Halcyon.root/'tmp')
+      # 
+      # OR
+      # 
+      #   Halcyon.paths.define(:tmp => Halcyon.root/'tmp')
+      # 
+      def define(key_or_hash, value = nil)
+        if key_or_hash.is_a?(Hash) and value.nil?
+          key_or_hash.keys.each do |key|
+            self.define(key, key_or_hash[key])
+          end
+        else
+          self.paths[key_or_hash] = value
+        end
+      end
+      
+      # Alias for <tt>define</tt>.
+      # 
+      def []=(key, value)
+        self.define(key, value)
+      end
+      
+      # Default paths.
+      # 
+      def defaults
+        {
+          :controller => Halcyon.root/'app',
+          :model => Halcyon.root/'app'/'models',
+          :lib => Halcyon.root/'lib',
+          :config => Halcyon.root/'config',
+          :init => Halcyon.root/'config'/'init',
+          :log => Halcyon.root/'log'
+        }
+      end
+      
+      def inspect
+        "#<Halcyon::Config::Paths #{self.paths.keys.join(', ')}>"
+      end
+      
+    end
+  end
+end

data/lib/halcyon/controller.rb

@@ -12,28 +12,27 @@ module Halcyon
     # Sets the <tt>@env</tt> and <tt>@request</tt> instance variables, used by
     # various helping methods.
     #   +env+ the request environment details
+    # 
     def initialize(env)
       @env = env
       @request = Rack::Request.new(@env)
     end
     
-    class << self
-      
-      # Not implemented.
-      def before method, &proc
-        raise NotImplemented.new
-      end
-      
-      # Not implemented.
-      def after method, &proc
-        raise NotImplemented.new
-      end
-      
+    # Used internally.
+    # 
+    # Dispatches the action specified, including all filters.
+    # 
+    def _dispatch(action)
+      _run_filters(:before, action)
+      response = send(action)
+      _run_filters(:after, action)
+      response
     end
     
     # Returns the request params and the route params.
     # 
     # Returns Hash:{route_params, get_params, post_params}.to_mash
+    # 
     def params
       self.request.params.merge(self.env['halcyon.route']).to_mash
     end
@@ -41,6 +40,7 @@ module Halcyon
     # Returns any POST params, excluding GET and route params.
     # 
     # Returns Hash:{...}.to_mash
+    # 
     def post
       self.request.POST.to_mash
     end
@@ -48,6 +48,7 @@ module Halcyon
     # Returns any GET params, excluding POST and route params.
     # 
     # Returns Hash:{...}.to_mash
+    # 
     def get
       self.request.GET.to_mash
     end
@@ -55,6 +56,7 @@ module Halcyon
     # Returns query params (usually the GET params).
     # 
     # Returns Hash:{...}.to_mash
+    # 
     def query_params
       Rack::Utils.parse_query(self.env['QUERY_STRING']).to_mash
     end
@@ -62,6 +64,7 @@ module Halcyon
     # The path of the request URL.
     # 
     # Returns String:/path/of/request
+    # 
     def uri
       # special parsing is done to remove the protocol, host, and port that
       # some Handlers leave in there. (Fixes inconsistencies.)
@@ -71,10 +74,77 @@ module Halcyon
     # The request method.
     # 
     # Returns Symbol:get|post|put|delete
+    # 
     def method
       self.env['REQUEST_METHOD'].downcase.to_sym
     end
     
+    # Returns the name of the controller in path form.
+    # 
+    def self.controller_name
+      @controller_name ||= self.name.to_const_path
+    end
+    
+    # Returns the name of the controller in path form.
+    # 
+    def controller_name
+      self.class.controller_name
+    end
+    
+    # Generates a URL based on the given name and passed
+    # options. Used with named routes and resources:
+    #
+    #  url(:users) # => "/users"
+    #  url(:admin_permissons) # => "/admin/permissions"
+    #  url(:user, @user) # => "/users/1"
+    #
+    # Based on the identical method of Merb's controller.
+    # 
+    def url(name, rparams={})
+      Halcyon::Application::Router.generate(name, rparams,
+        { :controller => controller_name,
+          :action => method
+        }
+      )
+    end
+    
+    #--
+    # Responders
+    #++
+    
+    # Responds with the correct status and body specified.
+    # 
+    # * +state+ a snake-case symbol of the status (ie, <tt>:not_found</tt>,
+    #   <tt>:unprocessable_entity</tt>, or <tt>:forbidden</tt>)
+    # * +body+ the response body (if the default is insufficient)
+    # 
+    # Examples:
+    # 
+    #   class Foos < Application
+    #     def show
+    #       if (foo = Foo[params[:id]])
+    #         ok(foo)
+    #       else
+    #         status :not_found
+    #       end
+    #     end
+    #   end
+    # 
+    # The above example is the same as <tt>raise NotFound.new</tt>.
+    # 
+    # If the state specified is not found, it will
+    # <tt>raise ServiceUnavailable.new</tt> (a <tt>503</tt> error). The error
+    # is then logged along with the backtrace.
+    # 
+    def status(state, body = nil)
+      raise Halcyon::Exceptions.const_get(state.to_s.camel_case.to_sym).new(body)
+    rescue NameError => e
+      self.logger.error "Invalid status #{state.inspect} specified."
+      self.logger.error "Backtrace:\n" << e.backtrace.join("\n\t")
+      raise Halcyon::Exceptions::ServiceUnavailable.new
+    end
+    alias_method :error, :status
+    
     # Formats message into the standard success response hash, with a status of
     # 200 (the standard success response).
     #   +body+ the body of the response
@@ -93,8 +163,9 @@ module Halcyon
     #   <tt>success</tt>
     # 
     # Returns Hash:{:status=>200, :body=>body}
-    def ok(body='OK')
-      {:status => 200, :body => body}
+    # 
+    def ok(body='OK', headers = {})
+      {:status => 200, :body => body, :headers => headers}
     end
     alias_method :success, :ok
     
@@ -118,34 +189,93 @@ module Halcyon
     #   <tt>missing</tt>
     # 
     # Returns Hash:{:status=>404, :body=>body}
-    def not_found(body='Not Found')
-      {:status => 404, :body => body}
+    # 
+    def not_found(body='Not Found', headers = {})
+      {:status => 404, :body => body, :headers => headers}
     end
     alias_method :missing, :not_found
-
-    # Returns the name of the controller in path form.
-    def self.controller_name
-      @controller_name ||= self.name.to_const_path
+    
+    #--
+    # Filters
+    #++
+    
+    class << self
+      
+      # Creates +filters+ accessor method and initializes the +@filters+
+      # attribute with the necessary structure.
+      # 
+      def filters
+        @filters ||= {:before => [], :after => []}
+      end
+      
+      # Sets up filters for the method defined in the controllers.
+      # 
+      # Examples
+      # 
+      #   class Foos < Application
+      #     before :foo do
+      #       #
+      #     end
+      #     after :blah, :only => [:foo]
+      #     def foo
+      #       # the block is called before the method is called
+      #       # and the method is called after the method is called
+      #     end
+      #     private
+      #     def blah
+      #       #
+      #     end
+      #   end
+      # 
+      # Options
+      # * +method_or_filter+ either the method to run before 
+      # 
+      def before method_or_filter, options={}, &block
+        _add_filter(:before, method_or_filter, options, block)
+      end
+      
+      # See documentation for the +before+ method.
+      # 
+      def after method_or_filter, options={}, &block
+        _add_filter(:after, method_or_filter, options, block)
+      end
+      
+      # Used internally to save the filters, applied when called.
+      # 
+      def _add_filter(where, method_or_filter, options, block)
+        self.filters[where] << [method_or_filter, options, block]
+      end
+      
     end
-
-    # Returns the name of the controller in path form.
-    def controller_name
-      self.class.controller_name
+    
+    # Used internally.
+    # 
+    # Applies the filters defined by the +before+ and +after+ class methods.
+    # 
+    # +where+ specifies whether to apply <tt>:before</tt> or <tt>:after</tt>
+    #   filters
+    # +action+ the routed action (for testing filter applicability)
+    # 
+    def _run_filters(where, action)
+      self.class.filters[where].each do |(method_or_filter, options, block)|
+        if block
+          block.call(self) if _filter_condition_met?(method_or_filter, options, action)
+        else
+          send(method_or_filter) if _filter_condition_met?(method_or_filter, options, action)
+        end
+      end
     end
-
-    # Generates a URL based on the given name and passed
-    # options. Used with named routes and resources:
-    #
-    #  url(:users) # => "/users"
-    #  url(:admin_permissons) # => "/admin/permissions"
-    #  url(:user, @user) # => "/users/1"
-    #
-    # Based on the identical method of Merb's controller.
-    def url(name, rparams={})
-      Halcyon::Application::Router.generate(name, rparams,
-        { :controller => controller_name,
-          :action => method
-        }
+    
+    # Used internally.
+    # 
+    # Tests whether a filter should be run for an action or not.
+    # 
+    def _filter_condition_met?(method_or_filter, options, action)
+      (
+        options[:only] and options[:only].include?(action)) or
+        (options[:except] and !options[:except].include?(action)
+      ) or (
+        method_or_filter == action
       )
     end