Class: YARD::Config

Relationships & Source Files
Inherits:	Object
Defined in:	lib/yard/config.rb

Overview

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:

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.

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.

Constant Summary

CONFIG_DIR =

The location where ::YARD stores user-specific settings
Since:
- 0.6.2
# File 'lib/yard/config.rb', line 95
```
File.expand_path('~/.yard')
```
CONFIG_FILE =

The main configuration YAML file.
Since:
- 0.6.2
# File 'lib/yard/config.rb', line 98
```
File.join(CONFIG_DIR, 'config')
```

DEFAULT_CONFIG_OPTIONS =

Default configuration options

Since:

0.6.2

# File 'lib/yard/config.rb', line 105

{
  :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
}

IGNORED_PLUGINS =

Deprecated.
Set ignored_plugins in the CONFIG_FILE instead.

::File listing all ignored plugins
Since:
- 0.6.2
# File 'lib/yard/config.rb', line 102
```
File.join(CONFIG_DIR, 'ignored_plugins')
```
YARD_PLUGIN_PREFIX =

The prefix used for ::YARD plugins. Name your gem with this prefix to allow it to be used as a plugin.
Since:
- 0.6.2
# File 'lib/yard/config.rb', line 114
```
/^yard[-_]/
```

Class Attribute Summary

.options ⇒ SymbolHash rw

The system-wide configuration options for ::YARD.

Class Method Summary

.add_ignored_plugins_file

Legacy support for IGNORED_PLUGINS
.arguments ⇒ Array<String>
.load ⇒ void

Loads settings from CONFIG_FILE.
.load_autoload_plugins

Load plugins set in :autoload_plugins.
.load_commandline_plugins

Load plugins from .arguments
.load_commandline_safemode

Check for command-line safe_mode switch in .arguments
.load_gem_plugins

Load gem plugins if :load_plugins is true.
.load_plugin(name) ⇒ Boolean

Loads an individual plugin by name.
.load_plugin_failed(name, exception) ⇒ false

Print a warning if the plugin failed to load.
.load_plugins ⇒ Boolean

Loads gems that match the name 'yard-' (recommended) or 'yard_' except those listed in ~/.yard/ignored_plugins.
.read_config_file ⇒ Hash

Loads the YAML configuration file into memory.
.save ⇒ void

Saves settings to CONFIG_FILE.
.translate_plugin_name(name) ⇒ String

Sanitizes and normalizes a plugin name to include the 'yard-' prefix.
.translate_plugin_names

Translates plugin names to add yard- prefix.
.with_yardopts

Temporarily loads .yardopts file into @yardopts.

Class Attribute Details

.options ⇒ SymbolHash (rw)

The system-wide configuration options for ::YARD

Returns:

(SymbolHash) —
a map a key-value pair settings.

Class Method Details

.add_ignored_plugins_file

Legacy support for IGNORED_PLUGINS

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 221


def self.add_ignored_plugins_file
  if File.file?(IGNORED_PLUGINS)
    options[:ignored_plugins] += File.read(IGNORED_PLUGINS).split(/\s+/)
  end
end

.arguments ⇒ Array<String>

Returns:

(Array<String>) —
arguments from commandline and yardopts file

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 268


def self.arguments
  ARGV + @yardopts
end

.load ⇒ `void`

This method returns an undefined value.

Loads settings from CONFIG_FILE. This method is called by ::YARD at load time and should not be called by the user.

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 119


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

.load_autoload_plugins

Load plugins set in :autoload_plugins

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 189


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

.load_commandline_plugins

Load plugins from .arguments

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 194


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

.load_commandline_safemode

Check for command-line safe_mode switch in .arguments

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 204


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

.load_gem_plugins

Load gem plugins if :load_plugins is true

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 169


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

.load_plugin(name) ⇒ `Boolean`

Loads an individual plugin by name. It is not necessary to include the yard- plugin prefix here.

Parameters:

name (String) —
the name of the plugin (with or without yard- prefix)

Returns:

(Boolean) —
whether the plugin was successfully loaded

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 157


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

.load_plugin_failed(name, exception) ⇒ `false`

Print a warning if the plugin failed to load

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 214


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

.load_plugins ⇒ `Boolean`

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.

Returns:

(Boolean) —
true if all plugins loaded successfully, false otherwise.

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 146


def self.load_plugins
  load_gem_plugins &&
    load_autoload_plugins &&
    load_commandline_plugins ? true : false
end

.read_config_file ⇒ Hash

Loads the YAML configuration file into memory

Returns:

(Hash) —
the contents of the YAML file from disk

.save ⇒ `void`

This method returns an undefined value.

Saves settings to CONFIG_FILE.

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 135


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

.translate_plugin_name(name) ⇒ String

Sanitizes and normalizes a plugin name to include the 'yard-' prefix.

Parameters:

name (String) —
the plugin name

Returns:

(String) —
the sanitized and normalized plugin name.

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 252


def self.translate_plugin_name(name)
  name = name.delete('/') # Security sanitization
  name = "yard-" + name unless name =~ YARD_PLUGIN_PREFIX
  name
end

.translate_plugin_names

Translates plugin names to add yard- prefix.

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 228


def self.translate_plugin_names
  options[:ignored_plugins].map! {|name| translate_plugin_name(name) }
  options[:autoload_plugins].map! {|name| translate_plugin_name(name) }
end

.with_yardopts

Temporarily loads .yardopts file into @yardopts

Since:

0.6.2

[ GitHub ]

# File 'lib/yard/config.rb', line 259


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

Class: YARD::Config

Overview

User Configuration Files

Automatic Loading of Plugins

Ignored Plugins File

Safe Mode

Plugin Specific Configuration

Constant Summary

Class Attribute Summary

Class Method Summary

Class Attribute Details

.options ⇒ SymbolHash (rw)

Class Method Details

.add_ignored_plugins_file

.arguments ⇒ Array<String>

.load ⇒ void

.load_autoload_plugins

.load_commandline_plugins

.load_commandline_safemode

.load_gem_plugins

.load_plugin(name) ⇒ Boolean

.load_plugin_failed(name, exception) ⇒ false

.load_plugins ⇒ Boolean

.read_config_file ⇒ Hash

.save ⇒ void

.translate_plugin_name(name) ⇒ String

.translate_plugin_names

.with_yardopts

.load ⇒ `void`

.load_plugin(name) ⇒ `Boolean`

.load_plugin_failed(name, exception) ⇒ `false`

.load_plugins ⇒ `Boolean`

.save ⇒ `void`