yard 0.2.1 → 0.2.2

data/lib/yard/serializers/base.rb

@@ -0,0 +1,16 @@
+module YARD
+  module Serializers
+    class Base
+      attr_reader :options
+      
+      def initialize(opts = {})
+        @options = SymbolHash.new(false).update(opts)
+      end
+      
+      def before_serialize; end
+      def serialize(object, data) end
+      def after_serialize(data); end
+      def serialized_path(object) end
+    end
+  end
+end

data/lib/yard/serializers/file_system_serializer.rb

@@ -0,0 +1,48 @@
+require 'fileutils'
+
+module YARD
+  module Serializers
+    class FileSystemSerializer < Base
+      attr_reader :basepath, :extension
+      
+      def initialize(opts = {})
+        super
+        @basepath = (options[:basepath] || 'doc').to_s
+        @extension = (options.has_key?(:extension) ? options[:extension] : 'html').to_s
+      end
+      
+      def serialize(object, data)
+        path = File.join(basepath, *serialized_path(object))
+        FileUtils.mkdir_p File.dirname(path)
+        log.debug "Serializing to #{path}"
+        File.open(path, "w") {|f| f.write data }
+      end
+      
+      def serialized_path(object)
+        return object if object.is_a?(String)
+
+        objname = object.name.to_s
+        objname += '_' + object.scope.to_s[0,1] if object.is_a?(CodeObjects::MethodObject)
+        fspath = [objname + (extension.empty? ? '' : ".#{extension}")]
+        if object.namespace && object.namespace.path != ""
+          fspath.unshift *object.namespace.path.split(CodeObjects::NSEP)
+        end
+        
+        # Don't change the filenames, it just makes it more complicated
+        # to figure out the original name.
+        #fspath.map! do |p| 
+        #  p.gsub(/([a-z])([A-Z])/, '\1_\2').downcase 
+        #end
+        
+        # Remove special chars from filenames.
+        # Windows disallows \ / : * ? " < > | but we will just remove any
+        # non alphanumeric (plus period, underscore and dash).
+        fspath.map! do |p|
+          p.gsub(/[^\w\.-]/) {|x| '_' + x[0].to_s(16).upcase }
+        end
+        
+        File.join(fspath)
+      end
+    end
+  end
+end

data/lib/yard/serializers/process_serializer.rb

@@ -0,0 +1,14 @@
+module YARD
+  module Serializers
+    class ProcessSerializer < Base
+      def initialize(cmd)
+        @cmd = cmd
+      end
+      
+      def serialize(object, data)
+        IO.popen(@cmd, 'w') {|io| io.write(data) }
+      end
+    end
+  end
+end
+

data/lib/yard/serializers/stdout_serializer.rb

@@ -0,0 +1,21 @@
+module YARD
+  module Serializers
+    class StdoutSerializer < Base
+      def initialize(wrap = nil)
+        @wrap = wrap
+      end
+      
+      def serialize(object, data)
+        print(@wrap ? word_wrap(data, @wrap) : data)
+      end
+      
+      private
+      
+      def word_wrap(text, length = 80)
+        # See ruby-talk/10655 / Ernest Ellingson
+        text.gsub(/\t/,"     ").gsub(/.{1,50}(?:\s|\Z)/){($& + 
+          5.chr).gsub(/\n\005/,"\n").gsub(/\005/,"\n")}
+      end
+    end
+  end
+end

data/lib/yard/tags/default_factory.rb

@@ -0,0 +1,98 @@
+module YARD
+  module Tags
+    class DefaultFactory
+      ##
+      # Parses tag text and creates a new tag with descriptive text
+      #
+      # @param tag_name        the name of the tag to parse
+      # @param [String] text   the raw tag text
+      # @return [Tag]          a tag object with the tag_name and text values filled
+      def parse_tag(tag_name, text)
+        Tag.new(tag_name, text)
+      end
+      
+      ##
+      # Parses tag text and creates a new tag with a key name and descriptive text
+      #
+      # @param tag_name        the name of the tag to parse
+      # @param [String] text   the raw tag text
+      # @return [Tag]          a tag object with the tag_name, name and text values filled
+      def parse_tag_with_name(tag_name, text)
+        name, text = *extract_name_from_text(text)
+        Tag.new(tag_name, text, nil, name)
+      end
+      
+      ##
+      # Parses tag text and creates a new tag with formally declared types and 
+      # descriptive text
+      #
+      # @param tag_name        the name of the tag to parse
+      # @param [String] text   the raw tag text
+      # @return [Tag]          a tag object with the tag_name, types and text values filled
+      def parse_tag_with_types(tag_name, text)
+        types, text = *extract_types_from_text(text)
+        Tag.new(tag_name, text, types)
+      end
+      
+      ##
+      # Parses tag text and creates a new tag with formally declared types, a key 
+      # name and descriptive text
+      #
+      # @param tag_name        the name of the tag to parse
+      # @param [String] text   the raw tag text
+      # @return [Tag]          a tag object with the tag_name, name, types and text values filled
+      def parse_tag_with_types_and_name(tag_name, text)
+        types, text = *extract_types_from_text(text)
+        name, text = *extract_name_from_text(text)
+        Tag.new(tag_name, text, types, name)
+      end
+      
+      def parse_tag_with_raw_text(tag_name, text, raw_text)
+        Tag.new(tag_name, raw_text)
+      end
+      
+      def parse_tag_with_raw_title_and_text(tag_name, text, raw_text)
+        title, desc = *extract_title_and_desc_from_raw_text(raw_text)
+        Tag.new(tag_name, desc, nil, title)
+      end
+      
+      private
+      
+      ##
+      # Extracts the name from raw tag text returning the name and remaining value
+      #
+      # @param [String] text the raw tag text
+      # @return [Array] an array holding the name as the first element and the 
+      #                 value as the second element
+      def extract_name_from_text(text)
+        text.strip.split(" ", 2)
+      end
+      
+      ##
+      # Extracts the type signatures from the raw tag text
+      #
+      # @param [String] text the raw tag text
+      # @return [Array] an array holding the value as the first element and
+      #                 the array of types as the second element
+      def extract_types_from_text(text)
+        types, text = [], text.strip
+        if text =~ /^\s*\[(.+?)\]\s*(.*)/
+          text, types = $2, $1.split(",").collect {|e| e.strip }
+        end
+        [types, text]
+      end
+      
+      def extract_title_and_desc_from_raw_text(raw_text)
+        title, desc = nil, nil
+        if raw_text =~ /\A[ \t]\n/
+          desc = raw_text
+        else
+          raw_text = raw_text.split(/\r?\n/)
+          title = raw_text.shift.squeeze(' ').strip
+          desc = raw_text.join("\n")
+        end
+        [title, desc]
+      end
+    end
+  end
+end

data/lib/yard/tags/library.rb

@@ -0,0 +1,109 @@
+module YARD
+  module Tags
+    ##
+    # Holds all the registered meta tags. If you want to extend YARD and add
+    # a new meta tag, you can do it in one of two ways.
+    #
+    # == Method #1
+    # Write your own +tagname_tag+ method that takes the raw text as a parameter.
+    # Example:
+    #   def mytag_tag(text)
+    #     Tag.parse_tag("mytag", text)
+    #   end
+    #
+    # This will allow you to use @mytag TEXT to add meta data to classes through
+    # the docstring. {Tag} has a few convenience factory methods to create 
+    #
+    # == Method #2
+    # Use {Library::define_tag!} to define a new tag by passing the tag name
+    # and the factory method to use when creating the tag. These definitions will
+    # be auto expanded into ruby code similar to what is shown in method #1. If you
+    # do not provide a factory method to use, it will default to {Tag::parse_tag}
+    # Example:
+    #   define_tag :param, :with_types_and_name
+    #   define_tag :author
+    #
+    # The first line will expand to the code:
+    #   def param_tag(text) Tag.parse_tag_with_types_and_name(text) end
+    #
+    # The second line will expand to:
+    #   def author_tag(text) Tag.parse_tag(text) end
+    #
+    # @see Library::define_tag
+    class Library
+      class << self
+        attr_reader :labels
+        attr_accessor :default_factory
+        
+        def default_factory
+          @default_factory ||= DefaultFactory.new
+        end
+        
+        def default_factory=(factory)
+          @default_factory = factory.is_a?(Class) ? factory.new : factory
+        end
+      
+        ## 
+        # Sorts the labels lexically by their label name, often used when displaying
+        # the tags.
+        # 
+        # @return [Array<Symbol>, String] the sorted labels as an array of the tag name and label
+        def sorted_labels
+          labels.sort_by {|a| a.last.downcase }
+        end
+      
+        ##
+        # Convenience method to define a new tag using one of {Tag}'s factory methods, or the
+        # regular {Tag::parse_tag} factory method if none is supplied.
+        #
+        # @param [#to_s] tag the tag name to create
+        # @param meth the {Tag} factory method to call when creating the tag
+        def define_tag(label, tag, meth = "")
+          class_eval <<-eof, __FILE__, __LINE__
+            def #{tag}_tag(text, raw_text)
+              send_to_factory(#{tag.inspect}, #{meth.inspect}, text, raw_text)
+            end
+          eof
+
+          @labels ||= SymbolHash.new(false)
+          @labels.update(tag => label)
+          tag
+        end
+      end
+      
+      private
+      
+      def send_to_factory(tag_name, meth, text, raw_text)
+        meth = meth.to_s
+        send_name = "parse_tag" + (meth.empty? ? "" : "_" + meth)
+        if @factory.respond_to?(send_name)
+          arity = @factory.method(send_name).arity
+          @factory.send send_name, tag_name, text, *(arity == 3 ? [raw_text] : [])
+        else
+          raise NoMethodError, "Factory #{@factory.class_name} does not implement factory method :#{meth}."
+        end
+      end
+      
+      public
+      
+      def initialize(factory = Library.default_factory)
+        @factory = factory
+      end
+      
+      define_tag "Parameters",        :param,       :with_types_and_name
+      define_tag "Yield Parameters",  :yieldparam,  :with_types_and_name
+      define_tag "Yields",            :yield,       :with_types
+      define_tag "Default Value",     :default,     :with_name
+      define_tag "Returns",           :return,      :with_types
+      define_tag "Deprecated",        :deprecated
+      define_tag "Author",            :author
+      define_tag "Raises",            :raise,       :with_types
+      define_tag "See Also",          :see
+      define_tag "Since",             :since
+      define_tag "Version",           :version
+      define_tag "API Visibility",    :api
+      define_tag "Todo Item",         :todo      
+      define_tag "Example",           :example,     :with_raw_title_and_text
+    end
+  end
+end

data/lib/yard/tags/merbdoc_factory.rb

@@ -0,0 +1,47 @@
+module YARD
+  module Tags
+    class MerbdocFactory < DefaultFactory
+      ##
+      # Parses tag text and creates a new tag with formally declared types and 
+      # descriptive text
+      #
+      # @param tag_name        the name of the tag to parse
+      # @param text<String>    the raw tag text
+      # @return <Tag>          a tag object with the tag_name, types and text values filled
+      def parse_tag_with_types(tag_name, text)
+        _, types, text = *extract_types_from_text(text)
+        # TODO warn if name value ('_') is not nil, because that's invalid syntax
+        Tag.new(tag_name, text, types)
+      end
+      
+      ##
+      # Parses tag text and creates a new tag with formally declared types, a key 
+      # name and descriptive text
+      #
+      # @param tag_name        the name of the tag to parse
+      # @param text<String>    the raw tag text
+      # @return <Tag>          a tag object with the tag_name, name, types and text values filled
+      def parse_tag_with_types_and_name(tag_name, text)
+        name, types, text = *extract_types_from_text(text)
+        name, text = *extract_name_from_text(text) if name.nil?
+        Tag.new(tag_name, text, types, name)
+      end
+      
+      private
+      
+      ##
+      # Extracts the type signatures with an optional name from the raw tag text
+      #
+      # @param text<String> the raw tag text
+      # @return <Array> an array holding the name as the first element (nil if empty),
+      #                 array of types as the second element and the raw text as the last.
+      def extract_types_from_text(text)
+        name, types, text = nil, [], text.strip
+        if text =~ /^\s*(\S*)\s*<(.+?)>\s*(.*)/
+          name, text, types = $1, $3, $2.split(",").collect {|e| e.strip }
+        end
+        [name, types, text]
+      end
+    end
+  end
+end

data/lib/yard/tags/tag.rb

@@ -0,0 +1,35 @@
+module YARD
+  module Tags
+    class Tag
+      attr_reader :tag_name, :text, :types, :name
+
+      ##
+      # Creates a new tag object with a tag name and text. Optionally, formally declared types
+      # and a key name can be specified.
+      #
+      # Types are mainly for meta tags that rely on type information, such as +param+, +return+, etc.
+      # 
+      # Key names are for tags that declare meta data for a specific key or name, such as +param+,
+      # +raise+, etc.
+      #
+      # @param tag_name                the tag name to create the tag for
+      # @param [String] text           the descriptive text for this tag
+      # @param [Array<String>] types   optional type list of formally declared types
+      #                                for the tag
+      # @param [String] name           optional key name which the tag refers to
+      def initialize(tag_name, text, types = nil, name = nil)
+        @tag_name, @text, @name, @types = tag_name.to_s, text, name, (types ? [types].flatten.compact : nil)
+      end
+
+      ##
+      # Convenience method to access the first type specified. This should mainly
+      # be used for tags that only specify one type.
+      #
+      # @return [String] the first of the list of specified types 
+      # @see #types
+      def type
+        types.first
+      end
+    end
+  end
+end

data/spec/code_objects/base_spec.rb

@@ -0,0 +1,219 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::CodeObjects::Base do
+  before { Registry.clear }
+  
+  it "should return a unique instance of any registered object" do
+    obj = ClassObject.new(:root, :Me)
+    obj2 = ModuleObject.new(:root, :Me)
+    obj.object_id.should == obj2.object_id
+    
+    obj3 = ModuleObject.new(obj, :Too)
+    obj4 = CodeObjects::Base.new(obj3, :Hello)
+    obj4.parent = obj
+    
+    obj5 = CodeObjects::Base.new(obj3, :hello)
+    obj4.object_id.should_not == obj5.object_id
+  end
+  
+  it "should recall the block if #new is called on an existing object" do
+    o1 = ClassObject.new(:root, :Me) do |o|
+      o.docstring = "DOCSTRING"
+    end
+    
+    o2 = ClassObject.new(:root, :Me) do |o|
+      o.docstring = "NOT_DOCSTRING"
+    end
+    
+    o1.object_id.should == o2.object_id
+    o1.docstring.should == "NOT_DOCSTRING"
+    o2.docstring.should == "NOT_DOCSTRING"
+  end
+  
+  it "should handle empty docstrings with #short_docstring" do
+    o1 = ClassObject.new(nil, :Me) 
+    o1.short_docstring.should == ""
+  end
+  
+  it "should return the first sentence with #short_docstring" do
+    o = ClassObject.new(nil, :Me) 
+    o.docstring = "DOCSTRING. Another sentence"
+    o.short_docstring.should == "DOCSTRING."
+  end
+
+  it "should return the first paragraph with #short_docstring" do
+    o = ClassObject.new(nil, :Me)
+    o.docstring = "DOCSTRING, and other stuff\n\nAnother sentence."
+    o.short_docstring.should == "DOCSTRING, and other stuff."
+  end
+  
+  it "should return proper short_docstring when docstring is changed" do
+    o = ClassObject.new(:root, :Me)
+    o.docstring = "DOCSTRING, and other stuff\n\nAnother sentence."
+    o.short_docstring.should == "DOCSTRING, and other stuff."
+    o.docstring = "DOCSTRING."
+    o.short_docstring.should == "DOCSTRING."
+  end
+  
+  it "should not double the ending period in short_docstring" do
+    o = ClassObject.new(nil, :Me)
+    o.docstring = "Returns a list of tags specified by +name+ or all tags if +name+ is not specified.\n\nTest"
+    o.short_docstring.should == "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
+    
+    Parser::SourceParser.parse_string <<-eof
+      ##
+      # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
+      #
+      # @param name the tag name to return data for, or nil for all tags
+      # @return [Array<Tags::Tag>] the list of tags by the specified tag name
+      def tags(name = nil)
+        return @tags if name.nil?
+        @tags.select {|tag| tag.tag_name.to_s == name.to_s }
+      end
+    eof
+    P('#tags').short_docstring.should == "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
+  end
+  
+  it "should allow complex name and convert that to namespace" do
+    obj = CodeObjects::Base.new(nil, "A::B")
+    obj.namespace.path.should == "A"
+    obj.name.should == :B
+  end
+  
+  it "should allow namespace to be nil and not register in the Registry" do
+    obj = CodeObjects::Base.new(nil, :Me)
+    obj.namespace.should == nil
+    Registry.at(:Me).should == nil
+  end
+  
+  it "should allow namespace to be a NamespaceObject" do
+    ns = ModuleObject.new(:root, :Name)
+    obj = CodeObjects::Base.new(ns, :Me)
+    obj.namespace.should == ns
+  end
+  
+  it "should allow :root to be the shorthand namespace of `Registry.root`" do
+    obj = CodeObjects::Base.new(:root, :Me)
+    obj.namespace.should == Registry.root
+  end
+  
+  
+  it "should not allow any other types as namespace" do
+    lambda { CodeObjects::Base.new("ROOT!", :Me) }.should raise_error(ArgumentError)
+  end
+  
+  it "should register itself in the registry if namespace is supplied" do
+    obj = ModuleObject.new(:root, :Me)
+    Registry.at(:Me).should == obj
+    
+    obj2 = ModuleObject.new(obj, :Too)
+    Registry.at(:"Me::Too").should == obj2
+  end
+  
+  it "should set any attribute using #[]=" do
+    obj = ModuleObject.new(:root, :YARD)
+    obj[:some_attr] = "hello"
+    obj[:some_attr].should == "hello"
+  end
+  
+  it "#[]= should use the accessor method if available" do
+    obj = CodeObjects::Base.new(:root, :YARD)
+    obj[:source] = "hello"
+    obj.source.should == "hello"
+    obj.source = "unhello"
+    obj[:source].should == "unhello"
+  end
+  
+  it "should set attributes via attr= through method_missing" do
+    obj = CodeObjects::Base.new(:root, :YARD)
+    obj.something = 2
+    obj.something.should == 2
+    obj[:something].should == 2
+  end
+  
+  it "should exist in the parent's #children after creation" do
+    obj = ModuleObject.new(:root, :YARD)
+    obj2 = MethodObject.new(obj, :testing)
+    obj.children.should include(obj2)
+  end
+  
+  it "should parse comments into tags" do
+    obj = CodeObjects::Base.new(nil, :Object)
+    comments = <<-eof
+      @param name Hello world
+        how are you?
+      @param name2 
+        this is a new line
+      @param name3 and this
+        is a new paragraph:
+
+        right here.
+    eof
+    obj.send(:parse_comments, comments)
+    obj.tags("param").each do |tag|
+      if tag.name == "name"
+        tag.text.should == "Hello world how are you?"
+      elsif tag.name == "name2"
+        tag.text.should == "this is a new line"
+      elsif tag.name == "name3"
+        tag.text.should == "and this is a new paragraph:\n\nright here."
+      end
+    end
+  end
+  
+  it "should properly re-indent source starting from 0 indentation" do
+    obj = CodeObjects::Base.new(nil, :test)
+    obj.source = <<-eof
+      def mymethod
+        if x == 2 &&
+            5 == 5
+          3 
+        else
+          1
+        end
+      end
+    eof
+    obj.source.should == "def mymethod\n  if x == 2 &&\n      5 == 5\n    3 \n  else\n    1\n  end\nend"
+    
+    Registry.clear
+    Parser::SourceParser.parse_string <<-eof
+      def key?(key)
+        super(key)
+      end
+    eof
+    Registry.at('#key?').source.should == "def key?(key)\n  super(key)\nend"
+
+    Registry.clear
+    Parser::SourceParser.parse_string <<-eof
+        def key?(key)
+          if x == 2
+            puts key
+          else
+            exit
+          end
+        end
+    eof
+    Registry.at('#key?').source.should == "def key?(key)\n  if x == 2\n    puts key\n  else\n    exit\n  end\nend"
+  end
+  
+  it "should not add newlines to source when parsing sub blocks" do
+    Parser::SourceParser.parse_string <<-eof
+      module XYZ
+        module ZYX
+          class ABC
+            def msg
+              hello_world
+            end
+          end
+        end
+      end
+    eof
+    Registry.at('XYZ::ZYX::ABC#msg').source.should == "def msg\n  hello_world\nend"    
+  end
+  
+  it "should handle source for 'def x; end'" do
+    Registry.clear
+    Parser::SourceParser.parse_string "def x; 2 end"
+    Registry.at('#x').source.should == "def x; 2 end"
+  end
+end