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
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
-
(Array
- arguments from commandline and yardopts file)
def self.arguments ARGV + @yardopts end
def self.load
-
(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
def self.load_autoload_plugins options[:autoload_plugins].each {|name| load_plugin(name) } end
def self.load_commandline_plugins
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
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
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)
-
(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)
-
(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
-
(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
- 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
-
(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)
-
(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
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
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