Class: YARD::Handlers::Processor

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/handlers/processor.rb

Overview

Iterates over all statements in a file and delegates them to the Handlers::Base objects that are registered to handle the statement.

This class is passed to each handler and keeps overall processing state. For example, if the #visibility is set in a handler, all following statements will have access to this state. This allows “public”, “protected” and “private” statements to be handled in classes and modules. In addition, the #namespace can be set during parsing to control where objects are being created from.

See Also:

Instance Attribute Summary

Instance Method Summary

Constructor Details

- (Processor) initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type)

Creates a new Processor for a file.

Parameters:

  • (String) file (defaults to: nil) — the name of the file that is being processed. uses ’(stdin)’ if file is nil.
  • (Boolean) load_order_error — whether or not to raise Parser::LoadOrderError when a file has unresolved references that need to be parsed first. If these errors are raised, the processor will attempt to load all other files before continuing to parse the file.
  • (Symbol) parser_type (defaults to: Parser::SourceParser.parser_type) — the parser type (:ruby, :ruby18, :c) from the parser. Used to select the handler (since handlers are specific to a parser type). 


50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/yard/handlers/processor.rb', line 50

def initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type)
  @file = file || "(stdin)"
  @namespace = YARD::Registry.root
  @visibility = :public
  @scope = :instance
  @owner = @namespace
  @load_order_errors = load_order_errors
  @parser_type = parser_type
  @handlers_loaded = {}
  load_handlers
end

Instance Attribute Details

- (String) file

The filename

Returns:



16
17
18
 
# File 'lib/yard/handlers/processor.rb', line 16

def file
  @file
end

- (Boolean) load_order_errors

Whether or not Parser::LoadOrderError is raised

Returns:



34
35
36
 
# File 'lib/yard/handlers/processor.rb', line 34

def load_order_errors
  @load_order_errors
end

- (CodeObjects::NamespaceObject) namespace

The current namespace

Returns:



19
20
21
 
# File 'lib/yard/handlers/processor.rb', line 19

def namespace
  @namespace
end

- (CodeObjects::Base?) owner

Unlike the namespace, the owner is a non-namespace object that should be stored between statements. For instance, when parsing a method body, the CodeObjects::MethodObject is set as the owner, in case any extra method information is processed.

Returns:

  • (CodeObjects::Base, nil) — unlike the namespace, the owner is a non-namespace object that should be stored between statements. For instance, when parsing a method body, the CodeObjects::MethodObject is set as the owner, in case any extra method information is processed. 


31
32
33
 
# File 'lib/yard/handlers/processor.rb', line 31

def owner
  @owner
end

- (Symbol) parser_type

The parser type (:ruby, :ruby18 or :c)

Returns:

  • (Symbol) — the parser type (:ruby, :ruby18 or :c) 


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

def parser_type
  @parser_type
end

- (Symbol) scope

The current scope

Returns:

  • (Symbol) — the current scope 


25
26
27
 
# File 'lib/yard/handlers/processor.rb', line 25

def scope
  @scope
end

- (Symbol) visibility

The current visibility

Returns:

  • (Symbol) — the current visibility 


22
23
24
 
# File 'lib/yard/handlers/processor.rb', line 22

def visibility
  @visibility
end

Instance Method Details

- (Array<Base>) find_handlers(statement)

Searches for all handlers in Base.subclasses that match the statement

Parameters:

  • statement — the statement object to match.

Returns:

  • (Array<Base>) — a list of handlers to process the statement with. 


95
96
97
98
99
100
101
 
# File 'lib/yard/handlers/processor.rb', line 95

def find_handlers(statement)
  Base.subclasses.find_all do |handler|
    handler_base_class > handler &&
    (handler.namespace_only? ? owner.is_a?(CodeObjects::NamespaceObject) : true) &&
    handler.handles?(statement)
  end
end

- (void) process(statements)

This method returns an undefined value.

Processes a list of statements by finding handlers to process each one.

Parameters:

  • (Array) statements — a list of statements 


67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/yard/handlers/processor.rb', line 67

def process(statements)
  statements.each_with_index do |stmt, index|
    find_handlers(stmt).each do |handler| 
      begin
        handler.new(self, stmt).process
      rescue Parser::LoadOrderError => loaderr
        raise # Pass this up
      rescue NamespaceMissingError => missingerr
        log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized." 
        log.warn "If this class/method is part of your source tree, this will affect your documentation results." 
        log.warn "You can correct this issue by loading the source file for this object before `#{file}'"
        log.warn 
      rescue Parser::UndocumentableError => undocerr
        log.warn "in #{handler.to_s}: Undocumentable #{undocerr.message}"
        log.warn "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
      rescue => e
        log.error "Unhandled exception in #{handler.to_s}:"
        log.error "  in `#{file}`:#{stmt.line}:\n\n#{stmt.show}\n"
        log.backtrace(e)
      end
    end
  end
end