# Class: YARD::CodeObjects::Base Abstract

Inherits:
  Object
  - Object
  - YARD::CodeObjects::Base
  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).

See Also:

- Registry
- #path
- #[]=
- NamespaceObject
- NamespaceMapper#register_separator

## Direct Known Subclasses

ClassVariableObject, ConstantObject, MacroObject, MethodObject, NamespaceObject

## Instance Attribute Summary collapse

- #base_docstring ⇒ Docstring readonly

  The non-localized documentation string associated with the object.

- #dynamic ⇒ Boolean

  Marks whether or not the method is conditionally defined at runtime.

- #files ⇒ Array<Array(String, Integer)> readonly

  The files the object was defined in.

- #group ⇒ String

  The group this object is associated with.

- #namespace ⇒ NamespaceObject (also: #parent)

  The namespace the object is defined in.

- #signature ⇒ String

  The one line signature representing an object.

- #source ⇒ String?

  The source code associated with the object.

- #source_type ⇒ Symbol

  Language of the source code associated with the object.

- #visibility ⇒ Symbol

  The visibility of an object (:public, :private, :protected).

## Class Method Summary collapse

- .===(other) ⇒ Boolean

  Compares the class with subclasses.

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

  Allocates a new code object.

## Instance Method Summary collapse

- #[](key) ⇒ Object?

  Accesses a custom attribute on the object.

- #[]=(key, value) ⇒ void

  Sets a custom attribute on the object.

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

  Associates a file with a code object, optionally adding the line where it was defined.

- #add_tag(*tags) ⇒ Object

  Add tags to the #docstring.

- #copy_to(other) ⇒ Base

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

- #copyable_attributes ⇒ Array<String> protected

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

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

  The documentation string associated with the object.

- #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.

- #dynamic? ⇒ Boolean

  Is the object defined conditionally at runtime?.

- #equal?(other) ⇒ Boolean (also: #==, #eql?)

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

- #file ⇒ String?

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

- #format(options = {}) ⇒ String

  Renders the object using the templating system.

- #has_tag?(name) ⇒ Boolean

  Tests if the #docstring has a tag.

- #hash ⇒ Integer

  The object’s hash value (for equality checking).

- #initialize(namespace, name) {|self| ... } ⇒ Base constructor

  Creates a new code object.

- #inspect ⇒ String

  Inspects the object, returning the type and path.

- #line ⇒ Fixnum?

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

- #method_missing(meth, *args, &block) ⇒ Object
- #name(prefix = false) ⇒ Symbol, String

  The name of the object.

- #path ⇒ String (also: #to_s)

  Represents the unique path of the object.

- #relative_path(other) ⇒ String

  The shortest relative path from this object to `other`.

- #root? ⇒ Boolean

  Whether or not this object is a RootObject.

- #sep ⇒ String

  Override this method with a custom component separator.

- #tag(name) ⇒ Object

  Gets a tag from the #docstring.

- #tags(name = nil) ⇒ Object

  Gets a list of tags from the #docstring.

- #title ⇒ String

  The display title for an object.

- #to_ary ⇒ nil

  This object does not turn into an array.

- #type ⇒ Symbol

  Default type is the lowercase class name without the “Object” suffix.

## 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")

Parameters:

- namespace (`NamespaceObject`, `:root`, `nil`) —

  the namespace the object belongs in, Registry.root or :root should be provided if it is associated with the top level namespace.

- name (`Symbol`, `String`) —

  the name (or complex path) of the object.

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_name ⇒ `Object` #dynamic_attr_name=(value) ⇒ `Object`

Overloads:

- #dynamic_attr_name ⇒ `Object`

  Returns the value of attribute named by the method attribute name.

  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`.

  Parameters:

  - value —

    a value to set

  Returns:

  - `value`

  See Also:

  - #[]=

    373
    374
    375
    376
    377
    378
    379
    380
    381

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

    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_docstring ⇒ `Docstring` (readonly)

The non-localized documentation string associated with the object

Returns:

- (`Docstring`) —

  the documentation string

Since:

- 0.8.4

    164
    165
    166

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

    def base_docstring
      @base_docstring
    end

### #dynamic ⇒ `Boolean`

Marks whether or not the method is conditionally defined at runtime

Returns:

- (`Boolean`) —

  true if the method is conditionally defined at runtime

    170
    171
    172

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

    def dynamic
      @dynamic
    end

### #files ⇒ `Array<Array(String, Integer)>` (readonly)

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

Returns:

- (`Array<Array(String, Integer)>`) —

  a list of files

See Also:

- #add_file

    137
    138
    139

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

    def files
      @files
    end

### #group ⇒ `String`

Returns the group this object is associated with.

Returns:

- (`String`) —

  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

### #namespace ⇒ `NamespaceObject` Also known as: parent

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

Returns:

- (`NamespaceObject`) —

  the namespace object

    142
    143
    144

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

    def namespace
      @namespace
    end

### #signature ⇒ `String`

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.

Returns:

- (`String`) —

  a line of source

    159
    160
    161

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

    def signature
      @signature
    end

### #source ⇒ `String`?

The source code associated with the object

Returns:

- (`String`, `nil`) —

  source, if present, or nil

    146
    147
    148

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

    def source
      @source
    end

### #source_type ⇒ `Symbol`

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

Returns:

- (`Symbol`) —

  the language type

    152
    153
    154

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

    def source_type
      @source_type
    end

### #visibility ⇒ `Symbol`

Returns the visibility of an object (:public, :private, :protected).

Returns:

- (`Symbol`) —

  the visibility of an object (:public, :private, :protected)

    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

Parameters:

- other (`Object`) —

  the other object to compare classes with

Returns:

- (`Boolean`) —

  true if other is a subclass of self

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

Returns:

- (`Base`)

Raises:

- (`ArgumentError`)

See Also:

- #initialize

    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

Parameters:

- key (`#to_s`) —

  the name of the custom attribute

Returns:

- (`Object`, `nil`) —

  the custom attribute or nil if not found.

See Also:

- #[]=

    343
    344
    345
    346
    347
    348
    349

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

    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

Parameters:

- key (`#to_s`) —

  the name of the custom attribute

- value (`Object`) —

  the value to associate

See Also:

- #[]

    356
    357
    358
    359
    360
    361
    362

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

    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.

Parameters:

- file (`String`) —

  the filename (‘<stdin>’ for standard input)

- line (`Fixnum`, `nil`) (defaults to: `nil`) —

  the line number where the object lies in the file

- has_comments (`Boolean`) (defaults to: `false`) —

  whether or not the definition has comments associated. This will allow #file to return the definition where the comments were made instead of any empty definitions that might have been parsed before (module namespaces for instance).

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:

- Docstring#add_tag

Since:

- 0.8.4

    561
    562
    563
    564

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

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

Parameters:

- other (`Base`) —

  the object to copy data to

Returns:

- (`Base`) —

  the other object

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_attributes ⇒ `Array<String>` (protected)

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

Returns:

- (`Array<String>`) —

  the list of instance variable names (without “@” prefix) that should be copied when #copy_to is called

See Also:

- #copy_to

Since:

- 0.8.0

    587
    588
    589
    590
    591

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

    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

Parameters:

- locale (`String`, `I18n::Locale`) (defaults to: `I18n::Locale.default`) —

  (I18n::Locale.default) the locale of the documentation string.

Returns:

- (`Docstring`) —

  the documentation string

    405
    406
    407
    408
    409
    410
    411
    412
    413
    414
    415
    416
    417
    418
    419

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

    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.

Parameters:

- comments (`String`, `Array<String>`, `Docstring`) —

  the comments attached to the code object to be parsed into a docstring and meta tags.

    427
    428
    429
    430
    431

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

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

### #dynamic? ⇒ `Boolean`

Is the object defined conditionally at runtime?

Returns:

- (`Boolean`)

See Also:

- #dynamic

    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

Parameters:

- other (`Base`, `Proxy`) —

  if other is a Proxy, tests if the paths are equal

Returns:

- (`Boolean`) —

  whether or not the objects are considered the same

    323
    324
    325
    326
    327
    328
    329

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

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

### #file ⇒ `String`?

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

Returns:

- (`String`) —

  a filename

- (`nil`) —

  if there is no file associated with the object

    307
    308
    309

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

    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)

Parameters:

- options (`Hash`) (defaults to: `{}`) —

  a set of options to pass to the template

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

Returns:

- (`String`) —

  the rendered template

See Also:

- Templates::Engine#render

    505
    506
    507
    508
    509

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

    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

Returns:

- (`Boolean`)

See Also:

- Docstring#has_tag?

    556

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

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

### #hash ⇒ `Integer`

Returns the object’s hash value (for equality checking).

Returns:

- (`Integer`) —

  the object’s hash value (for equality checking)

    334

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

    def hash; path.hash end

### #inspect ⇒ `String`

Inspects the object, returning the type and path

Returns:

- (`String`) —

  a string describing the object

    513
    514
    515

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

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

### #line ⇒ `Fixnum`?

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

Returns:

- (`Fixnum`) —

  the line where the object was first defined.

- (`nil`) —

  if there is no line associated with the object

    315
    316
    317

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

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

### #name(prefix = false) ⇒ `Symbol`, `String`

The name of the object

Parameters:

- prefix (`Boolean`) (defaults to: `false`) —

  whether to show a prefix. Implement this in a subclass to define how the prefix is showed.

Returns:

- (`Symbol`) —

  if prefix is false, the symbolized name

- (`String`) —

  if prefix is true, prefix + the name as a String. This must be implemented by the subclass.

    278
    279
    280

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

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

### #path ⇒ `String` 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"

Returns:

- (`String`) —

  the unique path of the object

See Also:

- #sep

    453
    454
    455
    456
    457
    458
    459

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

    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`.

Parameters:

- other (`Base`, `String`) —

  another code object (or object path)

Returns:

- (`String`) —

  the shortest relative path from this object to `other`

Since:

- 0.5.3

    475
    476
    477
    478
    479
    480
    481
    482
    483
    484
    485
    486
    487
    488
    489
    490

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

    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`

Returns whether or not this object is a RootObject.

Returns:

- (`Boolean`) —

  whether or not this object is a RootObject

    567

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

    def root?; false end

### #sep ⇒ `String`

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

Returns:

- (`String`) —

  the component that separates the namespace path and the name (default is NSEP)

    576

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

    def sep; NSEP end

### #tag(name) ⇒ `Object`

Gets a tag from the #docstring

See Also:

- Docstring#tag

    548

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

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

### #tags(name = nil) ⇒ `Object`

Gets a list of tags from the #docstring

See Also:

- Docstring#tags

    552

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

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

### #title ⇒ `String`

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.

Returns:

- (`String`) —

  the display title for an object

See Also:

- YARD::CodeObjects::Base.00.80.8.4

    468
    469
    470

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

    def title
      path
    end

### #to_ary ⇒ `nil`

Returns this object does not turn into an array.

Returns:

- (`nil`) —

  this object does not turn into an array

    337

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

    def to_ary; nil end

### #type ⇒ `Symbol`

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

Returns:

- (`Symbol`) —

  the type of code object this represents

    437
    438
    439
    440
    441
    442

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

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