Class: Yard::Yaml::Converter

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/yaml/converter.rb

Overview

Thin wrapper around the yaml-converter gem with safe defaults.

Phase 2 scope:

  • Provide class methods to convert from a YAML string or a file path.

  • Apply safe defaults and respect config toggles (strict, allow_erb, front_matter).

  • Delegate conversion to an underlying backend (default: ::Yaml::Converter if available).

  • Return a normalized result Hash: { html:, title:, description:, meta: }.

Note: We intentionally keep the contract minimal and stable. Tests stub the backend.

Constant Summary collapse

BACKEND_STATE = 
{backend: nil}
BACKEND_MUTEX = 
Mutex.new

Class Method Summary collapse

Class Method Details

.backend ⇒ Object

Backend accessor with auto-discovery.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/yard/yaml/converter.rb', line 50

def backend
  configured_backend = BACKEND_MUTEX.synchronize { BACKEND_STATE[:backend] }
  return configured_backend if configured_backend

  begin
    require "yaml/converter"
  rescue LoadError
    # ignore; backend may be set by tests
  end

  BACKEND_MUTEX.synchronize do
    BACKEND_STATE[:backend] ||= ::Yaml::Converter if defined?(::Yaml) && ::Yaml.const_defined?(:Converter)
  end
end

.backend=(backend) ⇒ Object

Assignable backend for dependency injection in tests. Preferred backends respond to ‘to_markdown(yaml, options:)`. Legacy test backends may respond to `convert(yaml, options)` and return a Hash with :html, :title, :description, and :meta keys.



23
24
25
 
# File 'lib/yard/yaml/converter.rb', line 23

def backend=(backend)
  BACKEND_MUTEX.synchronize { BACKEND_STATE[:backend] = backend }
end

.from_file(path, options = {}, config: Yard::Yaml.config) ⇒ Hash

Convert a YAML file from disk.

Parameters:

  • path (String)
  • options (Hash) (defaults to: {})
  • config (Yard::Yaml::Config) (defaults to: Yard::Yaml.config)

Returns:

  • (Hash) 


43
44
45
46
47
 
# File 'lib/yard/yaml/converter.rb', line 43

def from_file(path, options = {}, config: Yard::Yaml.config)
  content = read_file(path, config: config)
  return empty_result if content.nil?
  run_convert(content, options.merge(source_path: path.to_s), config)
end

.from_string(yaml, options = {}, config: Yard::Yaml.config) ⇒ Hash

Convert a YAML string into an HTML result.

Parameters:

  • yaml (String)
  • options (Hash) (defaults to: {}) —

    additional options passed to backend

  • config (Yard::Yaml::Config) (defaults to: Yard::Yaml.config) —

    yard-yaml config (defaults to Yard::Yaml.config)

Returns:

  • (Hash) —

    { html:, title:, description:, meta: }



33
34
35
 
# File 'lib/yard/yaml/converter.rb', line 33

def from_string(yaml, options = {}, config: Yard::Yaml.config)
  run_convert(yaml.to_s, options, config)
end