class 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
@return [SymbolHash{Symbol=>String}] the map of tag names and their
respective display labels.
A factory class to handle parsing of tags, defaults to {default_factory}
Public Class Methods
Source
# File lib/yard/tags/library.rb, line 83 def default_factory @default_factory ||= DefaultFactory.new end
@!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
Source
# File lib/yard/tags/library.rb, line 87 def default_factory=(factory) @default_factory = factory.is_a?(Class) ? factory.new : factory end
Source
# File lib/yard/tags/library.rb, line 196 def define_directive(tag, tag_meth = nil, directive_class = nil) directive_meth = directive_method_name(tag) if directive_class.nil? directive_class = tag_meth tag_meth = nil end class_eval <<-eof, __FILE__, __LINE__ def #{directive_meth}(tag, parser) directive_call(tag, parser) end eof @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
@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
Source
# File lib/yard/tags/library.rb, line 157 def define_tag(label, tag, meth = nil) tag_meth = tag_method_name(tag) if meth.is_a?(Class) && Tag > meth class_eval(<<-eof, __FILE__, __LINE__ + 1) def #{tag_meth}(text) #{meth}.new(#{tag.inspect}, text) end eof else class_eval(<<-eof, __FILE__, __LINE__ + 1) begin; undef #{tag_meth}; rescue NameError; end def #{tag_meth}(text) send_to_factory(#{tag.inspect}, #{meth.inspect}, text) end eof end @labels ||= SymbolHash.new(false) @labels.update(tag => label) @factory_methods ||= SymbolHash.new(false) @factory_methods.update(tag => meth) tag end
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
Source
# File lib/yard/tags/library.rb, line 220 def directive_method_name(tag_name) tag_or_directive_method_name(tag_name, 'directive') end
Source
# File lib/yard/tags/library.rb, line 99 def factory_method_for(tag) @factory_methods[tag] end
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
Source
# File lib/yard/tags/library.rb, line 112 def factory_method_for_directive(directive) @directive_factory_classes[directive] end
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
Source
# File lib/yard/tags/library.rb, line 67 def instance @instance ||= new end
@!attribute instance @return [Library] the main Library
instance object.
Source
# File lib/yard/tags/library.rb, line 260 def initialize(factory = Library.default_factory) self.factory = factory end
Source
# File lib/yard/tags/library.rb, line 142 def sorted_labels labels.sort_by {|a| a.last.downcase } end
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
Source
# File lib/yard/tags/library.rb, line 216 def tag_method_name(tag_name) tag_or_directive_method_name(tag_name) end
Private Class Methods
Source
# File lib/yard/tags/library.rb, line 226 def tag_or_directive_method_name(tag_name, type = 'tag') "#{tag_name.to_s.tr('.', '_')}_#{type}" end
Public Instance Methods
Source
# 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
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
Source
# 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
@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.
Source
# 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
@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.
Source
# 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
Creates a new {Tag} object with a given tag name and data @return [Tag] the newly created tag object
Private Instance Methods
Source
# File lib/yard/tags/library.rb, line 244 def directive_call(tag, parser) meth = self.class.factory_method_for_directive(tag.tag_name) if meth <= Directive meth = meth.new(tag, parser) meth.call meth else meth.call(tag, parser) end end
@return [Directive]
Source
# File lib/yard/tags/library.rb, line 233 def send_to_factory(tag_name, meth, text) meth = meth.to_s send_name = "parse_tag" + (meth.empty? ? "" : "_" + meth) if @factory.respond_to?(send_name) @factory.send(send_name, tag_name, text) else raise NoMethodError, "Factory #{@factory.class_name} does not implement factory method :#{meth}." end end