Class: Autoloaded::Autoloader

Inherits:
Object
  • Object
show all
Defined in:
lib/autoloaded/autoloader.rb

Overview

Autoloads files in a source directory.

Since:

  • 1.3

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host_binding) ⇒ Autoloader

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Constructs a new Autoloader with the specified host_binding.

Parameters:

  • host_binding (Binding) —

    a value for #host_binding

Raises:

  • (ArgumentError) —

    host_binding is nil

Since:

  • 1.3



30
31
32
33
34
35
 
# File 'lib/autoloaded/autoloader.rb', line 30

def initialize(host_binding)
  raise(::ArgumentError, "can't be nil") if host_binding.nil?

  @host_binding = host_binding
  @specifications = Specifications.new
end

Instance Attribute Details

#host_binding ⇒ Binding (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The source code context in which autoloading is to occur.

Returns:

  • (Binding)

See Also:

Since:

  • 1.3



21
22
23
 
# File 'lib/autoloaded/autoloader.rb', line 21

def host_binding
  @host_binding
end

Instance Method Details

#autoload! ⇒ Array of Array

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Issues autoload statements for source files found in #from. The constants are renamed by #with and #only. The source files are filtered by #except and #only.

Returns:

  • (Array of Array) —

    the arguments passed to each autoload statement made

See Also:

Since:

  • 1.3



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/autoloaded/autoloader.rb', line 52

def autoload!
  result = []
  from_load_pathed_directory.each_source_filename do |source_filename|
    source_basename = ::File.basename(source_filename)
    next if specifications.except.any? { |spec| spec.match source_basename }

    unless specifications.only.empty? ||
           specifications.only.any? { |spec| spec.match source_basename }
      next
    end

    first_match = (specifications.with + specifications.only).inject(nil) do |match, spec|
      match || spec.match(source_basename)
    end
    constant_names = Array(first_match ||
                           Inflection.to_constant_name(source_basename))
    existing_source_filenames = constant_names.collect do |const|
      existing_autoload? const
    end
    if existing_source_filenames.all? { |file| file == source_filename }
      next
    end

    existing_source_filenames.zip(constant_names).each do |file, const|
      if file
        Warning.changing_autoload constant_name:        constant_full_name(const),
                                  old_source_filename:  file,
                                  new_source_filename:  source_filename,
                                  host_source_location: host_source_location
      end
    end

    if existing_source_filenames.compact.empty?
      constant_names.each do |const|
        next unless existing_constant?(const)

        # Don't warn about an existing MyAwesomeGem::VERSION constant since
        # probably it was loaded by a `require 'my_awesome_gem/version'`
        # statement in 'my_awesome_gem.gemspec'.
        next if (const == :VERSION)

        Warning.existing_constant constant_name:        constant_full_name(const),
                                  source_filename:      source_filename,
                                  host_source_location: host_source_location
      end
    end

    constant_names.each do |const|
      establish_autoload const, source_filename
      result << [const, source_filename]
    end
  end
  result
end

#except(*arguments) ⇒ Autoloader

Specifies constants and/or source files not to be autoloaded. Symbol arguments signify the names of constants and String arguments signify the names of source files. You can specify #except multiple times, and its effects are cumulative.

Source file names specified are relative to #from.

Valid arguments include:

  • Symbol values

  • String values

  • Array values comprising Symbol and/or String values

  • Hash values comprising Symbol, String, and/or Array values described above

  • Any combination of the options described above

Returns:

Raises:

  • (RuntimeError) —

    #only already has a specification

See Also:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/autoloaded/autoloader.rb', line 180

[:except, :only, :with].each do |attr|
  define_method attr do |*arguments|
    attr_specs = specifications.send(attr)
    if arguments.empty?
      return attr_specs.collect(&:value)
    end

    attr_specs << Specification.new(*arguments)
    begin
      specifications.validate! attr
    rescue
      attr_specs.pop
      raise
    end

    self
  end
end

#from(value = nil) ⇒ String, Autoloader

The directory from which source files are autoloaded.

Defaults to the directory corresponding to the __FILE__ of #host_binding. For example, if eval('__FILE__', host_binding) evaluates to ‘/absolute/path/to/my_awesome_gem.rb’, then the default value of #from is ‘/absolute/path/to/my_awesome_gem’.

Parameters:

  • value (String) (defaults to: nil) —

    a source directory path; optional

Returns:

  • (String) —

    if value is nil, the source directory

  • (Autoloader) —

    if value is not nil, the Autoloader

Raises:

  • (ArgumentError) —

    value is a relative path

See Also:

Since:

  • 1.3



215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/autoloaded/autoloader.rb', line 215

def from(value=nil)
  if value.nil?
    return (instance_variable_defined?(:@from) && @from && @from.path) ||
           default_from
  end

  # Validate value.
  @from = LoadPathedDirectory.new(value)

  self
end

#only(*arguments) ⇒ Autoloader

Specifies constants and/or source files to be autoloaded exclusively. Symbol arguments signify the names of constants and String arguments signify the names of source files. You can specify #only multiple times, and its effects are cumulative.

Source file names specified are relative to #from.

Valid arguments include:

  • Symbol values

  • String values

  • Array values comprising Symbol and/or String values

  • Hash values comprising Symbol, String, and/or Array values described above, which will autoload specified constants from their associated source files

  • Any combination of the options described above

Returns:

Raises:

  • (RuntimeError) —

    #except already has a specification

See Also:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/autoloaded/autoloader.rb', line 180

[:except, :only, :with].each do |attr|
  define_method attr do |*arguments|
    attr_specs = specifications.send(attr)
    if arguments.empty?
      return attr_specs.collect(&:value)
    end

    attr_specs << Specification.new(*arguments)
    begin
      specifications.validate! attr
    rescue
      attr_specs.pop
      raise
    end

    self
  end
end

#with(*arguments) ⇒ Autoloader

Specifies constants and/or source files to be autoloaded whose names may have unpredictable spellings, stylization, or organization. Symbol arguments signify the names of constants and String arguments signify the names of source files. You can specify #with multiple times, and its effects are cumulative.

Source file names specified are relative to #from.

Valid arguments include:

  • Symbol values

  • Array values comprising Symbol values

  • Hash values comprising Symbol, String, and/or Array values described above, which will autoload specified constants from their associated source files

  • Any combination of the options described above

Returns:

See Also:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/autoloaded/autoloader.rb', line 180

[:except, :only, :with].each do |attr|
  define_method attr do |*arguments|
    attr_specs = specifications.send(attr)
    if arguments.empty?
      return attr_specs.collect(&:value)
    end

    attr_specs << Specification.new(*arguments)
    begin
      specifications.validate! attr
    rescue
      attr_specs.pop
      raise
    end

    self
  end
end