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


238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
# File 'lib/yard/code_objects/base.rb', line 238

def initialize(namespace, name, *)
  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:


372
373
374
375
376
377
378
379
380
# File 'lib/yard/code_objects/base.rb', line 372

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


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

def base_docstring
  @base_docstring
end

#dynamicBoolean

Marks whether or not the method is conditionally defined at runtime


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

def dynamic
  @dynamic
end

#filesArray<Array(String, Integer)> (readonly)

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

See Also:


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

def files
  @files
end

#groupString

Returns the group this object is associated with.

Since:

  • 0.6.0


174
175
176
# File 'lib/yard/code_objects/base.rb', line 174

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


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

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.


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

def signature
  @signature
end

#sourceString?

The source code associated with the object


146
147
148
# File 'lib/yard/code_objects/base.rb', line 146

def source
  @source
end

#source_typeSymbol

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


152
153
154
# File 'lib/yard/code_objects/base.rb', line 152

def source_type
  @source_type
end

#visibilitySymbol


181
182
183
# File 'lib/yard/code_objects/base.rb', line 181

def visibility
  @visibility
end

Class Method Details

.===(other) ⇒ Boolean

Compares the class with subclasses


219
220
221
# File 'lib/yard/code_objects/base.rb', line 219

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

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

Allocates a new code object

Yields:

  • (obj)

Raises:

  • (ArgumentError)

See Also:


189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
# File 'lib/yard/code_objects/base.rb', line 189

def new(namespace, name, *args, &block)
  raise ArgumentError, "invalid empty object name" if name.to_s.empty?
  if namespace.is_a?(ConstantObject)
    unless namespace.value =~ /\A#{NAMESPACEMATCH}\Z/
      raise Parser::UndocumentableError, "constant mapping"
    end

    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:


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

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:


355
356
357
358
359
360
361
# File 'lib/yard/code_objects/base.rb', line 355

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)

290
291
292
293
294
295
296
297
298
299
300
# File 'lib/yard/code_objects/base.rb', line 290

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


557
558
559
560
# File 'lib/yard/code_objects/base.rb', line 557

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


263
264
265
266
267
268
269
270
# File 'lib/yard/code_objects/base.rb', line 263

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


583
584
585
586
587
# File 'lib/yard/code_objects/base.rb', line 583

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


404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
# File 'lib/yard/code_objects/base.rb', line 404

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.


426
427
428
429
430
# File 'lib/yard/code_objects/base.rb', line 426

def docstring=(comments)
  @docstrings.clear
  @docstring = Docstring === comments ?
    comments : Docstring.new(comments, self)
end

#dynamic?Boolean

Is the object defined conditionally at runtime?

See Also:


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

def dynamic?; @dynamic end

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

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


322
323
324
325
326
327
328
# File 'lib/yard/code_objects/base.rb', line 322

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.


306
307
308
# File 'lib/yard/code_objects/base.rb', line 306

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

501
502
503
504
505
# File 'lib/yard/code_objects/base.rb', line 501

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

#has_tag?(name) ⇒ Boolean

Tests if the #docstring has a tag

See Also:


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

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

#hashInteger


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

def hash; path.hash end

#inspectString

Inspects the object, returning the type and path


509
510
511
# File 'lib/yard/code_objects/base.rb', line 509

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

#lineFixnum?

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


314
315
316
# File 'lib/yard/code_objects/base.rb', line 314

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

#name(prefix = false) ⇒ Symbol, String

The name of the object


278
279
280
# File 'lib/yard/code_objects/base.rb', line 278

def name(prefix = false)
  prefix ? @name.to_s : (defined?(@name) && @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:


449
450
451
452
453
454
455
# File 'lib/yard/code_objects/base.rb', line 449

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


471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
# File 'lib/yard/code_objects/base.rb', line 471

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
  suffix = %w(. :).include?(common[-1, 1]) || other[common.size, 1] == '#' ?
    '' : '(::|\.)'
  result = other.sub(/^#{Regexp.quote common}#{suffix}/, '')
  result.empty? ? other : result
end

#root?Boolean


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

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


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

def sep; NSEP end

#tag(name) ⇒ Object

Gets a tag from the #docstring

See Also:


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

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

#tags(name = nil) ⇒ Object

Gets a list of tags from the #docstring

See Also:


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

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

464
465
466
# File 'lib/yard/code_objects/base.rb', line 464

def title
  path
end

#to_arynil


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

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


436
437
438
# File 'lib/yard/code_objects/base.rb', line 436

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