yard 0.6.1 → 0.6.2

data/lib/yard/cli/server.rb

@@ -15,11 +15,21 @@ module YARD
       # @return [Adapter] the adapter to use for loading the web server
       attr_accessor :adapter
       
+      # @return [Array<String>] a list of scripts to load
+      # @since 0.6.2
+      attr_accessor :scripts
+      
+      # @return [Array<String>] a list of template paths to register
+      # @since 0.6.2
+      attr_accessor :template_paths
+      
       def description
         "Runs a local documentation server"
       end
       
       def run(*args)
+        self.scripts = []
+        self.template_paths = []
         self.libraries = {}
         self.options = SymbolHash.new(false).update(
           :single_library => true,
@@ -28,12 +38,23 @@ module YARD
         self.server_options = {:Port => 8808}
         optparse(*args)
         
-        select_adapter
+        select_adapter.setup
+        load_scripts
+        load_template_paths
         adapter.new(libraries, options, server_options).start
       end
       
       private
       
+      def load_scripts
+        scripts.each {|file| load_script(file) }
+      end
+      
+      def load_template_paths
+        return if YARD::Config.options[:safe_mode]
+        Templates::Engine.template_paths |= template_paths
+      end
+      
       def select_adapter
         return adapter if adapter
         require 'rubygems'
@@ -68,19 +89,13 @@ module YARD
         opts = OptionParser.new
         opts.banner = 'Usage: yard server [options] [[library yardoc_file] ...]'
         opts.separator ''
-        opts.separator 'Example: yard server yard .yardoc ruby-core ../ruby/.yardoc'
+        opts.separator 'Example: yard server -m yard .yardoc ruby-core ../ruby/.yardoc'
         opts.separator 'The above example serves documentation for YARD and Ruby-core'
         opts.separator ''
         opts.separator 'If no library/yardoc_file is specified, the server uses'
         opts.separator 'the name of the current directory and `.yardoc` respectively'
         opts.separator ''
         opts.separator "General Options:"
-        opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
-          if !require(file.gsub(/\.rb$/, ''))
-            log.error "The file `#{file}' was already loaded, perhaps you need to specify the absolute path to avoid name collisions."
-            exit
-          end
-        end
         opts.on('-m', '--multi-library', 'Serves documentation for multiple libraries') do
           options[:single_library] = false
         end
@@ -93,6 +108,10 @@ module YARD
         opts.on('-g', '--gems', 'Serves documentation for installed gems') do
           add_gems
         end
+        opts.on('-t', '--template-path PATH', 
+                'The template path to look for templates in. (used with -t).') do |path|
+          self.template_paths << path
+        end
         opts.separator ''
         opts.separator "Web Server Options:"
         opts.on('-d', '--daemon', 'Daemonizes the server process') do
@@ -117,6 +136,9 @@ module YARD
           server_options[:server] = type
         end
         common_options(opts)
+        opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
+          self.scripts << file
+        end
         parse_options(opts, args)
         
         if args.empty? && libraries.empty?

data/lib/yard/cli/stats.rb

@@ -67,7 +67,7 @@ module YARD
       
       # Prints list of undocumented objects
       def print_undocumented_objects
-        return unless @undoc_list
+        return if !@undoc_list || @undoc_list.empty?
         puts
         puts "Undocumented Objects:"
         

data/lib/yard/cli/yardoc.rb

@@ -197,6 +197,9 @@ module YARD
       def run(*args)
         parse_arguments(*args)
         
+        # fail early if markup provider is not found
+        return if generate && !verify_markup_options
+        
         checksums = nil
         if use_cache
           Registry.load
@@ -294,6 +297,16 @@ module YARD
         Templates::Engine.generate(objects, options)
       end
       
+      # Verifies that the markup options are valid before parsing any code.
+      # Failing early is better than failing late.
+      # 
+      # @return (see YARD::Templates::Helpers::MarkupHelper#load_markup_provider)
+      def verify_markup_options
+        obj = Struct.new(:options).new(options)
+        obj.extend(Templates::Helpers::MarkupHelper)
+        obj.load_markup_provider
+      end
+      
       # Copies any assets to the output directory
       # @return [void]
       # @since 0.6.0
@@ -479,7 +492,7 @@ module YARD
 
         opts.on('--no-private', "Hide objects with @private tag") do
           options[:verifier].add_expressions '!object.tag(:private) && 
-            (object.namespace.type == :proxy || !object.namespace.tag(:private))'
+            (object.namespace.is_a?(CodeObjects::Proxy) || !object.namespace.tag(:private))'
         end
 
         opts.on('--no-highlight', "Don't highlight code blocks in output.") do 
@@ -495,6 +508,7 @@ module YARD
         end
 
         opts.on('--query QUERY', "Only show objects that match a specific query") do |query|
+          next if YARD::Config.options[:safe_mode]
           options[:verifier].add_expressions(query.taint)
         end
 
@@ -555,6 +569,7 @@ module YARD
 
         opts.on('-p', '--template-path PATH', 
                 'The template path to look for templates in. (used with -t).') do |path|
+          next if YARD::Config.options[:safe_mode]
           YARD::Templates::Engine.register_template_path(path)
         end
 

data/lib/yard/code_objects/base.rb

@@ -400,11 +400,16 @@ module YARD
       # @return [String] the shortest relative path from this object to +other+
       # @since 0.5.3
       def relative_path(other)
-        other = other.path if other.respond_to?(:path)
+        other = Registry.at(other) if String === other && Registry.at(other)
+        same_parent = false
+        if other.respond_to?(:path)
+          same_parent = other.parent == parent
+          other = other.path
+        end
         return other unless namespace
         common = [path, other].join(" ").match(/^(\S*)\S*(?: \1\S*)*$/)[1]
         common = path unless common =~ /(\.|::|#)$/
-        common = common.sub(/(\.|::|#)[^:#\.]*?$/, '')
+        common = common.sub(/(\.|::|#)[^:#\.]*?$/, '') if same_parent
         result = other.sub(/^#{Regexp.quote common}(::|\.|)?/, '')
         result.empty? ? other : result
       end

data/lib/yard/code_objects/class_object.rb

@@ -45,6 +45,7 @@ module YARD::CodeObjects
         list += [superclass] unless superclass == P(:Object) || superclass == P(:BasicObject)
       end
       [self] + list.map do |m|
+        next m if m == self
         next m unless m.respond_to?(:inheritance_tree)
         m.inheritance_tree(include_mods)
       end.flatten.uniq

data/lib/yard/code_objects/method_object.rb

@@ -104,6 +104,7 @@ module YARD::CodeObjects
     # @return [nil] if it does not override a method
     # @since 0.6.0
     def overridden_method
+      return nil if namespace.is_a?(Proxy)
       meths = namespace.meths(:all => true)
       meths.find {|m| m.path != path && m.name == name && m.scope == scope }
     end

data/lib/yard/code_objects/proxy.rb

@@ -230,8 +230,14 @@ module YARD
       def to_obj
         return @obj if @obj
         if @obj = Registry.resolve(@namespace, (@imethod ? ISEP : '') + @name.to_s)
-          @namespace = @obj.namespace
-          @name = @obj.name
+          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

data/lib/yard/config.rb

@@ -0,0 +1,225 @@
+module YARD
+  # This class maintains all system-wide configuration for YARD and handles
+  # the loading of plugins. To access options call {options}, and to load
+  # a plugin use {load_plugin}. All other public methods are used by YARD
+  # during load time.
+  # 
+  # == User Configuration Files
+  # 
+  # Persistent user configuration files can be stored in the file 
+  # +~/.yard/config+, which is read when YARD first loads. The file should
+  # be formatted as YAML, and should contain a map of keys and values.
+  # 
+  # Although you can specify any key-value mapping in the configuration file,
+  # YARD defines special keys specified in {DEFAULT_CONFIG_OPTIONS}.
+  # 
+  # An example of a configuration file is listed below:
+  # 
+  #     !!!yaml
+  #     load_plugins: true # Auto-load plugins when YARD starts
+  #     ignored_plugins:
+  #       - yard-broken
+  #       - broken2 # yard- prefix not necessary
+  #     autoload_plugins:
+  #       - yard-rspec
+  # 
+  # == Automatic Loading of Plugins
+  # 
+  # YARD 0.6.2 will no longer automatically load all plugins by default. This 
+  # option can be reset by setting 'load_plugins' to true in the configuration 
+  # file. In addition, you can specify a set of specific plugins to load on 
+  # load through the 'autoload_plugins' list setting. This setting is 
+  # independent of the 'load_plugins' value and will always be processed.
+  # 
+  # == Ignored Plugins File
+  # 
+  # YARD 0.5 and below used a +~/.yard/ignored_plugins+ file to specify
+  # plugins to be ignored at load time. Ignored plugins in 0.6.2 and above
+  # should now be specified in the main configuration file, though YARD
+  # will support the +ignored_plugins+ file until 0.7.x.
+  # 
+  # == Safe Mode
+  # 
+  # YARD supports running in safe-mode. By doing this, it will avoid executing
+  # any user code such as require files or queries. Plugins will still be
+  # 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.
+  # 
+  # @since 0.6.2
+  # @see options
+  class Config
+    class << self
+      # The system-wide configuration options for YARD
+      # @return [SymbolHash] a map a key-value pair settings.
+      # @see DEFAULT_CONFIG_OPTIONS
+      attr_accessor :options
+    end
+
+    # The location where YARD stores user-specific settings
+    CONFIG_DIR = File.expand_path('~/.yard')
+    
+    # The main configuration YAML file.
+    CONFIG_FILE = File.join(CONFIG_DIR, 'config')
+    
+    # File listing all ignored plugins 
+    # @deprecated Set `ignored_plugins` in the {CONFIG_FILE} instead.
+    IGNORED_PLUGINS = File.join(CONFIG_DIR, 'ignored_plugins')
+    
+    # Default configuration options
+    DEFAULT_CONFIG_OPTIONS = {
+      :load_plugins => false,   # Whether to load plugins automatically with YARD
+      :ignored_plugins => [],   # A list of ignored plugins by name
+      :autoload_plugins => [],  # A list of plugins to be automatically loaded
+      :safe_mode => false       # Does not execute or eval any user-level code
+    }
+    
+    # The prefix used for YARD plugins. Name your gem with this prefix
+    # to allow it to be used as a plugin.
+    YARD_PLUGIN_PREFIX = /^yard[-_]/
+    
+    # Loads settings from {CONFIG_FILE}. This method is called by YARD at
+    # load time and should not be called by the user.
+    # @return [void]
+    def self.load
+      self.options = SymbolHash.new(false)
+      options.update(DEFAULT_CONFIG_OPTIONS)
+      options.update(read_config_file)
+      add_ignored_plugins_file
+      translate_plugin_names
+      load_plugins
+    rescue
+      log.error "Invalid configuration file, using default options."
+      options.update(DEFAULT_CONFIG_OPTIONS)
+    end
+    
+    # Saves settings to {CONFIG_FILE}.
+    # @return [void]
+    def self.save
+      require 'yaml'
+      File.open(CONFIG_FILE, 'w') {|f| f.write(YAML.dump(options)) }
+    end
+    
+    # Loads gems that match the name 'yard-*' (recommended) or 'yard_*' except
+    # those listed in +~/.yard/ignored_plugins+. This is called immediately 
+    # after YARD is loaded to allow plugin support.
+    # 
+    # @return [Boolean] true if all plugins loaded successfully, false otherwise.
+    def self.load_plugins
+      load_gem_plugins &&
+        load_autoload_plugins &&
+        load_commandline_plugins ? true : false
+    end
+    
+    # Loads an individual plugin by name. It is not necessary to include the
+    # +yard-+ plugin prefix here.
+    # 
+    # @param [String] name the name of the plugin (with or without +yard-+ prefix)
+    # @return [Boolean] whether the plugin was successfully loaded
+    def self.load_plugin(name)
+      name = translate_plugin_name(name)
+      return false if options[:ignored_plugins].include?(name)
+      return false if name =~ /^yard-doc-/
+      log.debug "Loading plugin '#{name}'..."
+      require name
+      true
+    rescue LoadError => e
+      load_plugin_failed(name, e)
+    end
+    
+    private
+    
+    # Load gem plugins if :load_plugins is true
+    def self.load_gem_plugins
+      return true unless options[:load_plugins]
+      require 'rubygems'
+      result = true
+      Gem.source_index.find_name('').each do |gem|
+        begin
+          next true unless gem.name =~ YARD_PLUGIN_PREFIX
+          load_plugin(gem.name)
+        rescue Gem::LoadError => e
+          tmp = load_plugin_failed(gem.name, e)
+          result = tmp if !tmp
+        end
+      end
+      result
+    rescue LoadError
+      log.debug "RubyGems is not present, skipping plugin loading"
+      false
+    end
+    
+    # Load plugins set in :autoload_plugins
+    def self.load_autoload_plugins
+      options[:autoload_plugins].each {|name| load_plugin(name) }
+    end
+    
+    # Load plugins from {#arguments}
+    def self.load_commandline_plugins
+      with_yardopts do
+        arguments.each_with_index do |arg, i|
+          next unless arg == '--plugin'
+          load_plugin(arguments[i+1])
+        end
+      end
+    end
+    
+    # Print a warning if the plugin failed to load
+    # @return [false]
+    def self.load_plugin_failed(name, exception)
+      log.warn "Error loading plugin '#{name}'"
+      log.backtrace(exception) if $DEBUG
+      false
+    end
+    
+    # Legacy support for {IGNORED_PLUGINS}
+    def self.add_ignored_plugins_file
+      if File.file?(IGNORED_PLUGINS)
+        options[:ignored_plugins] += File.read(IGNORED_PLUGINS).split(/\s+/)
+      end
+    end
+    
+    # Translates plugin names to add yard- prefix.
+    def self.translate_plugin_names
+      options[:ignored_plugins].map! {|name| translate_plugin_name(name) }
+      options[:autoload_plugins].map! {|name| translate_plugin_name(name) }
+    end
+
+    # Loads the YAML configuration file into memory
+    # @return [Hash] the contents of the YAML file from disk
+    # @see CONFIG_FILE
+    def self.read_config_file
+      if File.file?(CONFIG_FILE)
+        require 'yaml'
+        YAML.load_file(CONFIG_FILE)
+      else
+        {}
+      end
+    end
+    
+    # Sanitizes and normalizes a plugin name to include the 'yard-' prefix.
+    # @param [String] name the plugin name
+    # @return [String] the sanitized and normalized plugin name.
+    def self.translate_plugin_name(name)
+      name = name.gsub('/', '') # Security sanitization
+      name = "yard-" + name unless name =~ YARD_PLUGIN_PREFIX
+      name
+    end
+    
+    # Temporarily loads .yardopts file into @yardopts
+    def self.with_yardopts(&block)
+      yfile = CLI::Yardoc::DEFAULT_YARDOPTS_FILE
+      @yardopts = File.file?(yfile) ? File.read_binary(yfile).shell_split : []
+      result = yield
+      @yardopts = nil
+      result
+    end
+    
+    # @return [Array<String>] arguments from commandline and yardopts file
+    def self.arguments
+      ARGV + @yardopts
+    end
+  end
+  
+  Config.options = Config::DEFAULT_CONFIG_OPTIONS
+end

data/lib/yard/handlers/base.rb

@@ -219,6 +219,33 @@ module YARD
           (@namespace_only ||= false) ? true : false
         end
         
+        # Declares that a handler should only be called when inside a filename
+        # by its basename or a regex match for the full path.
+        # 
+        # @param [String, Regexp] filename a matching filename or regex
+        # @return [void]
+        # @since 0.6.2
+        def in_file(filename)
+          (@in_files ||= []) << filename
+        end
+        
+        # @return [Boolean] whether the filename matches the declared file
+        #   match for a handler. If no file match is specified, returns true.
+        # @since 0.6.2
+        def matches_file?(filename)
+          return true unless @in_files
+          @in_files.any? do |in_file|
+            case in_file
+            when String
+              File.basename(filename) == in_file
+            when Regexp
+              filename =~ in_file
+            else
+              true
+            end
+          end
+        end
+        
         # Generates a +process+ method, equivalent to +def process; ... end+.
         # Blocks defined with this syntax will be wrapped inside an anonymous
         # module so that the handler class can be extended with mixins that
@@ -427,10 +454,10 @@ module YARD
           end
         end
         
-        if RUBY_PLATFORM =~ /java/ || defined?(::Rubinius)
+        unless CONTINUATIONS_SUPPORTED
           unless $NO_CONTINUATION_WARNING
             $NO_CONTINUATION_WARNING = true
-            log.warn "JRuby/Rubinius do not implement Kernel#callcc and cannot " +
+            log.warn "JRuby/MacRuby/Rubinius do not implement Kernel#callcc and cannot " +
               "load files in order. You must specify the correct order manually."
           end
           raise NamespaceMissingError, object