Class: YARD::Handlers::Base Abstract
- Inherits:
-
Object
- Object
- YARD::Handlers::Base
- Includes:
- CodeObjects, Parser
- Defined in:
- lib/yard/handlers/base.rb
Overview
Subclass this class to provide a handler for YARD to use during the processing phase.
Handlers are pluggable semantic parsers for YARD's code generation phase. They allow developers to control what information gets generated by YARD, giving them the ability to, for instance, document any Ruby DSLs that a customized framework may use. A good example of this would be the ability to document and generate meta data for the 'describe' declaration of the RSpec testing framework by simply adding a handler for such a keyword. Similarly, any Ruby API that takes advantage of class level declarations could add these to the documentation in a very explicit format by treating them as first- class objects in any outputted documentation.
Overview of a Typical Handler Scenario
Generally, a handler class will declare a set of statements which it will handle using the handles class declaration. It will then implement the #process method to do the work. The processing would usually involve the manipulation of the #namespace, #owner code objects or the creation of new ones, in which case they should be registered by #register, a method that sets some basic attributes for the new objects.
Handlers are usually simple and take up to a page of code to process and register a new object or add new attributes to the current namespace.
Setting up a Handler for Use
A Handler is automatically registered when it is subclassed from the base class. The only other thing that needs to be done is to specify which statement the handler will process. This is done with the handles declaration, taking either a Parser::Ruby::Legacy::RubyToken, String or `Regexp`. Here is a simple example which processes module statements.
class MyModuleHandler < YARD::Handlers::Base handles TkMODULE def process # do something end end
Processing Handler Data
The goal of a specific handler is really up to the developer, and as such there is no real guideline on how to process the data. However, it is important to know where the data is coming from to be able to use it.
statement Attribute
The statement attribute pertains to the Parser::Ruby::Legacy::Statement object containing a set of tokens parsed in by the parser. This is the main set of data to be analyzed and processed. The comments attached to the statement can be accessed by the Parser::Ruby::Legacy::Statement#comments method, but generally the data to be processed will live in the tokens attribute. This list can be converted to a String using #to_s to parse the data with regular expressions (or other text processing mechanisms), if needed.
namespace Attribute
The namespace attribute is a namespace object which represents the current namespace that the parser is in. For instance:
module SomeModule class MyClass def mymethod; end end end
If a handler was to parse the 'class MyClass' statement, it would be necessary to know that it belonged inside the SomeModule module. This is the value that namespace would return when processing such a statement. If the class was then entered and another handler was called on the method, the namespace would be set to the 'MyClass' code object.
owner Attribute
The owner attribute is similar to the namespace attribute in that it also follows the scope of the code during parsing. However, a namespace object is loosely defined as a module or class and YARD has the ability to parse beyond module and class blocks (inside methods, for instance), so the owner attribute would not be limited to modules and classes.
To put this into context, the example from above will be used. If a method handler was added to the mix and decided to parse inside the method body, the owner would be set to the method object but the namespace would remain set to the class. This would allow the developer to process any method definitions set inside a method (def x; def y; 2 end end) by adding them to the correct namespace (the class, not the method).
In summary, the distinction between namespace and owner can be thought of as the difference between first-class Ruby objects (namespaces) and second-class Ruby objects (methods).
visibility and scope Attributes
Mainly needed for parsing methods, the visibility and scope attributes refer to the public/protected/private and class/instance values (respectively) of the current parsing position.
Parsing Blocks in Statements
In addition to parsing a statement and creating new objects, some handlers may wish to continue parsing the code inside the statement's block (if there is one). In this context, a block means the inside of any statement, be it class definition, module definition, if statement or classic 'Ruby block'.
For example, a class statement would be "class MyClass" and the block would be a list of statements including the method definitions inside the class. For a class handler, the programmer would execute the #parse_block method to continue parsing code inside the block, with the namespace now pointing to the class object the handler created.
YARD has the ability to continue into any block: class, module, method, even if statements. For this reason, the block parsing method must be invoked explicitly out of efficiency sake.
Direct Known Subclasses
Constant Summary
Constants included from CodeObjects
BUILTIN_ALL, BUILTIN_CLASSES, BUILTIN_EXCEPTIONS, BUILTIN_EXCEPTIONS_HASH, BUILTIN_MODULES, CONSTANTMATCH, CSEP, CSEPQ, ISEP, ISEPQ, METHODMATCH, METHODNAMEMATCH, NAMESPACEMATCH, NSEP, NSEPQ
Instance Attribute Summary (collapse)
-
- (OpenStruct) extra_state
readonly
protected
Share state across different handlers inside of a file.
-
- (OpenStruct) globals
readonly
protected
Handlers can share state for the entire post processing stage through this attribute.
-
- (CodeObjects::NamespaceObject) namespace
protected
The current namespace.
-
- (CodeObjects::Base?) owner
protected
Unlike the namespace, the owner is a non-namespace object that should be stored between statements.
-
- (Processor) parser
readonly
protected
The processor object that manages all global state during handling.
-
- (Symbol) scope
protected
The current scope (class, instance).
-
- (Object) statement
readonly
protected
The statement object currently being processed.
-
- (Symbol) visibility
protected
The current visibility (public, private, protected).
Macro Support (collapse)
-
- (Array<String>) call_params
protected
Abstract
A list of argument names.
- - (String?) caller_method protected Abstract
-
- (void) expand_macro(object, macro)
protected
Sets the docstring on object to the expanded macro.
-
- (CodeObjects::MacroObject?) find_or_create_macro(object_or_docstring)
protected
Attempts to find or create a macro if a @macro tag is found in the docstring (or the object's docstring).
Class Method Summary (collapse)
-
+ (void) clear_subclasses
Clear all registered subclasses.
-
+ (Array) handlers
A list of matchers for the handler object.
-
+ (Object) handles(*matches)
Declares the statement type which will be processed by this handler.
-
+ (Boolean) handles?(statement)
This class is implemented by Ruby::Base and Ruby::Legacy::Base.
-
+ (void) in_file(filename)
Declares that a handler should only be called when inside a filename by its basename or a regex match for the full path.
-
+ (Boolean) matches_file?(filename)
Whether the filename matches the declared file match for a handler.
-
+ (void) namespace_only
Declares that the handler should only be called when inside a CodeObjects::NamespaceObject, not a method body.
-
+ (Boolean) namespace_only?
Whether the handler should only be processed inside a namespace.
-
+ (void) process(&block)
Generates a process method, equivalent to +def process; ...
-
+ (Array<Base>) subclasses
Returns all registered handler subclasses.
Instance Method Summary (collapse)
-
- (Object) ensure_loaded!(object, max_retries = 1)
protected
Ensures that a specific object has been parsed and loaded into the registry.
-
- (Base) initialize(source_parser, stmt)
constructor
A new instance of Base.
-
- (Object) parse_block(*args)
Abstract
Parses the semantic "block" contained in the statement node.
-
- (Array<CodeObjects::Base>, ...) process
The main handler method called by the parser on a statement that matches the handles declaration.
-
- (Object) push_state(opts = {}, &block) { ... }
protected
Executes a given block with specific state values for #owner, #namespace and #scope.
-
- (CodeObjects::Base+) register(*objects)
protected
Do some post processing on a list of code objects.
Constructor Details
- (Base) initialize(source_parser, stmt)
A new instance of Base
268 269 270 271 |
# File 'lib/yard/handlers/base.rb', line 268 def initialize(source_parser, stmt) @parser = source_parser @statement = stmt end |
Instance Attribute Details
- (OpenStruct) extra_state (readonly, protected)
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.
327 |
# File 'lib/yard/handlers/base.rb', line 327 def extra_state; parser.extra_state end |
- (OpenStruct) globals (readonly, protected)
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
324 |
# File 'lib/yard/handlers/base.rb', line 324 def globals; parser.globals end |
- (CodeObjects::NamespaceObject) namespace (protected)
The current namespace
315 |
# File 'lib/yard/handlers/base.rb', line 315 def namespace; parser.namespace end |
- (CodeObjects::Base?) owner (protected)
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.
312 |
# File 'lib/yard/handlers/base.rb', line 312 def owner; parser.owner end |
- (Processor) parser (readonly, protected)
The processor object that manages all global state during handling.
304 305 306 |
# File 'lib/yard/handlers/base.rb', line 304 def parser @parser end |
- (Symbol) scope (protected)
The current scope (class, instance)
321 |
# File 'lib/yard/handlers/base.rb', line 321 def scope; parser.scope end |
- (Object) statement (readonly, protected)
The statement object currently being processed. Usually refers to one semantic language statement, though the strict definition depends on the parser used.
309 310 311 |
# File 'lib/yard/handlers/base.rb', line 309 def statement @statement end |
- (Symbol) visibility (protected)
The current visibility (public, private, protected)
318 |
# File 'lib/yard/handlers/base.rb', line 318 def visibility; parser.visibility end |
Class Method Details
+ (void) clear_subclasses
This method returns an undefined value.
Clear all registered subclasses. Testing purposes only
152 153 154 |
# File 'lib/yard/handlers/base.rb', line 152 def clear_subclasses @@subclasses = [] end |
+ (Array) handlers
A list of matchers for the handler object.
204 205 206 |
# File 'lib/yard/handlers/base.rb', line 204 def handlers @handlers ||= [] end |
+ (Object) handles(*matches)
Declares the statement type which will be processed by this handler.
A match need not be unique to a handler. Multiple handlers can process the same statement. However, in this case, care should be taken to make sure that #parse_block would only be executed by one of the handlers, otherwise the same code will be parsed multiple times and slow YARD down.
185 186 187 |
# File 'lib/yard/handlers/base.rb', line 185 def handles(*matches) (@handlers ||= []).push(*matches) end |
+ (Boolean) handles?(statement)
This class is implemented by Ruby::Base and Ruby::Legacy::Base. To implement a base handler class for another language, implement this method to return true if the handler should process the given statement object. Use handlers to enumerate the matchers declared for the handler class.
198 199 200 |
# File 'lib/yard/handlers/base.rb', line 198 def handles?(statement) raise NotImplementedError, "override #handles? in a subclass" end |
+ (void) in_file(filename)
This method returns an undefined value.
Declares that a handler should only be called when inside a filename by its basename or a regex match for the full path.
228 229 230 |
# File 'lib/yard/handlers/base.rb', line 228 def in_file(filename) (@in_files ||= []) << filename end |
+ (Boolean) matches_file?(filename)
Whether the filename matches the declared file match for a handler. If no file match is specified, returns true.
235 236 237 238 239 240 241 242 243 244 245 246 247 |
# File 'lib/yard/handlers/base.rb', line 235 def matches_file?(filename) return true unless @in_files @in_files.any? do |in_file| case in_file when String File.basename(filename) == in_file when Regexp filename =~ in_file else true end end end |
+ (void) namespace_only
This method returns an undefined value.
Declares that the handler should only be called when inside a CodeObjects::NamespaceObject, not a method body.
212 213 214 |
# File 'lib/yard/handlers/base.rb', line 212 def namespace_only @namespace_only = true end |
+ (Boolean) namespace_only?
Whether the handler should only be processed inside a namespace.
218 219 220 |
# File 'lib/yard/handlers/base.rb', line 218 def namespace_only? (@namespace_only ||= false) ? true : false end |
+ (void) process(&block)
This method returns an undefined value.
Generates a process method, equivalent to def process; ... end. Blocks defined with this syntax will be wrapped inside an anonymous module so that the handler class can be extended with mixins that override the process method without alias chaining.
261 262 263 264 265 |
# File 'lib/yard/handlers/base.rb', line 261 def process(&block) mod = Module.new mod.send(:define_method, :process, &block) include mod end |
Instance Method Details
- (Array<String>) call_params (protected)
Implement this method to return the parameters in a method call statement. It should return an empty list if the statement is not a method call.
A list of argument names
506 507 508 |
# File 'lib/yard/handlers/base.rb', line 506 def call_params raise NotImplementedError end |
- (String?) caller_method (protected)
Implement this method to return the method being called in a method call. It should return nil if the statement is not a method call.
515 516 517 |
# File 'lib/yard/handlers/base.rb', line 515 def caller_method raise NotImplementedError end |
- (Object) ensure_loaded!(object, max_retries = 1) (protected)
Ensures that a specific object has been parsed and loaded into the registry. This is necessary when adding data to a namespace, for instance, since the namespace may not have been processed yet (it can be located in a file that has not been handled).
Calling this method defers the handler until all other files have been processed. If the object gets resolved, the rest of the handler continues, otherwise an exception is raised.
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 |
# File 'lib/yard/handlers/base.rb', line 469 def ensure_loaded!(object, max_retries = 1) return if object.root? return object unless object.is_a?(Proxy) unless parser.load_order_errors if object.is_a?(Proxy) raise NamespaceMissingError, object else nil end end unless CONTINUATIONS_SUPPORTED log.warn_no_continuations raise NamespaceMissingError, object end retries = 0 context = callcc {|c| c } retries += 1 if object.is_a?(Proxy) if retries <= max_retries log.debug "Missing object #{object} in file `#{parser.file}', moving it to the back of the line." raise Parser::LoadOrderError.new(context) else raise NamespaceMissingError, object end end object end |
- (void) expand_macro(object, macro) (protected)
This method returns an undefined value.
Sets the docstring on object to the expanded macro.
561 562 563 564 565 566 |
# File 'lib/yard/handlers/base.rb', line 561 def (object, macro) return unless macro all_params = ([caller_method] + call_params).compact data = MacroObject.apply_macro(macro, object.docstring, all_params, statement.source) object.docstring = Docstring.new(data, object) end |
- (CodeObjects::MacroObject?) find_or_create_macro(object_or_docstring) (protected)
Attempts to find or create a macro if a @macro tag is found in the docstring (or the object's docstring).
526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 |
# File 'lib/yard/handlers/base.rb', line 526 def find_or_create_macro(object_or_docstring) if object_or_docstring.is_a?(Docstring) object, docstring = nil, object_or_docstring else object, docstring = object_or_docstring, object_or_docstring.docstring end return unless macro_tag = docstring.tag(:macro) unless macro_tag.name if object log.warn "Invalid/missing macro name for #{object.path} (#{parser.file}:#{statement.line})" return nil else raise UndocumentableError, 'method/attribute, missing macro name' end end caller_obj = caller_method ? P(namespace, caller_method) : nil if macro = MacroObject.find_or_create(docstring, caller_obj) attached_method_name = caller_method if object && object.is_a?(MethodObject) && object.scope == :class macro.method_object = object attached_method_name = object.name.to_s end if macro.attached? globals.__attached_macros ||= {} globals.__attached_macros[attached_method_name] ||= [] globals.__attached_macros[attached_method_name] |= [macro] end end macro end |
- (Object) parse_block(*args)
Subclasses should call parser.process
Parses the semantic "block" contained in the statement node.
296 297 298 |
# File 'lib/yard/handlers/base.rb', line 296 def parse_block(*args) raise NotImplementedError, "#{self} did not implement a #parse_block method for handling" end |
- (Array<CodeObjects::Base>, ...) process
The main handler method called by the parser on a statement that matches the handles declaration.
Subclasses should override this method to provide the handling functionality for the class.
289 290 291 |
# File 'lib/yard/handlers/base.rb', line 289 def process raise NotImplementedError, "#{self} did not implement a #process method for handling." end |
- (Object) push_state(opts = {}, &block) { ... } (protected)
Executes a given block with specific state values for #owner, #namespace and #scope.
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 |
# File 'lib/yard/handlers/base.rb', line 355 def push_state(opts = {}, &block) opts = { :namespace => namespace, :scope => :instance, :owner => owner || namespace }.update(opts) ns, vis, sc, oo = namespace, visibility, scope, owner self.namespace = opts[:namespace] self.visibility = :public self.scope = opts[:scope] self.owner = opts[:owner] yield self.namespace = ns self.visibility = vis self.scope = sc self.owner = oo end |
- (CodeObjects::Base+) register(*objects) (protected)
Do some post processing on a list of code objects. Adds basic attributes to the list of objects like the filename, line number, CodeObjects::Base#dynamic, source code and CodeObjects::Base#docstring, but only if they don't exist.
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 |
# File 'lib/yard/handlers/base.rb', line 388 def register(*objects) objects.flatten.each do |object| next unless object.is_a?(CodeObjects::Base) begin ensure_loaded!(object.namespace) object.namespace.children << object rescue NamespaceMissingError end # Yield the object to the calling block because ruby will parse the syntax # # register obj = ClassObject.new {|o| ... } # # as the block for #register. We need to make sure this gets to the object. yield(object) if block_given? object.add_file(parser.file, statement.line, statement.comments) # Add docstring if there is one. if statement.comments object.docstring = Docstring.new(statement.comments, object) end # Expand/create any @macro tags (object, find_or_create_macro(object)) # Add hash_flag/line_range if statement.comments object.docstring.hash_flag = statement.comments_hash_flag object.docstring.line_range = statement.comments_range end # Add group information if statement.group unless object.namespace.is_a?(Proxy) object.namespace.groups |= [statement.group] end object.group = statement.group end # Add transitive tags Tags::Library..each do |tag| next if object.namespace.is_a?(Proxy) next unless object.namespace.has_tag?(tag) next if object.has_tag?(tag) object.docstring.add_tag(*object.namespace.(tag)) end # Add source only to non-class non-module objects unless object.is_a?(NamespaceObject) object.source ||= statement end # Make it dynamic if its owner is not its namespace. # This generally means it was defined in a method (or block of some sort) object.dynamic = true if owner != namespace end objects.size == 1 ? objects.first : objects end |