Class | YARD::CodeObjects::Base
In: | lib/yard/code_objects/base.rb
Parent: | Object

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

@abstract This class should not be used directly. Instead, create a

      subclass that implements {#path}, {#sep} or {#type}.

@see Registry @see path @see #[]= @see NamespaceObject

### Methods

== === [] []= add_file copy_to copyable_attributes docstring docstring= dynamic? eql? equal? file format has_tag? hash inspect line method_missing name namespace= new new parent= path relative_path root? sep source= tag tags to_ary to_s type visibility=

### External Aliases

namespace | -> | parent

### Attributes

docstring | [R] | The documentation string associated with the object @return [Docstring] the documentation string
dynamic | [RW] | Marks whether or not the method is conditionally defined at runtime @return [Boolean] true if the method is conditionally defined at runtime
files | [R] | The files the object was defined in. To add a file, use {add_file}. @return [Array<String>] a list of files @see add_file
group | [RW] | @return [String] the group this object is associated with @since 0.6.0
namespace | [R] | The namespace the object is defined in. If the object is in the top level namespace, this is {Registry.root} @return [NamespaceObject] the namespace object
signature | [RW] | 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. @return [String] a line of source
source | [R] | The source code associated with the object @return [String, nil] source, if present, or nil
source_type | [RW] | Language of the source code associated with the object. Defaults to +:ruby+. @return [Symbol] the language type
visibility | [RW] | @return [Symbol] the visibility of an object (:public, :private, :protected)

### Public Class methods

===(other)

Compares the class with subclasses

@param [Object] other the other object to compare classes with @return [Boolean] true if other is a subclass of self

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

Allocates a new code object @return [Base] @see initialize

new(namespace, name, *args) {|self| ...}

Creates a new code object

@example Create a method in the root namespace

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

@example Create class Z inside namespace X::Y

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

@param [NamespaceObject] namespace the namespace the object belongs in,

      {Registry.root} or :root should be provided if it is associated with
      the top level namespace.

@param [Symbol, String] name the name (or complex path) of the object. @yield [self] a block to perform any extra initialization on the object @yieldparam [Base] self the newly initialized code object @return [Base] the newly created object

### Public Instance methods

==(other)

Alias for equal?

[](key)

Accesses a custom attribute on the object @param [to_s] key the name of the custom attribute @return [Object, nil] the custom attribute or nil if not found. @see #[]=

[]=(key, value)

Sets a custom attribute on the object @param [to_s] key the name of the custom attribute @param [Object] value the value to associate @return [void] @see #[]

add_file(file, line = nil, has_comments = false)

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.

@param [String] file the filename (’<stdin>’ for standard input) @param [Fixnum, nil] line the line number where the object lies in the file @param [Boolean] has_comments 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).

copy_to(other)

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

@param [Base] other the object to copy data to @return [Base] the other object @since 0.8.0

docstring()
docstring=(comments)

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.

@param [String, Array<String>, Docstring] comments

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

dynamic?()

Is the object defined conditionally at runtime? @see dynamic

eql?(other)

Alias for equal?

equal?(other)

Tests if another object is equal to this, including a proxy @param [Base, Proxy] other if other is a {Proxy}, tests if

      the paths are equal

@return [Boolean] whether or not the objects are considered the same

file()

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

@return [String] a filename

format(options = {})

Renders the object using the {Templates::Engine templating system}.

@example Formats a class in plaintext

      puts P('MyClass').format

@example Formats a method in html with rdoc markup

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

@param [Hash] options a set of options to pass to the template @option options [Symbol] :format (:text) :html, :text or another output format @option options [Symbol] :template (:default) a specific template to use @option options [Symbol] :markup (nil) the markup type (:rdoc, :markdown, :textile) @option options [Serializers::Base] :serializer (nil) see Serializers @return [String] the rendered template @see Templates::Engine#render

has_tag?(name)

Tests if the {docstring} has a tag @see Docstring#has_tag?

hash()

@return [Integer] the object‘s hash value (for equality checking)

inspect()

Inspects the object, returning the type and path @return [String] a string describing the object

line()

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

@return [Fixnum] the line where the object was first defined. @return [nil] if there is no line associated with the object

method_missing(meth, *args, &block)

@overload dynamic_attr_name

      @return the value of attribute named by the method attribute name
      @raise [NoMethodError] if no method or custom attribute exists by
        the attribute name
      @see #[]

@overload dynamic_attr_name=(value)

      @param value a value to set
      @return +value+
      @see #[]=

name(prefix = false)

The name of the object @param [Boolean] prefix whether to show a prefix. Implement

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

@return [Symbol] if prefix is false, the symbolized name @return [String] if prefix is true, prefix + the name as a String.

      This must be implemented by the subclass.

namespace=(obj)

Sets the namespace the object is defined in.

@param [NamespaceObject, :root, nil] obj the new namespace (:root

      for {Registry.root}). If obj is nil, the object is unregistered
      from the Registry.

parent=(obj)

Alias for namespace=

path()

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.

@example The path of an instance method

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

@return [String] the unique path of the object @see sep

relative_path(other)

@param [Base, String] other another code object (or object path) @return [String] the shortest relative path from this object to `other` @since 0.5.3

root?()

@return whether or not this object is a RootObject

sep()

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

@return [String] the component that separates the namespace path

      and the name (default is {NSEP})

source=(statement)

Attaches source code to a code object with an optional file location

@param [source, String] statement

      the +Parser::Statement+ holding the source code or the raw source
      as a +String+ for the definition of the code object only (not the block)

tag(name)

Gets a tag from the {docstring} @see Docstring#tag

tags(name = nil)

Gets a list of tags from the {docstring} @see Docstring#tags

to_ary()

@return [nil] this object does not turn into an array

to_s()

Alias for path

type()

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

@return [Symbol] the type of code object this represents

visibility=(v)

### Protected Instance methods

copyable_attributes()

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

@return [Array<String>] the list of instance variable names (without

      "@" prefix) that should be copied when {#copy_to} is called

@see copy_to @since 0.8.0

[Validate]