yard 0.2.2 → 0.2.3

data/lib/yard/handlers/processor.rb

@@ -0,0 +1,72 @@
+module YARD
+  module Handlers
+    class Processor
+      attr_accessor :file, :namespace, :visibility
+      attr_accessor :scope, :owner, :load_order_errors, :parser_type
+      
+      def initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type)
+        @file = file || "(stdin)"
+        @namespace = YARD::Registry.root
+        @visibility = :public
+        @scope = :instance
+        @owner = @namespace
+        @load_order_errors = load_order_errors
+        @parser_type = parser_type
+        @handlers_loaded = {}
+        load_handlers
+      end
+      
+      def process(statements)
+        statements.each_with_index do |stmt, index|
+          find_handlers(stmt).each do |handler| 
+            begin
+              handler.new(self, stmt).process
+            rescue Parser::LoadOrderError => loaderr
+              raise # Pass this up
+            rescue NamespaceMissingError => missingerr
+              log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized." 
+              log.warn "If this class/method is part of your source tree, this will affect your documentation results." 
+              log.warn "You can correct this issue by loading the source file for this object before `#{file}'"
+              log.warn 
+            rescue Parser::UndocumentableError => undocerr
+              log.warn "in #{handler.to_s}: Undocumentable #{undocerr.message}"
+              log.warn "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
+            rescue => e
+              log.error "Unhandled exception in #{handler.to_s}:"
+              log.error "#{e.class.class_name}: #{e.message}"
+              log.error "  in `#{file}`:#{stmt.line}:\n\n#{stmt.show}\n"
+              log.error "Stack trace:" + e.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n"
+            end
+          end
+        end
+      end
+      
+      def find_handlers(statement)
+        Base.subclasses.find_all do |handler|
+          handler_base_class > handler &&
+          (handler.namespace_only? ? owner.is_a?(CodeObjects::NamespaceObject) : true) &&
+          handler.handles?(statement)
+        end
+      end
+      
+      private
+      
+      def handler_base_class
+        handler_base_namespace.const_get(:Base)
+      end
+
+      def handler_base_namespace
+        case parser_type
+        when :ruby;   Ruby
+        when :ruby18; Ruby::Legacy
+        end
+      end
+      
+      def load_handlers
+        return if @handlers_loaded[parser_type]
+        handler_base_namespace.constants.each {|c| handler_base_namespace.const_get(c) }
+        @handlers_loaded[parser_type] = true
+      end
+    end
+  end
+end

data/lib/yard/handlers/ruby/alias_handler.rb

@@ -0,0 +1,38 @@
+class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
+  handles :alias, method_call(:alias_method)
+  
+  def process
+    names = []
+    if statement.type == :alias
+      names = statement.map {|o| o.jump(:ident, :op, :kw, :const).first }
+    elsif statement.call?
+      statement.parameters(false).each do |obj|
+        case obj.type
+        when :symbol_literal
+          names << obj.jump(:ident, :op, :kw, :const).source
+        when :string_literal
+          names << obj.jump(:string_content).source
+        end
+      end
+    end
+    raise YARD::Parser::UndocumentableError, "alias/alias_method" if names.size != 2
+    
+    new_meth, old_meth = names[0].to_sym, names[1].to_sym
+    old_obj = namespace.child(:name => old_meth, :scope => scope)
+    new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
+      o.visibility = visibility
+      o.scope = scope
+      o.add_file(parser.file, statement.line)
+      o.docstring = statement.comments
+
+      if old_obj
+        o.signature = old_obj.signature
+        o.source = old_obj.source
+      else
+        o.signature = "def #{new_meth}" # this is all we know.
+      end
+    end
+    
+    namespace.aliases[new_obj] = old_meth
+  end
+end

data/lib/yard/handlers/ruby/attribute_handler.rb

@@ -0,0 +1,69 @@
+class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:attr)
+  handles method_call(:attr_reader)
+  handles method_call(:attr_writer)
+  handles method_call(:attr_accessor)
+  
+  def process
+    read, write = true, false
+    params = statement.parameters(false).dup
+    
+    # Change read/write based on attr_reader/writer/accessor
+    case statement.method_name(true)
+    when :attr
+      # In the case of 'attr', the second parameter (if given) isn't a symbol.
+      if params.size == 2
+        write = true if params.pop == s(:var_ref, s(:kw, "true"))
+      end
+    when :attr_accessor
+      write = true
+    when :attr_reader
+      # change nothing
+    when :attr_writer
+      read, write = false, true
+    end
+
+    # Add all attributes
+    validated_attribute_names(params).each do |name|
+      namespace.attributes[scope][name] = SymbolHash[:read => nil, :write => nil]
+      
+      # Show their methods as well
+      {:read => name, :write => "#{name}="}.each do |type, meth|
+        next unless (type == :read ? read : write)
+        
+        namespace.attributes[scope][name][type] = MethodObject.new(namespace, meth, scope) do |o|
+          if type == :write
+            src = "def #{meth}(value)"
+            full_src = "#{src}\n  @#{name} = value\nend"
+            doc = "Sets the attribute +#{name}+\n@param value the value to set the attribute +#{name}+ to."
+          else
+            src = "def #{meth}"
+            full_src = "#{src}\n  @#{name}\nend"
+            doc = "Returns the value of attribute +#{name}+"
+          end
+          o.source ||= full_src
+          o.signature ||= src
+          o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
+        end
+        
+        # Register the objects explicitly
+        register namespace.attributes[scope][name][type]
+      end
+    end
+  end
+  
+  protected
+  
+  def validated_attribute_names(params)
+    params.map do |obj|
+      case obj.type
+      when :symbol_literal
+        obj.jump(:ident, :op, :kw, :const).source
+      when :string_literal
+        obj.jump(:string_content).source
+      else
+        raise YARD::Parser::UndocumentableError, obj.source
+      end
+    end
+  end
+end

data/lib/yard/handlers/ruby/base.rb

@@ -0,0 +1,72 @@
+module YARD
+  module Handlers
+    module Ruby
+      class HandlesExtension
+        def initialize(name) @name = name end
+        def matches?(node) raise NotImplementedError end
+        protected
+        attr_reader :name
+      end
+      
+      class MethodCallWrapper < HandlesExtension
+        def matches?(node)
+          case node.type
+          when :var_ref
+            if !node.parent || node.parent.type == :list
+              return true if node[0].type == :ident && node[0][0] == name
+            end
+          when :fcall, :command
+            return true if node[0][0] == name
+          when :call, :command_call
+            return true if node[2][0] == name
+          end
+          false
+        end
+      end
+      
+      class TestNodeWrapper < HandlesExtension
+        def matches?(node) !node.send(name).is_a?(FalseClass) end
+      end
+      
+      class Base < Handlers::Base
+        class << self
+          include Parser::Ruby
+          
+          def method_call(name)
+            MethodCallWrapper.new(name.to_s)
+          end
+          
+          def meta_type(meth)
+            TestNodeWrapper.new(meth.to_s + "?")
+          end
+          
+          def handles?(node)
+            handlers.any? do |a_handler| 
+              case a_handler 
+              when Symbol
+                a_handler == node.type
+              when String
+                node.source == a_handler
+              when Regexp
+                node.source =~ a_handler
+              when Parser::Ruby::AstNode
+                a_handler == node
+              when HandlesExtension
+                a_handler.matches?(node)
+              end
+            end
+          end
+        end
+
+        include Parser::Ruby
+        
+        def parse_block(inner_node, opts = {})
+          push_state(opts) do
+            nodes = inner_node.type == :list ? inner_node.children : [inner_node]
+            parser.process(nodes)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/ruby/class_condition_handler.rb

@@ -0,0 +1,70 @@
+class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
+  namespace_only
+  handles meta_type(:condition)
+  
+  def process
+    condition = parse_condition
+    if condition == nil
+      # Parse both blocks if we're unsure of the condition
+      parse_then_block
+      parse_else_block
+    elsif condition
+      parse_then_block
+    else
+      parse_else_block
+    end
+  end
+  
+  protected
+  
+  # Parses the condition part of the if/unless statement
+  # 
+  # @return [true, false, nil] true if the condition can be definitely
+  #   parsed to true, false if not, and nil if the condition cannot be
+  #   parsed with certainty (it's dynamic)
+  def parse_condition
+    condition = nil
+    
+    # Right now we can handle very simple unary conditions like:
+    #   if true
+    #   if false
+    #   if 0
+    #   if 100 (not 0)
+    #   if defined? SOME_CONSTANT
+    # 
+    # The last case will do a lookup in the registry and then one
+    # in the Ruby world (using eval).
+    case statement.condition.type
+    when :int
+      condition = statement.condition[0] != "0"
+    when :defined
+      # defined? keyword used, let's see if we can look up the name
+      # in the registry, then we'll try using Ruby's powers. eval() is not
+      # *too* dangerous here since code is not actually executed.
+      name = statement.condition[0].source
+      obj = YARD::Registry.resolve(namespace, name, true)
+      condition = true if obj || Object.instance_eval("defined? #{name}")
+    when :var_ref
+      var = statement.condition[0]
+      if var == s(:kw, "true")
+        condition = true
+      elsif var == s(:kw, "false")
+        condition = false
+      end
+    end
+    
+    # Invert an unless condition
+    if statement.type == :unless || statement.type == :unless_mod
+      condition = !condition if condition != nil
+    end
+    condition
+  end
+  
+  def parse_then_block
+    parse_block(statement.then_block)
+  end
+  
+  def parse_else_block
+    parse_block(statement.else_block) if statement.else_block
+  end
+end

data/lib/yard/handlers/ruby/class_handler.rb

@@ -0,0 +1,74 @@
+class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
+  handles :class, :sclass
+  
+  def process
+    if statement.type == :class
+      classname = statement[0].source
+      superclass = parse_superclass(statement[1])
+      undocsuper = statement[1] && superclass.nil?
+
+      klass = register ClassObject.new(namespace, classname) do |o|
+        o.docstring = statement.comments
+        o.superclass = superclass if superclass
+        o.superclass.type = :class if o.superclass.is_a?(Proxy)
+      end
+      parse_block(statement[2], namespace: klass)
+       
+      if undocsuper
+        raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
+      end
+    elsif statement.type == :sclass
+      if statement[0] == s(:var_ref, s(:kw, "self"))
+        parse_block(statement[1], namespace: namespace, scope: :class)
+      else
+        classname = statement[0].source
+        proxy = Proxy.new(namespace, classname)
+
+        # Allow constants to reference class names
+        if ConstantObject === proxy
+          if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
+            proxy = Proxy.new(namespace, proxy.value)
+          else
+            raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
+          end
+        end
+
+        if classname[0,1] =~ /[A-Z]/
+          register ClassObject.new(namespace, classname) if Proxy === proxy
+          parse_block(statement[1], namespace: proxy, scope: :class)
+        else
+          raise YARD::Parser::UndocumentableError, "class '#{classname}'"
+        end
+      end
+    else
+      sig_end = (statement[1] ? statement[1].source_end : statement[0].source_end) - statement.source_start
+      raise YARD::Parser::UndocumentableError, "class: #{statement.source[0..sig_end]}"
+    end
+  end
+  
+  private
+  
+  def parse_superclass(superclass)
+    return nil unless superclass
+    
+    case superclass.type
+    when :var_ref
+      return superclass.source if superclass.first.type == :const
+    when :const, :const_ref, :const_path_ref, :top_const_ref
+      return superclass.source
+    when :fcall, :command
+      methname = superclass.method_name.source
+      if methname == "DelegateClass"
+        return superclass.parameters.first.source
+      elsif superclass.method_name.type == :const
+        return methname
+      end
+    when :call, :command_call
+      cname = superclass.namespace.source
+      if cname =~ /^O?Struct$/ && superclass.method_name(true) == :new
+        return cname
+      end
+    end
+    nil
+  end
+end

data/lib/yard/handlers/ruby/class_variable_handler.rb

@@ -0,0 +1,11 @@
+class YARD::Handlers::Ruby::ClassVariableHandler < YARD::Handlers::Ruby::Base
+  namespace_only
+  handles :assign
+  
+  def process
+    if statement[0].type == :var_field && statement[0][0].type == :cvar
+      name = statement[0][0][0]
+      register ClassVariableObject.new(namespace, name) {|o| o.source = statement }
+    end
+  end
+end

data/lib/yard/handlers/ruby/constant_handler.rb

@@ -0,0 +1,12 @@
+class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
+  namespace_only
+  handles :assign
+  
+  def process
+    if statement[0].type == :var_field && statement[0][0].type == :const
+      name = statement[0][0][0]
+      value = statement[1].source
+      register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
+    end
+  end
+end

data/lib/yard/handlers/ruby/exception_handler.rb

@@ -0,0 +1,22 @@
+class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:raise)
+  
+  def process
+    return unless owner.is_a?(MethodObject) # Only methods yield
+    return if owner.has_tag?(:raise)
+
+    klass = nil
+    params = statement.parameters(false)
+    if params.size == 1 
+      if params.first.ref? && params.first.first.type != :ident
+        klass = params.first.source
+      elsif params.first.call? && params.first.method_name(true) == :new
+        klass = params.first.namespace.source
+      end
+    else
+      klass = params.first.source
+    end
+
+    owner.docstring.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
+  end
+end