yard 0.7.5 → 0.8.0

data/lib/yard/code_objects/base.rb

@@ -224,6 +224,21 @@ module YARD
         yield(self) if block_given?
       end
 
+      # Copies all data in this object to another code object, except for
+      # uniquely identifying information (path, namespace, name, scope).
+      #
+      # @param [Base] other the object to copy data to
+      # @return [Base] the other object
+      # @since 0.8.0
+      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
+
       # The name of the object
       # @param [Boolean] prefix whether to show a prefix. Implement
       #   this in a subclass to define how the prefix is showed.
@@ -286,7 +301,7 @@ module YARD
 
       # @return [Integer] the object's hash value (for equality checking)
       def hash; path.hash end
-      
+
       # @return [nil] this object does not turn into an array
       def to_ary; nil end
 
@@ -348,6 +363,7 @@ module YARD
         end
       end
 
+      undef docstring
       def docstring
         return @docstring if !@docstring_extra
         case @docstring
@@ -445,7 +461,7 @@ module YARD
       # @return [String] the rendered template
       # @see Templates::Engine#render
       def format(options = {})
-        options.merge!(:object => self)
+        options = options.merge(:object => self)
         Templates::Engine.render(options)
       end
 
@@ -494,8 +510,6 @@ module YARD
       # @return whether or not this object is a RootObject
       def root?; false end
 
-      protected
-
       # 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
@@ -505,6 +519,23 @@ module YARD
       #   and the name (default is {NSEP})
       def sep; NSEP end
 
+      protected
+
+      # Override this method if your code object subclass does not allow
+      # copying of certain attributes.
+      #
+      # @return [Array<String>] the list of instance variable names (without
+      #   "@" prefix) that should be copied when {#copy_to} is called
+      # @see #copy_to
+      # @since 0.8.0
+      def copyable_attributes
+        vars = instance_variables.map {|ivar| ivar.to_s[1..-1] }
+        vars -= %w(docstring namespace name path)
+        vars
+      end
+
+      private
+
       # Formats source code by removing leading indentation
       #
       # @param [String] source the source code to format

data/lib/yard/code_objects/extra_file_object.rb

@@ -66,7 +66,7 @@ module YARD::CodeObjects
       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])

data/lib/yard/code_objects/macro_object.rb

@@ -1,27 +1,29 @@
+require 'ostruct'
+
 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
+    # 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}
+    #
+    # Macros are fully described in the {file:docs/Tags.md#macro Tags Overview}
     # document.
-    # 
+    #
     # @example Creating a basic named macro
-    #   # @macro prop
-    #   # @method $1(${3-})
-    #   # @return [$2] the value of the $0
+    #   # @!macro prop
+    #   #   @!method $1(${3-})
+    #   #   @return [$2] the value of the $0
     #   property :foo, String, :a, :b
-    #   
-    #   # @macro prop
+    #
+    #   # @!macro prop
     #   property :bar, Numeric, :value
-    # 
+    #
     # @example Creating a macro that is attached to the method call
-    #   # @macro [attach] prop2
-    #   # @method $1(value)
+    #   # @!macro [attach] prop2
+    #   #   @!method $1(value)
     #   property :foo
-    #   
+    #
     #   # Extra data added to docstring
     #   property :bar
     class MacroObject < Base
@@ -40,56 +42,54 @@ module YARD
           obj.method_object = method_object
           obj
         end
-    
+
         # Finds a macro using +macro_name+
+        # @param [#to_s] macro_name the name of the macro
         # @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. 
-        # 
+        # 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 [#to_s] macro_name the name of the macro
         # @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.
+        #   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)
+        def find_or_create(macro_name, data, method_object = nil)
+          if macro = find(name)
+            macro
           else
-            find(name)
+            create(macro_name, data, method_object)
           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
+        #
+        # @!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) 
+        #   @param [String] full_source the full source line (excluding block)
         #     interpolated as \$*
-        #   @param [String] block_source Currently unused. Will support 
+        #   @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})
@@ -113,91 +113,48 @@ module YARD
         # 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
+        # @!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)
+          docstring = docstring.all if Docstring === docstring
+          parser = DocstringParser.new
+          handler = OpenStruct.new
+          handler.call_params = call_params[1..-1]
+          handler.caller_method = call_params.first
+          handler.statement = OpenStruct.new(:source => full_source)
+          parser.parse(docstring, nil, handler).to_docstring.to_raw
         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
+        # @!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
+          apply(docstring, call_params, full_source, block_source)
         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
+
+      # Overrides {Base#path} so the macro path is ".macro.MACRONAME"
       def path; '.macro.' + name.to_s end
+
+      # Overrides the separator to be '.'
       def sep; '.' end
-      
-      # Expands the macro using 
+
+      # 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)

data/lib/yard/code_objects/method_object.rb

@@ -23,12 +23,26 @@ module YARD::CodeObjects
     # Creates a new method object in +namespace+ with +name+ and an instance
     # or class +scope+
     #
+    # If scope is +:module+, this object is instantiated as a public
+    # method in +:class+ scope, but also creates a new (empty) method
+    # as a private +:instance+ method on the same class or module.
+    #
     # @param [NamespaceObject] namespace the namespace
     # @param [String, Symbol] name the method name
-    # @param [Symbol] scope +:instance+ or +:class+
-    def initialize(namespace, name, scope = :instance)
+    # @param [Symbol] scope +:instance+, +:class+, or +:module+
+    def initialize(namespace, name, scope = :instance, &block)
+      @module_function = false
       @scope = nil
-      self.visibility = :public
+
+      # handle module function
+      if scope == :module
+        other = self.class.new(namespace, name, &block)
+        other.visibility = :private
+        scope = :class
+        @module_function = true
+      end
+
+      @visibility = :public
       self.scope = scope
       self.parameters = []
 
@@ -39,9 +53,22 @@ module YARD::CodeObjects
     # @param [Symbol] v the new scope
     def scope=(v)
       reregister = @scope ? true : false
-      YARD::Registry.delete(self) if reregister
+
+      # handle module function
+      if v == :module
+        other = self.class.new(namespace, name)
+        other.visibility = :private
+        @visibility = :public
+        @module_function = true
+        @path = nil
+      end
+
+      YARD::Registry.delete(self)
       @path = nil
       @scope = v.to_sym
+      if @scope == :module
+        @scope = :class
+      end
       YARD::Registry.register(self) if reregister
     end
 
@@ -50,6 +77,13 @@ module YARD::CodeObjects
       name == :initialize && scope == :instance && namespace.is_a?(ClassObject)
     end
 
+    # @return [Boolean] whether or not this method was created as a module
+    #   function
+    # @since 0.8.0
+    def module_function?
+      @module_function
+    end
+
     # Returns the read/writer info for the attribute if it is one
     # @return [SymbolHash] if there is information about the attribute
     # @return [nil] if the method is not an attribute
@@ -137,8 +171,6 @@ module YARD::CodeObjects
       prefix ? (sep == ISEP ? "#{sep}#{super}" : super.to_s) : super
     end
 
-    protected
-
     # Override separator to differentiate between class and instance
     # methods.
     # @return [String] "#" for an instance method, "." for class
@@ -149,5 +181,11 @@ module YARD::CodeObjects
         ISEP
       end
     end
+
+    protected
+
+    def copyable_attributes
+      super - %w(scope module_function)
+    end
   end
 end

data/lib/yard/config.rb

@@ -45,14 +45,14 @@ module YARD
   # loaded with safe mode on, because plugins are properly namespaced with
   # a 'yard-' prefix, must be installed as a gem, and therefore cannot be
   # touched by the user. To specify safe mode, use the +safe_mode+ key.
-  # 
+  #
   # == Plugin Specific Configuration
-  # 
+  #
   # Additional settings can be defined within the configuration file
   # specifically to provide configuration for a plugin. A plugin that utilizes
   # the YARD configuration is strongly encouraged to utilize namespacing of
   # their configuration content.
-  # 
+  #
   #     !!!yaml
   #     load_plugins: true # Auto-load plugins when YARD starts
   #     ignored_plugins:
@@ -63,23 +63,23 @@ module YARD
   #     # Plugin Specific Configuration
   #     yard-sample-plugin:
   #       show-results-inline: true
-  # 
+  #
   # As the configuration is available system wide, it can be
   # accessed within the plugin code.
-  # 
-  # 
+  #
+  #
   #     if YARD::Config.options['yard-sample-plugin'] and
   #       YARD::Config.options['yard-sample-plugin']['show-results-inline']
   #       # ... perform the action that places the results inline ...
   #     else
   #       # ... do the default behavior of not showing the results inline ...
   #     end
-  # 
+  #
   # When accessing the configuration, be aware that this file is user managed
   # so configuration keys and values may not be present. Make no assumptions and
   # instead ensure that you check for the existence of keys before proceeding to
   # retrieve values.
-  # 
+  #
   # @since 0.6.2
   # @see options
   class Config
@@ -119,6 +119,7 @@ module YARD
       self.options = SymbolHash.new(false)
       options.update(DEFAULT_CONFIG_OPTIONS)
       options.update(read_config_file)
+      load_commandline_safemode
       add_ignored_plugins_file
       translate_plugin_names
       load_plugins
@@ -198,6 +199,15 @@ module YARD
       end
     end
 
+    # Check for command-line safe_mode switch in {#arguments}
+    def self.load_commandline_safemode
+      with_yardopts do
+        arguments.each_with_index do |arg, i|
+          options[:safe_mode] = true if arg == '--safe'
+        end
+      end
+    end
+
     # Print a warning if the plugin failed to load
     # @return [false]
     def self.load_plugin_failed(name, exception)