yard 0.4.0 → 0.5.0

data/lib/yard/cli/yri.rb

@@ -0,0 +1,128 @@
+module YARD
+  module CLI
+    # A tool to view documentation in the console like `ri`
+    class YRI < Base
+      CACHE_FILE = File.expand_path('~/.yard/yri_cache')
+      
+      # Helper method to run the utility on an instance.
+      # @see #run
+      def self.run(*args) new.run(*args) end
+        
+      def initialize
+        @cache = {}
+        @search_paths = [Registry.yardoc_file, YARD::ROOT + '/../.yardoc']
+        add_gem_paths
+        load_cache
+        @search_paths.uniq!
+      end
+        
+      # Runs the command-line utility.
+      # 
+      # @example
+      #   YRI.new.run('String#reverse')
+      # @param [Array<String>] args each tokenized argument
+      def run(*args)
+        optparse(*args)
+        
+        @serializer ||= YARD::Serializers::ProcessSerializer.new('less')
+        
+        if object = find_object(@name)
+          print_object(object)
+        else
+          STDERR.puts "No documentation for `#{@name}'"
+          exit(1)
+        end
+      end
+      
+      protected
+      
+      def cache_object(name, path)
+        return if path == Registry.yardoc_file
+        @cache[name] = path
+        
+        File.open(CACHE_FILE, 'w') do |file|
+          @cache.each do |key, value|
+            file.puts("#{key} #{value}")
+          end
+        end
+      end
+      
+      def print_object(object)
+        if object.type == :method && object.is_alias?
+          tmp = P(object.namespace, (object.scope == :instance ? "#" : "") + 
+            object.namespace.aliases[object].to_s) 
+          object = tmp unless YARD::CodeObjects::Proxy === tmp
+        end
+        object.format(:serializer => @serializer)
+      end
+      
+      def find_object(name)
+        @search_paths.unshift(@cache[name]) if @cache[name]
+        
+        log.debug "Searching for #{name} in search paths"
+        @search_paths.each do |path|
+          log.debug "Searching for #{name} in #{path}..."
+          Registry.load(path)
+          obj = Registry.at(name)
+          if obj
+            cache_object(name, path)
+            return obj
+          end
+        end
+        nil
+      end
+      
+      private
+      
+      def load_cache
+        return unless File.file?(CACHE_FILE)
+        File.readlines(CACHE_FILE).each do |line|
+          line = line.strip.split(/\s+/)
+          @cache[line[0]] = line[1]
+        end
+      end
+      
+      def add_gem_paths
+        require 'rubygems'
+        Gem.source_index.find_name('').each do |spec|
+          if yfile = Registry.yardoc_file_for_gem(spec.name)
+            @search_paths << yfile
+          end
+        end
+      rescue LoadError
+      end
+      
+      # Parses commandline options.
+      # @param [Array<String>] args each tokenized argument
+      def optparse(*args)
+        opts = OptionParser.new
+
+        opts.separator ""
+        opts.separator "General Options:"
+
+        opts.on('-b', '--db FILE', 'Use a specified .yardoc db to search in') do |yfile|
+          @search_paths.unshift(yfile)
+        end
+
+        opts.on('-T', '--no-pager', 'No pager') do
+          @serializer = YARD::Serializers::StdoutSerializer.new
+        end
+        
+        opts.on('-p PAGER', '--pager') do |pager|
+          @serializer = YARD::Serializers::ProcessSerializer.new(pager)
+        end
+        
+        common_options(opts)
+
+        begin
+          opts.parse!(args)
+          @name = args.first
+        rescue => e
+          STDERR.puts e.message
+          STDERR << "\n" << opts
+          exit
+        end
+      end
+    end
+  end
+end

data/lib/yard/code_objects/base.rb

@@ -36,7 +36,7 @@ module YARD
     CSEPQ = Regexp.quote CSEP
     CONSTANTMATCH = /[A-Z]\w*/
     NAMESPACEMATCH = /(?:(?:#{NSEPQ})?#{CONSTANTMATCH})+/
-    METHODNAMEMATCH = /[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
+    METHODNAMEMATCH = /[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|<=>|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
     METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|self)\s*(?:#{CSEPQ}|#{NSEPQ})\s*)?#{METHODNAMEMATCH}/
     
     BUILTIN_EXCEPTIONS = ["SecurityError", "Exception", "NoMethodError", "FloatDomainError", 
@@ -99,6 +99,12 @@ module YARD
       # @return [String, nil] source, if present, or nil
       attr_accessor :source
       
+      # Language of the source code associated with the object. Defaults to
+      # +:ruby+.
+      # 
+      # @return [Symbol] the language type
+      attr_accessor :source_type
+      
       # 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.
@@ -157,7 +163,7 @@ module YARD
         # @param [Object] other the other object to compare classes with
         # @return [Boolean] true if other is a subclass of self
         def ===(other)
-          self >= other.class ? true : false
+          other.is_a?(self)
         end
       end
           
@@ -184,6 +190,7 @@ module YARD
         @files = []
         @current_file_has_comments = false
         @name = name.to_sym
+        @source_type = :ruby
         @tags = []
         @docstring = Docstring.new('', self)
         self.namespace = namespace
@@ -262,7 +269,7 @@ module YARD
       # 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 [nil] 
+      # @return [void] 
       # @see #[]
       def []=(key, value)
         if respond_to?("#{key}=")
@@ -331,7 +338,7 @@ module YARD
       # @return [String] the unique path of the object
       # @see #sep
       def path
-        if parent && parent != Registry.root
+        if parent && !parent.root?
           [parent.path, name.to_s].join(sep)
         else
           name.to_s
@@ -396,6 +403,9 @@ module YARD
       # Tests if the {#docstring} has a tag
       # @see Docstring#has_tag?
       def has_tag?(name); @docstring.has_tag?(name) end
+      
+      # @return whether or not this object is a RootObject
+      def root?; false end
 
       protected
     
@@ -414,7 +424,8 @@ module YARD
       # @return [String] formatted source
       def format_source(source)
         source.chomp!
-        indent = source.split(/\r?\n/).last[/^([ \t]*)/, 1].length
+        last = source.split(/\r?\n/).last
+        indent = last ? last[/^([ \t]*)/, 1].length : 0
         source.gsub(/^[ \t]{#{indent}}/, '')
       end
     end

data/lib/yard/code_objects/class_object.rb

@@ -13,7 +13,14 @@ module YARD::CodeObjects
       if is_exception?
         self.superclass ||= :Exception unless P(namespace, name) == P(:Exception)
       else
-        self.superclass ||= :Object unless P(namespace, name) == P(:Object)
+        case P(namespace, name).path
+        when "BasicObject"
+          nil
+        when "Object"
+          self.superclass ||= :BasicObject
+        else
+          self.superclass ||= :Object
+        end
       end
     end
     
@@ -33,7 +40,7 @@ module YARD::CodeObjects
     def inheritance_tree(include_mods = false)
       list = (include_mods ? mixins(:instance) : [])
       if superclass.is_a?(Proxy) || superclass.respond_to?(:inheritance_tree)
-        list += [superclass] unless superclass == P(:Object)
+        list += [superclass] unless superclass == P(:Object) || superclass == P(:BasicObject)
       end
       [self] + list.map do |m|
         next m unless m.respond_to?(:inheritance_tree)
@@ -102,7 +109,7 @@ module YARD::CodeObjects
     # Sets the superclass of the object
     # 
     # @param [Base, Proxy, String, Symbol, nil] object the superclass value
-    # @return [nil] 
+    # @return [void] 
     def superclass=(object)
       case object
       when Base, Proxy, NilClass
@@ -113,7 +120,7 @@ module YARD::CodeObjects
         raise ArgumentError, "superclass must be CodeObject, Proxy, String or Symbol" 
       end
 
-      if name == @superclass.name && namespace != YARD::Registry.root
+      if name == @superclass.name && namespace != YARD::Registry.root && object.is_a?(String)
         @superclass = Proxy.new(namespace.namespace, object)
       end
       

data/lib/yard/code_objects/method_object.rb

@@ -52,15 +52,24 @@ module YARD::CodeObjects
     # @param [Symbol] v the new visibility (:public, :private, or :protected)
     def visibility=(v) @visibility = v.to_sym end
       
+    # @return whether or not the method is the #initialize constructor method
+    def constructor?
+      name == :initialize && scope == :instance && namespace.is_a?(ClassObject)
+    end
+      
     # Tests if the object is defined as an attribute in the namespace
     # @return [Boolean] whether the object is an attribute
     def is_attribute?
-      namespace.attributes[scope].has_key? name.to_s.gsub(/=$/, '')
+      return false unless namespace.is_a?(NamespaceObject)
+      attr_obj = namespace.attributes[scope][name.to_s.gsub(/=$/, '')]
+      return false unless attr_obj
+      attr_obj[name.to_s =~ /=$/ ? :write : :read] ? true : false
     end
       
     # Tests if the object is defined as an alias of another method
     # @return [Boolean] whether the object is an alias
     def is_alias?
+      return false unless namespace.is_a?(NamespaceObject)
       namespace.aliases.has_key? self
     end
     
@@ -75,6 +84,7 @@ module YARD::CodeObjects
     # @return [Array<Symbol>] the alias names
     def aliases
       list = []
+      return list unless namespace.is_a?(NamespaceObject)
       namespace.aliases.each do |o, aname| 
         list << o if aname == name && o.scope == scope 
       end

data/lib/yard/code_objects/proxy.rb

@@ -75,7 +75,7 @@ module YARD
         if obj = to_obj
           obj.path
         else
-          if @namespace == Registry.root
+          if @namespace.root?
             (@imethod ? ISEP : "") + name.to_s
           elsif @origname
             if @origname =~ /^[A-Z]/
@@ -154,7 +154,7 @@ module YARD
       
       # Allows a parser to infer the type of the proxy by its path.
       # @param [#to_sym] type the proxy's inferred type
-      # @return [nil] 
+      # @return [void] 
       def type=(type) Registry.proxy_types[path] = type.to_sym end
       
       # @return [Boolean] 
@@ -199,6 +199,9 @@ module YARD
           end
         end
       end
+      
+      # This class is never a root object
+      def root?; false end
     
       private
     

data/lib/yard/code_objects/root_object.rb

@@ -5,6 +5,7 @@ module YARD
     class RootObject < ModuleObject
       def path; "" end
       def inspect; "#<yardoc root>" end
+      def root?; true end
     end
   end
 end

data/lib/yard/core_ext/file.rb

@@ -19,7 +19,7 @@ class File
       from.shift; to.shift
     end
     fname = from.pop
-    join *(from.map { RELATIVE_PARENTDIR } + to)
+    join(*(from.map { RELATIVE_PARENTDIR } + to))
   end
   
   # Cleans a path by removing extraneous '..', '.' and '/' characters

data/lib/yard/core_ext/hash.rb

@@ -0,0 +1,15 @@
+class Hash
+  class << self
+    def create(*args)
+      if args.is_a?(Array)
+        obj = new
+        args.first.each {|k, v| obj[k] = v }
+        obj
+      else
+        create_186(*args)
+      end
+    end
+    alias create_186 []
+    alias [] create
+  end
+end if RUBY_VERSION < "1.8.7"

data/lib/yard/core_ext/module.rb

@@ -11,9 +11,9 @@ class Module
   # Returns the module namespace path minus the class/module name
   # 
   # @example
-  #   module A::B::C; namespace end # => "A::B"
+  #   module A::B::C; namespace_name end # => "A::B"
   # @return [String] the namespace minus the class/module name
-  def namespace
+  def namespace_name
     name.split("::")[0..-2].join("::")
   end
 end

data/lib/yard/core_ext/string.rb

@@ -17,4 +17,70 @@ class String
   def camelcase
     gsub(/([a-z])_([a-z])/i) { $1 + $2.upcase }.sub(/^(.)/) { $1.upcase }.gsub('/', '::') 
   end
+  
+  # Splits text into tokens the way a shell would, handling quoted
+  # text as a single token. Use '\"' and "\'" to escape quotes and
+  # '\\' to escape a backslash.
+  # 
+  # @return [Array] an array representing the tokens
+  def shell_split
+    out = [""]
+    state = :none
+    escape_next = false
+    quote = ""
+    strip.split(//).each do |char|
+      case state
+      when :none, :space
+        case char
+        when /\s/
+          out << "" unless state == :space
+          state = :space
+          escape_next = false
+        when "\\"
+          if escape_next
+            out.last << char
+            escape_next = false
+          else
+            escape_next = true
+          end
+        when '"', "'"
+          if escape_next
+            out.last << char
+            escape_next = false
+          else
+            state = char
+            quote = ""
+          end
+        else
+          state = :none
+          out.last << char
+          escape_next = false
+        end
+      when '"', "'"
+        case char
+        when '"', "'"
+          if escape_next
+            quote << char
+            escape_next = false
+          elsif char == state
+            out.last << quote
+            state = :none 
+          else
+            quote << char
+          end
+        when '\\'
+          if escape_next
+            quote << char
+            escape_next = false
+          else
+            escape_next = true
+          end
+        else
+          quote << char
+          escape_next = false
+        end
+      end
+    end
+    out
+  end
 end

data/lib/yard/core_ext/symbol_hash.rb

@@ -49,7 +49,7 @@ class SymbolHash < Hash
     
   # Deleted a key and value associated with it
   # @param [#to_sym] key the key to delete
-  # @return [nil]
+  # @return [void]
   def delete(key) super(key.to_sym) end
     
   # Tests if a symbolized key exists

data/lib/yard/docstring.rb

@@ -39,7 +39,6 @@ module YARD
     # @param [CodeObjects::Base] object an object to associate the docstring
     #   with.
     def initialize(content = '', object = nil)
-      @tag_factory = Tags::Library.new
       @object = object
       
       self.all = content
@@ -165,12 +164,13 @@ module YARD
         return create_ref_tag(tag_name, $1, $2)
       end
         
+      tag_factory = Tags::Library.instance
       tag_method = "#{tag_name}_tag"
-      if tag_name && @tag_factory.respond_to?(tag_method)
-        if @tag_factory.method(tag_method).arity == 2
-          add_tag *@tag_factory.send(tag_method, tag_buf, raw_buf.join("\n"))
+      if tag_name && tag_factory.respond_to?(tag_method)
+        if tag_factory.method(tag_method).arity == 2
+          add_tag *tag_factory.send(tag_method, tag_buf, raw_buf.join("\n"))
         else
-          add_tag *@tag_factory.send(tag_method, tag_buf) 
+          add_tag *tag_factory.send(tag_method, tag_buf) 
         end
       else
         log.warn "Unknown tag @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")