ramaze 2011.01.30 → 2011.07.25

data/lib/ramaze/controller.rb

@@ -2,7 +2,24 @@
 # All files in this distribution are subject to the terms of the Ruby license.
 
 module Ramaze
-  # TODO: Describe what this class does other than initailizing the Controller system.
+  ##
+  # Ramaze::Controller is the base controller of all controllers when developing
+  # applications in Ramaze. It acts as a nice wrapper around Innate::Node and
+  # allows for a more traditional MVC approach.
+  #
+  # == Example
+  #
+  #  class Posts < Ramaze::Controller
+  #    map '/posts'
+  #
+  #    def index
+  #
+  #    end
+  #  end
+  #
+  # @author Michael Fellinger
+  # @since  04-01-2009
+  #
   class Controller
     include Innate::Traited
     include Innate::Node
@@ -18,6 +35,27 @@ module Ramaze
     trait :app => :pristine
     trait :skip_controller_map => false
 
+    ##
+    # Hash containing the names of two common controller names and the URIs they
+    # should be mapped to.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    #
+    IRREGULAR_MAPPING = {
+      'Controller'     => nil,
+      'MainController' => '/'
+    }
+
+    ##
+    # Modifies the extending class so that it's properly set up to be used as a
+    # controller.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    # @param  [Class] into The class that extended Ramaze::Controller (or a sub
+    #  class).
+    #
     def self.inherited(into)
       Innate::Node.included(into)
       into.helper(:layout)
@@ -25,6 +63,13 @@ module Ramaze
       into.trait :skip_node_map => true
     end
 
+    ##
+    # Sets all the controllers up and loads a default controller in case no
+    # custom ones have been specified.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    #
     def self.setup
       case CONTROLLER_LIST.size
       when 0
@@ -46,28 +91,59 @@ module Ramaze
       end
     end
 
+    ##
+    # Method that's used to setup each controller, called by
+    # Ramaze::Controller.setup.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    #
     def self.setup_procedure
       unless ancestral_trait[:provide_set]
-        engine(:Etanni)
+        engine(:etanni)
         trait(:provide_set => false)
       end
 
       map(generate_mapping(name)) unless trait[:skip_controller_map]
     end
 
+    ##
+    # Sets the view engine to use for pages with a content type of text/html.
+    #
+    # @example
+    #  class Posts < Ramaze::Controller
+    #    engine :etanni
+    #  end
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    # @param  [#to_sym] name The name of the view engine to use.
+    #
     def self.engine(name)
       provide(:html, name.to_sym)
     end
 
+    ##
+    # Returns the URI a controller is mapped to.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    # @return [String]
+    #
     def self.mapping
       Ramaze.to(self)
     end
 
-    IRREGULAR_MAPPING = {
-      'Controller' => nil,
-      'MainController' => '/'
-    }
-
+    ##
+    # Generates a URI for the full namespace of a class. If a class is named
+    # A::B::C the URI would be /a/b/c.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    # @param  [String] klass_name The name of the class for which to generate
+    #  the mapping, defaults to the current class.
+    # @return [String]
+    #
     def self.generate_mapping(klass_name = self.name)
       chunks = klass_name.to_s.split(/::/)
       return if chunks.empty?
@@ -79,6 +155,15 @@ module Ramaze
       '/' << chunks.map{|chunk| chunk.snake_case }.join('/')
     end
 
+    ##
+    # Maps the current class to the specified location.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    # @param  [String] location The URI to map the controller to.
+    # @param  [String] app_name The name of the application the controller
+    #  belongs to.
+    #
     def self.map(location, app_name = nil)
       if app_name
         trait :app => app_name
@@ -91,13 +176,27 @@ module Ramaze
       App.find_or_create(app_name).map(location, self)
     end
 
+    ##
+    # Returns the application to which the controller belongs to.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    # @return [Ramaze::App]
+    #
     def self.app
       App[ancestral_trait[:app]]
     end
 
+    ##
+    # Returns all the options for the application the controller belongs to.
+    #
+    # @author Michael Fellinger
+    # @since  04-01-2009
+    # @return [Innate::Options]
+    #
     def self.options
       return unless app = self.app
       app.options
     end
-  end
-end
+  end # Controller
+end # Ramaze

data/lib/ramaze/controller/default.rb

@@ -1,12 +1,25 @@
 module Ramaze
   Log.debug "Default controller invoked"
 
+  ##
+  # The default controller that is loaded if no other controllers have been
+  # defined.
+  #
+  # @author Michael Fellinger
+  # @since  30-03-2009
+  #
   class DefaultController < Ramaze::Controller
     map '/'
 
+    ##
+    # Shows an ASCII lobster using Rack::Lobster::LobsterString.
+    #
+    # @author Michael Fellinger
+    # @since  06-04-2009
+    #
     def lobster
       require 'rack/lobster'
       respond Rack::Lobster::LobsterString
     end
-  end
-end
+  end # DefaultController
+end # Ramaze

data/lib/ramaze/current.rb

@@ -1,7 +1,19 @@
 module Ramaze
+  ##
+  # Class that's used to point to the current action. This can be useful if you
+  # want to access data such as the session() method without having to include
+  # Innate::Trinity (which can pollute your namespace and/or cause collisions).
+  #
+  # @author Michael Fellinger
+  # @since  25-03-2009
+  #
   class Current < Innate::Current
+    ##
+    # @author Michael Fellinger
+    # @since  25-03-2009
+    # @see    Innate::Current#setup
     def setup(env, request = Request, response = Response, session = Session)
       super
     end
-  end
-end
+  end # Current
+end # Ramaze

data/lib/ramaze/dependencies.rb

@@ -0,0 +1,46 @@
+module Ramaze
+  # Array containing the names and versions of all the gems required by Ramaze
+  # along with the name of how the gem should be required.
+  DEPENDENCIES = [
+    {:name => 'innate', :version => ['>= 2010.03']}
+  ]
+
+  # Array containing all the development dependencies.
+  DEVELOPMENT_DEPENDENCIES = [
+    {:name => 'bacon'       , :version => ['>= 1.1.0']},
+    {:name => 'dalli'       , :version => ['>= 1.0.5']},
+    {:name => 'erector'     , :version => ['>= 0.8.2']},
+    {:name => 'erubis'      , :version => ['>= 2.7.0']},
+    {:name => 'ezamar'      , :version => ['>= 2009.06']},
+    {:name => 'sass'        , :version => ['>= 3.1.4']},
+    {:name => 'haml'        , :version => ['>= 3.1.2']},
+    {:name => 'hpricot'     , :version => ['>= 0.8.4']},
+    {:name => 'liquid'      , :version => ['>= 2.2.2']},
+    {:name => 'locale'      , :version => ['>= 2.0.5']},
+    {:name => 'lokar'       , :version => ['>= 0.2.1']},
+    {:name => 'maruku'      , :version => ['>= 0.6.0']},
+    {:name => 'mustache'    , :version => ['>= 0.99.4']},
+    {:name => 'nagoro'      , :version => ['>= 2009.05']},
+    {:name => 'rack-contrib', :version => ['>= 1.1.0'], :lib => 'rack/contrib'},
+    {:name => 'rack-test'   , :version => ['>= 0.6.0'], :lib => 'rack/test'},
+    {:name => 'Remarkably'  , :version => ['>= 0.6.1'], :lib => 'remarkably'},
+    {:name => 'sequel'      , :version => ['>= 3.25.0']},
+    {:name => 'slippers'    , :version => ['>= 0.0.14']},
+    {:name => 'sqlite3'     , :version => ['>= 1.3.3']},
+    {:name => 'tagz'        , :version => ['>= 9.0.0']},
+    {:name => 'tenjin'      , :version => ['>= 0.6.1']},
+    {:name => 'yard'        , :version => ['>= 0.7.2']},
+  ]
+
+  if !RUBY_PLATFORM.include?('darwin')
+    DEVELOPMENT_DEPENDENCIES.push(
+      {:name => 'localmemcache', :version => ['>= 0.4.4']}
+    )
+  end
+
+  if RUBY_PLATFORM.include?('darwin')
+    DEVELOPMENT_DEPENDENCIES.push(
+      {:name => 'ruby-growl', :version => ['>= 3.0']}
+    )
+  end
+end # Ramaze

data/lib/ramaze/files.rb

@@ -1,24 +1,59 @@
 module Ramaze
-  # Serving multiple public directories made easy.
+  ##
+  # Class that makes it possible to easily use multiple public directories in
+  # your Ramaze application.
+  #
+  # @author Michael Fellinger
+  # @since  14-03-2009
+  #
   class Files
+    ##
+    # Creates a new instance of the class, stores the given root directories and
+    # syncs the changes with Rack::Cascade.
+    #
+    # @author Michael Fellinger
+    # @since  14-03-2009
+    # @param  [Array] *roots A set of root directories that contain a number of
+    #  public directories.
+    #
     def initialize(*roots)
       @roots = roots.flatten.map{|root| File.expand_path(root.to_s) }
       sync
     end
 
+    ##
+    # Allows this class to be called as a Rack middleware.
+    #
+    # @author Michael Fellinger
+    # @since  14-03-2009
+    # @param  [Hash] env Hash containing all the environment details.
+    #
     def call(env)
       @cascade.call(env)
     end
 
+    ##
+    # Adds a new path to the list of root directories.
+    #
+    # @author Michael Fellinger
+    # @since  14-03-2009
+    # @param  [String] path The path to add to the existing root directories.
+    #
     def <<(path)
       @roots << File.expand_path(path.to_s)
       @roots.uniq!
       sync
     end
 
+    ##
+    # Syncs the class with Rack::Cascade.
+    #
+    # @author Michael Fellinger
+    # @since  14-03-2009
+    #
     def sync
       file_apps = @roots.map{|root| Rack::File.new(root) }
       @cascade = Rack::Cascade.new(file_apps)
     end
-  end
-end
+  end # Files
+end # Ramaze

data/lib/ramaze/gestalt.rb

@@ -2,13 +2,11 @@
 # All files in this distribution are subject to the terms of the Ruby license.
 
 module Ramaze
-
   ##
   # Gestalt is the custom HTML/XML builder for Ramaze, based on a very simple
   # DSL it will build your markup.
   #
   # @example
-  #
   #   html =
   #     Gestalt.build do
   #       html do
@@ -28,7 +26,7 @@ module Ramaze
     # The default way to start building your markup.
     # Takes a block and returns the markup.
     #
-    # @param [Block] block 
+    # @param [Block] block
     #
     def self.build(&block)
       self.new(&block).to_s
@@ -62,17 +60,19 @@ module Ramaze
     ##
     # Workaround for Kernel#p to make <p /> tags possible.
     #
-    # @param [Hash] args Extra arguments that should be processed before creating the paragraph tag.
+    # @param [Hash] args Extra arguments that should be processed before
+    #  creating the paragraph tag.
     # @param [Block] block
     #
     def p(*args, &block)
       _gestalt_call_tag :p, args, &block
     end
-    
+
     ##
     # Workaround for Kernel#select to make <select></select> work.
     #
-    # @param [Hash] args Extra arguments that should be processed before creating the select tag.
+    # @param [Hash] args Extra arguments that should be processed before
+    #  creating the select tag.
     # @param [Block] block
     #
     def select(*args, &block)
@@ -80,7 +80,7 @@ module Ramaze
     end
 
     ##
-    # TODO: Describe this method, I'm not exactly sure what it does - Yorick
+    # Calls a particular tag based on the specified parameters.
     #
     # @param [String] name
     # @param [Hash] args
@@ -103,8 +103,6 @@ module Ramaze
     # Build a tag for `name`, using `args` and an optional block that
     # will be yielded.
     #
-    # TODO: Describe this method since I'm not exactly sure what it does - Yorick
-    #
     # @param [String] name
     # @param [Hash] attr
     # @param [Hash] text
@@ -139,7 +137,7 @@ module Ramaze
     end
 
     ##
-    # TODO: Describe this method since I'm not exactly sure what it does - Yorick
+    # Shortcut for building tags,
     #
     # @param [String] name
     # @param [Hash] args
@@ -153,9 +151,11 @@ module Ramaze
     # Convert the final output of Gestalt to a string.
     # This method has the following alias: "to_str".
     #
+    # @return [String]
+    #
     def to_s
       @out.join
     end
     alias to_str to_s
-  end
-end
+  end # Gestalt
+end # Ramaze

data/lib/ramaze/helper.rb

@@ -1,9 +1,7 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
 # All files in this distribution are subject to the terms of the Ruby license.
-
 require 'innate/helper'
 
-# TODO: Describe what this module does besides loading a few default helper.
 module Ramaze
   Helper = Innate::Helper
   Innate::HelpersHelper.options.paths << File.dirname(__FILE__)

data/lib/ramaze/helper/auth.rb

@@ -3,39 +3,42 @@
 
 module Ramaze
   module Helper
-
-    # A simple way to do authentication without a model.
-    # Please have a look at the docs of Auth#auth_login.
-    #
-    # If you want to do authentication with a model see Helper::User instead.
-    
     ##
     # The Auth helper can be used for authentication without using a model.
-    # This can be useful when working with very basic applications that don't require database access.
+    # This can be useful when working with very basic applications that don't
+    # require database access.
     #
-    # If you're looking for a way to do authentication using a model you should take a look at Helper::User instead.
+    # If you're looking for a way to do authentication using a model you should
+    # take a look at Helper::User instead.
     #
     module Auth
       Helper::LOOKUP << self
       include Ramaze::Traited
 
-      trait :auth_table => {}
-      trait :auth_hashify => lambda{|pass| Digest::SHA1.hexdigest(pass) }
+      trait :auth_table     => {}
+      trait :auth_hashify   => lambda { |pass| Digest::SHA1.hexdigest(pass) }
       trait :auth_post_only => false
 
       def self.included(into)
         into.helper(:stack)
       end
-      
+
       ##
-      # Log a user in based on the :username and :password key in the request hash.
+      # Log a user in based on the :username and :password key in the request
+      # hash.
       #
-      # @return [String] The login template in case the user's login data was incorrect.
+      # @return [String] The login template in case the user's login data was
+      #  incorrect.
       #
       def login
-        return auth_template if trait[:auth_post_only] and !request.post?
+        if trait[:auth_post_only] and !request.post?
+          return auth_template
+        end
+
         @username, password = request[:username, :password]
+
         answer(request.referer) if auth_login(@username, password)
+
         return auth_template
       end
 
@@ -44,20 +47,22 @@ module Ramaze
       #
       def logout
         auth_logout
-        answer(request.referer)
+        redirect_referrer
       end
 
       private
 
       ##
-      # Validate the user's session and redirect him/her to the login page in case the user isn't logged in.
+      # Validate the user's session and redirect him/her to the login page in
+      # case the user isn't logged in.
       #
       def login_required
         call(r(:login)) unless logged_in?
       end
 
       ##
-      # Validate the user's session and return a boolean that indicates if the user is logged in or not.
+      # Validate the user's session and return a boolean that indicates if the
+      # user is logged in or not.
       #
       # @return [true false] Whether user is logged in right now
       #
@@ -67,7 +72,8 @@ module Ramaze
 
       ##
       # Try to log the user in based on the username and password.
-      # This method is called by the login() method and shouldn't be called directly.
+      # This method is called by the login() method and shouldn't be called
+      # directly.
       #
       # @param [String] user The users's username.
       # @param [String] pass The user's password.
@@ -75,7 +81,8 @@ module Ramaze
       def auth_login(user, pass)
         return unless user and pass
         return if user.empty? or pass.empty?
-        return unless table = ancestral_trait[:auth_table]
+
+        return unless table   = ancestral_trait[:auth_table]
         return unless hashify = ancestral_trait[:auth_hashify]
 
         if table.respond_to?(:to_sym) or table.respond_to?(:to_str)
@@ -87,7 +94,7 @@ module Ramaze
         return unless table[user] == hashify.call(pass)
 
         session[:logged_in] = true
-        session[:username] = user
+        session[:username]  = user
       end
 
       ##
@@ -113,6 +120,6 @@ module Ramaze
 </form>
         TEMPLATE
       end
-    end
-  end
-end
+    end # Auth
+  end # Helper
+end # Ramaze