Class: Capsule

Inherits:
Module show all
Defined in:
lib/more/facets/capsule.rb

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

Constant Summary

Constants inherited from Module

Module::METHOD_TYPES

Constants included from Glue::Validation::ClassMethods

Glue::Validation::ClassMethods::LENGTHS

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Module

#*, #+, #-, #abstract, #alias_accessor!, #alias_reader!, #alias_setter, #alias_validator, #alias_writer!, #all_instance_methods, #ancestor?, #ann, #ann!, #annotations, #append_features, #append_features_without_class_extension, #append_features_without_classmethods, #attr, #attr_accessor!, #attr_reader!, #attr_setter, #attr_validator, #attr_writer!, #basename, #by_name, #class_def, #class_methods, #classified_attributes, #clone_removing, #clone_renaming, #clone_using, #conflict?, #define_dependency, #depend, #dependencies, #dirname, #equate_on, #extend, #extend_without_parameters, #heritage, #include_as, #include_function_module, #include_without_parameters, #instance_interface, #instance_method!, #instance_method_defined?, #integrate, #is, #is?, #let, #memoize, #method_overloads, #method_space, #mixin_parameters, #modspace, #module_load, #module_method_defined?, #module_require, #nesting, #on_included, #overload, #prepend, #private_conflict?, #protected_conflict?, #public_conflict?, #revisal, #setting, #sort_on, #wrap_method

Methods included from Glue::Validation::ClassMethods

#validate_format, #validate_inclusion, #validate_length, #validate_numeric, #validate_value

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.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/more/facets/capsule.rb', line 88

def initialize(main_file, options=nil, &block)
  extend self

  options ||= {}

  @main_file       = File.expand_path(main_file)
  @load_path       = options[:load_path] || []
  #@load_path |= [File.dirname(@main_file)]  # before or after?
  @loaded_features = options[: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 ‘.’)



62
63
64
 
# File 'lib/more/facets/capsule.rb', line 62

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.



67
68
69
 
# File 'lib/more/facets/capsule.rb', line 67

def loaded_features
  @loaded_features
end

#main_file ⇒ Object (readonly)

The script file with which the Import was instantiated.



52
53
54
 
# File 'lib/more/facets/capsule.rb', line 52

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. ++



74
75
76
77
78
79
80
81
 
# File 'lib/more/facets/capsule.rb', line 74

def load(main_file, options=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, options=nil, &block)
end

Instance Method Details

#include(*mods) ⇒ Object 



200
201
202
203
 
# File 'lib/more/facets/capsule.rb', line 200

def include(*mods)
  super
  extend self
end

#include_script(file) ⇒ Object 



189
190
191
192
193
194
195
196
197
 
# File 'lib/more/facets/capsule.rb', line 189

def include_script(file)
  include self.class.new(file, :load_path=>load_path, :loaded_features=>loaded_features)
rescue Errno::ENOENT => e
  if /#{file}$/ =~ e.message
    raise MissingFile, e.message
  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. ++



139
140
141
142
143
144
 
# File 'lib/more/facets/capsule.rb', line 139

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. Note that _\FILE\_ and _\LINE\_ work correctly in file. Called by #load and #require; not normally called directly.



179
180
181
182
183
184
185
186
187
 
# File 'lib/more/facets/capsule.rb', line 179

def load_in_module(file)
  module_eval(IO.read(file), File.expand_path(file))
rescue Errno::ENOENT => e
  if /#{file}$/ =~ e.message
    raise MissingFile, e.message
  else
    raise
  end
end

#load_path_lookup(feature) ⇒ Object

Lookup feature in load path.



114
115
116
117
118
119
 
# File 'lib/more/facets/capsule.rb', line 114

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. ++



160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/more/facets/capsule.rb', line 160

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:



205
206
207
 
# File 'lib/more/facets/capsule.rb', line 205

def to_s # :nodoc:
  "#<#{self.class}:#{main_file}>"
end