Class: YARD::Tags::Library

### Home Classes Methods

### In Files

- lib/yard/tags/library.rb

### Parent

Object

### Methods

- ::default_factory
- ::default_factory=
- ::define_directive
- ::define_tag
- ::directive_method_name
- ::factory_method_for
- ::factory_method_for_directive
- ::instance
- ::new
- ::sorted_labels
- ::tag_method_name
- #directive_create
- #has_directive?
- #has_tag?
- #tag_create

### 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::Tags::Library

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 {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 {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= 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.)

@example Defining a custom tag

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

@example Defining a custom directive

    define_directive :method, :with_title_and_text, MethodDirective

@see DefaultFactory @see define_tag @see define_directive @see Directive

### Attributes

labels[R]

@return [SymbolHash{Symbol=>String}] the map of tag names and their

    respective display labels.

transitive_tags[RW]

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.

@return [Array<Symbol>] a list of transitive tags @since 0.6.0

visible_tags[RW]

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)

@return [Array<Symbol>] a list of ordered tags @since 0.6.0

factory[RW]

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

### Public Class Methods

default_factory() click to toggle source

@!attribute default_factory 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.

@example

    YARD::Tags::Library.default_factory = MyFactory

@see DefaultFactory

    # File lib/yard/tags/library.rb, line 82
    def default_factory
      @default_factory ||= DefaultFactory.new
    end

default_factory=(factory) click to toggle source

    # File lib/yard/tags/library.rb, line 86
    def default_factory=(factory)
      @default_factory = factory.is_a?(Class) ? factory.new : factory
    end

define_directive(tag, tag_meth = nil, directive_class = nil) click to toggle source

@macro [attach] yard.directive

    @!method $1_directive
    @!visibility private
    @yard.directive $1 [$2] $-1

@overload define_directive(tag, tag_meth = nil, directive_class)

    Convenience method to define a new directive using a {Tag} factory
    method and {Directive} subclass that implements the directive
    callbacks.

    @param [#to_s] tag the tag name of the directive
    @param [#to_s] tag_meth the tag factory method to use when
      parsing tag information
    @param [Class<Directive>] the directive class that implements the
      directive behaviour
    @see define_tag

    # File lib/yard/tags/library.rb, line 194
    def define_directive(tag, tag_meth = nil, directive_class = nil)
      directive_meth = directive_method_name(tag)
      if directive_class.nil?
        tag_meth, directive_class = nil, tag_meth
      end
      class_eval             def #{directive_meth}(tag, parser)              directive_call(tag, parser)            end, __FILE__, __LINE__

      @factory_methods ||= SymbolHash.new(false)
      @factory_methods.update(tag => tag_meth)
      @directive_factory_classes ||= SymbolHash.new(false)
      @directive_factory_classes.update(tag => directive_class)

      tag
    end

define_tag(label, tag, meth = nil) click to toggle source

Convenience method to define a new tag using one of {Tag}'s factory methods, or the regular {DefaultFactory#parse_tag} factory method if none is supplied.

@!macro [attach] yard.tag

    @!method $2_tag
    @!visibility private
    @yard.tag $2 [$3] $1

@param [to_s] label the label used when displaying the tag in templates @param [to_s] tag the tag name to create @param [to_s, Class<Tag>] meth the {Tag} factory method to call when

    creating the tag or the name of the class to directly create a tag for

    # File lib/yard/tags/library.rb, line 156
    def define_tag(label, tag, meth = nil)
      tag_meth = tag_method_name(tag)
      if meth.is_a?(Class) && Tag > meth
        class_eval               def #{tag_meth}(text)                #{meth}.new(#{tag.inspect}, text)              end, __FILE__, __LINE__
      else
        class_eval               def #{tag_meth}(text)                send_to_factory(#{tag.inspect}, #{meth.inspect}, text)              end, __FILE__, __LINE__
      end

      @labels ||= SymbolHash.new(false)
      @labels.update(tag => label)
      @factory_methods ||= SymbolHash.new(false)
      @factory_methods.update(tag => meth)
      tag
    end

directive_method_name(tag_name) click to toggle source

    # File lib/yard/tags/library.rb, line 217
    def directive_method_name(tag_name)
      tag_or_directive_method_name(tag_name, 'directive')
    end

factory_method_for(tag) click to toggle source

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

@param [Symbol] tag the tag name @return [Symbol] the factory method name for the tag @return [Class<Tag>,Symbol] the Tag class to use to parse the tag

    or the method to call on the factory class

@return [nil] if the tag is freeform text @since 0.6.0

    # File lib/yard/tags/library.rb, line 98
    def factory_method_for(tag)
      @factory_methods[tag]
    end

factory_method_for_directive(directive) click to toggle source

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

@param [Symbol] directive the directive name @return [Symbol] the factory method name for the tag @return [Class<Tag>,Symbol] the Tag class to use to parse the tag or

    the methods to call on the factory class

@return [nil] if the tag is freeform text @since 0.8.0

    # File lib/yard/tags/library.rb, line 111
    def factory_method_for_directive(directive)
      @directive_factory_classes[directive]
    end

instance() click to toggle source

@!attribute instance @return [Library] the main Library instance object.

    # File lib/yard/tags/library.rb, line 66
    def instance
      @instance ||= new
    end

new(factory = Library.default_factory) click to toggle source

    # File lib/yard/tags/library.rb, line 258
    def initialize(factory = Library.default_factory)
      self.factory = factory
    end

sorted_labels() click to toggle source

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

@return [Array<Symbol>, String] the sorted labels as an array of the tag name and label

    # File lib/yard/tags/library.rb, line 141
    def sorted_labels
      labels.sort_by {|a| a.last.downcase }
    end

tag_method_name(tag_name) click to toggle source

    # File lib/yard/tags/library.rb, line 213
    def tag_method_name(tag_name)
      tag_or_directive_method_name(tag_name)
    end

### Public Instance Methods

directive_create(tag_name, tag_buf, parser) click to toggle source

Creates a new directive with tag information and a docstring parser object. @param [String] tag_name the name of the tag @param [String] tag_buf the tag data @param [DocstringParser] parser the parser object parsing the docstring @return [Directive] the newly created directive

    # File lib/yard/tags/library.rb, line 288
    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) click to toggle source

@param [to_s] tag_name the name of the tag to look for @return [Boolean] whether a directive by the given name is registered in

    the library.

    # File lib/yard/tags/library.rb, line 278
    def has_directive?(tag_name)
      tag_name && respond_to?(self.class.directive_method_name(tag_name))
    end

has_tag?(tag_name) click to toggle source

@param [to_s] tag_name the name of the tag to look for @return [Boolean] whether a tag by the given name is registered in

    the library.

    # File lib/yard/tags/library.rb, line 265
    def has_tag?(tag_name)
      tag_name && respond_to?(self.class.tag_method_name(tag_name))
    end

tag_create(tag_name, tag_buf) click to toggle source

Creates a new {Tag} object with a given tag name and data @return [Tag] the newly created tag object

    # File lib/yard/tags/library.rb, line 271
    def tag_create(tag_name, tag_buf)
      send(self.class.tag_method_name(tag_name), tag_buf)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.