deg-yard 0.8.7.1

data/lib/yard/config.rb

@@ -0,0 +1,269 @@
+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.
+  #
+  # == 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:
+  #       - yard-broken
+  #       - broken2 # yard- prefix not necessary
+  #     autoload_plugins:
+  #       - yard-rspec
+  #     # 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
+    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)
+      load_commandline_safemode
+      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
+
+    # 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)
+      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/core_ext/array.rb

@@ -0,0 +1,15 @@
+class Array
+  # Places values before or after another object (by value) in
+  # an array. This is used in tandem with the before and after
+  # methods of the {Insertion} class.
+  #
+  # @example Places an item before another
+  #   [1, 2, 3].place(4).before(3) # => [1, 2, 4, 3]
+  # @example Places an item after another
+  #   [:a, :b, :c].place(:x).after(:a) # => [:a, :x, :b, :c]
+  # @param [Array] values value to insert
+  # @return [Insertion] an insertion object to
+  # @see Insertion#before
+  # @see Insertion#after
+  def place(*values) Insertion.new(self, values) end
+end

data/lib/yard/core_ext/file.rb

@@ -0,0 +1,65 @@
+require 'fileutils'
+
+class File
+  RELATIVE_PARENTDIR = '..'
+  RELATIVE_SAMEDIR = '.'
+
+  # @group Manipulating Paths
+
+  # Turns a path +to+ into a relative path from starting
+  # point +from+. The argument +from+ is assumed to be
+  # a filename. To treat it as a directory, make sure it
+  # ends in +File::SEPARATOR+ ('/' on UNIX filesystems).
+  #
+  # @param [String] from the starting filename
+  #   (or directory with +from_isdir+ set to +true+).
+  # @param [String] to the final path that should be made relative.
+  # @return [String] the relative path from +from+ to +to+.
+  def self.relative_path(from, to)
+    from = expand_path(from).split(SEPARATOR)
+    to = expand_path(to).split(SEPARATOR)
+    from.length.times do
+      break if from[0] != to[0]
+      from.shift; to.shift
+    end
+    from.pop
+    join(*(from.map { RELATIVE_PARENTDIR } + to))
+  end
+
+  # Cleans a path by removing extraneous '..', '.' and '/' characters
+  #
+  # @example Clean a path
+  #   File.cleanpath('a/b//./c/../e') # => "a/b/e"
+  # @param [String] path the path to clean
+  # @return [String] the sanitized path
+  def self.cleanpath(path)
+    path = path.split(SEPARATOR)
+    path = path.inject([]) do |acc, comp|
+      next acc if comp == RELATIVE_SAMEDIR
+      if comp == RELATIVE_PARENTDIR && acc.size > 0 && acc.last != RELATIVE_PARENTDIR
+        acc.pop
+        next acc
+      end
+      acc << comp
+    end
+    File.join(*path)
+  end
+
+  # @group Reading Files
+
+  # Forces opening a file (for writing) by first creating the file's directory
+  # @param [String] file the filename to open
+  # @since 0.5.2
+  def self.open!(file, *args, &block)
+    dir = dirname(file)
+    FileUtils.mkdir_p(dir) unless directory?(dir)
+    open(file, *args, &block)
+  end
+
+  # Reads a file with binary encoding
+  # @return [String] the ascii-8bit encoded data
+  # @since 0.5.3
+  def self.read_binary(file)
+    File.open(file, 'rb') {|f| f.read }
+  end
+end

data/lib/yard/core_ext/hash.rb

@@ -0,0 +1,15 @@
+class Hash
+  class << self
+    def create(*args)
+      if args.first.is_a?(Array) && args.size == 1
+        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/insertion.rb

@@ -0,0 +1,60 @@
+# The Insertion class inserts a value before or after another
+# value in a list.
+#
+# @example
+#   Insertion.new([1, 2, 3], 4).before(3) # => [1, 2, 4, 3]
+class Insertion
+  # Creates an insertion object on a list with a value to be
+  # inserted. To finalize the insertion, call {#before} or
+  # {#after} on the object.
+  #
+  # @param [Array] list the list to perform the insertion on
+  # @param [Object] value the value to insert
+  def initialize(list, value) @list, @values = list, (Array === value ? value : [value]) end
+
+  # Inserts the value before +val+
+  # @param [Object] val the object the value will be inserted before
+  # @param [Boolean] recursive look inside sublists
+  def before(val, recursive = false) insertion(val, 0, recursive) end
+
+  # Inserts the value after +val+.
+  #
+  # @example If subsections are ignored
+  #   Insertion.new([1, [2], 3], :X).after(1) # => [1, [2], :X, 3]
+  # @param [Object] val the object the value will be inserted after
+  # @param [Boolean] recursive look inside sublists
+  def after(val, recursive = false) insertion(val, 1, recursive) end
+
+  # Alias for {#before} with +recursive+ set to true
+  # @since 0.6.0
+  def before_any(val) insertion(val, 0, true) end
+
+  # Alias for {#after} with +recursive+ set to true
+  # @since 0.6.0
+  def after_any(val) insertion(val, 1, true) end
+
+  private
+
+  # This method performs the actual insertion
+  #
+  # @param [Object] val the value to insert
+  # @param [Fixnum] rel the relative index (0 or 1) of where the object
+  #   should be placed
+  # @param [Boolean] recursive look inside sublists
+  # @param [Array] list the list to place objects into
+  def insertion(val, rel, recursive = false, list = @list)
+    if recursive
+      list.each do |item|
+        next unless item.is_a?(Array)
+        tmp = item.dup
+        insertion(val, rel, recursive, item)
+        return(list) unless item == tmp
+      end
+    end
+
+    if index = list.index(val)
+      list[index+rel,0] = @values
+    end
+    list
+  end
+end

data/lib/yard/core_ext/module.rb

@@ -0,0 +1,19 @@
+class Module
+  # Returns the class name of a full module namespace path
+  #
+  # @example
+  #   module A::B::C; class_name end # => "C"
+  # @return [String] the last part of a module path
+  def class_name
+    name.split("::").last
+  end
+
+  # Returns the module namespace path minus the class/module name
+  #
+  # @example
+  #   module A::B::C; namespace_name end # => "A::B"
+  # @return [String] the namespace minus the class/module name
+  def namespace_name
+    name.split("::")[0..-2].join("::")
+  end
+end

data/lib/yard/core_ext/string.rb

@@ -0,0 +1,67 @@
+class String
+  # 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

@@ -0,0 +1,73 @@
+# A subclass of Hash where all keys are converted into Symbols, and
+# optionally, all String values are converted into Symbols.
+class SymbolHash < Hash
+  # Creates a new SymbolHash object
+  #
+  # @param [Boolean] symbolize_value converts any String values into Symbols
+  #   if this is set to +true+.
+  def initialize(symbolize_value = true)
+    @symbolize_value = symbolize_value
+  end
+
+  # @overload [](hash)
+  #   Creates a SymbolHash object from an existing Hash
+  #
+  #   @example
+  #     SymbolHash['x' => 1, :y => 2] # => #<SymbolHash:0x...>
+  #   @param [Hash] hash the hash object
+  #   @return [SymbolHash] a new SymbolHash from a hash object
+  #
+  # @overload [](*list)
+  #   Creates a SymbolHash from an even list of keys and values
+  #
+  #   @example
+  #     SymbolHash[key1, value1, key2, value2, ...]
+  #   @param [Array] list an even list of key followed by value
+  #   @return [SymbolHash] a new SymbolHash object
+  def self.[](*hsh)
+    obj = new;
+    if hsh.size == 1 && hsh.first.is_a?(Hash)
+      hsh.first.each {|k,v| obj[k] = v }
+    else
+      0.step(hsh.size, 2) {|n| obj[hsh[n]] = hsh[n+1] }
+    end
+    obj
+  end
+
+  # Assigns a value to a symbolized key
+  # @param [#to_sym] key the key
+  # @param [Object] value the value to be assigned. If this is a String and
+  #   values are set to be symbolized, it will be converted into a Symbol.
+  def []=(key, value)
+    super(key.to_sym, value.instance_of?(String) && @symbolize_value ? value.to_sym : value)
+  end
+
+  # Accessed a symbolized key
+  # @param [#to_sym] key the key to access
+  # @return [Object] the value associated with the key
+  def [](key) super(key.to_sym) end
+
+  # Deleted a key and value associated with it
+  # @param [#to_sym] key the key to delete
+  # @return [void]
+  def delete(key) super(key.to_sym) end
+
+  # Tests if a symbolized key exists
+  # @param [#to_sym] key the key to test
+  # @return [Boolean] whether the key exists
+  def has_key?(key) super(key.to_sym) end
+
+  # Updates the object with the contents of another Hash object.
+  # This method modifies the original SymbolHash object
+  #
+  # @param [Hash] hash the hash object to copy the values from
+  # @return [SymbolHash] self
+  def update(hash) hash.each {|k,v| self[k] = v }; self end
+  alias_method :merge!, :update
+
+  # Merges the contents of another hash into a new SymbolHash object
+  #
+  # @param [Hash] hash the hash of objects to copy
+  # @return [SymbolHash] a new SymbolHash containing the merged data
+  def merge(hash) dup.merge!(hash) end
+end