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. You can also access extra stateful properties that any handler can set during the duration of the post processing of a file from #extra_state. If you need to access state across different files, look at #globals.

See Also:

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Processor) initialize(parser)

Creates a new Processor for a file.



92
93
94
95
96
97
98
99
100
101
102
103
# File 'lib/yard/handlers/processor.rb', line 92

def initialize(parser)
  @file = parser.file || "(stdin)"
  @namespace = YARD::Registry.root
  @visibility = :public
  @scope = :instance
  @owner = @namespace
  @parser_type = parser.parser_type
  @handlers_loaded = {}
  @globals = parser.globals || OpenStruct.new
  @extra_state = OpenStruct.new
  load_handlers
end

Instance Attribute Details

- (OpenStruct) extra_state

Share state across different handlers inside of a file. This attribute is similar to #visibility, #scope, #namespace and #owner, in that they all maintain state across all handlers for the entire source file. Use this attribute to store any data your handler might need to save during the parsing of a file. If you need to save state across files, see #globals.

See Also:



88
89
90
# File 'lib/yard/handlers/processor.rb', line 88

def extra_state
  @extra_state
end

- (String) file



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

def file
  @file
end

- (OpenStruct) globals

Handlers can share state for the entire post processing stage through this attribute. Note that post processing stage spans multiple files. To share state only within a single file, use #extra_state

Examples:

Sharing state among two handlers

class Handler1 < YARD::Handlers::Ruby::Base
  handles :class
  process { globals.foo = :bar }
end

class Handler2 < YARD::Handlers::Ruby::Base
  handles :method
  process { puts globals.foo }
end

See Also:



77
78
79
# File 'lib/yard/handlers/processor.rb', line 77

def globals
  @globals
end

- (CodeObjects::NamespaceObject) namespace



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

def namespace
  @namespace
end

- (CodeObjects::Base?) owner



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

def owner
  @owner
end

- (Symbol) parser_type



59
60
61
# File 'lib/yard/handlers/processor.rb', line 59

def parser_type
  @parser_type
end

- (Symbol) scope



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

def scope
  @scope
end

- (Symbol) visibility



47
48
49
# File 'lib/yard/handlers/processor.rb', line 47

def visibility
  @visibility
end

Class Method Details

+ (Object) register_handler_namespace(type, ns)

Registers a new namespace for handlers of the given type.

Since:

  • 0.6.0



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

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

Instance Method Details

- (Array<Base>) find_handlers(statement)

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



152
153
154
155
156
157
158
# File 'lib/yard/handlers/processor.rb', line 152

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

- (void) parse_remaining_files

This method returns an undefined value.

Continue parsing the remainder of the files in the globals.ordered_parser object. After the remainder of files are parsed, processing will continue on the current file.



141
142
143
144
145
146
# File 'lib/yard/handlers/processor.rb', line 141

def parse_remaining_files
  if globals.ordered_parser
    globals.ordered_parser.parse
    log.debug("Re-processing #{@file}...")
  end
end

- (void) process(statements)

This method returns an undefined value.

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



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
# File 'lib/yard/handlers/processor.rb', line 110

def process(statements)
  statements.each_with_index do |stmt, index|
    find_handlers(stmt).each do |handler|
      begin
        handler.new(self, stmt).process
      rescue HandlerAborted => abort
        log.debug "#{handler.to_s} cancelled from #{caller.last}"
        log.debug "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
      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