class YARD::Config

@see options
@since 0.6.2
retrieve values.
instead ensure that you check for the existence of keys before proceeding to
so configuration keys and values may not be present. Make no assumptions and
When accessing the configuration, be aware that this file is user managed
end
# … do the default behavior of not showing the results inline …
else
# … perform the action that places the results inline …
[‘show-results-inline’]
if YARD::Config.options and
accessed within the plugin code.
As the configuration is available system wide, it can be
show-results-inline: true
yard-sample-plugin:
# Plugin Specific Configuration
- yard-rspec
autoload_plugins:
- broken2 # yard- prefix not necessary
- yard-broken
ignored_plugins:
load_plugins: true # Auto-load plugins when YARD starts
!!!yaml
their configuration content.
the YARD configuration is strongly encouraged to utilize namespacing of
specifically to provide configuration for a plugin. A plugin that utilizes
Additional settings can be defined within the configuration file
== Plugin Specific Configuration
touched by the user. To specify safe mode, use the safe_mode key.
a ‘yard-’ prefix, must be installed as a gem, and therefore cannot be
loaded with safe mode on, because plugins are properly namespaced with
any user code such as require files or queries. Plugins will still be
YARD supports running in safe-mode. By doing this, it will avoid executing
== Safe Mode
will support the ignored_plugins file until 0.7.x.
should now be specified in the main configuration file, though YARD
plugins to be ignored at load time. Ignored plugins in 0.6.2 and above
YARD 0.5 and below used a +~/.yard/ignored_plugins+ file to specify
== Ignored Plugins File
independent of the ‘load_plugins’ value and will always be processed.
load through the ‘autoload_plugins’ list setting. This setting is
file. In addition, you can specify a set of specific plugins to load on
option can be reset by setting ‘load_plugins’ to true in the configuration
YARD 0.6.2 will no longer automatically load all plugins by default. This
== Automatic Loading of Plugins
- yard-rspec
autoload_plugins:
- broken2 # yard- prefix not necessary
- yard-broken
ignored_plugins:
load_plugins: true # Auto-load plugins when YARD starts
!!!yaml
An example of a configuration file is listed below:
YARD defines special keys specified in {DEFAULT_CONFIG_OPTIONS}.
Although you can specify any key-value mapping in the configuration file,
be formatted as YAML, and should contain a map of keys and values.
+~/.yard/config+, which is read when YARD first loads. The file should
Persistent user configuration files can be stored in the file
== User Configuration Files
during load time.
a plugin use {load_plugin}. All other public methods are used by YARD
the loading of plugins. To access options call {options}, and to load
This class maintains all system-wide configuration for YARD and handles

def self.add_ignored_plugins_file

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

def self.arguments

Returns:
  • (Array) - arguments from commandline and yardopts file
def self.arguments
  ARGV + @yardopts
end

def self.load

Returns:
  • (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 => e
  log.error "Invalid configuration file, using default options."
  log.backtrace(e)
  options.update(DEFAULT_CONFIG_OPTIONS)
end

def self.load_autoload_plugins

Load plugins set in :autoload_plugins
def self.load_autoload_plugins
  options[:autoload_plugins].each {|name| load_plugin(name) }
end

def self.load_commandline_plugins

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

def self.load_commandline_safemode

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

def self.load_gem_plugins

Load gem plugins if :load_plugins is true
def self.load_gem_plugins
  return true unless options[:load_plugins]
  require 'rubygems'
  result = true
  YARD::GemIndex.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 unless tmp
    end
  end
  result
rescue LoadError
  log.debug "RubyGems is not present, skipping plugin loading"
  false
end

def self.load_plugin(name)

Returns:
  • (Boolean) - whether the plugin was successfully loaded

Parameters:
  • name (String) -- the name of the plugin (with or without +yard-+ prefix)
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

def self.load_plugin_failed(name, exception)

Returns:
  • (false) -
def self.load_plugin_failed(name, exception)
  log.error "Error loading plugin '#{name}'"
  log.backtrace(exception) if $DEBUG
  false
end

def self.load_plugins

Returns:
  • (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

def self.read_config_file

Other tags:
    See: CONFIG_FILE -

Returns:
  • (Hash) - the contents of the YAML file from disk
def self.read_config_file
  if File.file?(CONFIG_FILE)
    require 'yaml'
    if YAML.respond_to?(:safe_load_file)
      YAML.safe_load_file(CONFIG_FILE, permitted_classes: [SymbolHash, Symbol])
    else
      YAML.load_file(CONFIG_FILE)
    end
  else
    {}
  end
end

def self.save

Returns:
  • (void) -
def self.save
  require 'yaml'
  Dir.mkdir(CONFIG_DIR) unless File.directory?(CONFIG_DIR)
  File.open(CONFIG_FILE, 'w') {|f| f.write(YAML.dump(options)) }
end

def self.translate_plugin_name(name)

Returns:
  • (String) - the sanitized and normalized plugin name.

Parameters:
  • name (String) -- the plugin name
def self.translate_plugin_name(name)
  name = name.delete('/') # Security sanitization
  name = "yard-" + name unless name =~ YARD_PLUGIN_PREFIX
  name
end

def self.translate_plugin_names

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

def self.with_yardopts

Temporarily loads .yardopts file into @yardopts
def self.with_yardopts
  yfile = CLI::Yardoc::DEFAULT_YARDOPTS_FILE
  @yardopts = File.file?(yfile) ? File.read_binary(yfile).shell_split : []
  result = yield
  @yardopts = nil
  result
end