Class: YARD::Tags::Library

Inherits:
Object
  • Object
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:

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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:



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

.define_directive(tag, tag_meth = nil, directive_class) ⇒ Object

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

Parameters:

  • tag (#to_s) —

    the tag name of the directive

  • tag_meth (#to_s) (defaults to: nil) —

    the tag factory method to use when parsing tag information

  • the (Class<Directive>) —

    directive class that implements the directive behaviour

See Also:



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# 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

.define_tag(label, tag, meth = nil) ⇒ Object

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.

Parameters:

  • label (#to_s) —

    the label used when displaying the tag in templates

  • tag (#to_s) —

    the tag name to create

  • meth (#to_s, Class<Tag>) (defaults to: nil) —

    the Tag factory method to call when creating the tag or the name of the class to directly create a tag for



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# 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

.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