Class: Capsule
Overview
A Capsule is subclass of Module. It encapsulates an extenal script as a funcitons module.
A module which is an instance of the Capsule class encapsulates in its scope the top-level methods, top-level constants, and instance variables defined in a ruby script file (and its subfiles) loaded by a ruby program. This allows use of script files to define objects that can be loaded into a program in much the same way that objects can be loaded from YAML or Marshal files.
See intro.txt for an overview.
Defined Under Namespace
Classes: MissingFile
Instance Attribute Summary collapse
-
#load_path ⇒ Object
readonly
An array of paths to search for scripts.
-
#loaded_features ⇒ Object
readonly
A hash that maps
filename=>true
for each file that has been required locally by the script. -
#main_file ⇒ Object
readonly
The script file with which the Import was instantiated.
Class Method Summary collapse
-
.load(main_file, options = nil, &block) ⇒ Object
As with #new but will search Ruby’s $LOAD_PATH first.
Instance Method Summary collapse
- #include(*mods) ⇒ Object
- #include_script(file) ⇒ Object
-
#initialize(main_file, options = nil, &block) ⇒ Capsule
constructor
Creates new Capsule, and loads main_file in the scope of the script.
-
#load(file, wrap = false) ⇒ Object
Loads file into the capsule.
-
#load_in_module(file) ⇒ Object
Loads file in this module’s context.Thomas Sawyer Note that
_\FILE\_
and_\LINE\_
work correctly in file. -
#load_path_lookup(feature) ⇒ Object
Lookup feature in load path.
-
#require(feature) ⇒ Object
Analogous to
Kernel#require
. -
#to_s ⇒ Object
:nodoc:.
Constructor Details
#initialize(main_file, options = nil, &block) ⇒ Capsule
Creates new Capsule, and loads main_file in the scope of the script. If a block is given, the script is passed to it before loading from the file, and constants can be defined as inputs to the script.
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 |
# File 'lib/capsule.rb', line 55 def initialize(main_file, =nil, &block) extend self ||= {} @main_file = File.(main_file) @load_path = [:load_path] || [] #@load_path |= [File.dirname(@main_file)] # before or after? @loaded_features = [:loaded_features] || {} # TODO In order to load/require at the instance level. # This needs to be in a separate namespace however # b/c it can interfere with what is expected. #[ :require, :load ].each{ |meth| # m = method(meth) # define_method(meth) do |*args| m.call(*args) end #} module_eval(&block) if block extend self load_in_module(main_file) end |
Instance Attribute Details
#load_path ⇒ Object (readonly)
An array of paths to search for scripts. This has the same semantics as $:
, alias $LOAD_PATH
, excpet that it is local to this script. The path of the current script is added automatically (equivalent to ‘.’)
29 30 31 |
# File 'lib/capsule.rb', line 29 def load_path @load_path end |
#loaded_features ⇒ Object (readonly)
A hash that maps filename=>true
for each file that has been required locally by the script. This has the same semantics as $"
, alias $LOADED_FEATURES
, except that it is local to this script.
34 35 36 |
# File 'lib/capsule.rb', line 34 def loaded_features @loaded_features end |
#main_file ⇒ Object (readonly)
The script file with which the Import was instantiated.
19 20 21 |
# File 'lib/capsule.rb', line 19 def main_file @main_file end |
Class Method Details
.load(main_file, options = nil, &block) ⇒ Object
As with #new but will search Ruby’s $LOAD_PATH first. – Will also try .rb, .so, .dll, et al extensions, like require does. ++
41 42 43 44 45 46 47 48 |
# File 'lib/capsule.rb', line 41 def load(main_file, =nil, &block) file = nil $LOAD_PATH.each do |path| break if file = File.file?(File.join(path, main_file)) #break if file = Dir.glob(File.join(path, main_file)+'{,.rb,.'+DLEXT+'}')[0] end new(file || main_file, =nil, &block) end |
Instance Method Details
#include(*mods) ⇒ Object
167 168 169 170 |
# File 'lib/capsule.rb', line 167 def include(*mods) super extend self end |
#include_script(file) ⇒ Object
156 157 158 159 160 161 162 163 164 |
# File 'lib/capsule.rb', line 156 def include_script(file) include self.class.new(file, :load_path=>load_path, :loaded_features=>loaded_features) rescue Errno::ENOENT => e if /#{file}$/ =~ e. raise MissingFile, e. else raise end end |
#load(file, wrap = false) ⇒ Object
Loads file into the capsule. Searches relative to the local dir, that is, the dir of the file given in the original call to Capsule.load(file)
, loads the file, if found, into this Capsule’s scope, and returns true. If the file is not found, falls back to Kernel.load
, which searches on $LOAD_PATH
, loads the file, if found, into global scope, and returns true. Otherwise, raises LoadError
.
The wrap argument is passed to Kernel.load
in the fallback case, when the file is not found locally.
Typically called from within the main file to load additional sub files, or from those sub files.
– TODO Need to add load_path lookup. ++
106 107 108 109 110 111 |
# File 'lib/capsule.rb', line 106 def load(file, wrap = false) load_in_module(File.join(@dir, file)) true rescue MissingFile super end |
#load_in_module(file) ⇒ Object
Loads file in this module’s context.Thomas Sawyer Note that _\FILE\_
and _\LINE\_
work correctly in file. Called by #load and #require; not normally called directly.
146 147 148 149 150 151 152 153 154 |
# File 'lib/capsule.rb', line 146 def load_in_module(file) module_eval(IO.read(file), File.(file)) rescue Errno::ENOENT => e if /#{file}$/ =~ e. raise MissingFile, e. else raise end end |
#load_path_lookup(feature) ⇒ Object
Lookup feature in load path.
81 82 83 84 85 86 |
# File 'lib/capsule.rb', line 81 def load_path_lookup(feature) paths = File.join('{' + @load_path.join(',') + '}', feature + '{,.rb,.rbs}') files = Dir.glob(paths) match = files.find{ |f| ! @loaded_features.include?(f) } return match end |
#require(feature) ⇒ Object
Analogous to Kernel#require
. First tries the local dir, then falls back to Kernel#require
. Will load a given feature only once.
Note that extensions (*.so, *.dll) can be required in the global scope, as usual, but not in the local scope. (This is not much of a limitation in practice–you wouldn’t want to load an extension more than once.) This implementation falls back to Kernel#require
when the argument is an extension or is not found locally.
– This was using load_in_module rather than include_script. Maybe is still should and one should have to call include_script instead? Think about this. ++
127 128 129 130 131 132 133 134 135 136 137 |
# File 'lib/capsule.rb', line 127 def require(feature) file = load_path_lookup(feature) return super unless file begin @loaded_features[file] = true load_in_module(file) rescue MissingFile @loaded_features[file] = false super end end |
#to_s ⇒ Object
:nodoc:
172 173 174 |
# File 'lib/capsule.rb', line 172 def to_s # :nodoc: "#<#{self.class}:#{main_file}>" end |