Class: YARD::Verifier

Inherits:
Object
  • Object
show all
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')

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*expressions) ⇒ Verifier

Creates a verifier from a set of expressions

Parameters:

  • expressions (Array<String>) —

    a list of Ruby expressions to parse.



48
49
50
51
 
# 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) ⇒ Object

Passes any method calls to the object from the #call



63
64
65
66
67
68
69
 
# 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>

Returns a list of all expressions the verifier checks for.

Returns:

  • (Array<String>) —

    a list of all expressions the verifier checks for

Since:

  • 0.5.6



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

def expressions
  @expressions
end

#object ⇒ CodeObjects::Base (readonly, protected) Also known as: o

Returns the current object being tested.

Returns:



98
99
100
 
# File 'lib/yard/verifier.rb', line 98

def object
  @object
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



58
59
60
 
# 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



76
77
78
79
80
81
82
83
 
# 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

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

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

Parameters:

Returns:



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

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