yard 0.2.3.5 → 0.4.0

data/lib/yard/verifier.rb

@@ -0,0 +1,110 @@
+module YARD
+  # Similar to a Proc, but runs a set of Ruby expressions using a small
+  # DSL to make tag lookups easier.
+  # 
+  # The syntax is as follows:
+  # * All syntax is Ruby compatible
+  # * +object+ (+o+ for short) exist to access the object being verified
+  # * +@TAGNAME+ is translated into +object.tag('TAGNAME')+
+  # * +@@TAGNAME+ is translated into +object.tags('TAGNAME')+
+  # * +object+ can be omitted as target for method calls (it is implied)
+  # 
+  # @example Create a verifier to check for objects that don't have @private tags
+  #   verifier = Verifier.new('!@private')
+  #   verifier.call(object) # => true (no @private tag)
+  # @example Create a verifier to find any return tag with an empty description
+  #   Verifier.new('@return.text.empty?')
+  #   # Equivalent to:
+  #   Verifier.new('object.tag(:return).text.empty?')
+  # @example Check if there are any @param tags
+  #   Verifier.new('@@param.empty?')
+  #   # Equivalent to:
+  #   Verifier.new('object.tags(:param).empty?')
+  # @example Using +object+ or +o+ to look up object attributes directly
+  #   Verifier.new('object.docstring == "hello world"')
+  #   # Equivalent to:
+  #   Verifier.new('o.docstring == "hello world"')
+  # @example Without using +object+ or +o+
+  #   Verifier.new('tag(:return).size == 1 || has_tag?(:author)')
+  # @example Specifying multiple expressions
+  #   Verifier.new('@return', '@param', '@yield')
+  #   # Equivalent to:
+  #   Verifier.new('@return && @param && @yield')
+  class Verifier
+    # Creates a verifier from a set of expressions
+    # 
+    # @param [Array<String>] expressions a list of Ruby expressions to
+    #   parse.
+    def initialize(*expressions)
+      create_method_from_expressions(expressions.flatten)
+    end
+    
+    # Passes any method calls to the object from the {#call}
+    def method_missing(sym, *args, &block)
+      if object.respond_to?(sym)
+        object.send(sym, *args, &block)
+      else
+        super
+      end
+    end
+
+    # Tests the expressions on the object
+    # 
+    # @param [CodeObjects::Base] object the object to verify
+    # @return [Boolean] the result of the expressions
+    def call(object)
+      modify_nilclass
+      @object = object
+      retval = __execute ? true : false
+      unmodify_nilclass
+      retval
+    end
+    
+    protected
+    
+    # @return [CodeObjects::Base] the current object being tested
+    attr_reader :object
+    alias o object
+    
+    private
+    
+    # Modifies nil to not throw NoMethodErrors. This allows
+    # syntax like object.tag(:return).text to work if the #tag
+    # call returns nil, which means users don't need to perform
+    # stringent nil checking
+    # 
+    # @return [nil] 
+    def modify_nilclass
+      NilClass.send(:define_method, :method_missing) {|*args| }
+    end
+    
+    # Returns the state of NilClass back to normal
+    # @return [nil] 
+    def unmodify_nilclass
+      NilClass.send(:undef_method, :method_missing)
+    end
+    
+    # Creates the +__execute+ method by evaluating the expressions
+    # as Ruby code
+    # @return [nil] 
+    def create_method_from_expressions(exprs)
+      expr = exprs.flatten.map {|e| "(#{parse_expression(e)})" }.join(" && ")
+      
+      instance_eval(<<-eof, __FILE__, __LINE__ + 1)
+        def __execute; #{expr}; end
+      eof
+    end
+    
+    # Parses a single expression, handling some of the DSL syntax.
+    # 
+    # The syntax "@tag" should be turned into object.tag(:tag),
+    # and "@@tag" should be turned into object.tags(:tag)
+    # 
+    # @return [String] the parsed expression
+    def parse_expression(expr)
+      expr = expr.gsub(/@@(\w+)/, 'object.tags("\1")')
+      expr = expr.gsub(/@(\w+)/, 'object.tag("\1")')
+      expr
+    end
+  end
+end

data/spec/cli/yardoc_spec.rb

@@ -15,7 +15,7 @@ describe YARD::CLI::Yardoc do
   end
 
   it "should alias --main to the --readme flag" do
-    readme = File.join(File.dirname(__FILE__),'..','..','README.markdown')
+    readme = File.join(File.dirname(__FILE__),'..','..','README.md')
 
     @yardoc.optparse('--main', readme)
     @yardoc.options[:readme].should == readme.to_sym
@@ -68,6 +68,7 @@ describe YARD::CLI::Yardoc do
   end
 
   it "should accept globs as extra files" do
+    Dir.should_receive(:glob).with('README*').and_return []
     Dir.should_receive(:glob).with('*.txt').and_return ['a.txt', 'b.txt']
     File.should_receive(:file?).with('a.txt').and_return(true)
     File.should_receive(:file?).with('b.txt').and_return(true)
@@ -80,4 +81,25 @@ describe YARD::CLI::Yardoc do
     @yardoc.optparse
     @yardoc.files.should == %w( lib/**/*.rb )
   end
+  
+  it "should accept a --query" do
+    @yardoc.optparse *%w( --query @return )
+    @yardoc.options[:verifier].should be_a(Verifier)
+  end
+  
+  it "should accept multiple --query arguments" do
+    obj = mock(:object)
+    obj.should_receive(:tag).ordered.with('return').and_return(true)
+    obj.should_receive(:tag).ordered.with('tag').and_return(false)
+    @yardoc.optparse *%w( --query @return --query @tag )
+    @yardoc.options[:verifier].should be_a(Verifier)
+    @yardoc.options[:verifier].call(obj).should == false
+  end
+  
+  it "should accept --no-private" do
+    obj = mock(:object)
+    obj.should_receive(:tag).ordered.with('private').and_return(true)
+    @yardoc.optparse *%w( --no-private )
+    @yardoc.options[:verifier].call(obj).should == false
+  end
 end

data/spec/code_objects/base_spec.rb

@@ -204,4 +204,12 @@ describe YARD::CodeObjects::Base do
     Registry.at(:X).line.should == 4
     Registry.at(:X).files.should == [['(stdin)', 4], ['(stdin)', 1], ['(stdin)', 2]]
   end
+  
+  describe '#format' do
+    it "should send to Templates.render" do
+      object = MethodObject.new(:root, :method)
+      Templates::Engine.should_receive(:render).with(:x => 1, :object => object)
+      object.format :x => 1
+    end
+  end
 end

data/spec/code_objects/class_object_spec.rb

@@ -1,188 +1,198 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
 describe YARD::CodeObjects::ClassObject do
-  before(:all) do 
-    Registry.clear 
-    @mixin = ModuleObject.new(:root, :SomeMixin)
-    @mixin2 = ModuleObject.new(:root, :SomeMixin2)
-    @mixin3 = ModuleObject.new(:root, :SomeMixin3)
-    @mixin4 = ModuleObject.new(:root, :SomeMixin4)
-    @mixin2.instance_mixins << @mixin3
-    @superyard = ClassObject.new(:root, :SuperYard)
-    @superyard.superclass = P("String")
-    @superyard.instance_mixins << @mixin2
-    @superyard.class_mixins << @mixin4
-    @yard = ClassObject.new(:root, :YARD)
-    @yard.superclass = @superyard
-    @yard.instance_mixins << @mixin
-  end
-  
-  it "should show the proper inheritance tree" do
-    @yard.inheritance_tree.should == [@yard, @superyard, P(:String)]
-  end
-  
-  it "should show proper inheritance tree when mixins are included" do
-    @yard.inheritance_tree(true).should == [@yard, @mixin, @superyard, @mixin2, @mixin3, P(:String)]
+  describe '#inheritance_tree' do
+    before(:all) do
+      Registry.clear
+      @mixin = ModuleObject.new(:root, :SomeMixin)
+      @mixin2 = ModuleObject.new(:root, :SomeMixin2)
+      @mixin3 = ModuleObject.new(:root, :SomeMixin3)
+      @mixin4 = ModuleObject.new(:root, :SomeMixin4)
+      @mixin2.instance_mixins << @mixin3
+      @superyard = ClassObject.new(:root, :SuperYard)
+      @superyard.superclass = P("String")
+      @superyard.instance_mixins << @mixin2
+      @superyard.class_mixins << @mixin4
+      @yard = ClassObject.new(:root, :YARD)
+      @yard.superclass = @superyard
+      @yard.instance_mixins << @mixin
+    end
+
+    it "should show the proper inheritance tree" do
+      @yard.inheritance_tree.should == [@yard, @superyard, P(:String)]
+    end
+
+    it "should show proper inheritance tree when mixins are included" do
+      @yard.inheritance_tree(true).should == [@yard, @mixin, @superyard, @mixin2, @mixin3, P(:String)]
+    end
+
+    it "should not modify the object's mixin list when mixins are included" do
+      @class1 = ClassObject.new(:root, :A)
+      @class2 = ClassObject.new(:root, :B)
+      @class2.superclass = @class1
+
+      @class2.inheritance_tree(true)
+      @class2.mixins.should == []
+    end
   end
-end
 
-describe YARD::CodeObjects::ClassObject, "#meths / #inherited_meths" do
-  before(:all) do 
-    Registry.clear 
+  describe "#meths / #inherited_meths" do
+    before(:all) do
+      Registry.clear
     
-    Parser::SourceParser.parse_string <<-eof
-      class SuperYard < String
-        def foo; end
-        def foo2; end
-        def bar; end
-        def middle; end
-        protected :foo2
-        private
-        def self.bar; end
-      end
+      Parser::SourceParser.parse_string <<-eof
+        class SuperYard < String
+          def foo; end
+          def foo2; end
+          def bar; end
+          def middle; end
+          protected :foo2
+          private
+          def self.bar; end
+        end
       
-      class MiddleYard < SuperYard
-        def middle; end
-      end
+        class MiddleYard < SuperYard
+          def middle; end
+        end
       
-      class YARD < MiddleYard
-        def mymethod; end
-        def bar; end
-      end
-    eof
-  end
+        class YARD < MiddleYard
+          def mymethod; end
+          def bar; end
+        end
+      eof
+    end
   
-  it "should show inherited methods by default" do
-    meths = P(:YARD).meths
-    meths.should include(P("YARD#mymethod"))
-    meths.should include(P("SuperYard#foo"))
-    meths.should include(P("SuperYard#foo2"))
-    meths.should include(P("SuperYard.bar"))
-  end
+    it "should show inherited methods by default" do
+      meths = P(:YARD).meths
+      meths.should include(P("YARD#mymethod"))
+      meths.should include(P("SuperYard#foo"))
+      meths.should include(P("SuperYard#foo2"))
+      meths.should include(P("SuperYard.bar"))
+    end
   
-  it "should allow :inherited to be set to false" do
-    meths = P(:YARD).meths(:inherited => false)
-    meths.should include(P("YARD#mymethod"))
-    meths.should_not include(P("SuperYard#foo"))
-    meths.should_not include(P("SuperYard#foo2"))
-    meths.should_not include(P("SuperYard.bar"))
-  end
+    it "should allow :inherited to be set to false" do
+      meths = P(:YARD).meths(:inherited => false)
+      meths.should include(P("YARD#mymethod"))
+      meths.should_not include(P("SuperYard#foo"))
+      meths.should_not include(P("SuperYard#foo2"))
+      meths.should_not include(P("SuperYard.bar"))
+    end
   
-  it "should not show overridden methods" do 
-    meths = P(:YARD).meths
-    meths.should include(P("YARD#bar"))
-    meths.should_not include(P("SuperYard#bar"))
+    it "should not show overridden methods" do 
+      meths = P(:YARD).meths
+      meths.should include(P("YARD#bar"))
+      meths.should_not include(P("SuperYard#bar"))
     
-    meths = P(:YARD).inherited_meths
-    meths.should_not include(P("YARD#bar"))
-    meths.should_not include(P("YARD#mymethod"))
-    meths.should include(P("SuperYard#foo"))
-    meths.should include(P("SuperYard#foo2"))
-    meths.should include(P("SuperYard.bar"))
-  end
+      meths = P(:YARD).inherited_meths
+      meths.should_not include(P("YARD#bar"))
+      meths.should_not include(P("YARD#mymethod"))
+      meths.should include(P("SuperYard#foo"))
+      meths.should include(P("SuperYard#foo2"))
+      meths.should include(P("SuperYard.bar"))
+    end
   
-  it "should not show inherited methods overridden by other subclasses" do
-    meths = P(:YARD).inherited_meths
-    meths.should include(P('MiddleYard#middle'))
-    meths.should_not include(P('SuperYard#middle'))
+    it "should not show inherited methods overridden by other subclasses" do
+      meths = P(:YARD).inherited_meths
+      meths.should include(P('MiddleYard#middle'))
+      meths.should_not include(P('SuperYard#middle'))
+    end
   end
-end
 
-describe YARD::CodeObjects::ClassObject, "#constants / #inherited_constants" do
-  before(:all) do 
-    Registry.clear 
+  describe "#constants / #inherited_constants" do
+    before(:all) do 
+      Registry.clear 
     
-    Parser::SourceParser.parse_string <<-eof
-      class YARD
-        CONST1 = 1
-        CONST2 = "hello"
-        CONST4 = 0
-      end
+      Parser::SourceParser.parse_string <<-eof
+        class YARD
+          CONST1 = 1
+          CONST2 = "hello"
+          CONST4 = 0
+        end
       
-      class SUPERYARD < YARD
-        CONST4 = 5
-      end
+        class SUPERYARD < YARD
+          CONST4 = 5
+        end
       
-      class SubYard < SUPERYARD
-        CONST2 = "hi"
-        CONST3 = "foo"
-      end
-    eof
-  end
+        class SubYard < SUPERYARD
+          CONST2 = "hi"
+          CONST3 = "foo"
+        end
+      eof
+    end
   
-  it "should list inherited constants by default" do
-    consts = P(:SubYard).constants
-    consts.should include(P("YARD::CONST1"))
-    consts.should include(P("SubYard::CONST3"))
+    it "should list inherited constants by default" do
+      consts = P(:SubYard).constants
+      consts.should include(P("YARD::CONST1"))
+      consts.should include(P("SubYard::CONST3"))
     
-    consts = P(:SubYard).inherited_constants
-    consts.should include(P("YARD::CONST1"))
-    consts.should_not include(P("YARD::CONST2"))
-    consts.should_not include(P("SubYard::CONST2"))
-    consts.should_not include(P("SubYard::CONST3"))
-  end
+      consts = P(:SubYard).inherited_constants
+      consts.should include(P("YARD::CONST1"))
+      consts.should_not include(P("YARD::CONST2"))
+      consts.should_not include(P("SubYard::CONST2"))
+      consts.should_not include(P("SubYard::CONST3"))
+    end
   
-  it "should not list inherited constants if turned off" do
-    consts = P(:SubYard).constants(:inherited => false)
-    consts.should_not include(P("YARD::CONST1"))
-    consts.should include(P("SubYard::CONST3"))
-  end
+    it "should not list inherited constants if turned off" do
+      consts = P(:SubYard).constants(:inherited => false)
+      consts.should_not include(P("YARD::CONST1"))
+      consts.should include(P("SubYard::CONST3"))
+    end
   
-  it "should not include an inherited constant if it is overridden by the object" do
-    consts = P(:SubYard).constants
-    consts.should include(P("SubYard::CONST2"))
-    consts.should_not include(P("YARD::CONST2"))
-  end
+    it "should not include an inherited constant if it is overridden by the object" do
+      consts = P(:SubYard).constants
+      consts.should include(P("SubYard::CONST2"))
+      consts.should_not include(P("YARD::CONST2"))
+    end
   
-  it "should not include an inherited constant if it is overridden by another subclass" do
-    consts = P(:SubYard).inherited_constants
-    consts.should include(P("SUPERYARD::CONST4"))
-    consts.should_not include(P("YARD::CONST4"))
-  end
+    it "should not include an inherited constant if it is overridden by another subclass" do
+      consts = P(:SubYard).inherited_constants
+      consts.should include(P("SUPERYARD::CONST4"))
+      consts.should_not include(P("YARD::CONST4"))
+    end
   
-  it "should not set a superclass on Object class" do
-    o = ClassObject.new(:root, :Object)
-    o.superclass.should be_nil
-  end
+    it "should not set a superclass on Object class" do
+      o = ClassObject.new(:root, :Object)
+      o.superclass.should be_nil
+    end
   
-  it "should raise ArgumentError if superclass == self" do
-    lambda do
-      o = ClassObject.new(:root, :Object) do |o|
-        o.superclass = :Object
-      end
-    end.should raise_error(ArgumentError)
-  end
+    it "should raise ArgumentError if superclass == self" do
+      lambda do
+        o = ClassObject.new(:root, :Object) do |o|
+          o.superclass = :Object
+        end
+      end.should raise_error(ArgumentError)
+    end
   
-  it "should tell the world if it is an exception class" do
-    o = ClassObject.new(:root, :MyClass) 
-    o2 = ClassObject.new(:root, :OtherClass)
-    o2.superclass = :SystemCallError
-    o3 = ClassObject.new(:root, :StandardError)
-    o3.superclass = :Object
-    o4 = ClassObject.new(:root, :Object)
+    it "should tell the world if it is an exception class" do
+      o = ClassObject.new(:root, :MyClass) 
+      o2 = ClassObject.new(:root, :OtherClass)
+      o2.superclass = :SystemCallError
+      o3 = ClassObject.new(:root, :StandardError)
+      o3.superclass = :Object
+      o4 = ClassObject.new(:root, :Object)
 
-    o.superclass = :Object
-    o.is_exception?.should == false
+      o.superclass = :Object
+      o.is_exception?.should == false
     
-    o.superclass = :Exception
-    o.is_exception?.should == true
+      o.superclass = :Exception
+      o.is_exception?.should == true
     
-    o.superclass = :NoMethodError
-    o.is_exception?.should == true
+      o.superclass = :NoMethodError
+      o.is_exception?.should == true
     
-    o.superclass = o2
-    o.is_exception?.should == true
+      o.superclass = o2
+      o.is_exception?.should == true
     
-    o.superclass = o3
-    o.is_exception?.should == true
-  end
-  
-  it "should not raise ArgumentError if superclass is proxy in different namespace" do
-    lambda do
-      o = ClassObject.new(:root, :X) do |o|
-        o.superclass = P('OTHER::X')
-      end
-    end.should_not raise_error(ArgumentError)
-  end
-end
+      o.superclass = o3
+      o.is_exception?.should == true
+    end
   
+    it "should not raise ArgumentError if superclass is proxy in different namespace" do
+      lambda do
+        o = ClassObject.new(:root, :X) do |o|
+          o.superclass = P('OTHER::X')
+        end
+      end.should_not raise_error(ArgumentError)
+    end
+  end
+end