# Class: YARD::Tags::Directive Abstract

Inherits:
  Object
  - Object
  - YARD::Tags::Directive
  show all

Defined in:
  lib/yard/tags/directives.rb

## Overview

This class is abstract.

Subclasses should implement #call.

The base directive class. Subclass this class to create a custom directive, registering it with Library.define_directive. Directive classes are executed via the #call method, which perform all directive processing on the object.

If processing occurs within a handler, the #handler attribute is available to access more information about parsing context and state. Handlers are only available when parsing from Parser::SourceParser, not when parsing directly from DocstringParser. If the docstring is attached to an object declaration, #object will be set and available to modify the generated code object directly. Note that both of these attributes may be nil, and directives should test their existence before attempting to use them.

See Also:

- Library.define_directive

Since:

- 0.8.0

## Direct Known Subclasses

EndGroupDirective, GroupDirective, MacroDirective, MethodDirective, ParseDirective, ScopeDirective, VisibilityDirective

## Instance Attribute Summary collapse

- #expanded_text ⇒ String?

  Set this field to replace the directive definition inside of a docstring with arbitrary text.

- #handler ⇒ Handlers::Base? readonly

  The handler object the docstring parser might be attached to.

- #object ⇒ CodeObjects::Base? readonly

  The object the parent docstring is attached to.

- #parser ⇒ DocstringParser protected

  The parser that is parsing all tag information out of the docstring.

- #tag ⇒ Tag

  The meta-data tag containing data input to the directive.

## Parser callbacks collapse

- #after_parse ⇒ void

  Called after parsing all directives and tags in the docstring.

- #call ⇒ void abstract

  Called when processing the directive.

- #inside_directive? ⇒ Boolean protected

## Instance Method Summary collapse

- #initialize(tag, parser) ⇒ Directive constructor

  A new instance of Directive.

## Constructor Details

### #initialize(tag, parser) ⇒ `Directive`

Returns a new instance of Directive.

Parameters:

- tag (`Tag`) —

  the meta-data tag containing all input to the docstring

- parser (`DocstringParser`) —

  the docstring parser object

Since:

- 0.8.0

    54
    55
    56
    57
    58

    # File 'lib/yard/tags/directives.rb', line 54

    def initialize(tag, parser)
      self.tag = tag
      self.parser = parser
      self.expanded_text = nil
    end

## Instance Attribute Details

### #expanded_text ⇒ `String`?

Set this field to replace the directive definition inside of a docstring with arbitrary text. For instance, the MacroDirective uses this field to expand its macro data in place of the call to a `@!macro`.

Returns:

- (`String`) —

  the text to expand in the original docstring in place of this directive definition.

- (`nil`) —

  if no expansion should take place for this directive

Since:

- 0.8.0

    33
    34
    35

    # File 'lib/yard/tags/directives.rb', line 33

    def expanded_text
      @expanded_text
    end

### #handler ⇒ `Handlers::Base`? (readonly)

Returns the handler object the docstring parser might be attached to. May be nil. Only available when parsing through Parser::SourceParser.

Returns:

- (`Handlers::Base`, `nil`) —

  the handler object the docstring parser might be attached to. May be nil. Only available when parsing through Parser::SourceParser.

Since:

- 0.8.0

    48

    # File 'lib/yard/tags/directives.rb', line 48

    def handler; parser.handler end

### #object ⇒ `CodeObjects::Base`? (readonly)

Returns the object the parent docstring is attached to. May be nil.

Returns:

- (`CodeObjects::Base`, `nil`) —

  the object the parent docstring is attached to. May be nil.

Since:

- 0.8.0

    42

    # File 'lib/yard/tags/directives.rb', line 42

    def object; parser.object end

### #parser ⇒ `DocstringParser` (protected)

Returns the parser that is parsing all tag information out of the docstring.

Returns:

- (`DocstringParser`) —

  the parser that is parsing all tag information out of the docstring

Since:

- 0.8.0

    37
    38
    39

    # File 'lib/yard/tags/directives.rb', line 37

    def parser
      @parser
    end

### #tag ⇒ `Tag`

Returns the meta-data tag containing data input to the directive.

Returns:

- (`Tag`) —

  the meta-data tag containing data input to the directive

Since:

- 0.8.0

    24
    25
    26

    # File 'lib/yard/tags/directives.rb', line 24

    def tag
      @tag
    end

## Instance Method Details

### #after_parse ⇒ `void`

This method returns an undefined value.

Called after parsing all directives and tags in the docstring. Used to perform any cleanup after all directives perform their main task.

Since:

- 0.8.0

    73

    # File 'lib/yard/tags/directives.rb', line 73

    def after_parse; end

### #call ⇒ `void`

This method is abstract.

implement this method to perform all data processing for the directive.

This method returns an undefined value.

Called when processing the directive. Subclasses should implement this method to perform all functionality of the directive.

Raises:

- (`NotImplementedError`)

Since:

- 0.8.0

    68

    # File 'lib/yard/tags/directives.rb', line 68

    def call; raise NotImplementedError end

### #inside_directive? ⇒ `Boolean` (protected)

Returns:

- (`Boolean`)

Since:

- 0.8.0

    79
    80
    81
    82

    # File 'lib/yard/tags/directives.rb', line 79

    def inside_directive?
      return true if parser.state.inside_directive
      parser.directives.any? { |d| d.is_a?(MethodDirective) && d.tag.text.empty? }
    end