Class: Coradoc::IncludeResolver

Inherits:
Object
  • Object
show all
Defined in:
lib/coradoc/include_resolver.rb,
lib/coradoc/include_resolver/filesystem.rb

Overview

Include resolver protocol.

A resolver is anything that responds to #call(target:, base_dir:, options:, context:) and returns the raw bytes of the included target, BEFORE tag/line/indent selectors are applied. Selectors live in the processor; the resolver only fetches bytes.

The default resolver is Filesystem. Custom resolvers (HTTP, database, generated) plug in here without changes to the processor (OCP).

Contract:

call(target:, base_dir:, options:, context:) -> String
  target   String              path/URL as authored
  base_dir String              absolute path to the including file's dir
  options  CoreModel::IncludeOptions
  context  Hash                recursion state (depth, parent_chain, ...)

Raises Coradoc::IncludeNotFoundError if the target cannot be located.
The processor's missing-file policy decides what to do with that.

This base class is provided for documentation and for is_a? checks. Custom resolvers do NOT need to inherit — duck typing on the call signature is sufficient. ( SPEC 13 uses a bare Object with define_singleton_method, which we support.)

Direct Known Subclasses

Filesystem

Defined Under Namespace

Classes: Filesystem

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.coerce(value, base_dir:, allow_unsafe: false) ⇒ Object

Coerce value into something that quacks like an IncludeResolver.

  • Already-callable objects (respond to :call) are returned as-is.

  • Symbols are interpreted as built-in names: :filesystem, :filesystem_strict (path-traversal protection on).

Parameters:

  • value (Object, nil) —

    the resolver or built-in name

  • base_dir (String) —

    required for built-in filesystem resolvers

  • allow_unsafe (Boolean) (defaults to: false) —

    opt-out of path-traversal protection

Returns:

  • (Object) —

    something callable as a resolver



47
48
49
50
51
52
53
54
 
# File 'lib/coradoc/include_resolver.rb', line 47

def coerce(value, base_dir:, allow_unsafe: false)
  return Filesystem.new(base_dir: base_dir, allow_unsafe: allow_unsafe) if value.nil?

  case value
  when Symbol then coerce_symbol(value, base_dir: base_dir, allow_unsafe: allow_unsafe)
  else value
  end
end

Instance Method Details

#call(target:, base_dir:, options:, context:) ⇒ Object

Raises:

  • (NotImplementedError) 


32
33
34
35
 
# File 'lib/coradoc/include_resolver.rb', line 32

def call(target:, base_dir:, options:, context:)
  raise NotImplementedError,
        "#{self.class} must implement #call(target:, base_dir:, options:, context:)"
end