Class: YARD::CodeObjects::Proxy

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

Overview

The Proxy class is a way to lazily resolve code objects in cases where the object may not yet exist. A proxy simply stores an unresolved path until a method is called on the object, at which point it does a lookup using Registry.resolve. If the object is not found, a warning is raised and ProxyMethodError might be raised.

Examples:

Creates a Proxy to the String class from a module

# When the String class is parsed this method will
# begin to act like the String ClassObject.
Proxy.new(mymoduleobj, "String")

See Also:

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Proxy) initialize(namespace, name, type = nil)

Creates a new Proxy

Raises:

  • (ArgumentError)

    if namespace is not a NamespaceObject



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# File 'lib/yard/code_objects/proxy.rb', line 28

def initialize(namespace, name, type = nil)
  namespace = Registry.root if !namespace || namespace == :root

  if name =~ /^#{NSEPQ}/
    namespace = Registry.root
    name = name[2..-1]
  end

  if name =~ /(?:#{NSEPQ}|#{ISEPQ}|#{CSEPQ})([^#{NSEPQ}#{ISEPQ}#{CSEPQ}]+)$/
    @orignamespace, @origname = namespace, name
    @imethod = true if name.include? ISEP
    namespace = Proxy.new(namespace, $`) unless $`.empty?
    name = $1
  else
    @orignamespace, @origname, @imethod = nil, nil, nil
  end

  @name = name.to_sym
  @namespace = namespace
  @obj = nil
  @imethod ||= nil
  self.type = type

  if @namespace.is_a?(ConstantObject)
    @origname = nil # forget these for a constant
    @orignamespace = nil
    @namespace = Proxy.new(@namespace.namespace, @namespace.value)
  end

  unless @namespace.is_a?(NamespaceObject) or @namespace.is_a?(Proxy)
    raise ArgumentError, "Invalid namespace object: #{namespace}"
  end

  # If the name begins with "::" (like "::String")
  # this is definitely a root level object, so
  # remove the namespace and attach it to the root
  if @name =~ /^#{NSEPQ}/
    @name.gsub!(/^#{NSEPQ}/, '')
    @namespace = Registry.root
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

- (Object) method_missing(meth, *args, &block)

Dispatches the method to the resolved object.

Raises:



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

def method_missing(meth, *args, &block)
  if obj = to_obj
    obj.__send__(meth, *args, &block)
  else
    log.warn "Load Order / Name Resolution Problem on #{path}:"
    log.warn "-"
    log.warn "Something is trying to call #{meth} on object #{path} before it has been recognized."
    log.warn "This error usually means that you need to modify the order in which you parse files"
    log.warn "so that #{path} is parsed before methods or other objects attempt to access it."
    log.warn "-"
    log.warn "YARD will recover from this error and continue to parse but you *may* have problems"
    log.warn "with your generated documentation. You should probably fix this."
    log.warn "-"
    begin
      super
    rescue NoMethodError
      raise ProxyMethodError, "Proxy cannot call method ##{meth} on object '#{path}'"
    end
  end
end

Instance Attribute Details

- (Object) namespace (readonly) Also known as: parent

Returns the value of attribute namespace



21
22
23
# File 'lib/yard/code_objects/proxy.rb', line 21

def namespace
  @namespace
end

Class Method Details

+ (Object) ===(other)



19
# File 'lib/yard/code_objects/proxy.rb', line 19

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

Instance Method Details

- (Boolean) <=>(other)



120
121
122
123
124
125
126
# File 'lib/yard/code_objects/proxy.rb', line 120

def <=>(other)
  if other.respond_to? :path
    path <=> other.path
  else
    false
  end
end

- (Boolean) ===(other)



111
112
113
114
115
116
117
# File 'lib/yard/code_objects/proxy.rb', line 111

def ===(other)
  if obj = to_obj
    obj === other
  else
    self.class <= other.class
  end
end

- (Class) class

Returns the class name of the object the proxy is mimicking, if resolved. Otherwise returns Proxy.



144
145
146
147
148
149
150
# File 'lib/yard/code_objects/proxy.rb', line 144

def class
  if obj = to_obj
    obj.class
  else
    Proxy
  end
end

- (Boolean) equal?(other) Also known as: ==



129
130
131
132
133
134
135
# File 'lib/yard/code_objects/proxy.rb', line 129

def equal?(other)
  if other.respond_to? :path
    path == other.path
  else
    false
  end
end

- (Integer) hash



139
# File 'lib/yard/code_objects/proxy.rb', line 139

def hash; path.hash end

- (String) inspect

Returns a text representation of the Proxy



77
78
79
80
81
82
83
# File 'lib/yard/code_objects/proxy.rb', line 77

def inspect
  if obj = to_obj
    obj.inspect
  else
    "P(#{path})"
  end
end

- (Boolean) instance_of?(klass)



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

def instance_of?(klass)
  self.class == klass
end

- (Boolean) is_a?(klass)



102
103
104
105
106
107
108
# File 'lib/yard/code_objects/proxy.rb', line 102

def is_a?(klass)
  if obj = to_obj
    obj.is_a?(klass)
  else
    self.class <= klass
  end
end

- (Boolean) kind_of?(klass)



176
177
178
# File 'lib/yard/code_objects/proxy.rb', line 176

def kind_of?(klass)
  self.class <= klass
end

- (Symbol, String) name(prefix = false)

The name of the object



71
72
73
# File 'lib/yard/code_objects/proxy.rb', line 71

def name(prefix = false)
  prefix ? (@imethod ? ISEP : '') + @name.to_s : @name
end

- (String) path Also known as: to_s, to_str, title

If the proxy resolves to an object, returns its path, otherwise guesses at the correct path using the original namespace and name.



90
91
92
93
94
95
96
# File 'lib/yard/code_objects/proxy.rb', line 90

def path
  if obj = to_obj
    obj.path
  else
    proxy_path
  end
end

- (Boolean) respond_to?(meth, include_private = false)



181
182
183
184
185
186
187
# File 'lib/yard/code_objects/proxy.rb', line 181

def respond_to?(meth, include_private = false)
  if obj = to_obj
    obj.respond_to?(meth, include_private)
  else
    super
  end
end

- (Boolean) root?

This class is never a root object



214
# File 'lib/yard/code_objects/proxy.rb', line 214

def root?; false end

- (Symbol) type

Returns the type of the proxy. If it cannot be resolved at the time of the call, it will either return the inferred proxy type (see #type=) or :proxy

See Also:



157
158
159
160
161
162
163
# File 'lib/yard/code_objects/proxy.rb', line 157

def type
  if obj = to_obj
    obj.type
  else
    @type || :proxy
  end
end

- (void) type=(type)

This method returns an undefined value.

Allows a parser to infer the type of the proxy by its path.



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

def type=(type) @type = type ? type.to_sym : nil end