capsule 1.0.0 → 1.1.0

data/COPYING.rdoc

@@ -0,0 +1,24 @@
+= COPYRIGHT NOTICES
+
+== Capsule
+
+Copyright (C)2007 Thomas Sawyer
+
+Unless otherwise agreed upon by the copyright holder this software is
+made available under the terms of the GNU Affero General Public License
+(see AGPL3.txt.)
+
+(http://rubyworks.github.com/capsule)
+
+
+== Script
+
+Capsule is a derivation of Joel VanderWerf's Script library.
+
+Usable under the Ruby license. 
+
+Copyright (C)2004 Joel VanderWerf.
+
+Questions to mailto:vjoel@users.sourceforge.net.
+
+(http://redshift.sourceforge.net/script/)

data/HISTORY.rdoc

@@ -0,0 +1,27 @@
+= RELEASE HISTORY
+
+== 1.1.0 / 2011-05-12
+
+This release makes two small enhancements to the Capsule class.
+It will automatically try `.rb` extension of script names that
+lack an extension and it now provides an `:extend` option which
+can be set to `false` to deactive a capsules sef extension
+(`extend self`).
+
+Changes:
+
+* Search for scripts with  common ruby extensions.
+* Add :extend option to control self extension.
+
+
+== 1.0.0 / 2009-07-01
+
+This is the initial stand-alone release of Capsule,
+spun-off from Ruby Facets.
+
+Changes:
+
+* 1 Major Enhancement
+
+  * Happy Birthday!
+

data/README.rdoc

@@ -0,0 +1,154 @@
+= Capsule
+
+
+== Description
+
+Capsule is a subclass of 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 (and its dependent files)
+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 Marshaled files. There is also an autoimport method which functions
+like Ruby's autoload but based on is Capsule.load.
+
+
+== Resources
+
+* home: http://rubyworks.github.com/capsule
+* work: http://github.com/rubyworks/capsule
+* mail: http://groups.google.com/group/rubyworks-mailinglist
+
+
+== Synopsis
+
+To encapsulate a script in a Capsule:
+
+  myscript = Capsule.new('myscript.rb')
+
+If the script is in Ruby's $LOAD_PATH, then you can use +Capsule.load+.
+
+  myscript = Capsule.load('myscript.rb')
+
+Here is an example:
+
+  # myscript.rb
+
+  VALUE = [1,2,3]
+
+  def run
+    puts "#{self} is running."
+  end
+
+And the encapsulating program:
+
+  # program.rb:
+
+  require 'capsule'
+
+  myscript = Capsule.load("myscript.rb")
+
+  p myscript::VALUE
+
+  myscript.run
+
+Running `program.rb` will result in:
+
+  $ ruby program.rb
+  [1, 2, 3]
+  #<Capsule:myscript.rb> is running.
+
+
+== Usage
+
+Capsule modules are instantiated with <tt>Capsule.new(main_file)</tt> or the alias
+<tt>Capsule.load(main_file)</tt>. All the top-level constants and top-level
+methods that are defined in the +main_file+ and its dependent local files (see
+below) are scoped in the same Capsule module, and are thereby available to the
+calling program.
+
+The +main_file+ can load or require other files with +load+ and +require+, as
+usual. These methods, in the Capsule context, add some behavior to the +Kernel+
++load+ and +require+ methods: <tt>Capsule#load</tt> and <tt>Capsule#require</tt>
+first search for files relative to the +main_file+'s dir. Files loaded in this
+way ("dependent local files") are treated like the script file itself: top-level
+definitions are added to the script module that is returned by +load+ or
++require+.
+
+Both <tt>Capsule#load</tt> and <tt>Capsule#require</tt> fall back to the Kernel
+versions if the file is not found locally. Hence, other ruby libraries can be
+loaded and required as usual, assuming their names do not conflict with local
+file names. Definitions from those files go into the usual scope (typically
+global). The normal ruby +load+ and +require+ behavior can be forced by calling
+<tt>Kernel.load</tt> and <tt>Kernel.require</tt>.
+
+A Capsule immitates the way the top-level ruby context works, so a ruby file that
+was originally intended to be run from the top level, defining top-level
+constants and top-level methods, can also be run as a Capsule, and its top-level
+constants and top-level methods are wrapped in the script's scope. The
+difference between this behavior and simply wrapping the loaded definitions in
+an _anonymous_ module using <tt>Kernel.load(main_file, true)</tt> is that the
+top-level methods and top-level constants defined in the script are accessible
+using the Capsule instance.
+
+The top-level definitions of a Capsule can be accessed after it has been
+loaded, as follows:
+
+<tt>script.meth</tt>
+
+- Call a method defined using <tt>def meth</tt> or <tt>def self.meth</tt> in
+  the script file.
+
+<tt>script::K</tt>
+
+- Access a class, module, or constant defined using <tt>K = val</tt> in the
+  script file.
+
+An "input" can be passed to the script before loading. Simply call Capsule.new
+(or Capsule.load) with a block. The block is passed a single argument, the
+Capsule module, and executed before the files are loaded into the Capsule's
+scope. Setting a constant in this block makes the constant available to the
+script during loading. For example:
+
+  script = Capsule.load("my-script.rb") { |capsule| capsule::INPUT = 3 }
+
+Note that all methods defined in the script file are both instance methods of
+the module and methods of the module instance (the effect of
+<tt>Module#module_function</tt>). So <tt>include</tt>-ing a Capsule module in a
+class will give instances of the class all the methods and constants defined in
+the script, and they will reference the instance's instance variables,
+rather than the Capsule module's instance variables.
+
+The Capsule class was inspired by Nobu Nokada's suggestion in
+http://ruby-talk.org/62727, in a thread (started in http://ruby-talk.org/62660)
+about how to use ruby script files as specifications of objects.
+
+
+== Installation
+
+To install with RubyGems simply open a console and type:
+
+  gem install capsule
+
+Local installation requires Setup.rb (gem install setup),
+then download the tarball package and type:
+
+  tar -xvzf capsule-1.0.0.tgz
+  cd capsule-1.0.0
+  sudo setup.rb all
+
+Windows users use 'ruby setup.rb all'.
+
+
+== Legal
+
+(AGPL 3 License)
+
+Copyright (c) 2007 Thomas Sawyer
+Copyright (c) 2004 Joel VanderWerf
+
+Capsule is based on Joel VanderWerf's Script library.
+
+Unless otherwise agreed upon by the copyright holder, this program is
+ditributed under the terms of the GNU Affero General Public License v3.
+
+See COPYING.rdoc file for details.

data/lib/capsule.rb

@@ -1,8 +1,6 @@
 #require 'rbconfig'
+require 'capsule/autoimport'
 
-# 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
@@ -15,7 +13,13 @@ class Capsule < Module
 
   #DLEXT = Config::CONFIG['DLEXT']
 
-  # The script file with which the Import was instantiated.
+  # Ruby script extensions to automatically try when searching for
+  # a script on the load_path.
+
+  SUFFIXES = ['.rb', '.rbs'] #, '.rbw', '.so', '.bundle', '.dll', '.sl', '.jar']
+
+  # The script file with which the import was instantiated.
+
   attr_reader :main_file
 
   # The directory in which main_file is located, and relative to which
@@ -23,29 +27,29 @@ class Capsule < Module
   #attr_reader :dir
 
   # An array of paths to search for scripts. This has the same
-  # semantics as <tt>$:</tt>, alias <tt>$LOAD_PATH</tt>, excpet
+  # semantics as <tt>$:</tt>, alias <tt>$LOAD_PATH</tt>, except
   # that it is local to this script. The path of the current
-  # script is added automatically (equivalent to '.')
+  # script is added automatically.
+
   attr_reader :load_path
 
   # A hash that maps <tt>filename=>true</tt> for each file that has been
   # required locally by the script. This has the same semantics as <tt>$"</tt>,
   # alias <tt>$LOADED_FEATURES</tt>, except that it is local to this script.
+
   attr_reader :loaded_features
 
-  class << self
-    # As with #new but will search Ruby's $LOAD_PATH first.
-    #--
-    # Will also try .rb, .so, .dll, et al extensions, like require does.
-    #++
-    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)
+  # As with #new but will search Ruby's $LOAD_PATH first.
+  # This will also try `.rb` extensions, like require does.
+
+  def self.load(main_file, options=nil, &block)
+    file = nil
+    $LOAD_PATH.each do |path|
+      file = File.join(path, main_file)
+      break if file = File.file?(file)
+      break if file = Dir.glob(file + '{' + SUFFIXES.join(',') + '}').first
     end
+    new(file || main_file, options=nil, &block)
   end
 
   # Creates new Capsule, and loads _main_file_ in the scope of the script. If a
@@ -53,25 +57,24 @@ class Capsule < Module
   # constants can be defined as inputs to the script.
 
   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
-    #}
+    @extend          = true  # default
+    @extend          = options[:extend] if options.key?(:extend)
+
+    ## add script's path to load_path
+    ## TODO: should we be doing this?
+    @load_path |= [File.dirname(@main_file)]
+
+    ## if @extend (the default) module extends itself
+    extend self if @extend
 
     module_eval(&block) if block
-    extend self
 
     load_in_module(main_file)
   end
@@ -79,7 +82,7 @@ class Capsule < Module
   # Lookup feature in load path.
 
   def load_path_lookup(feature)
-    paths = File.join('{' + @load_path.join(',') + '}', feature + '{,.rb,.rbs}')
+    paths = File.join('{' + @load_path.join(',') + '}', feature + '{' + SUFFIXES + '}')
     files = Dir.glob(paths)
     match = files.find{ |f| ! @loaded_features.include?(f) }
     return match
@@ -98,13 +101,11 @@ class Capsule < Module
   #
   # Typically called from within the main file to load additional sub files, or
   # from those sub files.
-  #
-  #--
-  # TODO Need to add load_path lookup.
-  #++
 
   def load(file, wrap = false)
-    load_in_module(File.join(@dir, file))
+    file = load_path_lookup(feature)
+    return super unless file
+    load_in_module(file) #File.join(@dir, file))
     true
   rescue MissingFile
     super
@@ -120,8 +121,7 @@ class Capsule < Module
   # 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.
+  # TODO: Should this be using #include_script instead?
   #++
 
   def require(feature)
@@ -136,25 +136,40 @@ class Capsule < Module
     end
   end
 
-  # Raised by #load_in_module, caught by #load and #require.
-  class MissingFile < LoadError; end
+  # Checks the class of each +mods+. If a String, then calls #include_script,
+  # otherwise behaves like normal #include.
 
-  # Loads _file_ in this module's context.Thomas Sawyer Note that <tt>\_\_FILE\_\_</tt> and
-  # <tt>\_\_LINE\_\_</tt> work correctly in _file_.
-  # Called by #load and #require; not normally called directly.
+  def include(*mods)
+    mods.reverse_each do |mod|
+      case mod
+      when String
+        include_script(mod)
+      else
+        super(mod)
+        extend self if @extend
+      end
+    end
+  end
 
-  def load_in_module(file)
-    module_eval(IO.read(file), File.expand_path(file))
+  # Create a new Capsule for a script and include it into the current capsule.
+
+  def include_script(file)
+    include self.class.new(file, :load_path=>load_path, :loaded_features=>loaded_features, :extend=>false)
   rescue Errno::ENOENT => e
     if /#{file}$/ =~ e.message
       raise MissingFile, e.message
     else
       raise
     end
+    extend self if @extend
   end
 
-  def include_script(file)
-    include self.class.new(file, :load_path=>load_path, :loaded_features=>loaded_features)
+  # Loads _file_ in this module's context. Note that <tt>\_\_FILE\_\_</tt> and
+  # <tt>\_\_LINE\_\_</tt> work correctly in _file_.
+  # Called by #load and #require; not normally called directly.
+
+  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
@@ -163,59 +178,15 @@ class Capsule < Module
     end
   end
 
-  #
-  def include(*mods)
-    super
-    extend self
-  end
+  # Give inspection of Capsule with script file name.
 
-  def to_s # :nodoc:
+  def inspect # :nodoc:
     "#<#{self.class}:#{main_file}>"
   end
 
-end
-
-# TODO Is autoimport bets name for this?
-
-class Module
-
-  const_missing_definition_for_autoimport = lambda do
-    #$autoimport_activated = true
-    alias const_missing_before_autoimport const_missing
-
-    def const_missing(sym) # :nodoc:
-      filename = @autoimport && @autoimport[sym]
-      if filename
-        mod = Import.load(filename)
-        const_set sym, mod
-      else
-        const_missing_before_autoimport(sym)
-      end
-    end
-  end
+  # Raised by #load_in_module, caught by #load and #require.
 
-  # When the constant named by symbol +mod+ is referenced, loads the script
-  # in filename using Capsule.load and defines the constant to be equal to the
-  # resulting Capsule module.
-  #
-  # Use like Module#autoload--however, the underlying opertation is #load rather
-  # than #require, because scripts, unlike libraries, can be loaded more than
-  # once. See examples/autoscript-example.rb
+  class MissingFile < ::LoadError; end
 
-  define_method(:autoimport) do |mod, file|
-    if @autoimport.empty? #unless $autoimport_activated
-      const_missing_definition_for_autoimport.call
-    end
-    (@autoimport ||= {})[mod] = file
-  end
 end
 
-
-module Kernel
-
-  # Calls Object.autoimport
-  def autoimport(mod, file)
-    Object.autoimport(mod, file)
-  end
-
-end