Class: YARD::CodeObjects::Base Abstract
- Inherits:
-
Object
- Object
- YARD::CodeObjects::Base
- Defined in:
- lib/yard/code_objects/base.rb
Overview
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.
Direct Known Subclasses
ClassVariableObject, ConstantObject, MacroObject, MethodObject, NamespaceObject
Instance Attribute Summary (collapse)
-
- (Docstring) base_docstring
readonly
The non-localized documentation string associated with the object.
-
- (Boolean) dynamic
Marks whether or not the method is conditionally defined at runtime.
-
- (Array<String>) files
readonly
The files the object was defined in.
-
- (String) group
The group this object is associated with.
-
- (NamespaceObject) namespace
(also: #parent)
The namespace the object is defined in.
-
- (String) signature
The one line signature representing an object.
-
- (String?) source
The source code associated with the object.
-
- (Symbol) source_type
Language of the source code associated with the object.
-
- (Symbol) visibility
The visibility of an object (:public, :private, :protected).
Class Method Summary (collapse)
-
+ (Boolean) ===(other)
Compares the class with subclasses.
-
+ (Base) new(namespace, name, *args) {|obj| ... }
Allocates a new code object.
Instance Method Summary (collapse)
-
- (Object?) [](key)
Accesses a custom attribute on the object.
-
- (void) []=(key, value)
Sets a custom attribute on the object.
-
- (Object) add_file(file, line = nil, has_comments = false)
Associates a file with a code object, optionally adding the line where it was defined.
-
- (Object) add_tag(*tags)
Add tags to the #docstring.
-
- (Base) copy_to(other)
Copies all data in this object to another code object, except for uniquely identifying information (path, namespace, name, scope).
-
- (Array<String>) copyable_attributes
protected
Override this method if your code object subclass does not allow copying of certain attributes.
-
- (Docstring) docstring(locale = I18n::Locale.default)
The documentation string associated with the object.
-
- (Object) 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.
-
- (Boolean) dynamic?
Is the object defined conditionally at runtime?.
-
- (Boolean) equal?(other)
(also: #==, #eql?)
Tests if another object is equal to this, including a proxy.
-
- (String) file
Returns the filename the object was first parsed at, taking definitions with docstrings first.
-
- (String) format(options = {})
Renders the object using the templating system.
-
- (Boolean) has_tag?(name)
Tests if the #docstring has a tag.
-
- (Integer) hash
The object's hash value (for equality checking).
-
- (Base) initialize(namespace, name, *args) {|self| ... }
constructor
Creates a new code object.
-
- (String) inspect
Inspects the object, returning the type and path.
-
- (Fixnum?) line
Returns the line the object was first parsed at (or nil).
- - (Object) method_missing(meth, *args, &block)
-
- (Symbol, String) name(prefix = false)
The name of the object.
-
- (String) path
(also: #to_s)
Represents the unique path of the object.
-
- (String) relative_path(other)
The shortest relative path from this object to
other
. -
- (Boolean) root?
Whether or not this object is a RootObject.
-
- (String) sep
Override this method with a custom component separator.
-
- (Object) tag(name)
Gets a tag from the #docstring.
-
- (Object) tags(name = nil)
Gets a list of tags from the #docstring.
-
- (String) title
The display title for an object.
-
- (nil) to_ary
This object does not turn into an array.
-
- (Symbol) type
Default type is the lowercase class name without the “Object” suffix.
Constructor Details
- (Base) initialize(namespace, name, *args) {|self| ... }
Creates a new code object
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 |
# File 'lib/yard/code_objects/base.rb', line 212 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
- (Object) dynamic_attr_name - (Object) dynamic_attr_name=(value)
346 347 348 349 350 351 352 353 354 |
# File 'lib/yard/code_objects/base.rb', line 346 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
- (Docstring) base_docstring (readonly)
The non-localized documentation string associated with the object
142 143 144 |
# File 'lib/yard/code_objects/base.rb', line 142 def base_docstring @base_docstring end |
- (Boolean) dynamic
Marks whether or not the method is conditionally defined at runtime
148 149 150 |
# File 'lib/yard/code_objects/base.rb', line 148 def dynamic @dynamic end |
- (Array<String>) files (readonly)
The files the object was defined in. To add a file, use #add_file.
115 116 117 |
# File 'lib/yard/code_objects/base.rb', line 115 def files @files end |
- (String) group
Returns the group this object is associated with
152 153 154 |
# File 'lib/yard/code_objects/base.rb', line 152 def group @group end |
- (NamespaceObject) namespace Also known as: parent
The namespace the object is defined in. If the object is in the top level namespace, this is Registry.root
120 121 122 |
# File 'lib/yard/code_objects/base.rb', line 120 def namespace @namespace end |
- (String) signature
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.
137 138 139 |
# File 'lib/yard/code_objects/base.rb', line 137 def signature @signature end |
- (String?) source
The source code associated with the object
124 125 126 |
# File 'lib/yard/code_objects/base.rb', line 124 def source @source end |
- (Symbol) source_type
Language of the source code associated with the object. Defaults to
:ruby
.
130 131 132 |
# File 'lib/yard/code_objects/base.rb', line 130 def source_type @source_type end |
- (Symbol) visibility
Returns the visibility of an object (:public, :private, :protected)
159 160 161 |
# File 'lib/yard/code_objects/base.rb', line 159 def visibility @visibility end |
Class Method Details
+ (Boolean) ===(other)
Compares the class with subclasses
193 194 195 |
# File 'lib/yard/code_objects/base.rb', line 193 def ===(other) other.is_a?(self) end |
+ (Base) new(namespace, name, *args) {|obj| ... }
Allocates a new code object
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 |
# File 'lib/yard/code_objects/base.rb', line 167 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
- (Object?) [](key)
Accesses a custom attribute on the object
316 317 318 319 320 321 322 |
# File 'lib/yard/code_objects/base.rb', line 316 def [](key) if respond_to?(key) send(key) elsif instance_variable_defined?("@#{key}") instance_variable_get("@#{key}") end end |
- (void) []=(key, value)
This method returns an undefined value.
Sets a custom attribute on the object
329 330 331 332 333 334 335 |
# File 'lib/yard/code_objects/base.rb', line 329 def []=(key, value) if respond_to?("#{key}=") send("#{key}=", value) else instance_variable_set("@#{key}", value) end end |
- (Object) 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.
264 265 266 267 268 269 270 271 272 273 274 |
# File 'lib/yard/code_objects/base.rb', line 264 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 |
- (Object) add_tag(*tags)
Add tags to the #docstring
528 529 530 531 |
# File 'lib/yard/code_objects/base.rb', line 528 def add_tag(*) @docstrings.clear @docstring.add_tag(*) end |
- (Base) copy_to(other)
Copies all data in this object to another code object, except for uniquely identifying information (path, namespace, name, scope).
237 238 239 240 241 242 243 244 |
# File 'lib/yard/code_objects/base.rb', line 237 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 |
- (Array<String>) copyable_attributes (protected)
Override this method if your code object subclass does not allow copying of certain attributes.
554 555 556 557 558 |
# File 'lib/yard/code_objects/base.rb', line 554 def copyable_attributes vars = instance_variables.map {|ivar| ivar.to_s[1..-1] } vars -= %w(docstring docstrings namespace name path) vars end |
- (Docstring) docstring(locale = I18n::Locale.default)
The documentation string associated with the object
375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 |
# File 'lib/yard/code_objects/base.rb', line 375 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 |
- (Object) 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.
397 398 399 400 401 402 403 404 |
# File 'lib/yard/code_objects/base.rb', line 397 def docstring=(comments) @docstrings.clear if Docstring === comments @docstring = comments else @docstring = Docstring.new(comments, self) end end |
- (Boolean) dynamic?
Is the object defined conditionally at runtime?
156 |
# File 'lib/yard/code_objects/base.rb', line 156 def dynamic?; @dynamic end |
- (Boolean) equal?(other) Also known as: ==, eql?
Tests if another object is equal to this, including a proxy
296 297 298 299 300 301 302 |
# File 'lib/yard/code_objects/base.rb', line 296 def equal?(other) if other.is_a?(Base) || other.is_a?(Proxy) path == other.path else super end end |
- (String) file
Returns the filename the object was first parsed at, taking definitions with docstrings first.
280 281 282 |
# File 'lib/yard/code_objects/base.rb', line 280 def file @files.first ? @files.first[0] : nil end |
- (String) format(options = {})
Renders the object using the templating system.
478 479 480 481 |
# File 'lib/yard/code_objects/base.rb', line 478 def format( = {}) = .merge(:object => self) Templates::Engine.render() end |
- (Boolean) has_tag?(name)
Tests if the #docstring has a tag
523 |
# File 'lib/yard/code_objects/base.rb', line 523 def has_tag?(name); docstring.has_tag?(name) end |
- (Integer) hash
Returns the object's hash value (for equality checking)
307 |
# File 'lib/yard/code_objects/base.rb', line 307 def hash; path.hash end |
- (String) inspect
Inspects the object, returning the type and path
485 486 487 |
# File 'lib/yard/code_objects/base.rb', line 485 def inspect "#<yardoc #{type} #{path}>" end |
- (Fixnum?) line
Returns the line the object was first parsed at (or nil)
288 289 290 |
# File 'lib/yard/code_objects/base.rb', line 288 def line @files.first ? @files.first[1] : nil end |
- (Symbol, String) name(prefix = false)
The name of the object
252 253 254 |
# File 'lib/yard/code_objects/base.rb', line 252 def name(prefix = false) prefix ? @name.to_s : @name end |
- (String) path 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.
423 424 425 426 427 428 429 |
# File 'lib/yard/code_objects/base.rb', line 423 def path @path ||= if parent && !parent.root? [parent.path, name.to_s].join(sep) else name.to_s end end |
- (String) relative_path(other)
Returns the shortest relative path from this object to other
445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 |
# File 'lib/yard/code_objects/base.rb', line 445 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 |
- (Boolean) root?
Returns whether or not this object is a RootObject
534 |
# File 'lib/yard/code_objects/base.rb', line 534 def root?; false end |
- (String) 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
543 |
# File 'lib/yard/code_objects/base.rb', line 543 def sep; NSEP end |
- (Object) tag(name)
Gets a tag from the #docstring
515 |
# File 'lib/yard/code_objects/base.rb', line 515 def tag(name); docstring.tag(name) end |
- (Object) tags(name = nil)
Gets a list of tags from the #docstring
519 |
# File 'lib/yard/code_objects/base.rb', line 519 def (name = nil); docstring.(name) end |
- (String) title
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
438 439 440 |
# File 'lib/yard/code_objects/base.rb', line 438 def title path end |
- (nil) to_ary
Returns this object does not turn into an array
310 |
# File 'lib/yard/code_objects/base.rb', line 310 def to_ary; nil end |
- (Symbol) type
Default type is the lowercase class name without the “Object” suffix. Override this method to provide a custom object type
410 411 412 |
# File 'lib/yard/code_objects/base.rb', line 410 def type self.class.name.split('::').last.gsub(/Object$/, '').downcase.to_sym end |