# Class: YARD::Config

Inherits:
  Object
  - Object
  - YARD::Config
  show all

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 Config.options, and to load a plugin use Config.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.

See Also:

- Config.options

Since:

- 0.6.2

## Constant Summary collapse

CONFIG_DIR =

The location where YARD stores user-specific settings

Since:

- 0.6.2

      File.expand_path('~/.yard')

CONFIG_FILE =

The main configuration YAML file.

Since:

- 0.6.2

      File.join(CONFIG_DIR, 'config')

IGNORED_PLUGINS =
Deprecated.

Set ‘ignored_plugins` in the CONFIG_FILE instead.

File listing all ignored plugins

Since:

- 0.6.2

      File.join(CONFIG_DIR, 'ignored_plugins')

DEFAULT_CONFIG_OPTIONS =

Default configuration options

Since:

- 0.6.2

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

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

      /^yard[-_]/

## Class Attribute Summary collapse

- .options ⇒ SymbolHash

  The system-wide configuration options for YARD.

## Class Method Summary collapse

- .add_ignored_plugins_file ⇒ Object

  Legacy support for IGNORED_PLUGINS.

- .arguments ⇒ Array<String>

  Arguments from commandline and yardopts file.

- .load ⇒ void

  Loads settings from CONFIG_FILE.

- .load_autoload_plugins ⇒ Object

  Load plugins set in :autoload_plugins.

- .load_commandline_plugins ⇒ Object

  Load plugins from Config.arguments.

- .load_commandline_safemode ⇒ Object

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

- .load_gem_plugins ⇒ Object

  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 ⇒ Object

  Translates plugin names to add yard- prefix.

- .with_yardopts ⇒ Object

  Temporarily loads .yardopts file into @yardopts.

## Class Attribute Details

### .options ⇒ `SymbolHash`

The system-wide configuration options for YARD

Returns:

- (`SymbolHash`) —

  a map a key-value pair settings.

See Also:

- DEFAULT_CONFIG_OPTIONS

Since:

- 0.6.2

    91
    92
    93

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

    def options
      @options
    end

## Class Method Details

### .add_ignored_plugins_file ⇒ `Object`

Legacy support for IGNORED_PLUGINS

Since:

- 0.6.2

    221
    222
    223
    224
    225

    # 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 arguments from commandline and yardopts file.

Returns:

- (`Array<String>`) —

  arguments from commandline and yardopts file

Since:

- 0.6.2

    268
    269
    270

    # 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

    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131

    # 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 ⇒ `Object`

Load plugins set in :autoload_plugins

Since:

- 0.6.2

    189
    190
    191

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

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

### .load_commandline_plugins ⇒ `Object`

Load plugins from arguments

Since:

- 0.6.2

    194
    195
    196
    197
    198
    199
    200
    201

    # 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 ⇒ `Object`

Check for command-line safe_mode switch in arguments

Since:

- 0.6.2

    204
    205
    206
    207
    208
    209
    210

    # 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 ⇒ `Object`

Load gem plugins if :load_plugins is true

Since:

- 0.6.2

    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186

    # 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

    157
    158
    159
    160
    161
    162
    163
    164
    165
    166

    # 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

Returns:

- (`false`)

Since:

- 0.6.2

    214
    215
    216
    217
    218

    # 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

    146
    147
    148
    149
    150

    # 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

See Also:

- CONFIG_FILE

Since:

- 0.6.2

    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247

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

    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

### .save ⇒ `void`

This method returns an undefined value.

Saves settings to CONFIG_FILE.

Since:

- 0.6.2

    135
    136
    137
    138
    139

    # 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

    252
    253
    254
    255
    256

    # 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 ⇒ `Object`

Translates plugin names to add yard- prefix.

Since:

- 0.6.2

    228
    229
    230
    231

    # 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 ⇒ `Object`

Temporarily loads .yardopts file into @yardopts

Since:

- 0.6.2

    259
    260
    261
    262
    263
    264
    265

    # 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