yard 0.6.8 → 0.7.0

data/lib/yard/code_objects/class_object.rb

@@ -5,9 +5,9 @@ module YARD::CodeObjects
     # The {ClassObject} that this class object inherits from in Ruby source.
     # @return [ClassObject] a class object that is the superclass of this one
     attr_reader :superclass
-    
+
     # Creates a new class object in +namespace+ with +name+
-    # 
+    #
     # @see Base.new
     def initialize(namespace, name, *args, &block)
       super
@@ -25,16 +25,16 @@ module YARD::CodeObjects
         end
       end
     end
-    
+
     # Whether or not the class is a Ruby Exception
-    # 
+    #
     # @return [Boolean] whether the object represents a Ruby exception
     def is_exception?
       inheritance_tree.reverse.any? {|o| BUILTIN_EXCEPTIONS_HASH.has_key? o.path }
     end
-    
+
     # Returns the inheritance tree of the object including self.
-    # 
+    #
     # @param [Boolean] include_mods whether or not to include mixins in the
     #   inheritance tree.
     # @return [Array<NamespaceObject>] the list of code objects that make up
@@ -50,10 +50,10 @@ module YARD::CodeObjects
         m.inheritance_tree(include_mods)
       end.flatten.uniq
     end
-    
+
     # Returns the list of methods matching the options hash. Returns
     # all methods if hash is empty.
-    # 
+    #
     # @param [Hash] opts the options hash to match
     # @option opts [Boolean] :inherited (true) whether inherited methods should be
     #   included in the list
@@ -62,16 +62,16 @@ module YARD::CodeObjects
     # @return [Array<MethodObject>] the list of methods that matched
     def meths(opts = {})
       opts = SymbolHash[:inherited => true].update(opts)
-      list = super(opts) 
+      list = super(opts)
       list += inherited_meths(opts).reject do |o|
         next(false) if opts[:all]
         list.find {|o2| o2.name == o.name && o2.scope == o.scope }
       end if opts[:inherited]
       list
     end
-    
+
     # Returns only the methods that were inherited.
-    # 
+    #
     # @return [Array<MethodObject>] the list of inherited method objects
     def inherited_meths(opts = {})
       inheritance_tree[1..-1].inject([]) do |list, superclass|
@@ -86,9 +86,9 @@ module YARD::CodeObjects
         end
       end
     end
-    
+
     # Returns the list of constants matching the options hash.
-    # 
+    #
     # @param [Hash] opts the options hash to match
     # @option opts [Boolean] :inherited (true) whether inherited constant should be
     #   included in the list
@@ -99,9 +99,9 @@ module YARD::CodeObjects
       opts = SymbolHash[:inherited => true].update(opts)
       super(opts) + (opts[:inherited] ? inherited_constants : [])
     end
-    
+
     # Returns only the constants that were inherited.
-    # 
+    #
     # @return [Array<ConstantObject>] the list of inherited constant objects
     def inherited_constants
       inheritance_tree[1..-1].inject([]) do |list, superclass|
@@ -114,11 +114,11 @@ module YARD::CodeObjects
         end
       end
     end
-    
+
     # Sets the superclass of the object
-    # 
+    #
     # @param [Base, Proxy, String, Symbol, nil] object the superclass value
-    # @return [void] 
+    # @return [void]
     def superclass=(object)
       case object
       when Base, Proxy, NilClass
@@ -126,13 +126,13 @@ module YARD::CodeObjects
       when String, Symbol
         @superclass = Proxy.new(namespace, object)
       else
-        raise ArgumentError, "superclass must be CodeObject, Proxy, String or Symbol" 
+        raise ArgumentError, "superclass must be CodeObject, Proxy, String or Symbol"
       end
 
       if name == @superclass.name && namespace != YARD::Registry.root && !object.is_a?(Base)
         @superclass = Proxy.new(namespace.namespace, object)
       end
-      
+
       if @superclass == self
         msg = "superclass #{@superclass.inspect} cannot be the same as the declared class #{self.inspect}"
         @superclass = P("::Object")

data/lib/yard/code_objects/constant_object.rb

@@ -5,7 +5,7 @@ module YARD::CodeObjects
     # The source code representing the constant's value
     # @return [String] the value the constant is set to
     attr_reader :value
-    
+
     def value=(value)
       @value = format_source(value)
     end

data/lib/yard/code_objects/extended_method_object.rb

@@ -1,20 +1,20 @@
 module YARD::CodeObjects
   # Represents an instance method of a module that was mixed into the class
   # scope of another namespace.
-  # 
+  #
   # @see MethodObject
   class ExtendedMethodObject
     instance_methods.each {|m| undef_method(m) unless m =~ /^__/ || m.to_sym == :object_id }
-    
+
     # @return [Symbol] always +:class+
     def scope; :class end
-    
+
     # Sets up a delegate for {MethodObject} obj.
-    # 
+    #
     # @param [MethodObject] obj the instance method to treat as a mixed in
     #   class method on another namespace.
     def initialize(obj) @del = obj end
-      
+
     # Sends all methods to the {MethodObject} assigned in {#initialize}
     # @see #initialize
     # @see MethodObject

data/lib/yard/code_objects/extra_file_object.rb

@@ -0,0 +1,89 @@
+module YARD::CodeObjects
+  # An ExtraFileObject represents an extra documentation file (README or other
+  # file). It is not strictly a CodeObject (does not inherit from `Base`) although
+  # it implements `path`, `name` and `type`, and therefore should be structurally
+  # compatible with most CodeObject interfaces.
+  class ExtraFileObject
+    attr_accessor :filename
+    attr_accessor :attributes
+    attr_accessor :name
+    attr_accessor :contents
+
+    # Creates a new extra file object.
+    # @param [String] filename the location on disk of the file
+    # @param [String] contents the file contents. If not set, the contents
+    #   will be read from disk using the +filename+.
+    def initialize(filename, contents = nil)
+      self.filename = filename
+      self.name = File.basename(filename).gsub(/\.[^.]+$/, '')
+      self.attributes = SymbolHash.new(false)
+      parse_contents(contents || File.read(@filename))
+    end
+
+    alias path name
+
+    def title
+      attributes[:title] || name
+    end
+
+    def inspect
+      "#<yardoc #{type} #{filename} attrs=#{attributes.inspect}>"
+    end
+    alias to_s inspect
+
+    def type; 'extra_file' end
+
+    def ==(other)
+      return false unless self.class === other
+      other.filename == filename
+    end
+    alias eql? ==
+    alias equal? ==
+    def hash; filename.hash end
+
+    private
+
+    # @param [String] data the file contents
+    def parse_contents(data)
+      retried = false
+      cut_index = 0
+      data = data.split("\n")
+      data.each_with_index do |line, index|
+        case line
+        when /^#!(\S+)\s*$/
+          if index == 0
+            attributes[:markup] = $1
+          else
+            cut_index = index
+            break
+          end
+        when /^\s*#\s*@(\S+)\s*(.+?)\s*$/
+          attributes[$1] = $2
+        else
+          cut_index = index
+          break
+        end
+      end
+      data = data[cut_index..-1] if cut_index > 0
+      self.contents = data.join("\n")
+      
+      if contents.respond_to?(:force_encoding) && attributes[:encoding]
+        begin
+          contents.force_encoding(attributes[:encoding])
+        rescue ArgumentError
+          log.warn "Invalid encoding `#{attributes[:encoding]}' in #{filename}"
+        end
+      end
+    rescue ArgumentError => e
+      if retried && e.message =~ /invalid byte sequence/
+        # This should never happen.
+        log.warn "Could not read #{filename}, #{e.message}. You probably want to set `--charset`."
+        self.contents = ''
+        return
+      end
+      data.force_encoding('binary') if data.respond_to?(:force_encoding)
+      retried = true
+      retry
+    end
+  end
+end

data/lib/yard/code_objects/macro_object.rb

@@ -0,0 +1,215 @@
+module YARD
+  module CodeObjects
+    # A MacroObject represents a docstring defined through +@macro NAME+ and can be
+    # reused by specifying the tag +@macro NAME+. You can also provide the
+    # +attached+ type flag to the macro definition to have it attached to the
+    # specific DSL method so it will be implicitly reused.
+    # 
+    # Macros are fully described in the {file:docs/Tags.md#macros Tags Overview}
+    # document.
+    # 
+    # @example Creating a basic named macro
+    #   # @macro prop
+    #   # @method $1(${3-})
+    #   # @return [$2] the value of the $0
+    #   property :foo, String, :a, :b
+    #   
+    #   # @macro prop
+    #   property :bar, Numeric, :value
+    # 
+    # @example Creating a macro that is attached to the method call
+    #   # @macro [attach] prop2
+    #   # @method $1(value)
+    #   property :foo
+    #   
+    #   # Extra data added to docstring
+    #   property :bar
+    class MacroObject < Base
+      MACRO_MATCH = /(\\)?\$(?:\{(-?\d+|\*)(-)?(-?\d+)?\}|(-?\d+|\*))/
+
+      class << self
+        # Creates a new macro and fills in the relevant properties.
+        # @param [String] macro_name the name of the macro, must be unique.
+        # @param [String] data the data the macro should expand when re-used
+        # @param [CodeObjects::Base] method_object an object to attach this
+        #   macro to. If supplied, {#attached?} will be true
+        # @return [MacroObject] the newly created object
+        def create(macro_name, data, method_object = nil)
+          obj = new(:root, macro_name)
+          obj.macro_data = data
+          obj.method_object = method_object
+          obj
+        end
+    
+        # Finds a macro using +macro_name+
+        # @return [MacroObject] if a macro is found
+        # @return [nil] if there is no registered macro by that name
+        def find(macro_name)
+          Registry.at('.macro.' + macro_name.to_s)
+        end
+      
+        # Parses a given docstring and determines if the macro is "new" or
+        # not. If the macro has $variable names or if it has a @macro tag
+        # with the [new] or [attached] flag, it is considered new. 
+        # 
+        # If a new macro is found, the macro is created and registered. Otherwise
+        # the macro name is searched and returned. If a macro is not found,
+        # nil is returned.
+        # 
+        # @param [CodeObjects::Base] method_object an optional method to attach
+        #   the macro to. Only used if the macro is being created, otherwise
+        #   this argument is ignored.
+        # @return [MacroObject] the newly created or existing macro, depending
+        #   on whether the @macro tag was a new tag or not.
+        # @return [nil] if the +data+ has no macro tag or if the macro is
+        #   not new and no macro by the macro name is found.
+        def find_or_create(data, method_object = nil)
+          docstring = Docstring === data ? data : Docstring.new(data)
+          return unless docstring.tag(:macro)
+          return unless name = macro_name(docstring)
+          if new_macro?(docstring)
+            method_object = nil unless attached_macro?(docstring, method_object)
+            create(name, macro_data(docstring), method_object)
+          else
+            find(name)
+          end
+        end
+        alias create_docstring find_or_create
+        
+        # Expands +macro_data+ using the interpolation parameters.
+        # 
+        # Interpolation rules:
+        # * $0, $1, $2, ... = the Nth parameter in +call_params+
+        # * $& = the full statement source (excluding block)
+        # * Also supports $\{N-M} ranges, as well as negative indexes on N or M
+        # * Use \$ to escape the variable name in a macro.
+        # 
+        # @macro [new] macro.expand
+        #   @param [Array<String>] call_params the method name and parameters
+        #     to the method call. These arguments will fill \$0-N
+        #   @param [String] full_source the full source line (excluding block) 
+        #     interpolated as \$&
+        #   @param [String] block_source Currently unused. Will support 
+        #     interpolating the block data as a variable.
+        #   @return [String] the expanded macro data
+        # @param [String] macro_data the macro data to expand (taken from {#macro_data})
+        def expand(macro_data, call_params = [], full_source = '', block_source = '')
+          macro_data = macro_data.all if macro_data.is_a?(Docstring)
+          macro_data.gsub(MACRO_MATCH) do
+            escape, first, last, rng = $1, $2 || $5, $4, $3 ? true : false
+            next $&[1..-1] if escape
+            if first == '*'
+              last ? $& : full_source
+            else
+              first_i = first.to_i
+              last_i = (last ? last.to_i : call_params.size)
+              last_i = first_i unless rng
+              params = call_params[first_i..last_i]
+              params ? params.join(", ") : ''
+            end
+          end
+        end
+
+        # Applies a macro on a docstring by creating any macro data inside of
+        # the docstring first. Equivalent to calling {find_or_create} and {apply_macro}
+        # on the new macro object.
+        # 
+        # @param [Docstring] docstring the docstring to create a macro out of
+        # @macro macro.expand
+        # @see find_or_create
+        def apply(docstring, call_params = [], full_source = '', block_source = '', method_object = nil)
+          macro = find_or_create(docstring, method_object)
+          apply_macro(macro, docstring, call_params, full_source, block_source)
+        end
+
+        # Applies a macro to a docstring, interpolating the macro's data on the
+        # docstring and appending any extra local docstring data that was in
+        # the original +docstring+ object.
+        # 
+        # @param [MacroObject] macro the macro object
+        # @macro macro.expand
+        def apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '')
+          docstring = Docstring.new(docstring) unless Docstring === docstring
+          data = []
+          data << macro.expand(call_params, full_source, block_source) if macro
+          if !macro && new_macro?(docstring)
+            data << expand(macro_data(docstring), call_params, full_source, block_source)
+          end
+          data << nonmacro_data(docstring)
+          data.join("\n").strip
+        end
+
+        private
+      
+        def new_macro?(docstring)
+          if docstring.tag(:macro) 
+            if types = docstring.tag(:macro).types
+              return true if types.include?('new') || types.include?('attach')
+            end
+            if docstring.all =~ MACRO_MATCH
+              return true
+            end
+          end
+          false
+        end
+        
+        def attached_macro?(docstring, method_object)
+          return false if method_object.nil?
+          return false if docstring.tag(:macro).types.nil?
+          docstring.tag(:macro).types.include?('attach')
+        end
+        
+        def macro_name(docstring)
+          docstring.tag(:macro).name
+        end
+        
+        def macro_data(docstring)
+          new_docstring = docstring.dup
+          new_docstring.delete_tags(:macro)
+          tag_text = docstring.tag(:macro).text
+          if !tag_text || tag_text.strip.empty?
+            new_docstring.to_raw.strip
+          else
+            tag_text
+          end
+        end
+        
+        def nonmacro_data(docstring)
+          if new_macro?(docstring)
+            text = docstring.tag(:macro).text
+            return '' if !text || text.strip.empty?
+          end
+          new_docstring = docstring.dup
+          new_docstring.delete_tags(:macro)
+          new_docstring.to_raw
+        end
+      end
+    
+      # @return [String] the macro data stored on the object
+      attr_accessor :macro_data
+      
+      # @return [CodeObjects::Base] the method object that this macro is
+      #   attached to.
+      attr_accessor :method_object
+    
+      # @return [Boolean] whether this macro is attached to a method
+      def attached?; method_object ? true : false end
+      def path; '.macro.' + name.to_s end
+      def sep; '.' end
+      
+      # Expands the macro using 
+      # @param [Array<String>] call_params a list of tokens that are passed
+      #   to the method call
+      # @param [String] full_source the full method call (not including the block)
+      # @param [String] block_source the source passed in the block of the method
+      #   call, if there is a block.
+      # @example Expanding a Macro
+      #   macro.expand(%w(property foo bar), 'property :foo, :bar', '') #=>
+      #     "...macro data interpolating this line of code..."
+      # @see expand
+      def expand(call_params = [], full_source = '', block_source = '')
+        self.class.expand(macro_data, call_params, full_source, block_source)
+      end
+    end
+  end
+end