utilrb 1.6.6 → 2.0

data/lib/utilrb/doc/rake.rb

@@ -9,43 +9,74 @@ module Utilrb
         rescue LoadError
             begin
                 require 'rdoc/task'
-                'rdoc-new'
+                'rdoc'
             rescue LoadError
-                begin
-                    require 'rake/rdoctask'
-                    'rdoc-old'
-                rescue LoadError
-                end
             end
         end
 
+    def self.doc?
+        if DOC_MODE
+            true
+        else
+            false
+        end
+    end
+
     def self.doc(target = 'docs', options = Hash.new)
+        if target.kind_of?(Hash)
+            target, options = 'docs', target
+        end
+
         options = Kernel.validate_options options,
-            :include => [File.join(Dir.pwd, 'lib', '**'), File.join(Dir.pwd, 'ext', '**')],
+            :include => [File.join('lib', '**', '*.rb'), File.join('ext', '**', '*.cc')],
             :exclude => [],
             :target_dir => 'doc',
             :title => '',
-            :plugins => []
+            :plugins => [],
+            :files => []
 
         case DOC_MODE
         when 'yard'
             task = YARD::Rake::YardocTask.new(target)
             task.files.concat(options[:include])
             task.options << '--title' << options[:title] << '--output-dir' << options[:target_dir]
+            if !options[:files].empty?
+                task.options << "--files" << options[:files].join(",")
+            end
             options[:plugins].each do |plugin_name|
                 require "#{plugin_name}/yard"
             end
-        when /rdoc/
-            klass = if DOC_MODE == 'rdoc-new'
-                        RDoc::Task
-                    else
-                        ::Rake::RDocTask
-                    end
-            task = klass.new(target)
+
+            task_clobber = ::Rake::Task.define_task "clobber_#{target}" do 
+                FileUtils.rm_rf options[:target_dir]
+            end
+            task_clobber.add_description "Remove #{target} products"
+
+            name = ::Rake.application.current_scope.dup
+            if name.respond_to?(:path)
+                name = name.map(&:to_s).reverse
+            end
+            name << task.name
+            task_re = ::Rake::Task.define_task "re#{target}" do
+                FileUtils.rm_rf options[:target_dir]
+                ::Rake::Task[name.join(":")].invoke
+            end
+            task_re.add_description "Force a rebuild of #{target}"
+
+        when "rdoc"
+            task = RDoc::Task.new(target)
             task.rdoc_files.include(*options[:include])
             task.rdoc_files.exclude(*options[:exclude])
             task.title = options[:title]
             task.rdoc_dir = File.expand_path(options[:target_dir])
+
+        else
+            [target, "re#{target}"].each do |task_name|
+                t = ::Rake::Task.define_task(task_name) do
+                    STDERR.puts "Documentation generation is disabled: install either the yard or rdoc gems"
+                end
+                t.add_description "Disabled on this installation as neither yard nor rdoc are available"
+            end
         end
     end
 end

data/lib/utilrb/kernel/load_dsl_file.rb

@@ -150,12 +150,12 @@ module Kernel
     def dsl_exec_common(file, proxied_object, context, full_backtrace, *exceptions, &code)
         load_dsl_filter_backtrace(file, full_backtrace, *exceptions) do
             sandbox = with_module(*context) do
-                Class.new do
+                Class.new(BasicObject) do
                     def self.name; "" end
                     attr_accessor :main_object
                     def initialize(obj); @main_object = obj end
                     def method_missing(*m, &block)
-                        main_object.send(*m, &block)
+                        main_object.__send__(*m, &block)
                     end
                 end
             end

data/lib/utilrb/kernel/options.rb

@@ -57,6 +57,12 @@ module Kernel
         return *[known_options, unknown_options]
     end
 
+    # Normalizes all keys in the given option hash to symbol and returns the
+    # modified hash
+    def normalize_options(options)
+        options.to_sym_keys
+    end
+
     # Validates an option hash, with default value support. See #filter_options
     # 
     # In the first form, +option_hash+ should contain keys which are also 

data/lib/utilrb/logger/forward.rb

@@ -15,10 +15,17 @@ class Logger
             EOF
         end
 
+        # Forwarded to {Logger#silent}
+        def log_silent(&block)
+            logger.silent(&block)
+        end
+
+        # Forwarded to {Logger#nest}
         def log_nest(size, level = nil, &block)
             logger.nest(size, level, &block)
         end
 
+        # Forwarded to {Logger#log_pp}
         def log_pp(level, object, *first_line_format)
             logger.log_pp(level, object, *first_line_format)
         end

data/lib/utilrb/logger/hierarchy.rb

@@ -1,9 +1,65 @@
 require 'facets/module/spacename'
 require 'facets/kernel/constant'
+require 'utilrb/object/attribute'
 require 'utilrb/object/singleton_class'
 require 'utilrb/logger/forward'
 
 class Logger
+    module HierarchyElement
+        attribute :log_children do
+            Array.new
+        end
+
+        # Makes it so that this level of the module hierarchy has its own
+        # logger. If +new_progname+ and/or +new_level+ are nil, the associated
+        # value are taken from the parent's logger.
+        def make_own_logger(new_progname = nil, new_level = nil)
+            new_logger = @logger || self.logger.dup
+            if new_progname
+                new_logger.progname = new_progname
+            end
+            if new_level
+                new_logger.level = new_level
+            end
+            self.logger = new_logger
+        end
+
+        # Allows to change the logger object at this level of the hierarchy
+        #
+        # This is usually not used directly: a new logger can be created with
+        # Hierarchy#make_own_logger and removed with Hierarchy#reset_own_logger
+        def logger=(new_logger)
+            @logger = new_logger
+            log_children.each do |child|
+                child.reset_default_logger
+            end
+        end
+
+        # Removes a logger defined at this level of the module hierarchy. The
+        # logging methods will now access the parent's module logger.
+        def reset_own_logger
+            @logger = nil
+            log_children.each do |child|
+                child.reset_default_logger
+            end
+        end
+
+        def reset_default_logger
+            @__utilrb_hierarchy__default_logger = nil
+            log_children.each do |child|
+                child.reset_default_logger
+            end
+        end
+
+        def logger
+            if defined?(@logger) && @logger
+                return @logger 
+            elsif defined?(@__utilrb_hierarchy__default_logger) && @__utilrb_hierarchy__default_logger
+                return @__utilrb_hierarchy__default_logger
+            end
+        end
+    end
+
     # Define a hierarchy of loggers mapped to the module hierarchy.
     #
     # It defines the #logger accessor which either returns the logger
@@ -26,26 +82,11 @@ class Logger
     # "extend Hierarchy" will also add the Forward support if the parent module
     # has it.
     module Hierarchy
-        # Allows to change the logger object at this level of the hierarchy
-        #
-        # This is usually not used directly: a new logger can be created with
-        # Hierarchy#make_own_logger and removed with Hierarchy#reset_own_logger
-        attr_writer :logger
+        include HierarchyElement
 
-        def self.included(obj) # :nodoc:
-            if obj.singleton_class.ancestors.include?(Logger::Forward)
-                obj.send(:include, Logger::Forward)
-            end
-        end
-
-        def self.extended(obj) # :nodoc:
-            if obj.kind_of?(Module)
-                parent_module = constant(obj.spacename)
-                if (parent_module.singleton_class.ancestors.include?(Logger::Forward))
-                    obj.send(:extend, Logger::Forward)
-                end
-            end
-        end
+        # Exception raised when a module/class in the logger hierarchy cannot
+        # find a parent logger
+        class NoParentLogger < RuntimeError; end
 
         # Returns true if the local module has its own logger, and false if it
         # returns the logger of the parent
@@ -53,40 +94,57 @@ class Logger
             defined?(@logger) && @logger
         end
 
-        # Makes it so that this level of the module hierarchy has its own
-        # logger. If +new_progname+ and/or +new_level+ are nil, the associated
-        # value are taken from the parent's logger.
-        def make_own_logger(new_progname = nil, new_level = nil)
-            if !has_own_logger?
-                @logger = self.logger.dup
-            end
-            if new_progname
-                @logger.progname = new_progname
-            end
-            if new_level
-                @logger.level = new_level
+        def self.included(obj) # :nodoc:
+            if obj.singleton_class.ancestors.include?(::Logger::Forward)
+                obj.send(:include, ::Logger::Forward)
             end
-            @logger
         end
 
-        # Removes a logger defined at this level of the module hierarchy. The
-        # logging methods will now access the parent's module logger.
-        def reset_own_logger
-            @logger = nil
+        def self.extended(obj) # :nodoc:
+            obj.logger # initialize the default logger. Also does some checking
+            if obj.kind_of?(Module) && !obj.spacename.empty?
+                parent_module = constant(obj.spacename)
+                if (parent_module.singleton_class.ancestors.include?(::Logger::Forward))
+                    obj.send(:extend, ::Logger::Forward)
+                end
+            end
         end
 
         # Returns the logger object that should be used to log at this level of
         # the module hierarchy
         def logger
-            if defined?(@logger) && @logger
-                return @logger 
-            elsif defined?(@default_logger) && @default_logger
-                return @default_logger
+            if logger = super
+                return logger
             end
 
-	    @default_logger ||=
+            @__utilrb_hierarchy__default_logger =
                 if kind_of?(Module)
-                    constant(self.spacename).logger
+                    m = self
+                    while m
+                        if m.name && !m.spacename.empty?
+                            parent_module =
+                                begin
+                                    constant(m.spacename)
+                                rescue NameError
+                                end
+                            if parent_module.respond_to?(:logger)
+                                break
+                            end
+                        end
+                        if m.respond_to?(:superclass)
+                            m = m.superclass
+                        else
+                            m = nil; break
+                        end
+                    end
+
+                    if !m
+                        raise NoParentLogger, "cannot find a logger for #{self}"
+                    end
+                    if parent_module.respond_to? :log_children
+                        parent_module.log_children << self
+                    end
+                    parent_module.logger
                 else
                     self.class.logger
                 end

data/lib/utilrb/logger/indent.rb

@@ -1,14 +1,47 @@
 require 'utilrb/object/attribute'
 class Logger
+    # [Integer] the current nest size
     attribute(:nest_size) { 0 }
+
+    # Sets the absolute number of spaces that should be prepended to every
+    # message
+    #
+    # You usually want to increment / decrement this with {nest}
     def nest_size=(new_value)
         @nest_string = nil
+        if new_value < 0
+            raise ArgumentError, "negative value for nest_size. You probably have unbalanced nest calls"
+        end
         @nest_size = new_value
     end
 
-    def nest(size, level = nil)
-        if level
-            send(level) do
+    # Adds a certain number number of spaces to the current indentation level
+    #
+    # @overload nest(size)
+    #   Permanently adds a number of spaces to the current indentation
+    #   @param [Integer] size the number of spaces that should be added to
+    #     {nest_size}
+    #
+    # @overload nest(size) { }
+    #   Adds a number of spaces to the current indentation for the duration of
+    #   the block, and restores the original indentation afterwards.
+    #
+    #   @param [Integer] size the number of spaces that should be added to
+    #     {nest_size}
+    #
+    # @overload nest(size, log_level) { }
+    #   Shortcut for
+    #   @example
+    #     
+    #     logger.send(log_level) do
+    #       logger.nest(size) do
+    #         ...
+    #       end
+    #     end
+    #
+    def nest(size, log_level = nil)
+        if log_level
+            send(log_level) do
                 nest(size) do
                     yield
                 end
@@ -29,6 +62,8 @@ class Logger
         end
     end
 
+    # Overloaded from the base logger implementation to add the current
+    # indentation
     def format_message(severity, datetime, progname, msg)
         if !@nest_string
             @nest_string = " " * self.nest_size

data/lib/utilrb/logger/log_pp.rb

@@ -34,7 +34,7 @@ class Logger
     def log_pp(level, object, *first_line_format)
         send(level) do
             first_line = !first_line_format.empty? && defined?(HighLine)
-            Logger.pp_to_array(object).each do |line|
+            self.class.pp_to_array(object).each do |line|
                 if first_line
                     line = color(line, *first_line_format)
                     first_line = false

data/lib/utilrb/logger/root.rb

@@ -1,3 +1,4 @@
+require 'utilrb/logger/hierarchy'
 class Logger
     HAS_COLOR =
         begin
@@ -16,9 +17,12 @@ class Logger
     # Defines a logger on a module, allowing to use that module as a root in a
     # hierarchy (i.e. having submodules use the Logger::Hierarchy support)
     #
-    # +progname+ is used as the logger's program name
-    #
-    # +base_level+ is the level at which the logger is initialized
+    # @param [String] progname is used as the logger's program name
+    # @param [Integer/Symbol] base_level is the level at which the logger is
+    #        initialized, this can be either a symbol from [:DEBUG, :INFO, :WARN,
+    #        :ERROR, :FATAL] or the integer constants from Logger::DEBUG,
+    #        Logger::INFO, etc.  This value is overriden if the BASE_LOG_LEVEL
+    #        environment variable is set.
     #
     # If a block is given, it will be provided the message severity, time,
     # program name and text and should return the formatted message.
@@ -27,15 +31,22 @@ class Logger
     # accessed. Moreover, it includes Logger::Forward, which allows to access
     # the logger's output methods on the module directly
     #
-    # Example:
-    #
+    # @example
     #   module MyModule
-    #       extend Logger.Root('MyModule', :WARN)
+    #       extend Logger.Root('MyModule', Logger::WARN)
     #   end
     #
     #   MyModule.info "text"
     #   MyModule.warn "warntext"
+    #
     def self.Root(progname, base_level, &block)
+	begin	
+	    base_level = ENV['BASE_LOG_LEVEL'].upcase.to_sym if ENV['BASE_LOG_LEVEL']
+	    base_level = Logger.const_get( base_level ) if base_level.is_a? Symbol
+	rescue Exception => e
+	    raise ArgumentError, "Log level #{base_level} is not available in the ruby Logger"
+	end
+
         console = @console
         formatter =
             if block then lambda(&block)
@@ -48,17 +59,21 @@ class Logger
 
         Module.new do
             include Logger::Forward
+            include Logger::HierarchyElement
 
-            singleton = (class << self; self end)
-            singleton.send(:define_method, :extended) do |mod|
-                logger = Logger.new(STDOUT)
+            def has_own_logger?; true end
+
+            define_method :logger do
+                if logger = super()
+                    return logger
+                end
+
+                logger = ::Logger.new(STDOUT)
                 logger.level = base_level
                 logger.progname = progname
                 logger.formatter = formatter
-                mod.instance_variable_set(:@logger, logger)
+                @__utilrb_hierarchy__default_logger = logger
             end
-
-            attr_accessor :logger
         end
     end
 end