ramaze 2011.07.25 → 2011.10.23

data/lib/ramaze/helper/user.rb

@@ -9,7 +9,6 @@ module Ramaze
     # request.env, usually this will involve a request to your database.
     #
     # @example Basic usage with User::authenticate
-    #
     #   # We assume that User::[] will make a query and returns the requested
     #   # User instance. This instance will be wrapped and cached.
     #
@@ -50,7 +49,6 @@ module Ramaze
     # You can however, add your own caching quite easily.
     #
     # @example caching the authentication lookup with memcached
-    #
     #   # Add the name of the cache you are going to use for the authentication
     #   # and set all caches to use memcached
     #
@@ -76,7 +74,6 @@ module Ramaze
     #   end
     #
     # @example Using a lambda instead of User::authenticate
-    #
     #   # assumes all your controllers inherit from this one
     #
     #   class Controller < Ramaze::Controller
@@ -86,7 +83,6 @@ module Ramaze
     #   end
     #
     # @example Using a different model instead of User
-    #
     #   # assumes all your controllers inherit from this one
     #
     #   class Controller < Ramaze::Controller
@@ -94,7 +90,7 @@ module Ramaze
     #   end
     #
     # @author manveru
-    # 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
@@ -103,7 +99,7 @@ module Ramaze
       # Use this method in your application, but do not use it in conditionals
       # as it will never be nil or false.
       #
-      # @return [Ramaze::Helper::User::Wrapper] wrapped return value from 
+      # @return [Ramaze::Helper::User::Wrapper] wrapped return value from
       #  model or callback
       #
       # @api external
@@ -122,7 +118,7 @@ module Ramaze
       ##
       # shortcut for user._login but default argument are request.params
       #
-      # @param [Hash] creds the credentials that will be passed to callback or 
+      # @param [Hash] creds the credentials that will be passed to callback or
       #  model
       # @return [nil Hash] the given creds are returned on successful login
       #
@@ -178,7 +174,7 @@ module Ramaze
         end
 
         ##
-        # @param [Hash] creds this hash will be stored in the session on 
+        # @param [Hash] creds this hash will be stored in the session on
         #  successful login
         # @return [Ramaze::Helper::User::Wrapper] wrapped return value from
         #  model or callback

data/lib/ramaze/helper/xhtml.rb

@@ -6,7 +6,7 @@ module Ramaze
     # 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'
+    #     css 'reset', 'screen', :only => 'ie'
     #
     # This would result in a stylesheet named "reset.css" being loaded only when
     # the user is using Internet Explorer.
@@ -24,10 +24,9 @@ module Ramaze
       # @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 
+      # @param [Hash] options A hash containing additional options for the
       #  stylesheet tag.
       # @example
-      #
       #   # A very basic example.
       #   css 'reset'
       #
@@ -50,7 +49,7 @@ module Ramaze
           else
             prefix = options[:prefix] || 'css'
             LINK_TAG % [
-              "#{Ramaze.options.prefix.chomp("/")}/#{prefix}/#{name}.css", 
+              "#{Ramaze.options.prefix.chomp("/")}/#{prefix}/#{name}.css",
               media
             ]
           end
@@ -63,7 +62,6 @@ module Ramaze
       # again.
       #
       # @example
-      # 
       #   # This is pretty basic
       #   css_for 'reset', '960', 'style'
       #
@@ -71,8 +69,8 @@ module Ramaze
       #   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 
+      # @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]
       #
@@ -81,24 +79,23 @@ module Ramaze
       end
 
       ##
-      # Generates a Javascript tag that loads an external Javascript file. This 
+      # 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 
+      # @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]
-      # 
+      #
       def js(name, options={})
         if name =~ /^http/ # consider it external full url
           SCRIPT_TAG % name
@@ -106,21 +103,20 @@ module Ramaze
           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
     end # XHTML
-  end # Helper 
+  end # Helper
 end # Ramaze

data/lib/ramaze/log.rb

@@ -21,11 +21,14 @@ module Ramaze
   # @since  11-08-2009
   #
   module Logger
-    autoload :Analogger, 'ramaze/log/analogger'
-    autoload :Knotify,   "ramaze/log/knotify"
-    autoload :Syslog,    "ramaze/log/syslog"
-    autoload :Growl,     "ramaze/log/growl"
-    autoload :Xosd,      "ramaze/log/xosd"
-    autoload :Logger,    "ramaze/log/logger"
+    autoload :Analogger       , 'ramaze/log/analogger'
+    autoload :Growl           , 'ramaze/log/growl'
+    autoload :LogHub          , 'ramaze/log/hub'
+    autoload :Knotify         , 'ramaze/log/knotify'
+    autoload :RotatingInformer, 'ramaze/log/rotatinginformer'
+    autoload :Syslog          , 'ramaze/log/syslog'
+    autoload :Growl           , 'ramaze/log/growl'
+    autoload :Xosd            , 'ramaze/log/xosd'
+    autoload :Logger          , 'ramaze/log/logger'
   end
 end

data/lib/ramaze/log/rotatinginformer.rb

@@ -1,10 +1,45 @@
 module Ramaze
-
   module Logger
-
     ##
-    # A customized logger (based on Informer) that creates multiple log files
-    # based on current date.
+    # A logger that rotates log files based on the current date. Log files are
+    # named after the date on which they were created. If the date changes a new
+    # log file is used.
+    #
+    # In order to use this logger you'll have to specify a base directory for
+    # all log files. This directory will not be created for you so make sure it
+    # exists. Loading the class can be done as following:
+    #
+    #     logger = Ramaze::Logger::RotatingInformer.new('./log')
+    #
+    # This creates a new instance that uses the directory ``./log`` for all it's
+    # log files.
+    #
+    # The default log format is ``%Y-%m-%d.log``. If you want to change this you
+    # can specify an alternative format (including the extension) as the
+    # secondary parameter of the ``.new()`` method:
+    #
+    #     logger = Ramaze::Logger::RotatingInformer.new('./log', '%d-%m-%Y.log')
+    #
+    # In this case the instance will use the date format ``dd-mm-yyyy`` along
+    # with the ``.log`` extension.
+    #
+    # Besides the date format you can also customize the timestamp format as
+    # well as the format of each logged messages. Both these are set in a trait.
+    # The timestamp format is located in the trait ``:timestamp`` while the
+    # message format is stored in the ``:format`` trait. These can be set as
+    # following:
+    #
+    #     logger = Ramaze::Logger::RotatingInformer.new('./log')
+    #
+    #     logger.trait[:timestamp] = '...'
+    #     logger.trait[:format]    = '...'
+    #
+    # When setting the ``:format`` trait you can use 3 tags that will be
+    # replaced by their corresponding values. These are the following tags:
+    #
+    # * ``%time``: will be replaced by the current time.
+    # * ``%prefix``: the log level such as "ERROR" or "INFO".
+    # * ``%text``: the actual log message.
     #
     class RotatingInformer
       include Innate::Traited
@@ -24,16 +59,14 @@ module Ramaze
       #
       # base_dir is the directory where all log files will be stored
       #
-      # time_format is the time format used to name the log files.
-      # Possible formats are identical to those
-      # accepted by Time.strftime
+      # time_format is the time format used to name the log files. Possible
+      # formats are identical to those accepted by Time.strftime
       #
-      # log_levelse is an array describing what kind of messages
-      # that the log receives. The array may contain
-      # any or all of the symbols :debug, :error, :info and/or :warn
+      # log_levelse is an array describing what kind of messages that the log
+      # receives. The array may contain any or all of the symbols :debug,
+      # :error, :info and/or :warn
       #
       # @example
-      #
       #   # Creates logs in directory called logs. The generated filenames
       #   # will be in the form YYYY-MM-DD.log
       #   RotatingInformer.new('logs')
@@ -57,7 +90,7 @@ module Ramaze
         send :base_dir=, base_dir, true
 
         @time_format = time_format
-        @log_levels = log_levels
+        @log_levels  = log_levels
 
         # Keep track of log shutdown (to prevent StackErrors due to recursion)
         @in_shutdown = false
@@ -66,13 +99,12 @@ module Ramaze
       ##
       # Set the base directory for log files
       #
-      # If this method is called with the raise_exception
-      # parameter set to true the method will raise an exception
-      # if the specified directory does not exist or is unwritable.
+      # If this method is called with the raise_exception parameter set to true
+      # the method will raise an exception if the specified directory does not
+      # exist or is unwritable.
       #
-      # If raise_exception is set to false, the method will just
-      # silently fail if the specified directory does not exist
-      # or is unwritable.
+      # If raise_exception is set to false, the method will just silently fail
+      # if the specified directory does not exist or is unwritable.
       #
       # @param [String] directory The base directory specified by the developer.
       # @param [Bool] raise_exception Boolean that indicates if an exception
@@ -119,7 +151,7 @@ module Ramaze
       # @param [String] tag The type of message we're logging.
       # @param [Array] messages An array of messages to log.
       #
-      def log tag, *messages
+      def log(tag, *messages)
         return unless @log_levels.include?(tag)
 
         # Update current log
@@ -144,7 +176,7 @@ module Ramaze
       # @param [String] text
       # @param [Integer] time
       #
-      def log_interpolate prefix, text, time = timestamp
+      def log_interpolate(prefix, text, time = timestamp)
         message = class_trait[:format].dup
 
         vars = { '%time' => time, '%prefix' => prefix, '%text' => text }
@@ -155,8 +187,9 @@ module Ramaze
 
       ##
       # This uses timestamp trait or a date in the format of
-      #   %Y-%m-%d %H:%M:%S
-      #   # => "2007-01-19 21:09:32"
+      # ``%Y-%m-%d %H:%M:%S``
+      #
+      # @return [String]
       #
       def timestamp
         mask = class_trait[:timestamp]
@@ -164,7 +197,9 @@ module Ramaze
       end
 
       ##
-      # Is @out closed?
+      # Is ``@out`` closed?
+      #
+      # @return [TrueClass|FalseClass]
       #
       def closed?
         @out.respond_to?(:closed?) && @out.closed?
@@ -176,19 +211,19 @@ module Ramaze
       # @author Yorick Peterse
       # @param  [String] message The data that has to be logged.
       #
-      def write message
+      def write(message)
         log(:info, message)
       end
 
       private
 
       ##
-      # Checks whether current filename is still valid.
-      # If not, update the current log to point at the new
-      # filename
+      # Checks whether current filename is still valid. If not, update the
+      # current log to point at the new filename.
       #
       def update_current_log
         out = File.join(@base_dir, Time.now.strftime(@time_format))
+
         if @out.nil? || @out.path != out
           # Close old log if necessary
           shutdown unless @out.nil? || closed?

data/lib/ramaze/log/syslog.rb

@@ -4,14 +4,6 @@
 
 require 'syslog'
 
-# Add aliases for the levelnames used by Ramaze logging
-module Syslog
-  alias dev debug
-  alias warn warning
-  alias error err
-  module_function :dev, :warn, :error 
-end
-
 module Ramaze
   module Logger
     ##
@@ -21,19 +13,25 @@ module Ramaze
     class Syslog
       include Logging
 
+      # Hash containing various method aliases. Rbx and Jruby don't seem to like
+      # the combination of alias() and module_function() so this works around
+      # that.
+      ALIASES = {:dev => :debug, :warn => :warning, :error => :err}
+
       ##
       # Open the syslog library, if it is allready open, we reopen it using the
-      # new argument list.  The argument list is passed on to the Syslog library
-      # so please check that, and man syslog for detailed information.  
+      # new argument list. The argument list is passed on to the Syslog library
+      # so please check that, and man syslog for detailed information.
+      #
       # There are 3 parameters:
       #
-      #   ident:  The identification used in the log file, defaults to $0
-      #   options:  defaults to  Syslog::LOG_PID | Syslog::LOG_CONS
-      #   facility: defaults to Syslog::LOG_USER
+      # * ident:  The identification used in the log file, defaults to $0
+      # * options:  defaults to  Syslog::LOG_PID | Syslog::LOG_CONS
+      # * facility: defaults to Syslog::LOG_USER
       #
-      def initialize( *args )
+      def initialize(*args)
         ::Syslog.close if ::Syslog.opened?
-        ::Syslog.open( *args )
+        ::Syslog.open(*args)
       end
 
       ##
@@ -41,8 +39,15 @@ module Ramaze
       # We simply return if the log was closed for some reason, this behavior
       # was copied from Informer.  We do not handle levels here. This will
       # be done by te syslog daemon based on it's configuration.
+      #
       def log(tag, *messages)
         return if !::Syslog.opened?
+        tag = tag.to_sym
+
+        if ALIASES.key?(tag)
+          tag = ALIASES[tag]
+        end
+
         ::Syslog.send(tag, *messages)
       end
 

data/lib/ramaze/log/xosd.rb

@@ -11,7 +11,8 @@ module Ramaze
     # Informer for the XOSD notification system for X11.
     #
     # You can install the ruby-bindings with:
-    #   gem install xosd.
+    #
+    #     gem install xosd.
     #
     class Xosd < ::Xosd
       attr_accessor :options

data/lib/ramaze/reloader.rb

@@ -2,6 +2,7 @@
 # All files in this distribution are subject to the terms of the Ruby license.
 
 module Ramaze
+  ##
   # High performant source reloader
   #
   # This class acts as Rack middleware.
@@ -24,6 +25,7 @@ module Ramaze
   #
   # A number of hooks will be executed during the reload cycle, see
   # Ramaze::ReloaderHooks for more information.
+  #
   class Reloader
     OPTIONS = {
       # At most check every n seconds

data/lib/ramaze/request.rb

@@ -19,11 +19,13 @@ module Ramaze
     # Sets any arguments passed as @instance_variables for the current action.
     #
     # Usage:
-    #   request.params # => {'name' => 'manveru', 'q' => 'google', 'lang' => 'de'}
-    #   request.to_ivs(:name, :q)
-    #   @q    # => 'google'
-    #   @name # => 'manveru'
-    #   @lang # => nil
+    #
+    #     request.params # => {'name' => 'manveru', 'q' => 'google', 'lang' => 'de'}
+    #     request.to_ivs(:name, :q)
+    #
+    #     @q    # => 'google'
+    #     @name # => 'manveru'
+    #     @lang # => nil
     #
     def to_instance_variables(*args)
       instance = Current.action.instance
@@ -49,8 +51,7 @@ module Ramaze
     #
     # Usage:
     #
-    #   request.accept_language
-    #   # => ['en-us', 'en', 'de-at', 'de']
+    #     request.accept_language # => ['en-us', 'en', 'de-at', 'de']
     #
     # @param [String #to_s] string the value of HTTP_ACCEPT_LANGUAGE
     # @return [Array] list of locales
@@ -67,14 +68,14 @@ module Ramaze
     ##
     # Transform the HTTP_ACCEPT_LANGUAGE header into an Array with:
     #
-    #   [[lang, weight], [lang, weight], ...]
+    #     [[lang, weight], [lang, weight], ...]
     #
     # This algorithm was taken and improved from the locales library.
     #
     # Usage:
     #
-    #   request.accept_language_with_weight
-    #   # => [["en-us", 1.0], ["en", 0.8], ["de-at", 0.5], ["de", 0.3]]
+    #     request.accept_language_with_weight
+    #     # => [["en-us", 1.0], ["en", 0.8], ["de-at", 0.5], ["de", 0.3]]
     #
     # @param [String #to_s] string the value of HTTP_ACCEPT_LANGUAGE
     # @return [Array] array of [lang, weight] arrays