ramaze 2010.06.18 → 2011.01

data/lib/ramaze/log/logging.rb

@@ -3,8 +3,10 @@
 
 module Ramaze
 
+  ##
   # This module provides a basic skeleton for your own loggers to be compatible.
-  # The minimal usage is like this:
+  # 
+  # @example
   #
   #   class MyLogger
   #     include Logging
@@ -13,14 +15,19 @@ module Ramaze
   #       p tag => args
   #     end
   #   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
     # Goes on and sends the tag and transformed messages each to the #log method.
     # If you include this module you have to define #log or it will raise.
-
+    #
+    # @param [String] tag The level of the log message.
+    # @param [String] method 
+    # @param [Array] msgs The data that should be logged.
+    #
     def tag_log(tag, meth, *msgs)
       msgs.each do |msg|
         string = (msg.respond_to?(:to_str) ? msg : msg.send(meth))
@@ -28,35 +35,50 @@ module Ramaze
       end
     end
 
+    ##
     # 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.
+    #
     def info(*objects)
       tag_log(:info, :to_s, *objects)
     end
 
+    ##
     # 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.
+    #
     def warn(*objects)
       tag_log(:warn, :to_s, *objects)
     end
 
-    # inspects objects if they are no strings. Tag is :debug
-
+    ##
+    # Inspects objects if they are no strings. Tag is :debug
+    #
+    # @param [Array] objects An array of objects that will be inspected.
+    #
     def debug(*objects)
       tag_log(:debug, :inspect, *objects)
     end
 
-    # inspects objects if they are no strings. Tag is :dev
-
+    ##
+    # Inspects objects if they are no strings. Tag is :dev
+    #
+    # @param [Array] objects An array of objects that will be inspected.
+    #
     def dev(*objects)
       tag_log(:dev, :inspect, *objects)
     end
 
     alias << debug
 
+    ##
     # Takes either an Exception or just a String, formats backtraces to be a bit
     # more readable and passes all of this on to tag_log :error
-
+    #
+    # @param [Object] ex The exception that was raised.
+    #
     def error(ex)
       if ex.respond_to?(:exception)
         message = ex.backtrace
@@ -68,13 +90,17 @@ module Ramaze
       tag_log(:error, :to_s, *message)
     end
 
-    # nothing
-
+    ##
+    # Nothing.
+    #
+    # THINK: Is this really required? It doesn't do anything anyway.
+    #
     def shutdown
     end
 
-    # stub for WEBrick
-
+    ##
+    # Stub for WEBrick
+    #
     def debug?
       false
     end

data/lib/ramaze/log/rotatinginformer.rb

@@ -2,8 +2,11 @@ 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.
+    #
     class RotatingInformer
       include Innate::Traited
       include Logging
@@ -16,7 +19,8 @@ module Ramaze
 
       # This is how the final output is arranged.
       trait :format => "[%time] %prefix  %text"
-
+      
+      ##
       # Create a new instance of RotatingInformer.
       #
       # base_dir is the directory where all log files will be stored
@@ -29,21 +33,24 @@ module Ramaze
       # that the log receives. The array may contain
       # any or all of the symbols :debug, :error, :info and/or :warn
       #
-      # Examples:
+      # @example
+      #   
+      #   # 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-DD.log
+      #
+      #   
+      #   # 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])
-      #                                   #=> 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.
-
+      #
+      # @param [String] base_dir The base directory for all the log files.
+      # @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])
         # Verify and set base directory
         send :base_dir=, base_dir, true
@@ -55,6 +62,7 @@ module Ramaze
         @in_shutdown = false
       end
 
+      ##
       # Set the base directory for log files
       #
       # If this method is called with the raise_exception
@@ -63,8 +71,11 @@ module Ramaze
       #
       # If raise_exception is set to false, the method will just
       # silently fail if the specified directory does not exist
-      # or is unwritable
-
+      # 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.
+      #
       def base_dir=(directory, raise_exception = false)
         # Expand directory path
         base_dir = File.expand_path(directory)
@@ -86,8 +97,9 @@ module Ramaze
         end
       end
 
+      ##
       # Close the file we log to if it isn't closed already.
-
+      #
       def shutdown
         if @out.respond_to?(:close)
           unless @in_shutdown
@@ -99,8 +111,12 @@ module Ramaze
         end
       end
 
+      ##
       # Integration to Logging.
-
+      #
+      # @param [String] tag The type of message we're logging.
+      # @param [Array] messages An array of messages to log.
+      #
       def log tag, *messages
 
         return unless @log_levels.include?(tag)
@@ -119,9 +135,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
 
@@ -131,27 +152,30 @@ 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?) && @out.closed?
       end
 
       private
 
+      ##
       # 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

data/lib/ramaze/log/syslog.rb

@@ -13,39 +13,45 @@ module Syslog
 end
 
 module Ramaze
-    module Logger
-        # Logger class for writing to syslog. It is a *very* thin wrapper
-        # around the Syslog library.
-        class Syslog
-		    include Logging
+  module Logger
+    ##
+    # Logger class for writing to syslog. It is a *very* thin wrapper
+    # around the Syslog library.
+    #
+    class Syslog
+      include Logging
 
-            # 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.  
-            # 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
-            #
-            def initialize( *args )
-	    	    ::Syslog.close if ::Syslog.opened?
-	    	    ::Syslog.open( *args )
-            end
+      ##
+      # 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.  
+      # 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
+      #
+      def initialize( *args )
+        ::Syslog.close if ::Syslog.opened?
+        ::Syslog.open( *args )
+      end
 
-            # just sends all messages received to ::Syslog
-            # 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?
-              	::Syslog.send(tag, *messages)
-            end
+      ##
+      # Just sends all messages received to ::Syslog
+      # 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?
+        ::Syslog.send(tag, *messages)
+      end
 
-            # Has to call the modules singleton-method.
-            def inspect
-              ::Syslog.inspect
-            end
-        end
+      ##
+      # Has to call the modules singleton-method.
+      #
+      def inspect
+        ::Syslog.inspect
+      end
     end
+  end
 end

data/lib/ramaze/log/xosd.rb

@@ -8,11 +8,12 @@ require 'thread'
 module Ramaze
   module Logger
 
+    ##
     # Informer for the XOSD notification system for X11.
     #
     # You can install the ruby-bindings with:
     #   gem install xosd.
-
+    #
     class Xosd < ::Xosd
       attr_accessor :options
 
@@ -43,11 +44,12 @@ module Ramaze
       # Here new messages are pushed to eventually displaying them.
       QUEUE = Queue.new
 
+      ##
       # Create a new instance, valid options are in DEFAULT.
       # In the background a new thread will be running that checks the QUEUE
       # and processes all messages that are being sent to it.
       # This is done to make output nicer and readable.
-
+      #
       def initialize(options = {})
         @options = DEFAULT.merge(options)
 
@@ -79,8 +81,9 @@ module Ramaze
         end
       end
 
-      # pushes all messages it gets on the QUEUE for further processing.
-
+      ##
+      # Pushes all messages it gets on the QUEUE for further processing.
+      #
       def log(tag, *messages)
         messages.each do |message|
           QUEUE << [tag, message]

data/lib/ramaze/middleware_compiler.rb

@@ -2,12 +2,12 @@ module Ramaze
   class MiddlewareCompiler < Innate::MiddlewareCompiler
     def static(path)
       require 'rack/contrib'
-      Rack::ETag.new(Rack::ConditionalGet.new(Rack::File.new(path)))
+      Rack::ETag.new(Rack::ConditionalGet.new(Rack::File.new(path)), 'public')
     end
 
     def directory(path)
       require 'rack/contrib'
-      Rack::ETag.new(Rack::ConditionalGet.new(Rack::Directory.new(path)))
+      Rack::ETag.new(Rack::ConditionalGet.new(Rack::Directory.new(path)), 'public')
     end
   end
 end

data/lib/ramaze/snippets/fiber.rb

@@ -1,63 +1,63 @@
-unless defined? Fiber
-  require 'thread'
-
-  class FiberError < StandardError; end
-
-  class Fiber
-    def initialize
-      raise ArgumentError, 'new Fiber requires a block' unless block_given?
-
-      @yield = Queue.new
-      @resume = Queue.new
-
-      @thread = Thread.new{ @yield.push [*yield(*wait)] }
-      @thread.abort_on_exception = true
-      @thread[:fiber] = self
-    end
-    attr_reader :yield, :thread
-
-    def resume *args
-      raise FiberError, 'dead fiber called' unless @thread.alive?
-      @resume.push(args)
-      result = @yield.pop
-      result.size > 1 ? result : result.first
-    end
-
-    def wait
-      @resume.pop
-    end
-    
-    def self.yield *args
-      raise FiberError, "can't yield from root fiber" unless fiber = Thread.current[:fiber]
-      fiber.yield.push(args)
-      result = fiber.wait
-      result.size > 1 ? result : result.first
-    end
-
-    def inspect
-      "#<#{self.class}:0x#{self.object_id.to_s(16)}>"
-    end
-  end
-end
-
-if __FILE__ == $0
-  f = Fiber.new{ puts 'hi'; p Fiber.yield(1); puts 'bye'; :done }
-  p f.resume
-  p f.resume(2)
-end
-
-__END__
-
-$ ruby fbr.rb 
-hi
-1
-2
-bye
-:done
-
-$ ruby1.9 fbr.rb 
-hi
-1
-2
-bye
-:done
+unless defined? Fiber
+  require 'thread'
+
+  class FiberError < StandardError; end
+
+  class Fiber
+    def initialize
+      raise ArgumentError, 'new Fiber requires a block' unless block_given?
+
+      @yield = Queue.new
+      @resume = Queue.new
+
+      @thread = Thread.new{ @yield.push [*yield(*wait)] }
+      @thread.abort_on_exception = true
+      @thread[:fiber] = self
+    end
+    attr_reader :yield, :thread
+
+    def resume *args
+      raise FiberError, 'dead fiber called' unless @thread.alive?
+      @resume.push(args)
+      result = @yield.pop
+      result.size > 1 ? result : result.first
+    end
+
+    def wait
+      @resume.pop
+    end
+    
+    def self.yield *args
+      raise FiberError, "can't yield from root fiber" unless fiber = Thread.current[:fiber]
+      fiber.yield.push(args)
+      result = fiber.wait
+      result.size > 1 ? result : result.first
+    end
+
+    def inspect
+      "#<#{self.class}:0x#{self.object_id.to_s(16)}>"
+    end
+  end
+end
+
+if __FILE__ == $0
+  f = Fiber.new{ puts 'hi'; p Fiber.yield(1); puts 'bye'; :done }
+  p f.resume
+  p f.resume(2)
+end
+
+__END__
+
+$ ruby fbr.rb 
+hi
+1
+2
+bye
+:done
+
+$ ruby1.9 fbr.rb 
+hi
+1
+2
+bye
+:done