Class: YARD::Handlers::Base Abstract

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.