Class: YARD::Handlers::Processor
- Inherits:
-
Object
- Object
- YARD::Handlers::Processor
- 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.
Instance Attribute Summary (collapse)
-
- (OpenStruct) extra_state
Share state across different handlers inside of a file.
-
- (String) file
The filename.
-
- (OpenStruct) globals
Handlers can share state for the entire post processing stage through this attribute.
-
- (Boolean) load_order_errors
Whether or not Parser::LoadOrderError is raised.
-
- (CodeObjects::NamespaceObject) namespace
The current namespace.
-
- (CodeObjects::Base?) owner
Unlike the namespace, the owner is a non-namespace object that should be stored between statements.
-
- (Symbol) parser_type
The parser type (:ruby, :ruby18, :c).
-
- (Symbol) scope
The current scope (class, instance).
-
- (Symbol) visibility
The current visibility (public, private, protected).
Class Method Summary (collapse)
-
+ (Object) register_handler_namespace(type, ns)
Registers a new namespace for handlers of the given type.
Instance Method Summary (collapse)
-
- (Array<Base>) find_handlers(statement)
Searches for all handlers in Base.subclasses that match the statement.
-
- (Processor) initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type, globals = nil)
constructor
Creates a new Processor for a file.
-
- (void) process(statements)
Processes a list of statements by finding handlers to process each one.
Constructor Details
- (Processor) initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type, globals = nil)
Creates a new Processor for a file.
105 106 107 108 109 110 111 112 113 114 115 116 117 |
# File 'lib/yard/handlers/processor.rb', line 105 def initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type, globals = nil) @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 = {} @globals = 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.
90 91 92 |
# File 'lib/yard/handlers/processor.rb', line 90 def extra_state @extra_state end |
- (String) file
The filename
40 41 42 |
# File 'lib/yard/handlers/processor.rb', line 40 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
79 80 81 |
# File 'lib/yard/handlers/processor.rb', line 79 def globals @globals end |
- (Boolean) load_order_errors
Whether or not Parser::LoadOrderError is raised
58 59 60 |
# File 'lib/yard/handlers/processor.rb', line 58 def load_order_errors @load_order_errors end |
- (CodeObjects::NamespaceObject) namespace
The current namespace
43 44 45 |
# File 'lib/yard/handlers/processor.rb', line 43 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.
55 56 57 |
# File 'lib/yard/handlers/processor.rb', line 55 def owner @owner end |
- (Symbol) parser_type
The parser type (:ruby, :ruby18, :c)
61 62 63 |
# File 'lib/yard/handlers/processor.rb', line 61 def parser_type @parser_type end |
- (Symbol) scope
The current scope (class, instance)
49 50 51 |
# File 'lib/yard/handlers/processor.rb', line 49 def scope @scope end |
- (Symbol) visibility
The current visibility (public, private, protected)
46 47 48 |
# File 'lib/yard/handlers/processor.rb', line 46 def visibility @visibility end |
Class Method Details
+ (Object) register_handler_namespace(type, ns)
Registers a new namespace for handlers of the given type.
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) && handler.matches_file?(file) && 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.
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 |
# File 'lib/yard/handlers/processor.rb', line 124 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.}" 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 |