class YARD::Verifier

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:

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

Constants

NILCLASS_METHODS

@private

Attributes

expressions[R]

@return [Array<String>] a list of all expressions the verifier checks for @since 0.5.6

o[R]

@return [CodeObjects::Base] the current object being tested

object[R]

@return [CodeObjects::Base] the current object being tested

Public Class Methods

new(*expressions) click to toggle source

Creates a verifier from a set of expressions

@param [Array<String>] expressions a list of Ruby expressions to

parse.
# File lib/yard/verifier.rb, line 48
def initialize(*expressions)
  @expressions = []
  add_expressions(*expressions)
end

Public Instance Methods

add_expressions(*expressions) click to toggle source

Adds a set of expressions and recompiles the verifier

@param [Array<String>] expressions a list of expressions @return [void] @since 0.5.6

# File lib/yard/verifier.rb, line 58
def add_expressions(*expressions)
  self.expressions += expressions.flatten
end
call(object) click to toggle source

Tests the expressions on the object.

@note If the object is a {CodeObjects::Proxy} the result will always be true. @param [CodeObjects::Base] object the object to verify @return [Boolean] the result of the expressions

# 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
expressions=(value) click to toggle source
# File lib/yard/verifier.rb, line 39
def expressions=(value)
  @expressions = value
  create_method_from_expressions
end
method_missing(sym, *args, &block) click to toggle source

Passes any method calls to the object from the {#call}

Calls superclass method
# 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
run(list) click to toggle source

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

@param [Array<CodeObjects::Base>] list a list of code objects @return [Array<CodeObjects::Base>] a list of code objects that match

the verifier.
# File lib/yard/verifier.rb, line 91
def run(list)
  list.reject {|item| call(item).is_a?(FalseClass) }
end

Private Instance Methods

create_method_from_expressions() click to toggle source

Creates the __execute method by evaluating the expressions as Ruby code @return [void]

# 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() click to toggle source

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 [void]

# 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) click to toggle source

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

# 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
unmodify_nilclass() click to toggle source

Returns the state of NilClass back to normal @return [void]

# 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