123456789_123456789_123456789_123456789_123456789_

Class: YARD::CodeObjects::Proxy

Relationships & Source Files
Inherits: Object
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:

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(namespace, name, type = nil) ⇒ Proxy

Creates a new Proxy

Raises:

[ GitHub ] 

  


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



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 =~ PROXY_MATCH
    @orignamespace = namespace
    @origname = name
    @imethod = true if name.include? ISEP
    namespace = Proxy.new(namespace, $`) unless $`.empty?
    name = $1
  else
    @orignamespace = nil
    @origname = nil
    @imethod = nil
  end

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

  if @namespace.is_a?(ConstantObject)
    unless @namespace.value =~ /\A#{NAMESPACEMATCH}\Z/
      raise Parser::UndocumentableError, "constant mapping for " +
        "#{@origname} (type=#{type.inspect})"
    end

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

  unless @namespace.is_a?(NamespaceObject) || @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




  

    #method_missing(meth, *args, &block)  
  



  

    
Dispatches the method to the resolved object.


  





  
Raises:





  [ GitHub ]


  

  


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



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


  







Class Method Details



  

    .===(other)  
  

  [ GitHub ]


  

  


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



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


  







Instance Attribute Details



  

    #namespace   (readonly)
    Also known as: #parent
  

  [ GitHub ]


  

  


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



attr_reader :namespace


  








  

    #parent   (readonly)
  



  

    
Alias for #namespace.


  



  [ GitHub ]


  

  


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



alias parent namespace


  








  

    #root?  ⇒ Boolean  (readonly)
  



  

    
This class is never a root object


  





  


  [ GitHub ]


  

  


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



def root?; false end


  








  

    #type  ⇒ Symbol  (rw)
  



  

    
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


  





  
Returns:


    
  
  • 
    (Symbol)
—    
    the Proxy's type
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


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



def type
  to_obj ? to_obj.type : @type || :proxy
end


  








  

    #type=(type)  ⇒ void  (rw)
  



  

    
This method returns an undefined value.
Allows a parser to infer the type of the proxy by its path.


  





  
Parameters:


    
  
  • 
    type
    (#to_sym)
—    
    the proxy's inferred type
    

    
  
    • 





  [ GitHub ]


  

  


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



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


  







Instance Method Details



  

    #<=>(other)  ⇒ Boolean 
  



  

    
  





  


  [ GitHub ]


  

  


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



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


  








  

    #==(other)  
  



  

    
Alias for #equal?.


  



  [ GitHub ]


  

  


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



alias == equal?


  








  

    #===(other)  ⇒ Boolean 
  



  

    
  





  


  [ GitHub ]


  

  


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



def ===(other)
  to_obj ? to_obj === other : self.class <= other.class
end


  








  

    #class  ⇒ Class 
  



  

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


  





  
Returns:


    
  
  • 
    (Class)
—    
    the resolved object's class or Proxy
    

    
  
    • 





  [ GitHub ]


  

  


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



def class
  to_obj ? to_obj.class : Proxy
end


  








  

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



  

    
  





  


  [ GitHub ]


  

  


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



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


  








  

    #hash  ⇒ Integer 
  



  

    
  





  
Returns:


    
  
  • 
    (Integer)
—    
    the object's hash value (for equality checking)
    

    
  
    • 





  [ GitHub ]


  

  


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



def hash; path.hash end


  








  

    #inspect  ⇒ String 
  



  

    
Returns a text representation of the Proxy


  





  
Returns:


    
  
  • 
    (String)
—    
    the object's #inspect method or P(OBJECTPATH)
    

    
  
    • 





  [ GitHub ]


  

  


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



def inspect
  to_obj ? to_obj.inspect : "P(#{path})"
end


  








  

    #instance_of?(klass)  ⇒ Boolean 
  



  

    
  





  


  [ GitHub ]


  

  


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



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


  








  

    #is_a?(klass)  ⇒ Boolean 
  



  

    
  





  


  [ GitHub ]


  

  


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



def is_a?(klass)
  to_obj ? to_obj.is_a?(klass) : self.class <= klass
end


  








  

    #kind_of?(klass)  ⇒ Boolean 
  



  

    
  





  


  [ GitHub ]


  

  


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



def kind_of?(klass)
  self.class <= klass
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.
    

    
  
    • 





  [ GitHub ]


  

  


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



def name(prefix = false)
  prefix ? "#{@imethod && ISEP}#{@name}" : @name
end


  








  

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


  





  
Returns:


    
  
  • 
    (String)
—    
    the assumed path of the proxy (or the real path
of the resolved object)
    

    
  
    • 





  [ GitHub ]


  

  


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



def path
  to_obj ? to_obj.path : proxy_path
end


  








  

    #proxy_path   (private)
  

  [ GitHub ]


  

  


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



def proxy_path
  if @namespace.root?
    (@imethod ? ISEP : "") + name.to_s
  elsif @origname
    if @origname =~ CONSTANTSTART
      @origname
    else
      [namespace.path, @origname].join
    end
  elsif name.to_s =~ CONSTANTSTART
    name.to_s
  else # class meth?
    [namespace.path, name.to_s].join(CSEP)
  end
end


  








  

    #respond_to?(meth, include_private = false)  ⇒ Boolean 
  



  

    
  





  


  [ GitHub ]


  

  


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



def respond_to?(meth, include_private = false)
  to_obj ? to_obj.respond_to?(meth, include_private) : super
end


  








  

    #title  
  



  

    
Alias for #path.


  



  [ GitHub ]


  

  


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



alias title path


  








  

    #to_ary   (private)
  



  

    
  

    Note:
    
this method fixes a bug in 1.9.2: http://gist.github.com/437136



  



  



  [ GitHub ]


  

  


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



def to_ary; nil end


  








  

    #to_obj  ⇒ Base?  (private)
  



  

    
Attempts to find the object that this unresolved object
references by checking if any objects by this name are
registered all the way up the namespace tree.


  





  
Returns:


    
  
  • 
    (Base, nil)
—    
    the registered code object or nil
    

    
  
    • 





  [ GitHub ]


  

  


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



def to_obj
  return @obj if @obj
  @obj = Registry.resolve(@namespace, (@imethod ? ISEP : '') + @name.to_s, false, false, @type)
  if @obj
    if @origname && @origname.include?("::") && !@obj.path.include?(@origname)
      # the object's path should include the original proxy namespace,
      # otherwise it's (probably) not the right object.
      @obj = nil
    else
      @namespace = @obj.namespace
      @name = @obj.name
    end
  end
  @obj
end


  








  

    #to_s  
  



  

    
Alias for #path.


  



  [ GitHub ]


  

  


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



alias to_s path


  








  

    #to_str  
  



  

    
Alias for #path.


  



  [ GitHub ]


  

  


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



alias to_str path