ramaze 2011.01.30 → 2011.07.25

data/lib/ramaze/reloader/watch_inotify.rb

@@ -1,5 +1,6 @@
 module Ramaze
   class Reloader
+    ##
     # TODO:
     #   * There seems to be a problem somewhere that I couldn't identify yet, a
     #     file has to be modified twice initially to make it show up as
@@ -11,7 +12,6 @@ module Ramaze
     # NOTE:
     #   * I have changed from using a Mutex to using a Queue, which uses a
     #     Mutex internally.
-
     class WatchInotify
       POLL_INTERVAL = 2 # seconds
       NOTIFY_MASK = RInotify::MODIFY | RInotify::IN_ONESHOT
@@ -54,7 +54,6 @@ module Ramaze
       # FIXME:
       #   Seems like this won't work due to some bug in the rinotify library.
       #   Would be cool if someone could make a FFI version.
-
       def remove_watch(file)
         @watcher.rm_watch(file)
       end
@@ -80,6 +79,6 @@ module Ramaze
           yield(file)
         end
       end
-    end
-  end
-end
+    end # WatchInotify
+  end # Reloader
+end # Ramaze

data/lib/ramaze/reloader/watch_stat.rb

@@ -53,6 +53,6 @@ module Ramaze
       rescue Errno::ENOENT, Errno::ENOTDIR
         nil
       end
-    end
-  end
-end
+    end # WatchStat
+  end # Reloader
+end # Ramaze

data/lib/ramaze/request.rb

@@ -1,11 +1,11 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
 # All files in this distribution are subject to the terms of the Ruby license.
-
 module Ramaze
+  ##
   # The purpose of this class is to act as a simple wrapper for Rack::Request
   # and provide some convinient methods for our own use.
   class Request < Innate::Request
-
+    ##
     # you can access the original @request via this method_missing,
     # first it tries to match your method with any of the HTTP parameters
     # then, in case that fails, it will relay to @request
@@ -15,6 +15,7 @@ module Ramaze
       super
     end
 
+    ##
     # Sets any arguments passed as @instance_variables for the current action.
     #
     # Usage:
@@ -23,7 +24,7 @@ module Ramaze
     #   @q    # => 'google'
     #   @name # => 'manveru'
     #   @lang # => nil
-
+    #
     def to_instance_variables(*args)
       instance = Current.action.instance
       args.each do |arg|
@@ -39,6 +40,7 @@ module Ramaze
       charset == '*' ? default : charset
     end
 
+    ##
     # Try to find out which languages the client would like to have and sort
     # them by weight, (most wanted first).
     #
@@ -54,6 +56,7 @@ module Ramaze
     # @return [Array] list of locales
     # @see Request#accept_language_with_weight
     # @author manveru
+    #
     def accept_language(string = env['HTTP_ACCEPT_LANGUAGE'])
       return [] unless string
 
@@ -61,6 +64,7 @@ module Ramaze
     end
     alias locales accept_language
 
+    ##
     # Transform the HTTP_ACCEPT_LANGUAGE header into an Array with:
     #
     #   [[lang, weight], [lang, weight], ...]
@@ -76,6 +80,7 @@ module Ramaze
     # @return [Array] array of [lang, weight] arrays
     # @see Request#accept_language
     # @author manveru
+    #
     def accept_language_with_weight(string = env['HTTP_ACCEPT_LANGUAGE'])
       string.to_s.gsub(/\s+/, '').split(',').
             map{|chunk|        chunk.split(';q=', 2) }.
@@ -102,14 +107,19 @@ module Ramaze
     # Pretty prints current action with parameters, cookies and enviroment
     # variables.
     def pretty_print(pp)
-      pp.object_group(self){
-        group = { 'params' => params, 'cookies' => cookies, 'env' => http_variables }
+      pp.object_group(self) do
+        group = {
+          'params'  => params,
+          'cookies' => cookies,
+          'env'     => http_variables
+        }
+
         group.each do |name, hash|
           pp.breakable
           pp.text " @#{name}="
           pp.nest(name.size + 3){ pp.pp_hash(hash) }
         end
-      }
+      end
     end
-  end
-end
+  end # Request
+end # Ramaze

data/lib/ramaze/response.rb

@@ -1,36 +1,67 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
 # All files in this distribution are subject to the terms of the Ruby license.
-
 module Ramaze
+  ##
+  # Ramaze::Response is a small wrapper around Rack::Response that makes it
+  # easier to send response data to the browser from a Ramaze application.
+  #
+  # @author Michael Fellinger
+  # @since  01-03-2008
+  #
   class Response < Rack::Response
     # Alias for Current.response
     def self.current; Current.response; end
 
+    ##
+    # Creates a new instance of the response class and processes the specified
+    # parameters. Once this has been done it calls Rack::Response#initialize.
+    #
+    # @author Michael Fellinger
+    # @since  01-03-2008
+    # @param  [Array] body An array containing the data for the response body.
+    # @param  [Fixnum] status The HTPP status code for the response.
+    # @param  [Hash] header A hash containing additional headers and their
+    #  values.
+    # @param  [Proc] &block
+    #
     def initialize(body = [], status = 200, header = {}, &block)
       modified_header = Ramaze.options.header.merge(header)
       header.merge!(modified_header)
       super
     end
 
-    # Build/replace this responses data
+    ##
+    # Updates the body, status and headers.
+    #
+    # @author Michael Fellinger
+    # @since  01-03-2008
+    # @see    Ramaze::Response#initialize
+    #
     def build(new_body = nil, new_status = nil, new_header = nil)
       self.header.merge!(new_header) if new_header
 
-      self.body   = new_body if new_body
+      self.body   = new_body   if new_body
       self.status = new_status if new_status
     end
 
+    ##
+    # Sets the body of the response to the given object.
+    #
+    # @author Michael Fellinger
+    # @since  01-03-2008
+    # @param  [Object] obj The object to use as the response body.
+    #
     def body=(obj)
       if obj.respond_to?(:stat)
         @length = obj.stat.size
-        @body = obj
+        @body   = obj
       elsif obj.respond_to?(:size)
-        @body = []
+        @body   = []
         @length = 0
         write(obj)
       else
         raise(ArgumentError, "Invalid body: %p" % obj)
       end
     end
-  end
-end
+  end # Response
+end # Ramaze

data/lib/ramaze/rest.rb

@@ -0,0 +1,36 @@
+##
+# The code in this file adds an extra option and a route to Ramaze that allows
+# REST like HTTP requests. For example, when this file is loaded a GET request
+# to a controller will be mapped to the "show" method while a POST request will
+# be mapped to "create". In order to use this extension you have to load it
+# manually:
+#
+#  require 'ramaze/rest'
+#
+# From this point on you can customize the route as following:
+#
+#  Ramaze.options.rest_rewrite['GET'] = 'another_method'
+#
+module Ramaze
+  # Don't use one option per method, we don't want to turn request_method into a
+  # symbol, together with MethodOverride this could lead to a memory leak.
+  options.o(
+    'REST rewrite mapping',
+    :rest_rewrite,
+    {
+      'GET'    => 'show',
+      'POST'   => 'create',
+      'PUT'    => 'update',
+      'DELETE' => 'destroy'
+    }
+  )
+
+  # Re-write the URLs according to the settings set above
+  Rewrite['REST dispatch'] = lambda do |path, request|
+    if suffix = Ramaze.options[:rest_rewrite][request.request_method]
+      "#{path}/#{suffix}".squeeze('/')
+    else
+      path
+    end
+  end
+end # Ramaze

data/lib/ramaze/setup.rb

@@ -1,35 +1,47 @@
 module Ramaze
+  ##
   # Convenient setup and activation of gems from different sources and specific
-  # versions.
-  # It's almost like Kernel#gem but also installs automatically if a gem is
-  # missing.
+  # versions.  It's almost like Kernel#gem but also installs automatically if a
+  # gem is missing.
   #
   # @example
+  #  Ramaze.setup :verbose => true do
+  #    # gem and specific version
+  #    gem 'makura', '>=2009.01'
   #
-  #   Ramaze.setup :verbose => true do
-  #     # gem and specific version
-  #     gem 'makura', '>=2009.01'
+  #    # gem and name for require
+  #    gem 'aws-s3', :lib => 'aws/s3'
   #
-  #     # gem and name for require
-  #     gem 'aws-s3', :lib => 'aws/s3'
+  #    # gem with specific version from rubyforge (default)
+  #    gem 'json', :version => '=1.1.3', :source => rubyforge
+  #  end
   #
-  #     # gem with specific version from rubyforge (default)
-  #     gem 'json', :version => '=1.1.3', :source => rubyforge
-  #
-  #     # gem from github
-  #     gem 'manveru-org', :lib => 'org', :source => github
-  #   end
-  #
-  # @option options [boolean] (true) verbose
-  # @option options [String] (nil) extconf
-  # @yield block
-  # @see GemSetup#initialize
   # @author manveru
+  # @since  19-05-2009
+  # @see    GemSetup#initialize
+  #
   def self.setup(options = {:verbose => true}, &block)
     GemSetup.new(options, &block)
   end
 
+  ##
+  # Class responsible for installing and loading all the gems.
+  #
+  # @author Michael Fellinger (manveru)
+  # @since  19-05-2009
+  #
   class GemSetup
+    ##
+    # Creates a new instance of the class and saves the parameters that were set.
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    # @param  [Hash] options Hash containing various options to pass to the
+    #  GemSetup class.
+    # @option options :verbose When set to true Ramaze will log
+    #  various actions such as messages about the installation process.
+    # @yield block
+    #
     def initialize(options = {}, &block)
       @gems = []
       @options = options.dup
@@ -38,12 +50,33 @@ module Ramaze
       run(&block)
     end
 
+    ##
+    # Executes the data inside the block, loading all the gems and optionally
+    # installing them.
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    # @param  [Proc] block A block containing all the calls to gem().
+    #
     def run(&block)
       return unless block_given?
       instance_eval(&block)
       setup
     end
 
+    ##
+    # Adds the given gem to the list of required gems.
+    #
+    # @example
+    #  gem('json', '>=1.5.1')
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    # @param  [String] name The name of the gem to load.
+    # @param  [String] version The version of the gem.
+    # @param  [Hash] options Additional options to use when loading the gem.
+    # @option options :lib The name to load the gem as.
+    #
     def gem(name, version = nil, options = {})
       if version.respond_to?(:merge!)
         options = version
@@ -54,7 +87,12 @@ module Ramaze
       @gems << [name, options]
     end
 
-    # all gems defined, let's try to load/install them
+    ##
+    # Tries to install all the gems.
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    #
     def setup
       require 'rubygems'
       require 'rubygems/dependency_installer'
@@ -64,35 +102,55 @@ module Ramaze
       end
     end
 
-    # first try to activate, install and try to activate again if activation
-    # fails the first time
+    ##
+    # First try to activate, install and try to activate again if activation
+    # fails the first time.
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    # @param  [String] name The name of the gem to activate.
+    # @param  [Hash] options The options from GemSetup#initialize.
+    #
     def setup_gem(name, options)
-      version = [options[:version]].compact
+      version  = [options[:version]].compact
       lib_name = options[:lib] || name
 
-      log "activating #{name}"
+      log "Activating gem #{name}"
 
       Gem.activate(name, *version)
       require(lib_name)
 
+    # Gem not installed yet
     rescue LoadError
-
       install_gem(name, options)
       Gem.activate(name, *version)
       require(lib_name)
     end
 
-    # tell rubygems to install a gem
+    ##
+    # Tell Rubygems to install a gem.
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    # @param  [String] name The name of the gem to activate.
+    # @param  [Hash] options The options to use for installing the gem.
+    #
     def install_gem(name, options)
       installer = Gem::DependencyInstaller.new(options)
 
       temp_argv(options[:extconf]) do
-        log "Installing #{name}"
+        log "Installing gem #{name}"
         installer.install(name, options[:version])
       end
     end
 
-    # prepare ARGV for rubygems installer
+    ##
+    # Prepare ARGV for rubygems installer
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    # @param  [String] extconf
+    #
     def temp_argv(extconf)
       if extconf ||= @options[:extconf]
         old_argv = ARGV.clone
@@ -107,6 +165,13 @@ module Ramaze
 
     private
 
+    ##
+    # Writes the message to the logger.
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    # @param  [String] msg The message to write to the logger.
+    #
     def log(msg)
       return unless @verbose
 
@@ -117,7 +182,12 @@ module Ramaze
       end
     end
 
+    ##
+    # Installs a gem from Rubyforge.
+    #
+    # @author Michael Fellinger (manveru)
+    # @since  19-05-2009
+    #
     def rubyforge; 'http://gems.rubyforge.org/' end
-    def github; 'http://gems.github.com/' end
-  end
-end
+  end # GemSetup
+end # Ramaze

data/lib/ramaze/spec.rb

@@ -2,7 +2,7 @@ require File.expand_path('../', __FILE__) unless defined?(Ramaze)
 
 def spec_requires(*libs)
   spec_precondition 'require' do
-    libs.each{|lib| require(lib) }
+    libs.each { |lib| require(lib) }
   end
 end
 alias spec_require spec_requires