Class: YARD::Handlers::Base

### Home Classes Methods

### In Files

- lib/yard/handlers/base.rb

### Parent

Object

### Methods

- ::clear_subclasses
- ::handlers
- ::handles
- ::handles?
- ::in_file
- ::inherited
- ::matches_file?
- ::namespace_only
- ::namespace_only?
- ::new
- ::process
- ::subclasses
- #abort!
- #call_params
- #caller_method
- #ensure_loaded!
- #namespace=
- #owner=
- #parse_block
- #process
- #push_state
- #register
- #register_docstring
- #register_dynamic
- #register_ensure_loaded
- #register_file_info
- #register_group
- #register_module_function
- #register_source
- #register_transitive_tags
- #register_visibility
- #scope=
- #visibility=

### Included Modules

- YARD::CodeObjects
- YARD::Parser

### Files

- LICENSE.txt
- MIT.txt

### Class/Module Index

Quicksearch

- YARD
- YARD::CLI
- YARD::CLI::Command
- YARD::CLI::CommandParser
- YARD::CLI::Config
- YARD::CLI::Diff
- YARD::CLI::Display
- YARD::CLI::Gems
- YARD::CLI::Graph
- YARD::CLI::GraphOptions
- YARD::CLI::Help
- YARD::CLI::I18n
- YARD::CLI::List
- YARD::CLI::MarkupTypes
- YARD::CLI::Server
- YARD::CLI::Stats
- YARD::CLI::YRI
- YARD::CLI::Yardoc
- YARD::CLI::YardocOptions
- YARD::CLI::YardoptsCommand
- YARD::CodeObjects
- YARD::CodeObjects::Base
- YARD::CodeObjects::ClassObject
- YARD::CodeObjects::ClassVariableObject
- YARD::CodeObjects::CodeObjectList
- YARD::CodeObjects::ConstantObject
- YARD::CodeObjects::ExtendedMethodObject
- YARD::CodeObjects::ExtraFileObject
- YARD::CodeObjects::MacroObject
- YARD::CodeObjects::MethodObject
- YARD::CodeObjects::ModuleObject
- YARD::CodeObjects::NamespaceObject
- YARD::CodeObjects::Proxy
- YARD::CodeObjects::ProxyMethodError
- YARD::CodeObjects::RootObject
- YARD::Config
- YARD::Docstring
- YARD::DocstringParser
- YARD::Handlers
- YARD::Handlers::Base
- YARD::Handlers::C
- YARD::Handlers::C::AliasHandler
- YARD::Handlers::C::AttributeHandler
- YARD::Handlers::C::Base
- YARD::Handlers::C::ClassHandler
- YARD::Handlers::C::ConstantHandler
- YARD::Handlers::C::HandlerMethods
- YARD::Handlers::C::InitHandler
- YARD::Handlers::C::MethodHandler
- YARD::Handlers::C::MixinHandler
- YARD::Handlers::C::ModuleHandler
- YARD::Handlers::C::OverrideCommentHandler
- YARD::Handlers::C::PathHandler
- YARD::Handlers::C::StructHandler
- YARD::Handlers::C::SymbolHandler
- YARD::Handlers::HandlerAborted
- YARD::Handlers::NamespaceMissingError
- YARD::Handlers::Processor
- YARD::Handlers::Ruby
- YARD::Handlers::Ruby::AliasHandler
- YARD::Handlers::Ruby::AttributeHandler
- YARD::Handlers::Ruby::Base
- YARD::Handlers::Ruby::ClassConditionHandler
- YARD::Handlers::Ruby::ClassHandler
- YARD::Handlers::Ruby::ClassVariableHandler
- YARD::Handlers::Ruby::CommentHandler
- YARD::Handlers::Ruby::ConstantHandler
- YARD::Handlers::Ruby::DSLHandler
- YARD::Handlers::Ruby::DSLHandlerMethods
- YARD::Handlers::Ruby::ExceptionHandler
- YARD::Handlers::Ruby::ExtendHandler
- YARD::Handlers::Ruby::HandlesExtension
- YARD::Handlers::Ruby::Legacy
- YARD::Handlers::Ruby::Legacy::AliasHandler
- YARD::Handlers::Ruby::Legacy::AttributeHandler
- YARD::Handlers::Ruby::Legacy::Base
- YARD::Handlers::Ruby::Legacy::ClassConditionHandler
- YARD::Handlers::Ruby::Legacy::ClassHandler
- YARD::Handlers::Ruby::Legacy::ClassVariableHandler
- YARD::Handlers::Ruby::Legacy::CommentHandler
- YARD::Handlers::Ruby::Legacy::ConstantHandler
- YARD::Handlers::Ruby::Legacy::DSLHandler
- YARD::Handlers::Ruby::Legacy::ExceptionHandler
- YARD::Handlers::Ruby::Legacy::ExtendHandler
- YARD::Handlers::Ruby::Legacy::MethodHandler
- YARD::Handlers::Ruby::Legacy::MixinHandler
- YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler
- YARD::Handlers::Ruby::Legacy::ModuleHandler
- YARD::Handlers::Ruby::Legacy::PrivateClassMethodHandler
- YARD::Handlers::Ruby::Legacy::PrivateConstantHandler
- YARD::Handlers::Ruby::Legacy::VisibilityHandler
- YARD::Handlers::Ruby::Legacy::YieldHandler
- YARD::Handlers::Ruby::MethodCallWrapper
- YARD::Handlers::Ruby::MethodConditionHandler
- YARD::Handlers::Ruby::MethodHandler
- YARD::Handlers::Ruby::MixinHandler
- YARD::Handlers::Ruby::ModuleFunctionHandler
- YARD::Handlers::Ruby::ModuleHandler
- YARD::Handlers::Ruby::PrivateClassMethodHandler
- YARD::Handlers::Ruby::PrivateConstantHandler
- YARD::Handlers::Ruby::StructHandlerMethods
- YARD::Handlers::Ruby::TestNodeWrapper
- YARD::Handlers::Ruby::VisibilityHandler
- YARD::Handlers::Ruby::YieldHandler
- YARD::I18n
- YARD::I18n::Locale
- YARD::I18n::Message
- YARD::I18n::Messages
- YARD::I18n::POParser
- YARD::I18n::PotGenerator
- YARD::I18n::Text
- YARD::Logger
- YARD::Options
- YARD::Parser
- YARD::Parser::Base
- YARD::Parser::C
- YARD::Parser::C::BodyStatement
- YARD::Parser::C::CParser
- YARD::Parser::C::Comment
- YARD::Parser::C::CommentParser
- YARD::Parser::C::Statement
- YARD::Parser::C::ToplevelStatement
- YARD::Parser::OrderedParser
- YARD::Parser::ParserSyntaxError
- YARD::Parser::Ruby
- YARD::Parser::Ruby::AstNode
- YARD::Parser::Ruby::ClassNode
- YARD::Parser::Ruby::CommentNode
- YARD::Parser::Ruby::ConditionalNode
- YARD::Parser::Ruby::KeywordNode
- YARD::Parser::Ruby::Legacy
- YARD::Parser::Ruby::Legacy::RubyLex
- YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
- YARD::Parser::Ruby::Legacy::RubyParser
- YARD::Parser::Ruby::Legacy::RubyToken
- YARD::Parser::Ruby::Legacy::RubyToken::TkBlockContents
- YARD::Parser::Ruby::Legacy::RubyToken::TkError
- YARD::Parser::Ruby::Legacy::RubyToken::TkId
- YARD::Parser::Ruby::Legacy::RubyToken::TkKW
- YARD::Parser::Ruby::Legacy::RubyToken::TkNode
- YARD::Parser::Ruby::Legacy::RubyToken::TkOPASGN
- YARD::Parser::Ruby::Legacy::RubyToken::TkOp
- YARD::Parser::Ruby::Legacy::RubyToken::TkStatementEnd
- YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar
- YARD::Parser::Ruby::Legacy::RubyToken::TkVal
- YARD::Parser::Ruby::Legacy::RubyToken::TkWhitespace
- YARD::Parser::Ruby::Legacy::RubyToken::Token
- YARD::Parser::Ruby::Legacy::Statement
- YARD::Parser::Ruby::Legacy::StatementList
- YARD::Parser::Ruby::Legacy::TokenList
- YARD::Parser::Ruby::LiteralNode
- YARD::Parser::Ruby::LoopNode
- YARD::Parser::Ruby::MethodCallNode
- YARD::Parser::Ruby::MethodDefinitionNode
- YARD::Parser::Ruby::ModuleNode
- YARD::Parser::Ruby::ParameterNode
- YARD::Parser::Ruby::ReferenceNode
- YARD::Parser::Ruby::RipperParser
- YARD::Parser::Ruby::RubyParser
- YARD::Parser::SourceParser
- YARD::Parser::UndocumentableError
- YARD::Rake
- YARD::Rake::YardocTask
- YARD::Registry
- YARD::RegistryStore
- YARD::Serializers
- YARD::Serializers::Base
- YARD::Serializers::FileSystemSerializer
- YARD::Serializers::ProcessSerializer
- YARD::Serializers::StdoutSerializer
- YARD::Serializers::YardocSerializer
- YARD::Server
- YARD::Server::Adapter
- YARD::Server::Commands
- YARD::Server::Commands::Base
- YARD::Server::Commands::DisplayFileCommand
- YARD::Server::Commands::DisplayObjectCommand
- YARD::Server::Commands::FramesCommand
- YARD::Server::Commands::LibraryCommand
- YARD::Server::Commands::LibraryIndexCommand
- YARD::Server::Commands::LibraryOptions
- YARD::Server::Commands::ListCommand
- YARD::Server::Commands::SearchCommand
- YARD::Server::Commands::StaticFileCommand
- YARD::Server::DocServerHelper
- YARD::Server::DocServerSerializer
- YARD::Server::FinishRequest
- YARD::Server::LibraryNotPreparedError
- YARD::Server::LibraryVersion
- YARD::Server::NotFoundError
- YARD::Server::RackAdapter
- YARD::Server::RackMiddleware
- YARD::Server::Router
- YARD::Server::StaticCaching
- YARD::Server::WebrickAdapter
- YARD::Server::WebrickServlet
- YARD::StubProxy
- YARD::Tags
- YARD::Tags::AttributeDirective
- YARD::Tags::DefaultFactory
- YARD::Tags::DefaultTag
- YARD::Tags::Directive
- YARD::Tags::EndGroupDirective
- YARD::Tags::GroupDirective
- YARD::Tags::Library
- YARD::Tags::MacroDirective
- YARD::Tags::MethodDirective
- YARD::Tags::OptionTag
- YARD::Tags::OverloadTag
- YARD::Tags::ParseDirective
- YARD::Tags::RefTag
- YARD::Tags::RefTagList
- YARD::Tags::ScopeDirective
- YARD::Tags::Tag
- YARD::Tags::TagFormatError
- YARD::Tags::VisibilityDirective
- YARD::Templates
- YARD::Templates::Engine
- YARD::Templates::ErbCache
- YARD::Templates::Helpers
- YARD::Templates::Helpers::BaseHelper
- YARD::Templates::Helpers::FilterHelper
- YARD::Templates::Helpers::HtmlHelper
- YARD::Templates::Helpers::HtmlSyntaxHighlightHelper
- YARD::Templates::Helpers::Markup
- YARD::Templates::Helpers::Markup::RDocMarkdown
- YARD::Templates::Helpers::Markup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::MarkupHelper
- YARD::Templates::Helpers::MethodHelper
- YARD::Templates::Helpers::ModuleHelper
- YARD::Templates::Helpers::TextHelper
- YARD::Templates::Helpers::UMLHelper
- YARD::Templates::Section
- YARD::Templates::Template
- YARD::Templates::Template::ClassMethods
- YARD::Templates::TemplateOptions
- YARD::Verifier
- Gem
- Gem::DocManager
- Gem::SourceIndex
- Gem::Specification
- Rack
- Rack::Request
- WEBrick
- WEBrick::HTTPRequest
- Array
- File
- Hash
- Insertion
- Module
- Object
- String
- SymbolHash

No matching classes.

# YARD::Handlers::Base

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} {CodeObjects::Base 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 {CodeObjects::NamespaceObject 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.

@abstract Subclass this class to provide a handler for YARD to use

    during the processing phase.

@see CodeObjects::Base @see CodeObjects::NamespaceObject @see handles @see namespace @see owner @see register @see parse_block

### Attributes

extra_state[R]

(see Processor#extra_state)

globals[R]

(see Processor#globals)

namespace[RW]

(see Processor#namespace)

owner[RW]

(see Processor#owner)

parser[R]

@return [Processor] the processor object that manages all global state

    during handling.

scope[RW]

(see Processor#scope)

statement[R]

@return [Object] the statement object currently being processed. Usually

    refers to one semantic language statement, though the strict definition
    depends on the parser used.

visibility[RW]

(see Processor#visibility)

### Public Class Methods

clear_subclasses() click to toggle source

Clear all registered subclasses. Testing purposes only @return [void]

    # File lib/yard/handlers/base.rb, line 158
    def clear_subclasses
      @@subclasses = []
    end

handlers() click to toggle source

@return [Array] a list of matchers for the handler object. @see handles?

    # File lib/yard/handlers/base.rb, line 210
    def handlers
      @handlers ||= []
    end

handles(*matches) click to toggle source

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.

@param [Parser::RubyToken, Symbol, String, Regexp] matches

    statements that match the declaration will be
    processed by this handler. A {String} match is
    equivalent to a +/\Astring/+ regular expression
    (match from the beginning of the line), and all
    token matches match only the first token of the
    statement.

    # File lib/yard/handlers/base.rb, line 191
    def handles(*matches)
      (@handlers ||= []).push(*matches)
    end

handles?(statement) click to toggle source

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.

@param statement a statement object or node (depends on language type) @return [Boolean] whether or not this handler object should process

    the given statement

    # File lib/yard/handlers/base.rb, line 204
    def handles?(statement)
      raise NotImplementedError, "override #handles? in a subclass"
    end

in_file(filename) click to toggle source

Declares that a handler should only be called when inside a filename by its basename or a regex match for the full path.

@param [String, Regexp] filename a matching filename or regex @return [void] @since 0.6.2

    # File lib/yard/handlers/base.rb, line 234
    def in_file(filename)
      (@in_files ||= []) << filename
    end

inherited(subclass) click to toggle source

    # File lib/yard/handlers/base.rb, line 168
    def inherited(subclass)
      @@subclasses ||= []
      @@subclasses << subclass
    end

matches_file?(filename) click to toggle source

@return [Boolean] whether the filename matches the declared file

    match for a handler. If no file match is specified, returns true.

@since 0.6.2

    # File lib/yard/handlers/base.rb, line 241
    def matches_file?(filename)
      @in_files ||= nil # avoid ruby warnings
      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

namespace_only() click to toggle source

Declares that the handler should only be called when inside a {CodeObjects::NamespaceObject}, not a method body.

@return [void]

    # File lib/yard/handlers/base.rb, line 218
    def namespace_only
      @namespace_only = true
    end

namespace_only?() click to toggle source

@return [Boolean] whether the handler should only be processed inside

    a namespace.

    # File lib/yard/handlers/base.rb, line 224
    def namespace_only?
      (@namespace_only ||= false) ? true : false
    end

new(source_parser, stmt) click to toggle source

    # File lib/yard/handlers/base.rb, line 275
    def initialize(source_parser, stmt)
      @parser = source_parser
      @statement = stmt
    end

process(&block) click to toggle source

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.

@!macro yard.handlers.process

    @!method process
    Main processing callback
    @return [void]

@see process @return [void] @since 0.5.4

    # File lib/yard/handlers/base.rb, line 268
    def process(&block)
      mod = Module.new
      mod.send(:define_method, :process, &block)
      include mod
    end

subclasses() click to toggle source

Returns all registered handler subclasses. @return [Array<Base>] a list of handlers

    # File lib/yard/handlers/base.rb, line 164
    def subclasses
      @@subclasses ||= []
    end

### Public Instance Methods

abort!() click to toggle source

Aborts a handler by raising {Handlers::HandlerAborted}. An exception will only be logged in debugging mode for this kind of handler exit.

@since 0.8.4

    # File lib/yard/handlers/base.rb, line 354
    def abort!
      raise Handlers::HandlerAborted
    end

call_params() click to toggle source

@abstract 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.

@return [Array<String>] a list of argument names

    # File lib/yard/handlers/base.rb, line 583
    def call_params
      raise NotImplementedError
    end

caller_method() click to toggle source

@abstract 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.

@return [String] the method name being called @return [nil] if the statement is not a method call

    # File lib/yard/handlers/base.rb, line 592
    def caller_method
      raise NotImplementedError
    end

ensure_loaded!(object, max_retries = 1) click to toggle source

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.

@example Adding a mixin to the String class programmatically

    ensure_loaded! P('String')
    # "String" is now guaranteed to be loaded
    P('String').mixins << P('MyMixin')

@param [Proxy, CodeObjects::Base] object the object to resolve. @param [Integer] max_retries the number of times to defer the handler

    before raising a +NamespaceMissingError+.

@raise [NamespaceMissingError] if the object is not resolved within

    +max_retries+ attempts, this exception is raised and the handler
    finishes processing.

    # File lib/yard/handlers/base.rb, line 560
    def ensure_loaded!(object, max_retries = 1)
      return if object.root?
      return object unless object.is_a?(Proxy)

      retries = 0
      while 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."
          parser.parse_remaining_files
        else
          raise NamespaceMissingError, object
        end
        retries += 1
      end
      object
    end

namespace=(v) click to toggle source

    # File lib/yard/handlers/base.rb, line 341
    def namespace=(v); parser.namespace=(v) end

owner=(v) click to toggle source

    # File lib/yard/handlers/base.rb, line 339
    def owner=(v) parser.owner=(v) end

parse_block(*args) click to toggle source

Parses the semantic "block" contained in the statement node.

@abstract Subclasses should call {Processor#process parser.process}

    # File lib/yard/handlers/base.rb, line 303
    def parse_block(*args)
      raise NotImplementedError, "#{self} did not implement a #parse_block method for handling"
    end

process() click to toggle source

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.

@return [Array<CodeObjects::Base>, CodeObjects::Base, Object]

    If this method returns a code object (or a list of them),
    they are passed to the +#register+ method which adds basic
    attributes. It is not necessary to return any objects and in
    some cases you may want to explicitly avoid the returning of
    any objects for post-processing by the register method.

@see handles @see register

    # File lib/yard/handlers/base.rb, line 296
    def process
      raise NotImplementedError, "#{self} did not implement a #process method for handling."
    end

push_state(opts = {}, &block) click to toggle source

Executes a given block with specific state values for {owner}, {namespace} and {scope}.

@param [Proc] block the block to execute with specific state @option opts [CodeObjects::NamespaceObject] :namespace (value of namespace)

    the namespace object that {#namespace} will be equal to for the
    duration of the block.

@option opts [Symbol] :scope (:instance)

    the scope for the duration of the block.

@option opts [CodeObjects::Base] :owner (value of owner)

    the owner object (method) for the duration of the block

@yield a block to execute with the given state values.

    # File lib/yard/handlers/base.rb, line 370
    def push_state(opts = {}, &block)
      opts = {
        :namespace => namespace,
        :scope => :instance,
        :owner => owner || namespace,
        :visibility => nil
      }.update(opts)

      ns, vis, sc, oo = namespace, visibility, scope, owner
      self.namespace = opts[:namespace]
      self.visibility = opts[:visibility] || :public
      self.scope = opts[:scope]
      self.owner = opts[:owner]

      yield

      self.namespace = ns
      self.visibility = vis
      self.scope = sc
      self.owner = oo
    end

register(*objects) click to toggle source

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.

@param [Array<CodeObjects::Base>] objects

    the list of objects to post-process.

@return [CodeObjects::Base, Array<CodeObjects::Base>]

    returns whatever is passed in, for chainability.

    # File lib/yard/handlers/base.rb, line 404
    def register(*objects)
      objects.flatten.each do |object|
        next unless object.is_a?(CodeObjects::Base)
        register_ensure_loaded(object)
        yield(object) if block_given?
        register_file_info(object)
        register_source(object)
        register_visibility(object)
        register_docstring(object)
        register_group(object)
        register_dynamic(object)
        register_module_function(object)
      end
      objects.size == 1 ? objects.first : objects
    end

register_docstring(object, docstring = statement.comments, stmt = statement) click to toggle source

Registers any docstring found for the object and expands macros

@param [CodeObjects::Base] object the object to register @return [void] @since 0.8.0

    # File lib/yard/handlers/base.rb, line 448
    def register_docstring(object, docstring = statement.comments, stmt = statement)
      docstring = docstring.join("\n") if Array === docstring
      parser = Docstring.parser
      parser.parse(docstring || "", object, self)

      if object && docstring
        object.docstring = parser.to_docstring

        # Add hash_flag/line_range
        if stmt
          object.docstring.hash_flag = stmt.comments_hash_flag
          object.docstring.line_range = stmt.comments_range
        end
      end

      register_transitive_tags(object)
    end

register_dynamic(object) click to toggle source

Registers the object as dynamic if the object is defined inside a method or block (owner != namespace)

@param [CodeObjects::Base] object the object to register @return [void] @since 0.8.0

    # File lib/yard/handlers/base.rb, line 536
    def register_dynamic(object)
      object.dynamic = true if owner != namespace
    end

register_ensure_loaded(object) click to toggle source

Ensures that the object's namespace is loaded before attaching it to the namespace.

@param [CodeObjects::Base] object the object to register @return [void] @since 0.8.0

    # File lib/yard/handlers/base.rb, line 426
    def register_ensure_loaded(object)
      begin
        ensure_loaded!(object.namespace)
        object.namespace.children << object
      rescue NamespaceMissingError
      end
    end

register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments) click to toggle source

Registers the file/line of the declaration with the object

@param [CodeObjects::Base] object the object to register @return [void] @since 0.8.0

    # File lib/yard/handlers/base.rb, line 439
    def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
      object.add_file(file, line, comments)
    end

register_group(object, group = extra_state.group) click to toggle source

Registers the object as being inside a specific group

@param [CodeObjects::Base] object the object to register @return [void] @since 0.8.0

    # File lib/yard/handlers/base.rb, line 471
    def register_group(object, group = extra_state.group)
      if group
        unless object.namespace.is_a?(Proxy)
          object.namespace.groups |= [group]
        end
        object.group = group
      end
    end

register_module_function(object) click to toggle source

Registers the same method information on the module function, if the object was defined as a module function.

@param [CodeObjects::Base] object the possible module function object

    to copy data for

@since 0.8.0

    # File lib/yard/handlers/base.rb, line 522
    def register_module_function(object)
      return unless object.is_a?(MethodObject)
      return unless object.module_function?
      modobj = MethodObject.new(object.namespace, object.name)
      object.copy_to(modobj)
      modobj.visibility = :private
    end

register_source(object, source = statement, type = parser.parser_type) click to toggle source

@param [CodeObjects::Base] object the object to register @return [void] @since 0.8.0

    # File lib/yard/handlers/base.rb, line 498
    def register_source(object, source = statement, type = parser.parser_type)
      return unless object.is_a?(MethodObject)
      object.source ||= source
      object.source_type = type
    end

register_transitive_tags(object) click to toggle source

Registers any transitive tags from the namespace on the object

@param [CodeObjects::Base, nil] object the object to register @return [void] @since 0.8.0

    # File lib/yard/handlers/base.rb, line 485
    def register_transitive_tags(object)
      return unless object
      Tags::Library.transitive_tags.each do |tag|
        next if object.namespace.is_a?(Proxy)
        next unless object.namespace.has_tag?(tag)
        next if object.has_tag?(tag)
        object.add_tag(*object.namespace.tags(tag))
      end
    end

register_visibility(object, visibility = self.visibility) click to toggle source

Registers visibility on a method object. If the object does not respond to setting visibility, nothing is done.

@param [visibility=] object the object to register @param [Symbol] visibility the visibility to set on the object @since 0.8.0

    # File lib/yard/handlers/base.rb, line 510
    def register_visibility(object, visibility = self.visibility)
      return unless object.respond_to?(:visibility=)
      return if object.is_a?(NamespaceObject)
      object.visibility = visibility
    end

scope=(v) click to toggle source

    # File lib/yard/handlers/base.rb, line 345
    def scope=(v); parser.scope=(v) end

visibility=(v) click to toggle source

    # File lib/yard/handlers/base.rb, line 343
    def visibility=(v); parser.visibility=(v) end

[Validate]

Generated with the Darkfish Rdoc Generator 2.