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 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 collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Creates a new Processor for a file.

Parameters:

  • file (String) (defaults to: nil) —

    the name of the file that is being processed. uses ‘(stdin)’ if file is nil.

  • load_order_error (Boolean) —

    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.

  • parser_type (Symbol) (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).



69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/yard/handlers/processor.rb', line 69

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

#file ⇒ String

Returns the filename.

Returns:



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

def file
  @file
end

#load_order_errors ⇒ Boolean

Returns whether or not Parser::LoadOrderError is raised.

Returns:



53
54
55
 
# File 'lib/yard/handlers/processor.rb', line 53

def load_order_errors
  @load_order_errors
end

#namespace ⇒ CodeObjects::NamespaceObject

Returns the current namespace.

Returns:



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

def namespace
  @namespace
end

#owner ⇒ CodeObjects::Base?

Returns 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.



50
51
52
 
# File 'lib/yard/handlers/processor.rb', line 50

def owner
  @owner
end

#parser_type ⇒ Symbol

Returns the parser type (:ruby, :ruby18, :c).

Returns:

  • (Symbol) —

    the parser type (:ruby, :ruby18, :c)



56
57
58
 
# File 'lib/yard/handlers/processor.rb', line 56

def parser_type
  @parser_type
end

#scope ⇒ Symbol

Returns the current scope (class, instance).

Returns:

  • (Symbol) —

    the current scope (class, instance)



44
45
46
 
# File 'lib/yard/handlers/processor.rb', line 44

def scope
  @scope
end

#visibility ⇒ Symbol

Returns the current visibility (public, private, protected).

Returns:

  • (Symbol) —

    the current visibility (public, private, protected)



41
42
43
 
# File 'lib/yard/handlers/processor.rb', line 41

def visibility
  @visibility
end

Class Method Details

.register_handler_namespace(type, ns) ⇒ Object

Registers a new namespace for handlers of the given type.

Since:

  • 0.6.0



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

def register_handler_namespace(type, ns)
  namespace_for_handler[type] = ns
end

Instance Method Details

#find_handlers(statement) ⇒ Array<Base>

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.



114
115
116
117
118
119
120
 
# File 'lib/yard/handlers/processor.rb', line 114

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

#process(statements) ⇒ void

This method returns an undefined value.

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

Parameters:

  • statements (Array) —

    a list of statements



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/yard/handlers/processor.rb', line 86

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