# Class: YARD::Tags::Library

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

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

## Overview

Keeps track of all the registered meta-data tags and directives. Also allows for defining of custom tags and customizing the tag parsing syntax.

## Defining Custom Meta-Data Tags

To define a custom tag, use Library.define_tag. You should pass the tag name and the factory method to use when creating the tag. If you do not provide a factory method to use, it will default to DefaultFactory#parse_tag

You can also define tag objects manually by simply implementing a “tagname_tag” method that returns a Tag object, but they will not take advantage of tag factory parsing:

    def mytag_tag(text)
      Tag.new(:mytag, text)
    end

## Defining Custom Directives

Directives can be defined by calling the Library.define_directive method, taking the directive name, an optional tag factory parser method (to parse the data in the directive into a temporary Tag object) and a Directive subclass that performs the directive processing. For more information on creating a Directive subclass, see the Directive class documentation.

Similar to tags, Directives can also be defined manually, in this case using the method name “mydirective_directive” and returning a new Directive object:

    def mydirective_directive(tag, parser)
      MyDirective.new(tag, parser)
    end

## Namespaced Tags

In YARD 0.8.0+, tags can be namespaced using the ‘.’ character. It is recommended to namespace project specific tags, like `@yard.tag_name`, so that tags do not collide with other plugins or new built-in tags.

## Adding/Changing the Tag Syntax

If you have specialized tag parsing needs you can substitute the #factory object with your own by setting Library.default_factory to a new class with its own parsing methods before running YARD. This is useful if you want to change the syntax of existing tags (@see, @since, etc.)

#### Examples:

#####

Defining a custom tag

    define_tag "Parameter", :param, :with_types_and_name
    define_tag "Author", :author

#####

Defining a custom directive

    define_directive :method, :with_title_and_text, MethodDirective

See Also:

- DefaultFactory
- Library.define_tag
- Library.define_directive
- Directive

## Class Attribute Summary collapse

- .default_factory ⇒ Object

  Replace the factory object responsible for parsing tags by setting this to an object (or class) that responds to `parse_TAGNAME` methods where `TAGNAME` is the name of the tag.

- .instance ⇒ Library

  The main Library instance object.

- .labels ⇒ SymbolHash{Symbol=>String} readonly

  The map of tag names and their respective display labels.

- .transitive_tags ⇒ Array<Symbol>

  Sets the list of tags that should apply to any children inside the namespace they are defined in.

- .visible_tags ⇒ Array<Symbol>

  Sets the list of tags to display when rendering templates.

## Instance Attribute Summary collapse

- #factory ⇒ Object

  A factory class to handle parsing of tags, defaults to Library.default_factory.

## Class Method Summary collapse

- .directive_method_name(tag_name) ⇒ Object
- .factory_method_for(tag) ⇒ Symbol, ...

  Returns the factory method used to parse the tag text for a specific tag.

- .factory_method_for_directive(directive) ⇒ Symbol, ...

  Returns the factory method used to parse the tag text for a specific directive.

- .sorted_labels ⇒ Array<Symbol>, String

  Sorts the labels lexically by their label name, often used when displaying the tags.

- .tag_method_name(tag_name) ⇒ Object

## Instance Method Summary collapse

- #directive_create(tag_name, tag_buf, parser) ⇒ Directive

  Creates a new directive with tag information and a docstring parser object.

- #has_directive?(tag_name) ⇒ Boolean

  Whether a directive by the given name is registered in the library.

- #has_tag?(tag_name) ⇒ Boolean

  Whether a tag by the given name is registered in the library.

- #initialize(factory = Library.default_factory) ⇒ Library constructor

  A new instance of Library.

- #tag_create(tag_name, tag_buf) ⇒ Tag

  Creates a new Tag object with a given tag name and data.

## Constructor Details

### #initialize(factory = Library.default_factory) ⇒ `Library`

Returns a new instance of Library.

    260
    261
    262

    # File 'lib/yard/tags/library.rb', line 260

    def initialize(factory = Library.default_factory)
      self.factory = factory
    end

## Class Attribute Details

### .default_factory ⇒ `Object`

Replace the factory object responsible for parsing tags by setting this to an object (or class) that responds to `parse_TAGNAME` methods where `TAGNAME` is the name of the tag.

You should set this value before performing any source parsing with YARD, otherwise your factory class will not be used.

#### Examples:

    YARD::Tags::Library.default_factory = MyFactory

See Also:

- DefaultFactory

    83
    84
    85

    # File 'lib/yard/tags/library.rb', line 83

    def default_factory
      @default_factory ||= DefaultFactory.new
    end

### .instance ⇒ `Library`

Returns the main Library instance object.

Returns:

- (`Library`) —

  the main Library instance object.

    67
    68
    69

    # File 'lib/yard/tags/library.rb', line 67

    def instance
      @instance ||= new
    end

### .labels ⇒ `SymbolHash{Symbol=>String}` (readonly)

Returns the map of tag names and their respective display labels.

Returns:

- (`SymbolHash{Symbol=>String}`) —

  the map of tag names and their respective display labels.

    63
    64
    65

    # File 'lib/yard/tags/library.rb', line 63

    def labels
      @labels
    end

### .transitive_tags ⇒ `Array<Symbol>`

Sets the list of tags that should apply to any children inside the namespace they are defined in. For instance, a “@since” tag should apply to all methods inside a module it is defined in. Transitive tags can be overridden by directly defining a tag on the child object.

Returns:

- (`Array<Symbol>`) —

  a list of transitive tags

Since:

- 0.6.0

    136
    137
    138

    # File 'lib/yard/tags/library.rb', line 136

    def transitive_tags
      @transitive_tags
    end

### .visible_tags ⇒ `Array<Symbol>`

Sets the list of tags to display when rendering templates. The order of tags in the list is also significant, as it represents the order that tags are displayed in templates.

You can use the Array#place to insert new tags to be displayed in the templates at specific positions:

    Library.visible_tags.place(:mytag).before(:return)

Returns:

- (`Array<Symbol>`) —

  a list of ordered tags

Since:

- 0.6.0

    127
    128
    129

    # File 'lib/yard/tags/library.rb', line 127

    def visible_tags
      @visible_tags
    end

## Instance Attribute Details

### #factory ⇒ `Object`

A factory class to handle parsing of tags, defaults to default_factory

    258
    259
    260

    # File 'lib/yard/tags/library.rb', line 258

    def factory
      @factory
    end

## Class Method Details

### .directive_method_name(tag_name) ⇒ `Object`

    220
    221
    222

    # File 'lib/yard/tags/library.rb', line 220

    def directive_method_name(tag_name)
      tag_or_directive_method_name(tag_name, 'directive')
    end

### .factory_method_for(tag) ⇒ `Symbol`, ...

Returns the factory method used to parse the tag text for a specific tag

Parameters:

- tag (`Symbol`) —

  the tag name

Returns:

- (`Symbol`) —

  the factory method name for the tag

- (`Class<Tag>`, `Symbol`) —

  the Tag class to use to parse the tag or the method to call on the factory class

- (`nil`) —

  if the tag is freeform text

Since:

- 0.6.0

    99
    100
    101

    # File 'lib/yard/tags/library.rb', line 99

    def factory_method_for(tag)
      @factory_methods[tag]
    end

### .factory_method_for_directive(directive) ⇒ `Symbol`, ...

Returns the factory method used to parse the tag text for a specific directive

Parameters:

- directive (`Symbol`) —

  the directive name

Returns:

- (`Symbol`) —

  the factory method name for the tag

- (`Class<Tag>`, `Symbol`) —

  the Tag class to use to parse the tag or the methods to call on the factory class

- (`nil`) —

  if the tag is freeform text

Since:

- 0.8.0

    112
    113
    114

    # File 'lib/yard/tags/library.rb', line 112

    def factory_method_for_directive(directive)
      @directive_factory_classes[directive]
    end

### .sorted_labels ⇒ `Array<Symbol>`, `String`

Sorts the labels lexically by their label name, often used when displaying the tags.

Returns:

- (`Array<Symbol>`, `String`) —

  the sorted labels as an array of the tag name and label

    142
    143
    144

    # File 'lib/yard/tags/library.rb', line 142

    def sorted_labels
      labels.sort_by {|a| a.last.downcase }
    end

### .tag_method_name(tag_name) ⇒ `Object`

    216
    217
    218

    # File 'lib/yard/tags/library.rb', line 216

    def tag_method_name(tag_name)
      tag_or_directive_method_name(tag_name)
    end

## Instance Method Details

### #directive_create(tag_name, tag_buf, parser) ⇒ `Directive`

Creates a new directive with tag information and a docstring parser object.

Parameters:

- tag_name (`String`) —

  the name of the tag

- tag_buf (`String`) —

  the tag data

- parser (`DocstringParser`) —

  the parser object parsing the docstring

Returns:

- (`Directive`) —

  the newly created directive

    290
    291
    292
    293
    294
    295

    # File 'lib/yard/tags/library.rb', line 290

    def directive_create(tag_name, tag_buf, parser)
      meth = self.class.factory_method_for(tag_name)
      tag = send_to_factory(tag_name, meth, tag_buf)
      meth = self.class.directive_method_name(tag_name)
      send(meth, tag, parser)
    end

### #has_directive?(tag_name) ⇒ `Boolean`

Returns whether a directive by the given name is registered in the library.

Parameters:

- tag_name (`#to_s`) —

  the name of the tag to look for

Returns:

- (`Boolean`) —

  whether a directive by the given name is registered in the library.

    280
    281
    282

    # File 'lib/yard/tags/library.rb', line 280

    def has_directive?(tag_name)
      tag_name && respond_to?(self.class.directive_method_name(tag_name))
    end

### #has_tag?(tag_name) ⇒ `Boolean`

Returns whether a tag by the given name is registered in the library.

Parameters:

- tag_name (`#to_s`) —

  the name of the tag to look for

Returns:

- (`Boolean`) —

  whether a tag by the given name is registered in the library.

    267
    268
    269

    # File 'lib/yard/tags/library.rb', line 267

    def has_tag?(tag_name)
      tag_name && respond_to?(self.class.tag_method_name(tag_name))
    end

### #tag_create(tag_name, tag_buf) ⇒ `Tag`

Creates a new Tag object with a given tag name and data

Returns:

- (`Tag`) —

  the newly created tag object

    273
    274
    275

    # File 'lib/yard/tags/library.rb', line 273

    def tag_create(tag_name, tag_buf)
      send(self.class.tag_method_name(tag_name), tag_buf)
    end