ramaze 2011.01.30 → 2011.07.25

data/lib/ramaze/log.rb

@@ -1,6 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
 # All files in this distribution are subject to the terms of the Ruby license.
-
 require 'ramaze/log/logging'
 require 'ramaze/log/informer'
 
@@ -16,17 +15,10 @@ 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:
+  # Module used as the base namespace for all loggers that ship with Ramaze.
   #
-  #   * Analogger
-  #   * Knotify
-  #   * Syslog
-  #   * Growl
-  #   * Xosd
-  #   * Logger
-  #   * Informer
-  #   * RotatingInformer
+  # @author Michael Fellinger
+  # @since  11-08-2009
   #
   module Logger
     autoload :Analogger, 'ramaze/log/analogger'

data/lib/ramaze/log/analogger.rb

@@ -31,7 +31,8 @@ module Ramaze
       # @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])
+      def initialize(name = class_trait[:name], host = class_trait[:host], 
+      port = class_trait[:port])
         super
       end
 
@@ -44,6 +45,6 @@ module Ramaze
       def log(tag, *args)
         super(tag, args.join("\n"))
       end
-    end
-  end
-end
+    end # Analogger
+  end # Log
+end # Ramaze

data/lib/ramaze/log/growl.rb

@@ -5,7 +5,6 @@ require 'ruby-growl'
 
 module Ramaze
   module Logger
-
     ##
     # Informer for the Growl notification system
     # Growl lets Mac OS X applications unintrusively tell you when things happen.
@@ -27,10 +26,14 @@ module Ramaze
       ##
       # Takes the options from the default trait for merging.
       #
-      # @param [Hash] options A hash containing extra options to use when initializing the Growl logger.
+      # @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)
+        options = class_trait[:defaults].merge(options).values_at(
+          :host, :name, :all_notifies, :default_notifies, :password
+        )
+        
         super(*options)
       end
 
@@ -47,7 +50,6 @@ module Ramaze
           # Send size was to big (not really), ignore
         end
       end
-    end
-
-  end
-end
+    end # Growl
+  end # Logger
+end # Ramaze

data/lib/ramaze/log/hub.rb

@@ -3,7 +3,6 @@
 
 module Ramaze
   module Logger
-
     ##
     # Bundles different informer instances and sends incoming messages to each.
     # This is the default with Informer as only member.
@@ -43,7 +42,6 @@ module Ramaze
           logger.log(tag, *args)
         end
       end
-    end
-
-  end
-end
+    end # Hub
+  end # log
+end # Ramaze

data/lib/ramaze/log/informer.rb

@@ -37,15 +37,19 @@ module Ramaze
       #
       # @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.
+      #   Informer.new          # => logs to stdout with all levels being shown.
+      #   Informer.new($stderr) # => same, but to stderr
       #
-      # @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.
+      #   # same, but logs to the file foo.log (or creates it if it doesn't 
+      #   # exist yet)
+      #   Informer.new("foo.log")
+      #
+      #   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
@@ -140,7 +144,6 @@ module Ramaze
       def closed?
         @out.respond_to?(:closed?) and @out.closed?
       end
-    end
-
-  end
-end
+    end # Informer
+  end # Log
+end # Ramaze

data/lib/ramaze/log/knotify.rb

@@ -3,7 +3,6 @@
 
 module Ramaze
   module Logger
-
     ##
     # Informer for the Knotify notfication system used on KDE.
     # Doesn't need any special libraries.
@@ -27,7 +26,6 @@ module Ramaze
           system(%{dcop knotify default notify Ramaze "#{tag}" "#{message}" '' '' #{present} 0})
         end
       end
-    end
-
-  end
-end
+    end # Knotify
+  end # Logger
+end # Ramaze

data/lib/ramaze/log/logger.rb

@@ -5,7 +5,6 @@ require 'logger'
 
 module Ramaze
   module Logger
-
     ##
     # Informer for the Stdlib Logger.
     #
@@ -28,7 +27,6 @@ module Ramaze
       def dev(*args)
         debug(*args)
       end
-    end
-
-  end
-end
+    end # Logger
+  end # Logger
+end # Ramaze

data/lib/ramaze/log/logging.rb

@@ -2,12 +2,10 @@
 # All files in this distribution are subject to the terms of the Ruby license.
 
 module Ramaze
-
   ##
   # This module provides a basic skeleton for your own loggers to be compatible.
   # 
   # @example
-  #
   #   class MyLogger
   #     include Logging
   #
@@ -17,7 +15,6 @@ module Ramaze
   #   end
   #
   module Logging
-
     ##
     # Takes the tag (:warn|:debug|:error|:info) and the name of a method to be
     # called upon elements of msgs that don't respond to :to_str
@@ -38,7 +35,8 @@ module Ramaze
     ##
     # Converts everything given to strings and passes them on with :info
     #
-    # @param [Array] objects An array of objects that need to be converted to strings.
+    # @param [Array] objects An array of objects that need to be converted to 
+    #  strings.
     #
     def info(*objects)
       tag_log(:info, :to_s, *objects)
@@ -47,7 +45,8 @@ module Ramaze
     ##
     # Converts everything given to strings and passes them on with :warn
     #
-    # @param [Array] objects An array of objects that need to be converted to strings.
+    # @param [Array] objects An array of objects that need to be converted to 
+    #  strings.
     #
     def warn(*objects)
       tag_log(:warn, :to_s, *objects)
@@ -104,6 +103,5 @@ module Ramaze
     def debug?
       false
     end
-  end
-
-end
+  end # Logging
+end # Ramaze

data/lib/ramaze/log/rotatinginformer.rb

@@ -3,9 +3,8 @@ module Ramaze
   module Logger
 
     ##
-    # A customized logger (based on Informer) that creates multiple log files based on time
-    #
-    # TODO: This class isn't fully documented and could use a few improvements.
+    # A customized logger (based on Informer) that creates multiple log files
+    # based on current date.
     #
     class RotatingInformer
       include Innate::Traited
@@ -19,7 +18,7 @@ module Ramaze
 
       # This is how the final output is arranged.
       trait :format => "[%time] %prefix  %text"
-      
+
       ##
       # Create a new instance of RotatingInformer.
       #
@@ -34,16 +33,17 @@ module Ramaze
       # 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
+      #
+      #   # Creates logs in directory called logs. The generated filenames
+      #   # will be in the form YYYY-MM-DD.log
       #   RotatingInformer.new('logs')
       #
-      #   
-      #   # Creates logs in directory called logs. The generated filenames will be in the form YYYY-MM.txt
+      #   # Creates logs in directory called logs. The generated filenames
+      #   # will be in the form YYYY-MM.txt
       #   RotatingInformer.new('logs', '%Y-%m.txt')
-      #                                   
       #
-      #   # Creates logs in directory called logs. The generated filenames will be in the form YYYY-MM.txt. 
+      #   # Creates logs in directory called logs. The generated filenames
+      #   # will be in the form YYYY-MM.txt.
       #   # Only errors will be logged to the files.
       #   RotatingInformer.new('logs', '%Y-%m.txt', [:error])
       #
@@ -51,7 +51,8 @@ module Ramaze
       # @param [String] time_format The time format for all log files.
       # @param [Array] log_levels Array containing the type of messages to log.
       #
-      def initialize(base_dir, time_format = '%Y-%m-%d.log', log_levels = [:debug, :error, :info, :warn])
+      def initialize(base_dir, time_format = '%Y-%m-%d.log',
+      log_levels = [:debug, :error, :info, :warn])
         # Verify and set base directory
         send :base_dir=, base_dir, true
 
@@ -74,7 +75,8 @@ module Ramaze
       # or is unwritable.
       #
       # @param [String] directory The base directory specified by the developer.
-      # @param [Bool] raise_exception Boolean that indicates if an exception should be raised if the base directory doesn't exist.
+      # @param [Bool] raise_exception Boolean that indicates if an exception
+      #  should be raised if the base directory doesn't exist.
       #
       def base_dir=(directory, raise_exception = false)
         # Expand directory path
@@ -118,7 +120,6 @@ module Ramaze
       # @param [Array] messages An array of messages to log.
       #
       def log tag, *messages
-
         return unless @log_levels.include?(tag)
 
         # Update current log
@@ -169,6 +170,16 @@ module Ramaze
         @out.respond_to?(:closed?) && @out.closed?
       end
 
+      ##
+      # Method that is called by Rack::CommonLogger when logging data to a file.
+      #
+      # @author Yorick Peterse
+      # @param  [String] message The data that has to be logged.
+      #
+      def write message
+        log(:info, message)
+      end
+
       private
 
       ##
@@ -186,7 +197,6 @@ module Ramaze
           @out = File.open(out, 'ab+')
         end
       end
-    end
-
-  end
-end
+    end # RotatingInformer
+  end # Log
+end # Ramaze

data/lib/ramaze/log/syslog.rb

@@ -6,10 +6,10 @@ 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 
+  alias dev debug
+  alias warn warning
+  alias error err
+  module_function :dev, :warn, :error 
 end
 
 module Ramaze
@@ -52,6 +52,6 @@ module Ramaze
       def inspect
         ::Syslog.inspect
       end
-    end
-  end
-end
+    end # Syslog
+  end # Logger
+end # Ramaze

data/lib/ramaze/log/xosd.rb

@@ -7,7 +7,6 @@ require 'thread'
 
 module Ramaze
   module Logger
-
     ##
     # Informer for the XOSD notification system for X11.
     #
@@ -89,7 +88,6 @@ module Ramaze
           QUEUE << [tag, message]
         end
       end
-    end
-
-  end
-end
+    end # Xosd
+  end # Logger
+end # Ramaze

data/lib/ramaze/middleware_compiler.rb

@@ -1,13 +1,36 @@
 module Ramaze
+  ##
+  # @author Michael Fellinger
+  # @since  14-03-2009
+  # @see    Innate::MiddelwareCompiler
+  #
   class MiddlewareCompiler < Innate::MiddlewareCompiler
+    ##
+    # Adds the path as a static file.
+    #
+    # @author Michael Fellinger
+    # @since  26-03-2009
+    # @param  [String] path The path to the static file to add.
+    #
     def static(path)
       require 'rack/contrib'
-      Rack::ETag.new(Rack::ConditionalGet.new(Rack::File.new(path)), 'public')
+      Rack::ETag.new(
+        Rack::ConditionalGet.new(Rack::File.new(path)), 'public'
+      )
     end
 
+    ##
+    # Adds the path as a directory.
+    #
+    # @author Michael Fellinger
+    # @since  26-03-2009
+    # @param  [String] path The path to the directory to add.
+    #
     def directory(path)
       require 'rack/contrib'
-      Rack::ETag.new(Rack::ConditionalGet.new(Rack::Directory.new(path)), 'public')
+      Rack::ETag.new(
+        Rack::ConditionalGet.new(Rack::Directory.new(path)), 'public'
+      )
     end
-  end
-end
+  end # MiddlewareCompiler
+end # Ramaze

data/lib/ramaze/reloader.rb

@@ -2,7 +2,6 @@
 # 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.
@@ -25,7 +24,6 @@ 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
@@ -60,6 +58,14 @@ module Ramaze
       Watcher = WatchStat
     end
 
+    ##
+    # Creates a new instance of the class and saves the application it has to
+    # watch.
+    #
+    # @author Michael Fellinger
+    # @since  09-08-2008
+    # @param  [Ramaze::App] app The application to monitor.
+    #
     def initialize(app)
       @app = app
       @files = {}
@@ -67,11 +73,25 @@ module Ramaze
       options_reload
     end
 
+    ##
+    # Returns all the options for this class.
+    #
+    # @author Michael Fellinger
+    # @since  09-08-2008
+    # @return [Array]
+    #
     def options_reload
       @cooldown, @ignore, @control, @thread =
         OPTIONS.values_at(:cooldown, :ignore, :control, :thread)
     end
 
+    ##
+    # Allows this class to be called as a Rack middleware.
+    #
+    # @author Michael Fellinger
+    # @since  09-08-2008
+    # @param  [Hash] env A hash containing all environment details.
+    #
     def call(env)
       options_reload
 
@@ -88,6 +108,12 @@ module Ramaze
       @app.call(env)
     end
 
+    ##
+    # Loops through all the files and reloads all changes files.
+    #
+    # @author Michael Fellinger
+    # @since  09-08-2008
+    #
     def cycle
       before_cycle
 
@@ -97,7 +123,13 @@ module Ramaze
       after_cycle
     end
 
+    ##
     # A safe Kernel::load, issuing the hooks depending on the results
+    #
+    # @author Michael Fellinger
+    # @since  09-08-2008
+    # @param  [String] file Path to the file to safely load.
+    #
     def safe_load(file)
       before_safe_load(file)
       load(file)
@@ -120,6 +152,15 @@ module Ramaze
       end
     end
 
+    ##
+    # Tries to find a given file in an array of file paths.
+    #
+    # @author Michael Fellinger
+    # @since  09-08-2008
+    # @param  [String] file The name of the file to look for.
+    # @param  [Array] paths An array of paths to search.
+    # @return [String]
+    #
     def figure_path(file, paths)
       if Pathname.new(file).absolute?
         return File.exist?(file) ? file : nil
@@ -132,16 +173,13 @@ module Ramaze
       nil
     end
 
-
     # Holds hooks that are called before and after #cycle and #safe_load
     module Hooks
       # Overwrite to add actions before the reload rotation is started.
-      def before_cycle
-      end
+      def before_cycle; end
 
       # Overwrite to add actions after the reload rotation has ended.
-      def after_cycle
-      end
+      def after_cycle; end
 
       # Overwrite to add actions before a file is Kernel::load-ed
       def before_safe_load(file)
@@ -149,7 +187,8 @@ module Ramaze
       end
 
       # Overwrite to add actions after a file is Kernel::load-ed successfully,
-      # by default we clean the Cache for compiled templates and resolved actions.
+      # by default we clean the Cache for compiled templates and resolved
+      # actions.
       def after_safe_load_succeed(file)
         Cache.clear_after_reload
         after_safe_load(file)
@@ -164,9 +203,8 @@ module Ramaze
       def after_safe_load_failed(file, error)
         Log.error(error)
       end
-    end
+    end # Hooks
 
     include Hooks
-
-  end
-end
+  end # Reloader
+end # Ramaze