Class: YARD::CodeObjects::Base Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/code_objects/base.rb

Overview

This class is abstract.

This class should not be used directly. Instead, create a subclass that implements #path, #sep or #type. You might also need to register custom separators if #sep uses alternate separator tokens.

Base is the superclass of all code objects recognized by YARD. A code object is any entity in the Ruby language (class, method, module). A DSL might subclass Base to create a new custom object representing a new entity type.

Registry Integration

Any created object associated with a namespace is immediately registered with the registry. This allows the Registry to act as an identity map to ensure that no object is represented by more than one Ruby object in memory. A unique #path is essential for this identity map to work correctly.

Custom Attributes

Code objects allow arbitrary custom attributes to be set using the #[]= assignment method.

Namespaces

There is a special type of object called a “namespace”. These are subclasses of the NamespaceObject and represent Ruby entities that can have objects defined within them. Classically these are modules and classes, though a DSL might create a custom NamespaceObject to describe a specific set of objects.

Separators

Custom classes with different separator tokens should define their own separators using the NamespaceMapper#register_separator method. The standard Ruby separators have already been defined ('::', '#', '.', etc).

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(namespace, name, *args) {|self| ... } ⇒ Base

Creates a new code object

Examples:

Create a method in the root namespace

CodeObjects::Base.new(:root, '#method') # => #<yardoc method #method>

Create class Z inside namespace X::Y

CodeObjects::Base.new(P("X::Y"), :Z) # or
CodeObjects::Base.new(Registry.root, "X::Y")

Yields:

  • (self)

    a block to perform any extra initialization on the object

Yield Parameters:

  • self (Base)

    the newly initialized code object



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
# File 'lib/yard/code_objects/base.rb', line 224

def initialize(namespace, name, *args, &block)
  if namespace && namespace != :root &&
      !namespace.is_a?(NamespaceObject) && !namespace.is_a?(Proxy)
    raise ArgumentError, "Invalid namespace object: #{namespace}"
  end

  @files = []
  @current_file_has_comments = false
  @name = name.to_sym
  @source_type = :ruby
  @visibility = :public
  @tags = []
  @docstrings = {}
  @docstring = Docstring.new!('', [], self)
  @namespace = nil
  self.namespace = namespace
  yield(self) if block_given?
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#dynamic_attr_nameObject #dynamic_attr_name=(value) ⇒ Object

Overloads:

  • #dynamic_attr_nameObject

    Returns the value of attribute named by the method attribute name

    Raises:

    • (NoMethodError)

      if no method or custom attribute exists by the attribute name

    See Also:

  • #dynamic_attr_name=(value) ⇒ Object

    Returns value

    See Also:



358
359
360
361
362
363
364
365
366
# File 'lib/yard/code_objects/base.rb', line 358

def method_missing(meth, *args, &block)
  if meth.to_s =~ /=$/
    self[meth.to_s[0..-2]] = args.first
  elsif instance_variable_get("@#{meth}")
    self[meth]
  else
    super
  end
end

Instance Attribute Details

#base_docstringDocstring (readonly)

The non-localized documentation string associated with the object

Since:

  • 0.8.4



154
155
156
# File 'lib/yard/code_objects/base.rb', line 154

def base_docstring
  @base_docstring
end

#dynamicBoolean

Marks whether or not the method is conditionally defined at runtime



160
161
162
# File 'lib/yard/code_objects/base.rb', line 160

def dynamic
  @dynamic
end

#filesArray<String> (readonly)

The files the object was defined in. To add a file, use #add_file.

See Also:



127
128
129
# File 'lib/yard/code_objects/base.rb', line 127

def files
  @files
end

#groupString

Returns the group this object is associated with

Since:

  • 0.6.0



164
165
166
# File 'lib/yard/code_objects/base.rb', line 164

def group
  @group
end

#namespaceNamespaceObject Also known as: parent

The namespace the object is defined in. If the object is in the top level namespace, this is Registry.root



132
133
134
# File 'lib/yard/code_objects/base.rb', line 132

def namespace
  @namespace
end

#signatureString

The one line signature representing an object. For a method, this will be of the form “def meth(arguments…)”. This is usually the first source line.



149
150
151
# File 'lib/yard/code_objects/base.rb', line 149

def signature
  @signature
end

#sourceString?

The source code associated with the object



136
137
138
# File 'lib/yard/code_objects/base.rb', line 136

def source
  @source
end

#source_typeSymbol

Language of the source code associated with the object. Defaults to :ruby.



142
143
144
# File 'lib/yard/code_objects/base.rb', line 142

def source_type
  @source_type
end

#visibilitySymbol



171
172
173
# File 'lib/yard/code_objects/base.rb', line 171

def visibility
  @visibility
end

Class Method Details

.===(other) ⇒ Boolean

Compares the class with subclasses



205
206
207
# File 'lib/yard/code_objects/base.rb', line 205

def ===(other)
  other.is_a?(self)
end

.new(namespace, name, *args) {|obj| ... } ⇒ Base

Allocates a new code object

Yields:

  • (obj)

Raises:

  • (ArgumentError)

See Also:



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
# File 'lib/yard/code_objects/base.rb', line 179

def new(namespace, name, *args, &block)
  raise ArgumentError, "invalid empty object name" if name.to_s.empty?
  if namespace.is_a?(ConstantObject)
    namespace = Proxy.new(namespace.namespace, namespace.value)
  end

  if name.to_s[0,2] == NSEP
    name = name.to_s[2..-1]
    namespace = Registry.root
  end

  if name =~ /(?:#{NSEPQ})([^:]+)$/
    return new(Proxy.new(namespace, $`), $1, *args, &block)
  end

  obj = super(namespace, name, *args)
  existing_obj = Registry.at(obj.path)
  obj = existing_obj if existing_obj && existing_obj.class == self
  yield(obj) if block_given?
  obj
end

Instance Method Details

#[](key) ⇒ Object?

Accesses a custom attribute on the object

See Also:



328
329
330
331
332
333
334
# File 'lib/yard/code_objects/base.rb', line 328

def [](key)
  if respond_to?(key)
    send(key)
  elsif instance_variable_defined?("@#{key}")
    instance_variable_get("@#{key}")
  end
end

#[]=(key, value) ⇒ void

This method returns an undefined value.

Sets a custom attribute on the object

See Also:



341
342
343
344
345
346
347
# File 'lib/yard/code_objects/base.rb', line 341

def []=(key, value)
  if respond_to?("#{key}=")
    send("#{key}=", value)
  else
    instance_variable_set("@#{key}", value)
  end
end

#add_file(file, line = nil, has_comments = false) ⇒ Object

Associates a file with a code object, optionally adding the line where it was defined. By convention, '<stdin>' should be used to associate code that comes form standard input.

Raises:

  • (ArgumentError)


276
277
278
279
280
281
282
283
284
285
286
# File 'lib/yard/code_objects/base.rb', line 276

def add_file(file, line = nil, has_comments = false)
  raise(ArgumentError, "file cannot be nil or empty") if file.nil? || file == ''
  obj = [file.to_s, line]
  return if files.include?(obj)
  if has_comments && !@current_file_has_comments
    @current_file_has_comments = true
    @files.unshift(obj)
  else
    @files << obj # back of the line
  end
end

#add_tag(*tags) ⇒ Object

Add tags to the #docstring

See Also:

Since:

  • 0.8.4



541
542
543
544
# File 'lib/yard/code_objects/base.rb', line 541

def add_tag(*tags)
  @docstrings.clear
  @docstring.add_tag(*tags)
end

#copy_to(other) ⇒ Base

Copies all data in this object to another code object, except for uniquely identifying information (path, namespace, name, scope).

Since:

  • 0.8.0



249
250
251
252
253
254
255
256
# File 'lib/yard/code_objects/base.rb', line 249

def copy_to(other)
  copyable_attributes.each do |ivar|
    ivar = "@#{ivar}"
    other.instance_variable_set(ivar, instance_variable_get(ivar))
  end
  other.docstring = @docstring.to_raw
  other
end

#copyable_attributesArray<String> (protected)

Override this method if your code object subclass does not allow copying of certain attributes.

See Also:

Since:

  • 0.8.0



567
568
569
570
571
# File 'lib/yard/code_objects/base.rb', line 567

def copyable_attributes
  vars = instance_variables.map {|ivar| ivar.to_s[1..-1] }
  vars -= %w(docstring docstrings namespace name path)
  vars
end

#docstring(locale = I18n::Locale.default) ⇒ Docstring

The documentation string associated with the object



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
# File 'lib/yard/code_objects/base.rb', line 387

def docstring(locale = I18n::Locale.default)
  if locale.nil?
    @docstring.resolve_reference
    return @docstring
  end

  if locale.is_a?(String)
    locale_name = locale
    locale = nil
  else
    locale_name = locale.name
  end
  @docstrings[locale_name] ||=
    translate_docstring(locale || Registry.locale(locale_name))
end

#docstring=(comments) ⇒ Object

Attaches a docstring to a code object by parsing the comments attached to the statement and filling the #tags and #docstring methods with the parsed information.



409
410
411
412
413
414
415
416
# File 'lib/yard/code_objects/base.rb', line 409

def docstring=(comments)
  @docstrings.clear
  if Docstring === comments
    @docstring = comments
  else
    @docstring = Docstring.new(comments, self)
  end
end

#dynamic?Boolean

Is the object defined conditionally at runtime?

See Also:



168
# File 'lib/yard/code_objects/base.rb', line 168

def dynamic?; @dynamic end

#equal?(other) ⇒ Boolean Also known as: ==, eql?

Tests if another object is equal to this, including a proxy



308
309
310
311
312
313
314
# File 'lib/yard/code_objects/base.rb', line 308

def equal?(other)
  if other.is_a?(Base) || other.is_a?(Proxy)
    path == other.path
  else
    super
  end
end

#fileString

Returns the filename the object was first parsed at, taking definitions with docstrings first.



292
293
294
# File 'lib/yard/code_objects/base.rb', line 292

def file
  @files.first ? @files.first[0] : nil
end

#format(options = {}) ⇒ String

Renders the object using the templating system.

Examples:

Formats a class in plaintext

puts P('MyClass').format

Formats a method in html with rdoc markup

puts P('MyClass#meth').format(:format => :html, :markup => :rdoc)

Options Hash (options):

  • :format (Symbol) — default: :text

    :html, :text or another output format

  • :template (Symbol) — default: :default

    a specific template to use

  • :markup (Symbol) — default: nil

    the markup type (:rdoc, :markdown, :textile)

  • :serializer (Serializers::Base) — default: nil

    see Serializers

See Also:

  • Templates::Engine#render


490
491
492
493
494
# File 'lib/yard/code_objects/base.rb', line 490

def format(options = {})
  options = options.merge(:object => self)
  options = options.merge(:type => type) if !options[:type]
  Templates::Engine.render(options)
end

#has_tag?(name) ⇒ Boolean

Tests if the #docstring has a tag

See Also:



536
# File 'lib/yard/code_objects/base.rb', line 536

def has_tag?(name); docstring.has_tag?(name) end

#hashInteger



319
# File 'lib/yard/code_objects/base.rb', line 319

def hash; path.hash end

#inspectString

Inspects the object, returning the type and path



498
499
500
# File 'lib/yard/code_objects/base.rb', line 498

def inspect
  "#<yardoc #{type} #{path}>"
end

#lineFixnum?

Returns the line the object was first parsed at (or nil)



300
301
302
# File 'lib/yard/code_objects/base.rb', line 300

def line
  @files.first ? @files.first[1] : nil
end

#name(prefix = false) ⇒ Symbol, String

The name of the object



264
265
266
# File 'lib/yard/code_objects/base.rb', line 264

def name(prefix = false)
  prefix ? @name.to_s : @name
end

#pathString Also known as: to_s

Represents the unique path of the object. The default implementation joins the path of #namespace with #name via the value of #sep. Custom code objects should ensure that the path is unique to the code object by either overriding #sep or this method.

Examples:

The path of an instance method

MethodObject.new(P("A::B"), :c).path # => "A::B#c"

See Also:



435
436
437
438
439
440
441
# File 'lib/yard/code_objects/base.rb', line 435

def path
  @path ||= if parent && !parent.root?
    [parent.path, name.to_s].join(sep)
  else
    name.to_s
  end
end

#relative_path(other) ⇒ String

Returns the shortest relative path from this object to other

Since:

  • 0.5.3



457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
# File 'lib/yard/code_objects/base.rb', line 457

def relative_path(other)
  other = Registry.at(other) if String === other && Registry.at(other)
  same_parent = false
  if other.respond_to?(:path)
    same_parent = other.parent == parent
    other = other.path
  end
  return other unless namespace
  common = [path, other].join(" ").match(/^(\S*)\S*(?: \1\S*)*$/)[1]
  common = path unless common =~ /(\.|::|#)$/
  common = common.sub(/(\.|::|#)[^:#\.]*?$/, '') if same_parent
  if %w(. :).include?(common[-1,1]) || other[common.size,1] == '#'
    suffix = ''
  else
    suffix = '(::|\.)'
  end
  result = other.sub(/^#{Regexp.quote common}#{suffix}/, '')
  result.empty? ? other : result
end

#root?Boolean



547
# File 'lib/yard/code_objects/base.rb', line 547

def root?; false end

#sepString

Override this method with a custom component separator. For instance, MethodObject implements sep as '#' or '.' (depending on if the method is instance or class respectively). #path depends on this value to generate the full path in the form: namespace.path + sep + name



556
# File 'lib/yard/code_objects/base.rb', line 556

def sep; NSEP end

#tag(name) ⇒ Object

Gets a tag from the #docstring

See Also:



528
# File 'lib/yard/code_objects/base.rb', line 528

def tag(name); docstring.tag(name) end

#tags(name = nil) ⇒ Object

Gets a list of tags from the #docstring

See Also:



532
# File 'lib/yard/code_objects/base.rb', line 532

def tags(name = nil); docstring.tags(name) end

#titleString

Note:

Override this method if your object has a special title that does not match the #path attribute value. This title will be used when linking or displaying the object.

Returns the display title for an object

See Also:

  • YARD::CodeObjects::Base.00.80.8.4


450
451
452
# File 'lib/yard/code_objects/base.rb', line 450

def title
  path
end

#to_arynil



322
# File 'lib/yard/code_objects/base.rb', line 322

def to_ary; nil end

#typeSymbol

Default type is the lowercase class name without the “Object” suffix. Override this method to provide a custom object type



422
423
424
# File 'lib/yard/code_objects/base.rb', line 422

def type
  self.class.name.split('::').last.gsub(/Object$/, '').downcase.to_sym
end