Permalink
Browse files

Initial import.

  • Loading branch information...
soveran committed Jul 26, 2010
0 parents commit 163a0480a83d610b3a7301d819632a5eab2ccce8
Showing with 305 additions and 0 deletions.
  1. +1 −0 .gitignore
  2. +19 −0 LICENSE
  3. +128 −0 README.markdown
  4. +5 −0 Rakefile
  5. +18 −0 cargo.gemspec.erb
  6. +25 −0 lib/cargo.rb
  7. +45 −0 test/cargo_test.rb
  8. +19 −0 test/foo-1.0.0.rb
  9. +19 −0 test/foo-2.0.0.rb
  10. +26 −0 test/helper.rb
@@ -0,0 +1 @@
+/pkg
19 LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2010 Michel Martens & Damian Janowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
@@ -0,0 +1,128 @@
+Cargo
+=====
+
+Require libraries without cluttering your namespace.
+
+Description
+-----------
+
+Consider these two versions of the same library:
+
+ # foo-1.0.0.rb
+ class Foo
+ VERSION = "1.0.0"
+ end
+
+ # foo-2.0.0.rb
+ class Foo
+ VERSION = "2.0.0"
+ end
+
+If you want to use both of them in your application, `require` and
+`load` will be of little help. Consider what happens when you require
+both libraries:
+
+ >> require "foo-1.0.0"
+ => true
+ >> require "foo-2.0.0"
+ => true
+ >> Foo::VERSION
+ => "2.0.0"
+
+As both files are opening the same class, there's no way for you to use
+them independently.
+
+Cargo solves that problem in a very simple way:
+
+ >> Foo1 = import("foo-1.0.0")
+ => #<Module:0x000001009ffa28>::Foo
+ >> Foo2 = import("foo-2.0.0")
+ => #<Module:0x000001009f2828>::Foo
+ >> Foo1::VERSION
+ => "1.0.0"
+ >> Foo2::VERSION
+ => "2.0.0"
+
+How does it work?
+-----------------
+
+The command `Kernel.load` accepts a second parameter, which value is
+`false` by default. When the passed value is `true`, the script is
+executed under an anonymous module, protecting the calling program's
+global namespace. No local variables in the loaded file are propagated
+to the loading environment.
+
+By using a global module as a temporal storage, it is possible to
+transfer a value from the anonymous module to the caller program.
+
+Usage
+-----
+
+After requiring `cargo` in the calling program, two methods will
+be available: `import` and `export`. Both use the global module
+`Cargo` for temporal storage.
+
+This is how you will use it in the calling program:
+
+ $ cat calling_program.rb
+ require "cargo"
+
+ MyFoo = import("foo")
+
+
+And for that to work, the imported library should look like this:
+
+ $ cat foo.rb
+ class Foo
+ VERSION = "1.0.0"
+ end
+
+ export(Foo)
+
+Note that you can only export one value per file. Multiple calls to
+`export` just change the value to be exported. This constraint is in
+place in order to make for a simple and clean implementation.
+
+How to prepare your library for Cargo
+-------------------------------------
+
+In your library entry point, you need to use `export` and provide a value. As
+the `export` method won't be available unless the caller is using
+Cargo, you can make a conditional call:
+
+ export(Foo) if defined?(export)
+
+If your library has just one file, that single line will make your code
+ready to be imported. Otherwise, you will need to require Cargo and
+make sure you don't mix import with require for local files.
+
+Installation
+------------
+
+ $ gem install cargo
+
+License
+-------
+
+Copyright (c) 2010 Michel Martens & Damian Janowski
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,5 @@
+task :test do
+ system "cd test && ruby cargo_test.rb"
+end
+
+task :default => :test
@@ -0,0 +1,18 @@
+<% require "./lib/cargo" -%>
+Gem::Specification.new do |s|
+ s.name = "cargo"
+ s.version = "<%= Cargo::VERSION %>"
+ s.summary = "Require libraries without cluttering your namespace."
+ s.description = "Cargo lets you use different versions of the same library by implementing two simple commands, which let you load programs without messing with your namespace."
+ s.authors = ["Michel Martens", "Damian Janowski"]
+ s.email = ["michel@soveran.com", "djanowski@dimaion.com"]
+ s.homepage = "http://github.com/soveran/cargo"
+ s.files = <%= Dir[
+ "LICENSE",
+ "README.markdown",
+ "Rakefile",
+ "lib/**/*.rb",
+ "*.gemspec",
+ "test/*.*"
+ ].inspect %>
+end
@@ -0,0 +1,25 @@
+module Cargo
+ VERSION = "0.0.1"
+
+ def self.import(file)
+ unless file.match(/\.rb$/)
+ file = "#{file}.rb"
+ end
+
+ load(file, true)
+
+ @cargo
+ end
+
+ def self.export(cargo)
+ @cargo = cargo
+ end
+end
+
+def import(file)
+ Cargo.import(file)
+end
+
+def export(cargo)
+ Cargo.export(cargo)
+end
@@ -0,0 +1,45 @@
+# encoding: UTF-8
+
+require File.join(File.dirname(__FILE__), "helper")
+require "ruby-debug"
+
+setup do
+ unless defined?(Foo1)
+ Foo1 = import("foo-1.0.0")
+ end
+
+ unless defined?(Foo2)
+ Foo2 = import("foo-2.0.0")
+ end
+end
+
+test "Foo is not available" do
+ assert nil == defined?(Foo)
+end
+
+test "Foo1 is a class" do
+ assert Class == Foo1.class
+end
+
+test "methods are available" do
+ assert "Hello" == Foo1.new.bar
+end
+
+test "methods on nested classes are available" do
+ assert "Hello" == Foo1::Bar.new.baz
+ assert "Hello" == Foo1::Bar::Baz.new.qux
+end
+
+test "nested classes are not available in the top level" do
+ begin
+ Bar::Baz.new.qux
+ rescue
+ assert NameError == $!.class
+ end
+end
+
+test "Foo2 should be possible" do
+ assert "Hello" == Foo2.new.bar
+end
+
+puts " ✔ All tests passed"
@@ -0,0 +1,19 @@
+class Foo
+ class Bar
+ class Baz
+ def qux
+ "Hello"
+ end
+ end
+
+ def baz
+ "Hello"
+ end
+ end
+
+ def bar
+ "Hello"
+ end
+end
+
+export(Foo) if defined?(export)
@@ -0,0 +1,19 @@
+class Foo
+ class Bar
+ class Baz
+ def qux
+ "Hello"
+ end
+ end
+
+ def baz
+ "Hello"
+ end
+ end
+
+ def bar
+ "Hello"
+ end
+end
+
+export(Foo) if defined?(export)
@@ -0,0 +1,26 @@
+# encoding: UTF-8
+
+require File.join(File.dirname(__FILE__), "..", "lib", "cargo")
+
+AssertionFailed = Class.new(StandardError)
+
+def assert(value)
+ return if value
+
+ file, line = caller[0].split(":")
+ code = File.readlines(file)[line.to_i - 1]
+
+ puts "#{code.strip}"
+ puts " #{file}:#{line}"
+ exit(1)
+end
+
+def setup(&block)
+ @_setup = block
+end
+
+def test(name = nil, &block)
+ @_test = name
+
+ block.call(@_setup.call)
+end

0 comments on commit 163a048

Please sign in to comment.