merb 0.4.1 → 0.4.2

data/lib/merb/abstract_controller.rb

@@ -2,6 +2,7 @@ module Merb
   
   class AbstractController                 
     include Merb::RenderMixin
+    include Merb::GeneralControllerMixin
     
     class_inheritable_accessor :before_filters
     class_inheritable_accessor :after_filters
@@ -112,12 +113,20 @@ module Merb
       end
       return :filter_chain_completed
     end 
-  
-    def finalize_session
+    
+    # +finalize_session+ is called at the end of a request to finalize/store any data placed in the session.
+    # Mixins/Classes wishing to define a new session store must implement this method.
+    # See merb/lib/sessions/* for examples of built in session stores.
+    
+    def finalize_session #:nodoc:
       # noop
     end  
-      
-    def setup_session
+
+    # +setup_session+ is called at the beginning of a request to load the current session data.
+    # Mixins/Classes wishing to define a new session store must implement this method.
+    # See merb/lib/sessions/* for examples of built in session stores.
+    
+    def setup_session #:nodoc:
       # noop
     end
     
@@ -175,21 +184,7 @@ module Merb
     #     throw :halt, Proc.new {|c| Tidy.new(c.index) }
     # 
     def self.before(filter, opts={})
-      raise(ArgumentError,
-        "You can specify either :only or :exclude but 
-         not both at the same time for the same filter."
-      ) if opts.has_key?(:only) && opts.has_key?(:exclude)
-      
-      opts = shuffle_filters!(opts)
-      
-      case filter
-      when Symbol, String, Proc
-        (self.before_filters ||= []) << [filter, opts]
-      else
-        raise(ArgumentError, 
-          'filters need to be either a Symbol, String or a Proc'
-        )        
-      end  
+      add_filter((self.before_filters ||= []), filter, opts)
     end
     
     # #after is a class method that allows you to specify after filters in your
@@ -199,24 +194,82 @@ module Merb
     # When you use a proc as a filter it needs to take one parameter. You can
     # gain access to the response body like so: after Proc.new {|c|
     # Tidy.new(c.body) }, :only => :index
+    
     def self.after(filter, opts={})
+      add_filter((self.after_filters ||= []), filter, opts)
+    end
+    
+    # Call #skip_before to remove an already declared (before) filter from your controller.
+    # 
+    # Example:
+    #   class Application < Merb::Controller
+    #     before :require_login
+    #   end
+    #
+    #   class Login < Merb::Controller
+    #     skip_before :require_login  # Users shouldn't have to be logged in to log in
+    #   end
+    
+    def self.skip_before(filter)
+      skip_filter((self.before_filters || []), filter)
+    end
+    
+    # Exactly like #skip_before, but for after filters
+    
+    def self.skip_after(filter)
+      skip_filter((self.after_filters || []), filter)
+    end
+    
+    def self.default_thrown_content
+      Hash.new{ |hash, key| hash[key] = "" }
+    end
+    
+    # Set here to respond when rendering to cover the provides syntax of setting the content_type
+    def content_type_set?
+      false
+    end
+
+    def content_type
+      params[:format] || :html
+    end
+    
+  private
+
+    def self.add_filter(filters, filter, opts={})
       raise(ArgumentError,
         "You can specify either :only or :exclude but 
          not both at the same time for the same filter."
       ) if opts.has_key?(:only) && opts.has_key?(:exclude)
-    
+  
       opts = shuffle_filters!(opts)
-      
+    
       case filter
       when Symbol, Proc, String
-        (self.after_filters ||= []) << [filter, opts]
+        if existing_filter = filters.find {|f| f.first.to_s[filter.to_s]}
+          existing_filter.last.replace(opts)
+        else
+          filters << [filter, opts]
+        end
       else
         raise(ArgumentError, 
-          'After filters need to be either a Symbol, String or a Proc'
+          'Filters need to be either a Symbol, String or a Proc'
         )        
       end
     end
     
+    def self.skip_filter(filters, filter)
+      raise(ArgumentError, 
+        'You can only skip filters that have a String or Symbol name.'
+      ) unless [Symbol, String].include? filter.class
+
+      MERB_LOGGER.warn("Filter #{filter} was not found in your filter chain."
+      ) unless filters.reject! {|f| f.first.to_s[filter.to_s] }
+    end
+
+    # Ensures that the passed in hash values are always arrays.
+    #
+    #   shuffle_filters!(:only => :new) #=> {:only => [:new]}   
+
     def self.shuffle_filters!(opts={})
       if opts[:only] && opts[:only].is_a?(Symbol)
         opts[:only] = [opts[:only]]
@@ -227,19 +280,6 @@ module Merb
       return opts
     end
     
-    def self.default_thrown_content
-      Hash.new{ |hash, key| hash[key] = "" }
-    end
-    
-    # Set here to respond when rendering to cover the provides syntax of setting the content_type
-    def content_type_set?
-      false
-    end
-    
-
-    def content_type
-      params[:format] || :html
-    end
   end  
   
 end

data/lib/merb/caching/store/memcache.rb

@@ -0,0 +1,20 @@
+module Merb
+  module Caching
+    module MemcachedStore
+    
+
+    def get(name)
+      ::Cache.get("fragment:#{name}")
+    end
+    
+    def put(name, content = nil)
+      ::Cache.put("fragment:#{name}", content)
+      content
+    end
+    
+    def expire_fragment(name)
+      ::Cache.delete(name)
+    end     
+    end
+  end
+end      

data/lib/merb/constants.rb

@@ -25,10 +25,8 @@ module Merb
     MULTIPART_REGEXP = /\Amultipart\/form-data.*boundary=\"?([^\";,]+)/n.freeze
     HTTP_COOKIE            = 'HTTP_COOKIE'.freeze
     QUERY_STRING           = 'QUERY_STRING'.freeze
-    APPLICATION_JSON       = 'application/json'.freeze 
-    TEXT_JSON              = 'text/x-json'.freeze
-    APPLICATION_XML        = 'application/xml'.freeze 
-    TEXT_XML               = 'text/xml'.freeze
+    JSON_MIME_TYPE_REGEXP  = %r{^application/json|^text/x-json}.freeze
+    XML_MIME_TYPE_REGEXP   = %r{^application/xml|^text/xml}.freeze
     FORM_URL_ENCODED_REGEXP = %r{^application/x-www-form-urlencoded}.freeze
     UPCASE_CONTENT_TYPE    = 'CONTENT_TYPE'.freeze
     CONTENT_TYPE           = "Content-Type".freeze

data/lib/merb/controller.rb

@@ -6,17 +6,49 @@ module Merb
   # stream it into a tempfile and pass in the filename and tempfile object
   # to your controller via params. It also parses the ?query=string and
   # puts that into params as well.
+  #
+  # == Sessions
+  # 
+  # Session data can be accessed through the +session+ hash:
+  #
+  #   session[:user_id] = @user.id
+  #
+  # Session data is available until the user's cookie gets deleted/expires,
+  # or until your specific session store expires the data.
+  #
+  # === Session Store
+  #
+  # The session store is set in MERB_ROOT/config/merb.yml :
+  #
+  #   :session_store: your_store
+  #
+  # Out of the box merb supports three session stores
+  #
+  # cookie:: All data (max 4kb) stored directly in cookie.  Data integrity is checked on each request to prevent tampering. (Merb::CookieStore)
+  # memory:: Data stored in a class in memory. (Merb::MemorySession)
+  # mem_cache:: Data stored in mem_cache. (Merb::MemCacheSession)
+  #
+  # See the documentation on each session store for more information.
+  #
+  # You can also use a session store provided by a plugin.  For instance, if you have DataMapper you can set
+  #
+  #   :session_store: datamapper
+  #
+  # In this case session data will be stored in the database, as defined by the merb_datamapper plugin.
+  # Similar functionality exists for +activerecord+ and +sequel+ currently.
+  
   class Controller < AbstractController
     class_inheritable_accessor :_session_id_key, :_session_expiry
-    cattr_accessor :_subclasses
+    cattr_accessor :_subclasses, :session_secret_key
     self._subclasses = []
-    
+    self.session_secret_key = nil
     self._session_id_key = '_session_id'
     self._session_expiry = Time.now + Merb::Const::WEEK * 2
 
     include Merb::ControllerMixin
     include Merb::ResponderMixin
     include Merb::ControllerExceptions
+    include Merb::Caching::Actions
         
     class << self
       def inherited(klass)
@@ -173,6 +205,16 @@ module Merb
       res.size == 1 ? res[0] : res
     end
     
+    private
+    
+    # This method is here to overwrite the one in the general_controller mixin
+    # The method ensures that when a url is generated with a hash, it contains a controller
+    def get_controller_for_url_generation(options)
+      controller = options[:controller] || params[:controller]
+      controller = params[:controller] if controller == :current
+      controller
+    end
+    
   end  
   
 end

data/lib/merb/core_ext/get_args.rb

@@ -1,7 +1,7 @@
 begin
   require 'ruby2ruby'
-
-  class ParseTreeArray < Array
+  
+  class ParseTreeArray < Array #:nodoc:
     def self.translate(*args)
       self.new(ParseTree.translate(*args))
     end
@@ -36,7 +36,26 @@ begin
   
   end
 
+  # Used in mapping controller arguments to the params hash.
+  # NOTE: You must have the 'ruby2ruby' gem installed for this to work.
+  # Example:
+  #   (In PostsController)
+  #   def show(id)  #=> id is the same as params[:id]
+
   module GetArgs
+    
+    # Returns an array of method arguments and their default values
+    # Example:
+    #   class Example
+    #     def hello(one,two="two",three)
+    #     end
+    #
+    #     def goodbye
+    #     end
+    #   end
+    #
+    #   Example.instance_method(:hello).get_args    #=> [[:one], [:two, "two"], [:three, "three"]]
+    #   Example.instance_method(:goodbye).get_args  #=> nil
     def get_args
       klass, meth = self.to_s.split(/ /).to_a[1][0..-2].split("#")
       # Remove stupidity for #<Method: Class(Object)#foo>
@@ -45,11 +64,11 @@ begin
     end
   end
 
-  class UnboundMethod
+  class UnboundMethod #:nodoc:
     include GetArgs
   end
 
-  class Method
+  class Method  #:nodoc:
     include GetArgs
   end
 rescue LoadError

data/lib/merb/core_ext/hash.rb

@@ -21,7 +21,7 @@ class Hash
       #
       # == Examples
       #
-      # ===Standard 
+      # === Standard 
       # <user gender='m'>
       #   <age type='integer'>35</age>
       #   <name>Home Simpson</name>
@@ -76,6 +76,8 @@ class Hash
  	end
  	
  	# convert this hash to a query string param
+ 	#   {:name => "Bob", :address => {:street => '111 Ruby Ave.', :city => 'Ruby Central', :phones => ['111-111-1111', '222-222-2222']}}
+  #   #=> "name=Bob&address[city]=Ruby Central&address[phones]=111-111-1111222-222-2222&address[street]=111 Ruby Ave."
   def to_params
     result = ''
     stack = []
@@ -97,24 +99,24 @@ class Hash
   end
   
   # lets through the keys in the argument
-  # >> {:one => 1, :two => 2, :three => 3}.pass(:one)
-  # => {:one=>1}
+  #   $ {:one => 1, :two => 2, :three => 3}.pass(:one)
+  #   #=> {:one=>1}
   def pass(*allowed) 
     self.reject { |k,v| ! allowed.include?(k) } 
   end
   alias only pass
   
   # blocks the keys in the arguments
-  # >> {:one => 1, :two => 2, :three => 3}.block(:one)
-  # => {:two=>2, :three=>3}
+  #   $ {:one => 1, :two => 2, :three => 3}.block(:one)
+  #   #=> {:two=>2, :three=>3}
   def block(*rejected) 
     self.reject { |k,v| rejected.include?(k) } 
   end
   alias except block
 
   # Converts the hash into xml attributes
-  # { :one => "ONE", "two"=>"TWO" }.to_xml_attributes
-  # #=> 'one="ONE" two="TWO"'
+  #   { :one => "ONE", "two"=>"TWO" }.to_xml_attributes
+  #   #=> 'one="ONE" two="TWO"'
   def to_xml_attributes
     map do |k,v|
       "#{k.to_s.camelize.sub(/^(.{1,1})/){|m| m.downcase}}=\"#{v}\""
@@ -128,10 +130,10 @@ class Hash
   # or create the key and add this as the first class
   #
   # Example
-  # @hash[:class] #=> nil
-  # @hash.add_html_class!(:selected) #=> @hash[:class] == "selected"
+  #   @hash[:class] #=> nil
+  #   @hash.add_html_class!(:selected) #=> @hash[:class] == "selected"
   #
-  # @hash.add_html_class!("class1 class2") #=> @hash[:class] == "selected class1 class2"
+  #   @hash.add_html_class!("class1 class2") #=> @hash[:class] == "selected class1 class2"
   def add_html_class!(html_class)
     if self[:class]
       self[:class] = "#{self[:class]} #{html_class}"
@@ -154,6 +156,9 @@ class Hash
     self
   end
   
+  # Converts every key to an uppercase string (non-recursive.)
+  #   {:name => "Bob", "age" => 12, "nick" => "Bobinator"}.environmentize_keys!
+  #   #=> {"NAME"=>"Bob", "NICK"=>"Bobinator", "AGE"=>12}
   def environmentize_keys!
     self.each do |key, value|
       self[key.to_s.upcase] = delete(key)
@@ -161,7 +166,7 @@ class Hash
     self
   end
     
- def method_missing(m,*a)
+ def method_missing(m,*a) #:nodoc:
    m.to_s =~ /=$/ ? self[$`]=a[0] : a==[] ? self[m] : raise(NoMethodError,"#{m}")
  end
   

data/lib/merb/core_ext/inflections.rb

@@ -51,7 +51,7 @@ Inflector.inflections do |inflect|
   inflect.uncountable(%w(equipment information rice money species series fish sheep))
 end
 
-module Inflections
+module Inflections #:nodoc:
 
   def pluralize
     Inflector.pluralize(self)

data/lib/merb/core_ext/kernel.rb

@@ -1,39 +1,79 @@
 module Kernel
-  # Example:
-  #   acquire 'foo/bar/*'
-  # requires all files inside foo/bar - recursive
-  # can take multiple parameters
-  def acquire(*files)
-    files.each do |file|
-      require file if %w(rb so).any?{|f| File.file?("#{file}.#{f}")}
-      $:.each do |path|
-        Dir[File.join(path, file, '*.rb')].each do |file|
-          require file
-        end
+  
+  # Loads both gem and library dependencies that are passed in as arguments.
+  # Each argument can be:
+  #   String - single dependency
+  #   Hash   - name => version
+  #   Array  - string dependencies
+  
+  def dependencies(*args)
+    args.each do |arg|
+      case arg
+        when String : dependency(arg)
+        when Hash   : arg.each { |r,v| dependency(r, v) }
+        when Array  : arg.each { |r|   dependency(r)    }
       end
     end
   end
   
+  # Loads the given string as a gem.
+  # An optional second parameter of a version string can be specified and is passed to rubygems.
+  # If rubygems cannot find the gem it requires the string as a library.
+  
+  def dependency(name, *ver)
+    begin
+      Gem.activate(name, true, *ver)
+      message = "#{Time.now.httpdate}: loading gem '#{name}' from #{__app_file_trace__.first} ..."
+      puts(message)
+      MERB_LOGGER.info(message)
+    rescue LoadError
+      # Failed requiring as a gem, let's try loading with a normal require.
+      requires(name)
+    end
+  end
+
+  # Requires the library string passed in.
+  # If the library fails to load then it will display a helpful message.
+  
+  def requires(library)
+    # TODO: Extract messages out into a messages file. This will also be the first step towards internationalization.
+    # TODO: adjust this message once logging refactor is complete.
+    require(library)
+    message = "#{Time.now.httpdate}: loading library '#{library}' from #{__app_file_trace__.first} ..."
+    puts(message)
+    MERB_LOGGER.info(message)
+  rescue LoadError
+    # TODO: adjust the two messages below to use merb's logger.error/info once logging refactor is complete.
+    message = "#{Time.now.httpdate}: <e> Could not find '#{library}' as either a library or gem, loaded from #{__app_file_trace__.first}.\n"
+    puts(message)
+    MERB_LOGGER.error(message)
+    
+    # Print a helpful message
+    message =  "#{Time.now.httpdate}: <i> Please be sure that if '#{library}': \n"
+    message << "#{Time.now.httpdate}: <i>   * is a normal ruby library (file), be sure that the path of the library it is present in the $LOAD_PATH via $LOAD_PATH.unshift(\"/path/to/#{library}\") \n"
+    message << "#{Time.now.httpdate}: <i>   * is included within a gem, be sure that you are specifying the gem as a dependency \n"
+    puts(message)
+    MERB_LOGGER.error(message)
+    exit() # Missing library/gem must be addressed.
+  end
+  
   # does a basic require, and prints the message passed as an optional
   # second parameter if an error occurs.
+  
   def rescue_require(sym, message = nil)
     require sym
   rescue LoadError, RuntimeError
     puts message if message
   end
   
-  def dependencies(*args)
-    args.each do |arg|
-      case arg
-        when String : dependency(arg)
-        when Hash : arg.each { |r,v|  dependency(r, v) }
-      end
-    end
-  end
-  
-  def dependency(gem, *ver)
-    Gem.activate(gem, true, *ver)
-  end
+  # Used in MERB_ROOT/dependencies.yml
+  # Tells merb which ORM (Object Relational Mapper) you wish to use.
+  # Currently merb has plugins to support ActiveRecord, DataMapper, and Sequel.
+  #
+  # Example
+  #   $ sudo gem install merb_datamapper # or merb_activerecord or merb_sequel
+  #   use_orm :datamapper # this line goes in dependencies.yml
+  #   $ ruby script/generate model MyModel # will use the appropriate generator for your ORM
   
   def use_orm(orm)
     raise "Don't call use_orm more than once" unless 
@@ -45,6 +85,15 @@ module Kernel
     Kernel.dependency(orm_plugin)
   end
   
+  # Used in MERB_ROOT/dependencies.yml
+  # Tells merb which testing framework to use.
+  # Currently merb supports rspec and test_unit for testing
+  #
+  # Example
+  #   $ sudo gem install rspec
+  #   use_test :rspec # this line goes in dependencies.yml (or use_test :test_unit)
+  #   $ ruby script/generate controller MyController # will use the appropriate generator for tests
+  
   def use_test(test_framework)
     test_framework = test_framework.to_sym
     raise "use_test only supports :rspec and :test_unit currently" unless
@@ -54,8 +103,20 @@ module Kernel
     Merb::GENERATOR_SCOPE.push(test_framework)
   end
   
+  # Returns an array with a stack trace of the application's files.
+
+  def __app_file_trace__
+    caller.select do |call| 
+      call.include?(MERB_ROOT) && !call.include?(MERB_ROOT + "/framework")
+    end.map do |call|
+      file, line = call.scan(Regexp.new("#{MERB_ROOT}/(.*):(.*)")).first
+      "#{file}:#{line}"
+    end
+  end
+
   # Gives you back the file, line and method of the caller number i
-  # Example:
+  #
+  # Example
   #   __caller_info__(1) # -> ['/usr/lib/ruby/1.8/irb/workspace.rb', '52', 'irb_binding']
 
   def __caller_info__(i = 1)
@@ -75,7 +136,7 @@ module Kernel
   #     ...,
   #     ...
   #   ]
-  # Example:
+  # Example
   #  __caller_lines__('/usr/lib/ruby/1.8/debug.rb', 122, 2) # ->
   #   [
   #     [ 120, "  def check_suspend",                               false ],
@@ -108,6 +169,19 @@ module Kernel
     area
   end
   
+  # Requires ruby-prof (<tt>sudo gem install ruby-prof</tt>)
+  # Takes a block and profiles the results of running the block 100 times.
+  # The resulting profile is written out to MERB_ROOT/log/#{name}.html.
+  # <tt>min</tt> specifies the minimum percentage of the total time a method must take for it to be included in the result.
+  #
+  # Example
+  #   __profile__("MyProfile", 5) do
+  #     30.times { rand(10)**rand(10) }
+  #     puts "Profile run"
+  #   end
+  # Assuming that the total time taken for #puts calls was less than 5% of the total time to run, #puts won't appear
+  # in the profilel report.
+  
   def __profile__(name, min=1)
     require 'ruby-prof' unless defined?(RubyProf)
     return_result = ''
@@ -124,8 +198,14 @@ module Kernel
   end  
   
   # Extracts an options hash if it is the last item in the args array
+  # Used internally in methods that take *args
+  #
+  # Example
+  #   def render(*args,&blk)
+  #     opts = extract_options_from_args!(args) || {}
+  
   def extract_options_from_args!(args)
-    args.pop if args.last.is_a?( Hash )
+    args.pop if Hash === args.last
   end
   
 end