Module: AnonymousLoader — Documentation by YARD 0.9.44

# Module: AnonymousLoader

Defined in:
  lib/anonymous_loader.rb,
  lib/anonymous_loader/version.rb

## Overview

Loads Ruby source under anonymous modules to avoid top-level namespace collisions.

## Defined Under Namespace

Modules: Version Classes: Error, FileNotFoundError, PathRequest, VersionMismatchError, VersionRequest

## Constant Summary collapse

VERSION =

Traditional Constant Location

      Version::VERSION

## Class Method Summary collapse

- .load(files:, root: nil, **_options) ⇒ Module

  Evaluate one or more Ruby files inside a fresh anonymous module.

- .load_path(**options) ⇒ Module

  Resolve and anonymously load a single file.

- .resolve_path(**options) ⇒ String

  Resolve a file from an explicit path, RubyGems metadata, or $LOAD_PATH.

## Class Method Details

### .load(files:, root: nil, **_options) ⇒ `Module`

Evaluate one or more Ruby files inside a fresh anonymous module.

The source’s natural constant nesting is preserved inside the anonymous
module. For example, a file declaring `module Auth; module Sanitizer; end`
becomes `anonymous_namespace::Auth::Sanitizer`, not `Object::Auth`.

Parameters:

- files (`String`, `Array<String>`) —

  absolute paths, or paths relative to root

- root (`String`, `nil`) (defaults to: `nil`) —

  optional root for relative paths

Returns:

- (`Module`) —

  anonymous namespace containing the evaluated source

    33
    34
    35
    36
    37
    38
    39
    40
    # File 'lib/anonymous_loader.rb', line 33

    def load(files:, root: nil, **_options)
      namespace = Module.new
      Array(files).each do |file|
        path = expand_file(file, root)
        namespace.module_eval(File.read(path), path, 1)
      end
      namespace
    end

### .load_path(**options) ⇒ `Module`

Resolve and anonymously load a single file.

Parameters:

- options (`Hash`) —

  resolver options

Options Hash (`**options`):

- :path (`String`, `nil`) —

  explicit file path

- :gem_name (`String`, `nil`) —

  gem name used for RubyGems lookup

- :require_path (`String`, `nil`) —

  path under lib, also used for $LOAD_PATH lookup

- :version_requirement (`String`, `Gem::Requirement`, `nil`) —

  accepted gem version

- :version_file (`String`, `nil`) —

  file next to require_path’s load root that declares VERSION

Returns:

- (`Module`) —

  anonymous namespace containing the evaluated source

    51
    52
    53
    # File 'lib/anonymous_loader.rb', line 51

    def load_path(**options)
      load(files: resolve_path(**options))
    end

### .resolve_path(**options) ⇒ `String`

Resolve a file from an explicit path, RubyGems metadata, or $LOAD_PATH.

RubyGems metadata is preferred when available. The $LOAD_PATH fallback
supports Bundler standalone setups where files are loadable but the
dependency is absent from Gem.loaded_specs and GEM_PATH.

Parameters:

- options (`Hash`) —

  resolver options

Options Hash (`**options`):

- :path (`String`, `nil`) —

  explicit file path

- :gem_name (`String`, `nil`) —

  gem name used for RubyGems lookup

- :require_path (`String`, `nil`) —

  path under lib, also used for $LOAD_PATH lookup

- :version_requirement (`String`, `Gem::Requirement`, `nil`) —

  accepted gem version

- :version_file (`String`, `nil`) —

  file next to require_path’s load root that declares VERSION

Returns:

- (`String`) —

  absolute path to the resolved file

Raises:

- (`FileNotFoundError`)

    68
    69
    70
    71
    72
    73
    74
    # File 'lib/anonymous_loader.rb', line 68

    def resolve_path(**options)
      request = path_request(options)
      resolved = explicit_path_for(request) || resolve_from_gemspec(request) || resolve_from_load_path(request)
      return resolved if resolved

      raise FileNotFoundError, unresolved_message(request)
    end