ramaze 2010.06.18 → 2011.01

data/lib/ramaze/helper/user.rb

@@ -4,7 +4,7 @@ module Ramaze
     # This helper provides a convenience wrapper for handling authentication
     # and persistence of users.
     #
-    # On every request, when you use the {User#user} method for the first time,
+    # On every request, when you use the {UserHelper#user} method for the first time,
     # we confirm the authentication and store the returned object in the
     # request.env, usually this will involve a request to your database.
     #
@@ -94,8 +94,8 @@ module Ramaze
     #   end
     #
     # @author manveru
-    # @todo convert the examples into real examples with specs
-    module User
+    # TODO:  convert the examples into real examples with specs
+    module UserHelper
       # Using this as key in request.env
       RAMAZE_HELPER_USER = 'ramaze.helper.user'.freeze
 
@@ -173,6 +173,7 @@ module Ramaze
         # @author manveru
         def _login(creds = _persistence)
           if @_user = _would_login?(creds)
+            Current.session.resid!
             self._persistence = creds
           end
         end

data/lib/ramaze/helper/xhtml.rb

@@ -2,34 +2,113 @@ module Ramaze
   module Helper
 
     # Provides shortcuts to the link/script tags.
+    ##
+    # The XHTML helper can be used for generating CSS and Javascript tags.
+    # Generating a CSS tag can be done by calling the css() method:
+    #
+    #   css 'reset', 'screen', :only => 'ie'
+    #
+    # This would result in a stylesheet named "reset.css" being loaded only when the user
+    # is using Internet Explorer.
+    #
     module XHTML
       LINK_TAG = '<link href=%p media=%p rel="stylesheet" type="text/css" />'
       SCRIPT_TAG = '<script src=%p type="text/javascript"></script>'
 
+      ##
+      # Generate a CSS tag based on the name, media type and a hash containing
+      # additional options. For example, if we want to load the stylesheet only when the user
+      # is using Internet Explorer we would have to add a key 'only' with a value of 'ie' to the hash.
+      #
+      # @param [String] name The name of the CSS file to load.
+      # @param [String] media The media type for which the stylesheet should be loaded.
+      # @param [Hash] options A hash containing additional options for the stylesheet tag.
+      # @example
+      #
+      #   # A very basic example.
+      #   css 'reset'
+      #
+      #   # Oh shiny, IE only
+      #   css 'reset', 'screen', :only => 'ie'
+      #
+      # @return [String] String containing the stylesheet tag.
+      #
       def css(name, media = 'screen', options = {})
-        if options.empty?
-          if name =~ /^http/ # consider it external full url
+        if media.respond_to?(:keys)
+          options = media
+          media = 'screen'
+        end
+
+        if only = options.delete(:only) and only.to_s == 'ie'
+          "<!--[if IE]>#{css(name, media, options)}<![endif]-->"
+        else
+          if name =~ /^http/
             LINK_TAG % [name, media]
           else
-            LINK_TAG % ["#{Ramaze.options.prefix.chomp("/")}/css/#{name}.css", media]
+            prefix = options[:prefix] || 'css'
+            LINK_TAG % ["#{Ramaze.options.prefix.chomp("/")}/#{prefix}/#{name}.css", media]
           end
-        elsif options[:only].to_s.downcase == 'ie'
-          "<!--[if IE]>#{css(name, media)}<![endif]-->"
         end
       end
 
+      ##
+      # The css_for method can be used when you want to load multiple stylesheets and don't
+      # want to call the css() method over and over again.
+      #
+      # @example
+      # 
+      #   # This is pretty basic
+      #   css_for 'reset', '960', 'style'
+      #
+      #   # Loading multiple stylesheets with custom options
+      #   css_for ['reset', 'print'], ['960', 'print']
+      #
+      # @see css()
+      # @param [Array] args An array containing either the names of all stylesheets to load or a collection of arrays
+      # of which each array defines the name, media and additional parameters.
+      # @return [String]
+      #
       def css_for(*args)
         args.map{|arg| css(*arg) }.join("\n")
       end
 
-      def js(name)
+      ##
+      # Generates a Javascript tag that loads an external Javascript file. This tag can't be used for loading inline
+      # javascript files.
+      #
+      # @example
+      #
+      #   # Simple isn't it?
+      #   js 'jquery'
+      #
+      #   # Let's change the directory to "some_other_directory"
+      #   js 'jquery', :prefix => 'some_other_directory'
+      #
+      # @param [String] name The name of the Javascript file that should be loaded.
+      # @param [Hash] options Hash that can contain a :prefix key that defines the directory in which the JS file
+      # is located. By default this key is set to "js".
+      # @return [String]
+      # TODO:  The js() method 2nd argument is a hash but only supports the :prefix key. Perhaps changing this hash into a string would be better - Yorick
+      # 
+      def js(name, options={})
         if name =~ /^http/ # consider it external full url
           SCRIPT_TAG % name
         else
-          SCRIPT_TAG % "#{Ramaze.options.prefix.chomp("/")}/js/#{name}.js"
+          SCRIPT_TAG % "#{Ramaze.options.prefix.chomp("/")}/#{options[:prefix] || 'js'}/#{name}.js"
         end
       end
-
+      
+      ##
+      # Generate multiple Javascript tags using the js() method.
+      #
+      # @example
+      #
+      #   # Pretty simple isn't it?
+      #   js_for 'jquery', 'application', 'jquery.gritter'
+      #
+      # @param [Array] args Array containing the Javascript files to load.
+      # @return [String]
+      # 
       def js_for(*args)
         args.map{|arg| js(*arg) }.join("\n")
       end

data/lib/ramaze/log.rb

@@ -15,6 +15,19 @@ end
 module Ramaze
   Log = Innate::Log
 
+  ##
+  # Logger module that will autoload a certain logging helper if it's needed.
+  # Ramaze ships with the following logging helpers:
+  #
+  #   * Analogger
+  #   * Knotify
+  #   * Syslog
+  #   * Growl
+  #   * Xosd
+  #   * Logger
+  #   * Informer
+  #   * RotatingInformer
+  #
   module Logger
     autoload :Analogger, 'ramaze/log/analogger'
     autoload :Knotify,   "ramaze/log/knotify"

data/lib/ramaze/log/analogger.rb

@@ -5,12 +5,13 @@ require 'swiftcore/Analogger/Client'
 
 module Ramaze
   module Logger
-
+    
+    ##
     # Informer for the Swiftcore Analogger logging system.
     #
     # You can find it at http://analogger.swiftcore.org and install with
     # gem install analogger
-
+    #
     class Analogger < ::Swiftcore::Analogger::Client
       include Logging
 
@@ -23,14 +24,23 @@ module Ramaze
       # Port analogger runs on
       trait :port => 6766
 
+      ##
       # Create a new instance, parameters default to the traits.
-
+      #
+      # @param [String] name The name of the logging system (can be anything you like).
+      # @param [String] host The IP/hostname on which the logging system is running.
+      # @param [Integer] port The port of the logging system.
+      #
       def initialize(name = class_trait[:name], host = class_trait[:host], port = class_trait[:port])
         super
       end
 
-      # integration to Logging
-
+      ##
+      # Integration to Logging
+      #
+      # @param [String] tag
+      # @param [Hash] args
+      #
       def log(tag, *args)
         super(tag, args.join("\n"))
       end

data/lib/ramaze/log/growl.rb

@@ -6,31 +6,46 @@ require 'ruby-growl'
 module Ramaze
   module Logger
 
-    # Informer for the growl notification system on OSX.
-
+    ##
+    # Informer for the Growl notification system
+    # Growl lets Mac OS X applications unintrusively tell you when things happen.
+    #
+    # Growl can be downloaded from the following website: http://growl.info/
+    #
     class Growl < ::Growl
-
+      include Innate::Traited
+      include Logging
+      
       trait :defaults => {
-        :name => 'walrus',
-        :host => 'localhost',
-        :password => 'walrus',
-        :all_notifies => %w[error warn debug info dev],
+        :name             => 'walrus'   ,
+        :host             => 'localhost',
+        :password         => 'walrus'   ,
+        :all_notifies     => %w[error warn debug info dev],
         :default_notifies => %w[error warn info]
       }
 
+      ##
       # Takes the options from the default trait for merging.
-
+      #
+      # @param [Hash] options A hash containing extra options to use when initializing the Growl logger.
+      #
       def initialize(options = {})
         options = class_trait[:defaults].merge(options).values_at(:host, :name, :all_notifies, :default_notifies, :password)
         super(*options)
       end
 
-      # integration to Logging
-
+      ##
+      # Integration to Logging
+      #
+      # @param [String] tag
+      # @param [Hash] args
+      #
       def log(tag, *args)
-        notify(tag.to_s, Time.now.strftime("%X"), args.join("\n")[0..100])
-      rescue Errno::EMSGSIZE
-        # Send size was to big (not really), ignore
+        begin
+          notify(tag.to_s, Time.now.strftime("%X"), args.join("\n")[0..100])
+        rescue Errno::EMSGSIZE
+          # Send size was to big (not really), ignore
+        end
       end
     end
 

data/lib/ramaze/log/hub.rb

@@ -4,18 +4,22 @@
 module Ramaze
   module Logger
 
+    ##
     # Bundles different informer instances and sends incoming messages to each.
     # This is the default with Informer as only member.
-
+    #
     class LogHub
       include Logging
 
       attr_accessor :loggers
       attr_accessor :ignored_tags
 
+      ##
       # Takes a list of instances or classes (which will be initialized) and that
       # are added to @loggers. All messages are then sent to each member.
-
+      #
+      # @param [Array] loggers
+      #
       def initialize(*loggers)
         @loggers = loggers
         @ignored_tags = Set.new
@@ -27,8 +31,12 @@ module Ramaze
         @loggers.compact!
       end
 
-      # integration to Logging
-
+      ##
+      # Integration to Logging
+      #
+      # @param [String] tag
+      # @param [Hash] args
+      #
       def log(tag, *args)
         return if @ignored_tags.include?(tag)
         @loggers.each do |logger|

data/lib/ramaze/log/informer.rb

@@ -4,9 +4,10 @@
 module Ramaze
   module Logger
 
+    ##
     # A minimal logger for Ramaze, supports files, CLI, colors and some
     # customization.
-
+    #
     class Informer
       include Logging
       include Innate::Traited
@@ -31,17 +32,21 @@ module Ramaze
         :error => :red,
       }
 
+      ##
       # Create a new instance of Informer.
-      # You can spcify
       #
-      # Examples:
+      # @example
+      #
       #   Informer.new                    #=> logs to stdout with all levels being
       #                                       shown.
       #   Informer.new($stderr)           #=> same, but to stderr
       #   Informer.new("foo.log")         #=> same, but logs to the file foo.log
       #                                       (or creates it if it doesn't exist yet)
       #   Informer.new($stdout, [:info])  #=> show only #info messages to stdout.
-
+      #
+      # @param [String] out Specifies where the output should go. By default this is set to STDOUT.
+      # @param [Array] log_leves Array containing the levels that should be logged.
+      #
       def initialize(out = $stdout, log_levels = [:debug, :error, :info, :warn])
         @colorize = false
 
@@ -68,8 +73,9 @@ module Ramaze
         @log_levels = log_levels
       end
 
+      ##
       # Close the file we log to if it isn't closed already.
-
+      #
       def shutdown
         if @out.respond_to?(:close)
           Log.debug("close, #{@out.inspect}")
@@ -77,8 +83,12 @@ module Ramaze
         end
       end
 
-      # Integration to Logging.
-
+      ##
+      # Integration to Logging
+      #
+      # @param [String] tag The log level for the current message(s).
+      # @param [Array] messages Array containing the data that should be logged.
+      #
       def log tag, *messages
         return if closed? || !@log_levels.include?(tag)
         messages.flatten!
@@ -97,9 +107,14 @@ module Ramaze
         @out.flush if @out.respond_to?(:flush)
       end
 
+      ##
       # Takes the prefix (tag), text and timestamp and applies it to
       # the :format trait.
-
+      #
+      # @param [String] prefix
+      # @param [String] text
+      # @param [Integer] time
+      #
       def log_interpolate prefix, text, time = timestamp
         message = class_trait[:format].dup
 
@@ -109,17 +124,19 @@ module Ramaze
         message
       end
 
+      ##
       # This uses timestamp trait or a date in the format of
       #   %Y-%m-%d %H:%M:%S
       #   # => "2007-01-19 21:09:32"
-
+      #
       def timestamp
         mask = class_trait[:timestamp]
         Time.now.strftime(mask || "%Y-%m-%d %H:%M:%S")
       end
 
-      # is @out closed?
-
+      ##
+      # Is @out closed?
+      #
       def closed?
         @out.respond_to?(:closed?) and @out.closed?
       end

data/lib/ramaze/log/knotify.rb

@@ -4,17 +4,22 @@
 module Ramaze
   module Logger
 
+    ##
     # Informer for the Knotify notfication system used on KDE.
     # Doesn't need any special libraries.
-
+    #
     class Knotify
       include Logging
 
       trait :present => 16
 
+      ##
       # Please see for more information on the API used here:
       # http://lukeplant.me.uk/articles.php?id=3
-
+      #
+      # @param [String] tag
+      # @param [Hash] args
+      #
       def log(tag, *messages)
         present = class_trait[:present]
         tag = tag.to_s.capitalize

data/lib/ramaze/log/logger.rb

@@ -6,17 +6,25 @@ require 'logger'
 module Ramaze
   module Logger
 
-    # Informer for the Stdlib Logger
-
+    ##
+    # Informer for the Stdlib Logger.
+    #
     class Logger < ::Logger
 
-      # integration to Logging
-
+      ##
+      # Integration to Logging
+      #
+      # @param [String] tag
+      # @param [Hash] args
+      #
       def log(tag, *args)
         __send__(tag, args.join("\n"))
       end
 
+      ##
       # Stub for compatibility
+      #
+      # @param [Hash] args
       def dev(*args)
         debug(*args)
       end