namespace 1.0 → 1.2

data/README.md

@@ -1,18 +1,24 @@
-Namespaces for ruby <hack>
-==========================
+Namespaces for ruby
+===================
 
-Brings a namespace system to ruby. By loading the .rb files into a temporary
-module, it is possible to avoid polluting the global namespace and select what to import
-in the current module.
+It is an experiment to bring namespaces to ruby. It is not quite clear yet
+why this would be useful, but it can be interesting nonetheless.
 
-This system is inspired by the CommonJS module system, but it was adapted
+This system is inspired by the CommonJS and Python module systems, adapted
 for the ruby particularities.
 
+
+By loading the .rb files into a temporary
+module, it is possible to avoid polluting the global namespace and select what to import
+in the current module.
+
 Feature:
+
+* Compatible with ruby 1.8.7 and 1.9.2 (and others?)
 * Possible to avoid namespace collision on the module level
-* Relative requires (if import is used in the top-level of the file)
 
 Unfeatures:
+
 * uses eval and other nasty ruby hacks
 * classes and namespaces don't mix well because "class X; <<here>>; end"
  is a new context that doesn't inherit from it's parent.
@@ -23,10 +29,27 @@ TODO
 * Handle circular dependencies ?
 * Avoid eval (but I don't see how)
 
+Tricks
+------
+
+A module can emulate the main object behavior by extending itself. In that way,
+it makes it's functions directly available to consumption.
+
+    module X
+      extend self
+      def test
+        "x"
+      end
+      test #=> "x"
+    end
+
+TODO
+
 Bikeshed
 --------
 
 * Should ruby "namespaced" modules have their own $LOAD_PATH and file extensions ?
+* 
 
 Licence
 -------
@@ -34,4 +57,4 @@ Licence
 Public domain
 
 Cheers,
-  Jonas
+  Jonas

data/lib/namespace.rb

@@ -1,92 +1,102 @@
 # Namespaces for ruby.
 #
-# See Namespace#import
+# See Namespace.open and Namespace#import for more details
 module Namespace
   @cache = {}
+  @load_path = $LOAD_PATH
   class << self;
     attr_reader :cache
-    include Namespace
-  end
-  
-  module Def
-    def self.included(mod)
-      eigenclass = (class << mod
-        # Override to not show Namespace::NS for all modules
-        def inspect
-          defined?(@__namespace__) ? "<#{@__namespace__} #{(constants+instance_methods).sort.join(', ')}>" : super
-        end
-        self
-      end)
-      eigenclass.send(:include, mod, Namespace)
-    end
-  end
+    attr_reader :load_path
     
-  #
-  # Loads a file according to the +namespace+ in the context of a module,
-  # and returns that object.
-  #
-  # It's not a Python import, where the namespace is available. What you
-  # get here, is a sort of Sandbox where constants defined in the file are
-  # not polluting the global namespace but available on the returned object.
-  # Since the returned object is a Module, it can be included in the current
-  # module if you're also in the contect of a "Sandbox".
-  #
-  # #import has been chosen because the ruby namespace is already crowded
-  # (require, load and include are already taken)
-  #
-  def import(namespace)
-    namespace = namespace.to_s.gsub(/[\/\\:]+/, ':') # allow symbols
+    # Loads a file according to the +namespace+ in the context of a module,
+    # and returns that object.
+    #
+    # It's not a Python import, where the namespace is available. What you
+    # get here, is a sort of Sandbox where constants defined in the file are
+    # not polluting the global namespace but available on the returned object.
+    # Since the returned object is a Module, it can be included in the current
+    # module if you're also in the context of a "Sandbox".
+    #
+    # #import has been chosen because the ruby namespace is already crowded
+    # (require, load and include are already taken)
+    def open(namespace)
+      namespace = normalize(namespace)
+      
+      # Cache lookup
+      ns = @cache[namespace]
+      return ns if ns
+  
+      # File lookup
+      file_path = namespace.gsub(':', File::SEPARATOR) + '.rb'
+      file = @load_path.inject(nil) do |file, load_path|
+        path = File.join(load_path, file_path)
+        File.exists?(path) ? path : file
+      end
     
-    # @__namespace__ is not available outside of the ruby top-level
-    if defined?(@__namespace__) && namespace[0..0] != ":"
-      # expand namespace
-      namespace = @__namespace__.sub(/:[^:]+$/,'') + ':' + namespace
-    else
-      namespace = ':' + namespace
-    end
-    puts "ns##{namespace}"
+      raise ImportError, "no such file to load -- #{file_path}" unless file
     
-    # Cache lookup
-    ns = Namespace::cache[namespace]
-    return ns if ns
+      file_content = File.read(file)
+      # Pre-process __NAMESPACE__ keyword to act like __FILE__
+      # in know... it's not exactly the same... (eg "__FILE__") but it should do the trick
+      file_content.gsub!('__NAMESPACE__', namespace.inspect)
     
-    file = nil
-    # File lookup
-    file_path = namespace[1..-1].gsub(':', File::SEPARATOR) + '.rb'
-    $LOAD_PATH.each do |path|
-      path = File.join(path, file_path)
-      if File.exists? path
-        file = path
-        break
-      end
-    end
+      ns = Module.new
+      ns.instance_variable_set("@__namespace__", namespace)
+      # Allow calling methods in self, like in global namespace
+      ns.extend(ns)
+      # Adds the #import methods from the DSL
+      ns.extend(Namespace, Namespace::Ext)
+      ns.module_eval(file_content, file)
     
-    raise LoadError, "no such file to load -- #{file_path}" unless file
+      # Cache
+      @cache[namespace] = ns
     
-    file_content = File.read(file_path)
-    # Pre-process __NAMESPACE__ keyword to act like __FILE__
-    # in know... it's not exactly the same... (eg "__FILE__") but it should do the trick
-    file_content.gsub!('__NAMESPACE__', namespace.inspect)
+      return ns
+    end
     
-    # Make sure NS is new (in the cases where the current NS requires another NS)
-    Object.send(:remove_const, :NS) rescue nil
-    # String is on 1 line to make sure line-errors are preserved
-    ns = eval("module NS; @__namespace__ = #{namespace.inspect}; include Namespace::Def; #{file_content}; self; end", TOPLEVEL_BINDING, file)
+    # Transforms a string into a normalized namespace identifier
+    def normalize(namespace)
+      namespace.to_s.sub(/^[\/:\s]*/, '').sub(/[\/:\s]*$/, '').gsub(/[\/\\:]+/, '::')
+    end
     
-    # Cache
-    Namespace::cache[namespace] = ns
+    # Returns the top name of a namespace
+    #
+    # Example: basename("some::deep::namespace") => "namespace"
+    def basename(namespace)
+      normalize(namespace).gsub(/.*::/,'')
+    end
     
-    return ns
-  ensure
-    Object.send(:remove_const, :NS) rescue nil
+    # Raises a ScriptError if the module is included
+    def included(mod)
+      raise ScriptError, "Namespace is not designed to be included, only extended. See #{mod}"
+    end
+    private :included
   end
-end
+  
+  
+  # options[:as] = select the imported name
+  #
+  # THINK: since variable is already returned, is :as necessary?
+  def import(namespace, options={})
+    mod = Namespace::open(namespace)
+
+    name = options[:as] || options['as'] || Namespace.basename(namespace)
+    raise ConflictError, "name `#{name}` is already taken" if method_defined?(name)
+    instance_variable_set("@#{name}", mod)
+    attr_reader name
+    private name
 
-# Make #import available to all
-class Object; include Namespace; end
+    mod
+  end
 
-if __FILE__ == $0
-  require 'irb'
-  require 'irb/completion'
-  IRB.start
+  # Used to override #inspect and #to_s of a namespace
+  module Ext
+    attr_reader :__namespace__
+    alias inspect __namespace__
+    alias to_s __namespace__
+    private :__namespace__
+  end
+  
+  class ImportError < ScriptError; end
+  class ConflictError < ScriptError; end
 end

data/test/fixtures/a.rb

@@ -0,0 +1,18 @@
+def assert(cond, msg=nil)
+  raise AssertionError, (msg || "Assertion Error") unless cond
+end
+
+def assert_equal(obj1, obj2)
+  assert(obj1 == obj2, "#{obj1} and #{obj2} should be equal")
+end
+
+import 'b'
+import 'sub/dir', :as=>'foo'
+
+assert(defined? b::B)
+
+assert_equal("b", b::b)
+assert_equal("dir", foo::dir)
+
+def a; "a"; end
+class A; end

data/test/fixtures/b.rb

@@ -0,0 +1,4 @@
+
+def b; "b"; end
+
+class B; end

data/test/fixtures/dyn_import.rb

@@ -0,0 +1,4 @@
+# this should return module b
+def return_b
+  import('b')
+end

data/test/fixtures/name_conflict.rb

@@ -0,0 +1,5 @@
+# Used to test name conflict
+
+def a; "foo"; end
+
+import :a

data/test/fixtures/sub/dir.rb

@@ -0,0 +1,2 @@
+
+def dir; "dir"; end

data/test/helper.rb

@@ -0,0 +1,2 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'namespace'

data/test/test.rb

@@ -0,0 +1,78 @@
+require File.expand_path('../helper', __FILE__)
+require 'test/unit'
+
+class TestNamespace < Test::Unit::TestCase
+  def setup
+    Namespace.cache.clear
+    Namespace.load_path.replace([File.expand_path('../fixtures', __FILE__)])
+  end
+  
+  def test_basics
+    a = Namespace.open 'a'
+    assert(a.const_defined?(:A))
+    assert(a.method_defined?(:a))
+    
+    assert(a::A.kind_of? Module)
+    assert_equal("a", a.a)
+  end
+  
+  def test_importing_namespace
+    m = Module.new
+    m.extend Namespace
+    ret = m.module_eval do
+      import(:a).class
+    end
+    assert_equal(Module, ret)
+    
+    assert_raise(ScriptError) do
+      m.send(:include, Namespace)
+    end
+  end
+  
+  def test_naming
+    a = Namespace.open 'a'
+    assert_equal('a', a.to_s)
+    assert_equal('a', a.inspect)
+    
+    # THIS test is broken. If I remember well, ruby finds the module name internally
+    # so it can't be overridden.
+    # To fix this, we would have to override the #to_s, #inspect and #name
+    # methods of all the exported modules and classes. Not good :-/
+    #assert_equal('a::A', a::A.name)
+  end
+  
+  def test_naming_conflict
+    assert_raises(Namespace::ConflictError) do
+      Namespace::open('name_conflict')
+    end
+  end
+  
+  def test_normalization
+    norm_test = proc do |output, namespace|
+      assert_equal(output, Namespace::normalize(namespace))
+    end
+    
+    norm_test["simple", "simple"]
+    norm_test["simple", :simple]
+    norm_test["sub::dir", "sub/dir"]
+    norm_test["sub::dir", "sub:dir"]
+    norm_test["sub::dir", "sub::dir"]
+    norm_test["strip", "/strip"]
+    norm_test["strip", "strip/"]
+    norm_test["strip", " ::strip/ "]
+  end
+  
+  def test_basename
+    base_test = proc do |output, namespace|
+      assert_equal(output, Namespace::basename(namespace))
+    end
+    base_test["simple", "simple"]
+    base_test["dir", "sub::dir"]
+  end
+  
+  def test_dynimport
+    a = Namespace.open 'dyn_import'
+    b = Namespace.open 'b'
+    assert_equal(a.return_b, b)
+  end
+end

metadata

@@ -1,12 +1,11 @@
 --- !ruby/object:Gem::Specification 
 name: namespace
 version: !ruby/object:Gem::Version 
-  hash: 15
   prerelease: false
   segments: 
   - 1
-  - 0
-  version: "1.0"
+  - 2
+  version: "1.2"
 platform: ruby
 authors: 
 - Jonas Pfenniger
@@ -14,13 +13,13 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-20 00:00:00 +00:00
+date: 2011-01-05 00:00:00 +00:00
 default_executable: 
 dependencies: []
 
 description: |-
-  This module is a hack that allows you to load specific
-  ruby files in the context of a Module, thus avoiding global namespace 
+  This module is an experiment to bring namespaces to ruby.
+  Each imported file is loaded in it's own context,thus avoiding global namespace 
   pollution
 email: jonas@pfenniger.name
 executables: []
@@ -32,6 +31,13 @@ extra_rdoc_files: []
 files: 
 - README.md
 - lib/namespace.rb
+- test/fixtures/a.rb
+- test/fixtures/b.rb
+- test/fixtures/dyn_import.rb
+- test/fixtures/name_conflict.rb
+- test/fixtures/sub/dir.rb
+- test/helper.rb
+- test/test.rb
 has_rdoc: true
 homepage: https://github.com/zimbatm/namespace.rb
 licenses: []
@@ -46,7 +52,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -55,7 +60,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -65,6 +69,6 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Bringing namespaces to Ruby
+summary: Ruby namespaces experiment
 test_files: []