123456789_123456789_123456789_123456789_123456789_

Class: YARD::Verifier

Relationships & Source Files
Inherits: Object
Defined in: lib/yard/verifier.rb

Overview

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)

Examples:

Create a verifier to check for objects that don't have @private tags

verifier = Verifier.new('!@private')
verifier.call(object) # => true (no @private tag)

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?')

Check if there are any @param tags

Verifier.new('@@param.empty?')
# Equivalent to:
Verifier.new('object.tags(:param).empty?')

Using object or o to look up object attributes directly

Verifier.new('object.docstring == "hello world"')
# Equivalent to:
Verifier.new('o.docstring == "hello world"')

Without using object or o

Verifier.new('tag(:return).size == 1 || has_tag?(:author)')

Specifying multiple expressions

Verifier.new('@return', '@param', '@yield')
# Equivalent to:
Verifier.new('@return && @param && @yield')

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(*expressions) ⇒ Verifier

Creates a verifier from a set of expressions

Parameters:

  • expressions (Array<String>) —

    a list of Ruby expressions to parse.

[ GitHub ] 

  


# File 'lib/yard/verifier.rb', line 48



def initialize(*expressions)
  @expressions = []
  add_expressions(*expressions)
end


  







Dynamic Method Handling

  

    This class handles dynamic methods through the method_missing method




  

    #method_missing(sym, *args, &block)  
  



  

    
Passes any method calls to the object from the #call


  



  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 63



def method_missing(sym, *args, &block)
  if object.respond_to?(sym)
    object.send(sym, *args, &block)
  else
    super
  end
end


  







Instance Attribute Details



  

    #expressions  ⇒ Array<String>  (rw)
  



  

    
  





  
Returns:


    
  
  • 
    (Array<String>)
—    
    a list of all expressions the verifier checks for
    

    
  
    • 



Since:


    
  
  • 
    
    0.5.6
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 37



attr_reader :expressions


  








  

    #expressions=(value)   (rw)
  

  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 39



def expressions=(value)
  @expressions = value
  create_method_from_expressions
end


  







Instance Method Details



  

    #add_expressions(*expressions)  ⇒ void 
  



  

    
This method returns an undefined value.
Adds a set of expressions and recompiles the verifier


  





  
Parameters:


    
  
  • 
    expressions
    (Array<String>)
—    
    a list of expressions
    

    
  
    • 



Since:


    
  
  • 
    
    0.5.6
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 58



def add_expressions(*expressions)
  self.expressions += expressions.flatten
end


  








  

    #call(object)  ⇒ Boolean 
  



  

    
  

    Note:
    
If the object is a CodeObjects::Proxy the result will always be true.



  



Tests the expressions on the object.


  





  
Parameters:



Returns:


    
  
  • 
    (Boolean)
—    
    the result of the expressions
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 76



def call(object)
  return true if object.is_a?(CodeObjects::Proxy)
  modify_nilclass
  @object = object
  retval = __execute ? true : false
  unmodify_nilclass
  retval
end


  








  

    #create_method_from_expressions  ⇒ void  (private)
  



  

    
This method returns an undefined value.
Creates the __execute method by evaluating the expressions
as Ruby code


  





  


  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 130



def create_method_from_expressions
  expr = expressions.map {|e| "(#{parse_expression(e)})" }.join(" && ")

  instance_eval(<<-eof, __FILE__, __LINE__ + 1)
    begin; undef __execute; rescue NameError; end
    def __execute; #{expr}; end
  eof
end


  








  

    #modify_nilclass  ⇒ void  (private)
  



  

    
This method returns an undefined value.
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


  





  


  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 112



def modify_nilclass
  NILCLASS_METHODS.each do |meth|
    NilClass.send(:define_method, meth) {|*args| }
  end
end


  








  

    #parse_expression(expr)  ⇒ String  (private)
  



  

    
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)


  





  
Returns:


    
  
  • 
    (String)
—    
    the parsed expression
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 145



def parse_expression(expr)
  expr = expr.gsub(/@@(?:(\w+)|\{([\w\.]+)\})/, 'object.tags("\1\2")')
  expr = expr.gsub(/@(?:(\w+)|\{([\w\.]+)\})/, 'object.tag("\1\2")')
  expr
end


  








  

    #run(list)  ⇒ Array<CodeObjects::Base> 
  



  

    
Runs a list of objects against the verifier and returns the subset
of verified objects.


  





  
Parameters:



Returns:





  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 91



def run(list)
  list.reject {|item| call(item).is_a?(FalseClass) }
end


  








  

    #unmodify_nilclass  ⇒ void  (private)
  



  

    
This method returns an undefined value.
Returns the state of NilClass back to normal


  





  


  [ GitHub ]


  

  


# File 'lib/yard/verifier.rb', line 120



def unmodify_nilclass
  NILCLASS_METHODS.each do |meth|
    next unless nil.respond_to?(meth)
    NilClass.send(:remove_method, meth)
  end
end