yard 0.2.1 → 0.2.2

data/lib/yard/core_ext/logger.rb

@@ -0,0 +1,5 @@
+class Logger::Formatter
+  def call(sev, time, prog, msg)
+    "[#{sev.downcase}]: #{msg}\n"
+  end
+end

data/lib/yard/core_ext/module.rb

@@ -0,0 +1,9 @@
+class Module
+  def class_name
+    name.split("::").last
+  end
+  
+  def namespace
+    name.split("::")[0..-2].join("::")
+  end
+end

data/lib/yard/core_ext/string.rb

@@ -0,0 +1,13 @@
+class String
+  # @it should turn hello_world into HelloWorld
+  #   "hello_world".camelcase.should == "HelloWorld"
+  def underscore
+    gsub(/([a-z])([A-Z])/, '\1_\2').downcase 
+  end
+  
+  # @it should turn HelloWorld into hello_world
+  #   "HelloWorld".underscore.should == "hello_world"
+  def camelcase
+    gsub(/([a-z])_([a-z])/i) { $1 + $2.upcase }.sub(/^(.)/) { $1.upcase } 
+  end
+end

data/lib/yard/core_ext/symbol_hash.rb

@@ -0,0 +1,24 @@
+class SymbolHash < Hash
+  def initialize(symbolize_value = true)
+    @symbolize_value = symbolize_value
+  end
+  
+  def self.[](*hsh)
+    obj = new;
+    if hsh.size == 1 && hsh.first.is_a?(Hash)
+      hsh.first.each {|k,v| obj[k] = v }
+    else
+      0.step(hsh.size, 2) {|n| obj[hsh[n]] = hsh[n+1] }
+    end
+    obj
+  end
+  
+  def []=(key, value) 
+    super(key.to_sym, value.instance_of?(String) && @symbolize_value ? value.to_sym : value) 
+  end
+  def [](key) super(key.to_sym) end
+  def delete(key) super(key.to_sym) end
+  def has_key?(key) super(key.to_sym) end
+  def update(hsh) hsh.each {|k,v| self[k] = v }; self end
+  alias_method :merge, :update
+end

data/lib/yard/generators/attributes_generator.rb

@@ -0,0 +1,22 @@
+module YARD
+  module Generators
+    class AttributesGenerator < Base
+      include Helpers::MethodHelper
+      
+      before_generate :has_attributes?
+      before_list :includes
+      
+      def sections_for(object) [:header] end
+        
+      protected
+      
+      def includes
+        extend Helpers::UMLHelper if format == :text
+      end
+      
+      def has_attributes?
+        current_object.class_attributes.size + current_object.instance_attributes.size > 0
+      end
+    end
+  end
+end

data/lib/yard/generators/base.rb

@@ -0,0 +1,285 @@
+require 'erb'
+
+module YARD
+  module Generators
+    class Base
+      include Helpers::BaseHelper
+      include Helpers::FilterHelper
+
+      class << self
+        def template_paths
+          @@template_paths ||= [TEMPLATE_ROOT]
+        end
+
+        ##
+        # Convenience method to registering a template path.
+        # Equivalent to calling:
+        #   GeneratorName.template_paths.unshift(path)
+        # 
+        # @param [String] path 
+        #   the pathname to look for the template
+        # 
+        # @see template_paths
+        def register_template_path(path)
+          template_paths.unshift(path)
+        end
+        
+        def before_section(*args)
+          if args.size == 1
+            before_section_filters.push [nil, args.first]
+          elsif args.size == 2
+            before_section_filters.push(args)
+          else
+            raise ArgumentError, "before_section takes a generator followed by a Proc/lambda or Symbol referencing the method name"
+          end
+        end
+        
+        def before_section_filters
+          @before_section_filters ||= []
+        end
+        
+        def before_generate(meth)
+          before_generate_filters.push(meth)
+        end
+        
+        def before_generate_filters
+          @before_generate_filters ||= []
+        end
+        
+        def before_list(meth)
+          before_list_filters.push(meth)
+        end
+        
+        def before_list_filters
+          @before_list_filters ||= []
+        end
+      end
+      
+      # Creates a generator by adding extra options
+      # to the options hash. 
+      # 
+      # @example [Creates a new MethodSummaryGenerator for public class methods]
+      #   G(MethodSummaryGenerator, :scope => :class, :visibility => :public)
+      # 
+      # @param [Class] generator 
+      #   the generator class to use.
+      # 
+      # @options opts
+      #   :ignore_serializer -> true => value
+      #
+      # 
+      def G(generator, opts = {})
+        opts = SymbolHash[:ignore_serializer => true].update(opts)
+        generator.new(options, opts)
+      end
+
+      attr_reader :format, :template, :verifier
+      attr_reader :serializer, :ignore_serializer
+      attr_reader :options
+      attr_reader :current_object
+      
+      def initialize(opts = {}, extra_opts = {})
+        opts = SymbolHash[
+          :format => :html,
+          :template => :default,
+          :serializer => nil,
+          :verifier => nil
+        ].update(opts).update(extra_opts)
+        
+        @options = opts
+        @format = options[:format]
+        @template = options[:template] 
+        @serializer = options[:serializer] 
+        @ignore_serializer = options[:ignore_serializer]
+        @verifier = options[:verifier]
+        
+        extend Helpers::HtmlHelper if format == :html
+      end
+      
+      def generator_name
+        self.class.to_s.split("::").last.gsub(/Generator$/, '').downcase
+      end
+      
+      def generate(*list, &block)
+        output = ""
+
+        list = list.flatten
+        @current_object = Registry.root
+        return output if FalseClass === run_before_list(list)
+
+        serializer.before_serialize if serializer && !ignore_serializer
+        
+        list.each do |object|
+          next unless object && object.is_a?(CodeObjects::Base)
+          
+          objout = ""
+          @current_object = object
+
+          next if call_verifier(object).is_a?(FalseClass)
+          next if run_before_generate(object).is_a?(FalseClass)
+          
+          objout << render_sections(object, &block) 
+
+          if serializer && !ignore_serializer && !objout.empty?
+            serializer.serialize(object, objout) 
+          end
+          output << objout
+        end
+        
+        if serializer && !ignore_serializer
+          serializer.after_serialize(output) 
+        end
+        output
+      end
+      
+      protected
+      
+      def call_verifier(object)
+        if verifier.is_a?(Symbol)
+          send(verifier, object)
+        elsif verifier.respond_to?(:call)
+          verifier.call(self, object)
+        end
+      end
+      
+      def run_before_list(list)
+        self.class.before_list_filters.each do |meth|
+          meth = method(meth) if meth.is_a?(Symbol)
+          result = meth.call *(meth.arity == 0 ? [] : [list])
+          return result if result.is_a?(FalseClass)
+        end
+      end
+      
+      def run_before_generate(object)
+        self.class.before_generate_filters.each do |meth|
+          meth = method(meth) if meth.is_a?(Symbol)
+          result = meth.call *(meth.arity == 0 ? [] : [object])
+          return result if result.is_a?(FalseClass)
+        end
+      end
+
+      def run_before_sections(section, object)
+        result = before_section(section, object)
+        return result if result.is_a?(FalseClass)
+        
+        self.class.before_section_filters.each do |info|
+          result, sec, meth = nil, *info
+          if sec.nil? || sec == section
+            meth = method(meth) if meth.is_a?(Symbol)
+            args = [section, object]
+            if meth.arity == 1 
+              args = [object]
+            elsif meth.arity == 0
+              args = []
+            end
+
+            result = meth.call(*args)
+            log.debug("Calling before section filter for %s%s with `%s`, result = %s" % [
+              self.class.class_name, section.inspect, object, 
+              result.is_a?(FalseClass) ? 'fail' : 'pass'
+            ])
+          end
+
+          return result if result.is_a?(FalseClass)
+        end
+      end
+      
+      def sections_for(object); [] end
+      
+      def before_section(section, object); end
+      
+      def render_sections(object, sections = nil)
+        sections ||= sections_for(object) || []
+
+        data = ""
+        sections.each_with_index do |section, index|
+          next if section.is_a?(Array)
+          
+          data << if sections[index+1].is_a?(Array)
+            render_section(section, object) do |obj|
+              tmp, @current_object = @current_object, obj
+              out = render_sections(obj, sections[index+1])
+              @current_object = tmp
+              out
+            end
+          else
+            render_section(section, object)
+          end
+        end
+        data
+      end
+
+      def render_section(section, object, &block)
+        begin
+          if section.is_a?(Class) && section <= Generators::Base
+            opts = options.dup
+            opts.update(:ignore_serializer => true)
+            sobj = section.new(opts)
+            sobj.generate(object, &block)
+          elsif section.is_a?(Generators::Base)
+            section.generate(object, &block)
+          elsif section.is_a?(Symbol) || section.is_a?(String)
+            return "" if run_before_sections(section, object).is_a?(FalseClass)
+
+            if section.is_a?(Symbol)
+              if respond_to?(section)
+                if method(section).arity != 1
+                  send(section, &block)
+                else
+                  send(section, object, &block) 
+                end || ""
+              else # treat it as a String
+                render(object, section, &block)
+              end
+            else
+              render(object, section, &block)
+            end
+          else
+            type = section.is_a?(String) || section.is_a?(Symbol) ? 'section' : 'generator'
+            log.warn "Ignoring invalid #{type} '#{section}' in #{self.class}"
+            ""
+          end
+        end
+      end
+      
+      def render(object, file = nil, locals = {}, &block)
+        if object.is_a?(Symbol)
+          object, file, locals = current_object, object, (file||{})
+        end
+        
+        __path = template_path(file.to_s + '.erb', generator_name)
+        __f = find_template(__path)
+        if __f
+          __l = locals.map {|k,v| "#{k} = #{v.inspect}" unless k.to_s == "__f" }.join(";")
+          begin
+            erb("<% #{__l} %>" + File.read(__f)).result(binding)
+          rescue => e
+            log.error "#{e.class.class_name}: #{e.message}"
+            log.error "in generator #{self.class} section #{file} on '#{object}'"
+            log.error e.backtrace[0..10].join("\n")
+            exit
+          end
+        else
+          log.warn "Cannot find template `#{__path}`"
+          ""
+        end
+      end
+      
+      def erb(str)
+        ERB.new(str, nil, '<>')
+      end
+      
+      def template_path(file, generator = generator_name)
+        File.join(template.to_s, generator, format.to_s, file.to_s)
+      end
+      
+      def find_template(path)
+        self.class.template_paths.each do |basepath| 
+          f = File.join(basepath, path)
+          return f if File.file?(f)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/yard/generators/class_generator.rb

@@ -0,0 +1,25 @@
+module YARD
+  module Generators
+    class ClassGenerator < Base
+      before_generate :is_class?
+      
+      def sections_for(object) 
+        [
+          :header,
+          [
+            G(InheritanceGenerator), 
+            G(MixinsGenerator), 
+            G(DocstringGenerator), 
+            G(AttributesGenerator), 
+            G(ConstantsGenerator),
+            G(ConstructorGenerator),
+            G(MethodMissingGenerator),
+            G(VisibilityGroupGenerator, :visibility => :public),
+            G(VisibilityGroupGenerator, :visibility => :protected),
+            G(VisibilityGroupGenerator, :visibility => :private)
+          ]
+        ]
+      end
+    end
+  end
+end

data/lib/yard/generators/constants_generator.rb

@@ -0,0 +1,73 @@
+module YARD
+  module Generators
+    class ConstantsGenerator < Base
+      before_section :constants, :has_constants?
+      before_section :inherited, :has_inherited_constants?
+      before_section :included,  :has_included_constants?
+      
+      def sections_for(object) 
+        if object.is_a?(CodeObjects::ClassObject)
+          [:header, [:constants, :inherited, :included]] 
+        elsif object.is_a?(CodeObjects::ModuleObject)
+          [:header, [:constants]]
+        end
+      end
+
+      protected
+      
+      def has_constants?(object)
+        object.constants(:included => false, :inherited => false).size > 0
+      end
+      
+      def has_inherited_constants?(object)
+        return false unless object.is_a?(CodeObjects::ClassObject)
+        object.inherited_constants.size > 0
+      end
+      
+      def has_included_constants?(object)
+        object.included_constants.size > 0
+      end
+        
+      # @yield a the list of methods pertaining to a superclass
+      #   in the inheritance order.
+      # 
+      # @yieldparam [CodeObjects::ClassObject] superclass 
+      #   The superclass the constants belong to
+      # 
+      # @yieldparam [Array<CodeObjects::ConstantObject>] consts
+      #   The list of constants inherited from the superclass
+      # 
+      def inherited_constants_by_class
+        all_consts = current_object.inherited_constants
+        current_object.inheritance_tree[1..-1].each do |superclass|
+          next if superclass.is_a?(CodeObjects::Proxy)
+          opts = { :included => false, :inherited => false }
+          consts = superclass.constants(opts).select {|c| all_consts.include?(c) }
+          next if consts.empty?
+          yield(superclass, consts)
+        end
+      end
+
+      # @yield [module, constlist] 
+      #   Yields a the list of methods pertaining to a module
+      #   in the module order.
+      # 
+      # @yieldparam [CodeObjects::ModuleObject] module 
+      #   The module the constants belong to
+      # 
+      # @yieldparam [Array<CodeObjects::ConstantObject>] consts
+      #   The list of constants included from the module
+      # 
+      def included_constants_by_module
+        all_consts = current_object.included_constants
+        current_object.mixins.each do |superclass|
+          next if superclass.is_a?(CodeObjects::Proxy)
+          opts = { :included => false, :inherited => false }
+          consts = superclass.constants(opts).select {|c| all_consts.include?(c) }
+          next if consts.empty?
+          yield(superclass, consts)
+        end
+      end
+    end
+  end
+end