bootstrapping and little else

middleclass.lua

@@ -0,0 +1,136 @@
+-----------------------------------------------------------------------------------------------------------------------
+-- middleclass.lua - v2.0 (2011-08)
+-- Enrique Garcia Cota - enrique.garcia.cota [AT] gmail [DOT] com
+-- Based on YaciCode, from Julien Patte and LuaObject, from Sebastien Rocca-Serra
+-----------------------------------------------------------------------------------------------------------------------
+
+local _nilf = function() end -- empty function
+
+local _classes = setmetatable({}, {__mode = "k"})
+
+function checkClass(theClass, methodName)
+  assert(_classes[theClass], "Make sure that you are using 'Class:" .. methodName .. "' instead of 'Class." .. methodName .. "')")
+end
+
+Object = {
+  name = "Object", __mixins = {}, __classDict = {}, __instanceDict = {},
+  __metamethods = { '__add', '__call', '__concat', '__div', '__le', '__lt', 
+                    '__mod', '__mul', '__pow', '__sub', '__tostring', '__unm' }
+}
+
+setmetatable(Object, { 
+  __tostring = function() return "class Object" end
+})
+
+function Object:allocate()
+  checkClass(self, 'allocate')
+  return setmetatable({ class = self }, self.__instanceDict)
+end
+
+--[[
+ -- register Object on the list of classes.
+
+-- creates the instance based of the class, but doesn't initialize it
+function Object.allocate(theClass)
+  
+  return setmetatable({ class = theClass }, theClass.__classDict)
+end
+
+-- both creates and initializes an instance
+function Object.new(theClass, ...)
+  local instance = theClass:allocate()
+  instance:initialize(...)
+  return instance
+end
+
+]]
+
+_classes[Object] = true
+
+function Object:subclass(name)
+  local theSubClass = { name = name, superclass = self, __classDict = {}, __mixins={} }
+  return theSubClass
+end
+
+--[[
+
+-- creates a subclass
+function Object.subclass(theClass, name)
+  assert(_classes[theClass], "Use Class:subclass instead of Class.subclass")
+  assert( type(name)=="string", "You must provide a name(string) for your class")
+
+  local theSubClass = { name = name, superclass = theClass, __classDict = {}, __mixins={} }
+  
+  local dict = theSubClass.__classDict   -- classDict contains all the [meta]methods of the class
+  dict.__index = dict                    -- It "points to itself" so instances can use it as a metatable.
+  local superDict = theClass.__classDict -- The superclass' classDict
+
+  setmetatable(dict, superDict) -- when a method isn't found on classDict, 'escalate upwards'.
+
+  setmetatable(theSubClass, {
+    __index = dict,                              -- look for stuff on the dict
+    __newindex = function(_, methodName, method) -- ensure that __index isn't modified by mistake
+        assert(methodName ~= '__index', "Can't modify __index. Include middleclass-extras.Indexable and use 'index' instead")
+        rawset(dict, methodName , method)
+      end,
+    __tostring = function() return ("class ".. name) end,      -- allows tostring(MyClass)
+    __call = function(_, ...) return theSubClass:new(...) end  -- allows MyClass(...) instead of MyClass:new(...)
+  })
+
+  for _,mmName in ipairs(theClass.__metamethods) do -- Creates the initial metamethods
+    dict[mmName]= function(...)           -- by default, they just 'look up' for an implememtation
+      local method = superDict[mmName]    -- and if none found, they throw an error
+      assert( type(method)=='function', tostring(theSubClass) .. " doesn't implement metamethod '" .. mmName .. "'" )
+      return method(...)
+    end
+  end
+
+  theSubClass.initialize = function(instance,...) theClass.initialize(instance, ...) end
+  _classes[theSubClass]= true -- registers the new class on the list of _classes
+  theClass:subclassed(theSubClass)   -- hook method. By default it does nothing
+
+  return theSubClass
+end
+
+-- Mixin extension function - simulates very basically ruby's include. Receives a table table, probably with functions.
+-- Its contents are copied to theClass, with one exception: the included() method will be called instead of copied
+function Object.include(theClass, mixin, ... )
+  assert(_classes[theClass], "Use class:include instead of class.include")
+  assert(type(mixin)=='table', "mixin must be a table")
+  for methodName,method in pairs(mixin) do
+    if methodName ~="included" then theClass[methodName] = method end
+  end
+  if type(mixin.included)=="function" then mixin:included(theClass, ... ) end
+  theClass.__mixins[mixin] = mixin
+  return theClass
+end
+
+-- Returns true if aClass is a subclass of other, false otherwise
+function subclassOf(other, aClass)
+  if not _classes[aClass] or not _classes[other] then return false end
+  if aClass.superclass==nil then return false end -- aClass is Object, or a non-class
+  return aClass.superclass == other or subclassOf(other, aClass.superclass)
+end
+
+-- Returns true if obj is an instance of aClass (or one of its subclasses) false otherwise
+function instanceOf(aClass, obj)
+  if not _classes[aClass] or type(obj)~='table' or not _classes[obj.class] then return false end
+  if obj.class==aClass then return true end
+  return subclassOf(aClass, obj.class)
+end
+
+-- Returns true if the mixin has already been included on a class (or a superclass)
+function includes(mixin, aClass)
+  if not _classes[aClass] then return false end
+  if aClass.__mixins[mixin]==mixin then return true end
+  return includes(mixin, aClass.superclass)
+end
+
+-- Creates a new class named 'name'. Uses Object if no baseClass is specified.
+function class(name, baseClass, ...)
+  baseClass = baseClass or Object
+  return baseClass:subclass(name, ...)
+end
+
+]]
+

spec/middleclass-spec.lua

@@ -0,0 +1,610 @@
+require 'middleclass'
+
+context( 'Object', function()
+
+  context( 'name', function()
+    test('is correctly set', function()
+      assert_equal(Object.name, 'Object')
+    end)
+  end)
+
+  context('__metamethods', function()
+    local metamethods = { 'add', 'call', 'concat', 'div', 'le', 'lt',
+                          'mod', 'mul', 'pow', 'sub', 'tostring', 'unm'
+    }
+    test('are correctly set', function()
+      for i,m in ipairs(metamethods) do
+        assert_equal('__' .. m, Object.__metamethods[i])
+      end
+    end)
+  end)
+
+  context('bootstrapping', function()
+    test('Object has two dictionaries and mixins properly set up', function()
+      for _,m in pairs{'__mixins', '__classDict', '__instanceDict'} do
+        assert_type(Object[m], "table")
+      end
+    end)
+  end)
+
+  context('tostring', function()
+    test('returns "class Object"', function()
+      assert_equal(tostring(Object), 'class Object')
+    end)
+  end)
+
+  context('allocate', function()
+    test( 'allocates instances properly', function()
+      local instance = Object:allocate()
+      assert_equal(instance.class, Object)
+      assert_equal(getmetatable(instance), Object.__instanceDict)
+    end)
+
+    test( 'throws an error when used without the :', function()
+      assert_error(function()
+        Object.allocate()
+      end, "Make sure that you are using 'Class:allocate' instead of 'Class.allocate'")
+    end)
+
+    --[[
+    context( 'Allocation and creation', function()
+      test( 'allocate should not call the initializer', function()
+        local MyClass = Object:subclass('MyClass')
+        function MyClass:initialize() self.mark=true end
+
+        local allocated = MyClass:allocate()
+        assert_nil(allocated.mark)
+
+        local initialized = MyClass:new()
+        assert_true(initialized.mark)
+      end)
+      
+      test( 'allocate should be overridable', function()
+        local MyClass = Object:subclass('MyClass')
+        function MyClass.allocate(theClass)
+          local instance = Object:allocate()
+          instance.mark = true
+          return instance
+        end
+        
+        local allocated = MyClass:allocate()
+        assert_true(allocated.mark)
+        
+        local initialized = MyClass:new()
+        assert_true(initialized.mark)
+      end)
+
+    end)
+    ]]
+
+  end)
+
+  context( 'subclass', function()
+    context( 'when given a name', function()
+
+      local MyClass = Object:subclass('MyClass')
+
+      test('returns a class with the correct name', function()
+        assert_equal(MyClass.name, 'MyClass')
+      end)
+
+      test('returns a class with the correct superclass', function()
+        assert_equal(MyClass.superclass, Object)
+      end)
+    end)
+  end)
+
+
+
+end)
+
+--[[
+
+  context( 'When creating a direct subclass of Object', function()
+
+    context( 'using Object:subclass("name")', function()
+      local MyClass = Object:subclass('MyClass')
+
+      test( 'should have its name correctly set up', function()
+        assert_equal(MyClass.name, 'MyClass')
+      end)
+
+      test( 'should have Object as its superclass', function()
+        assert_equal(MyClass.superclass, Object)
+      end)
+    end)
+
+    context( 'When no name is given', function()
+      test( 'should throw an error', function()
+        assert_false( pcall(Object.subclass, Object) )
+      end)
+    end)
+
+  end)
+
+  context( 'An instance attribute', function()
+    local Person = class('Person')
+    function Person:initialize(name)
+      self.name = name
+    end
+    
+    local AgedPerson = class('AgedPerson', Person)
+    function AgedPerson:initialize(name, age)
+      Person.initialize(self, name)
+      self.age = age
+    end
+
+    test('should be available after being initialized', function()
+      local bob = Person:new('bob')
+      assert_equal(bob.name, 'bob')
+    end)
+    
+    test('should be available after being initialized by a superclass', function()
+      local pete = AgedPerson:new('pete', 31)
+      assert_equal(pete.name, 'pete')
+      assert_equal(pete.age, 31)
+    end)
+  end)
+  
+  context( 'An instance method', function()
+    local A = class('A')
+    function A:foo() return 'foo' end
+    function A:bar() return 'bar' end
+    
+    local B = class('B', A)
+    function B:foo() return 'baz' end
+    
+    local a = A:new()
+    local b = B:new()
+
+    test('should be available for any instance', function()
+      assert_equal(a:foo(), 'foo')
+    end)
+    
+    test('should be inheritable', function()
+      assert_equal(b:bar(), 'bar')
+    end)
+    
+    test('should be overridable', function()
+      assert_equal(b:foo(), 'baz')
+    end)
+  end)
+  
+  context( 'A class attribute', function()
+    local A = class('A')
+    A.foo = 'foo'
+
+    local B = class('B', A)
+
+    test('should be available after being initialized', function()
+      assert_equal(A.foo, 'foo')
+    end)
+
+    test('should be available for subclasses', function()
+      assert_equal(B.foo, 'foo')
+    end)
+    
+    test('should be overridable by subclasses, without affecting the superclasses', function()
+      B.foo = 'chunky bacon'
+      assert_equal(B.foo, 'chunky bacon')
+      assert_equal(A.foo, 'foo')
+    end)
+  end)
+  
+  context( 'A class method', function()
+    local A = class('A')
+    function A.foo(theClass) return 'foo' end
+
+    local B = class('B', A)
+
+    test('should be available after being initialized', function()
+      assert_equal(A:foo(), 'foo')
+    end)
+
+    test('should be available for subclasses', function()
+      assert_equal(B:foo(), 'foo')
+    end)
+    
+    test('should be overridable by subclasses, without affecting the superclasses', function()
+      function B.foo(theClass) return 'chunky bacon' end
+      assert_equal(B:foo(), 'chunky bacon')
+      assert_equal(A:foo(), 'foo')
+    end)
+  end)
+  
+  context( 'A Mixin', function()
+
+    local Class1 = class('Class1')
+    local Mixin = {}
+    function Mixin:included(theClass) theClass.includesMixin = true end
+    function Mixin:foo() return 'foo' end
+    function Mixin:bar() return 'bar' end
+    Class1:include(Mixin)
+
+    Class2 = class('Class2', Class1)
+    function Class2:foo() return 'baz' end
+
+    test('should invoke the "included" method when included', function()
+      assert_true(Class1.includesMixin)
+    end)
+    
+    test('should have all its functions (except "included") copied to its target class', function()
+      assert_equal(Class1:foo(), 'foo')
+      assert_equal(Class1.included, nil)
+    end)
+    
+    test('should make its functions available to subclasses', function()
+      assert_equal(Class2:bar(), 'bar')
+    end)
+    
+    test('should allow overriding of methods on subclasses', function()
+      assert_equal(Class2:foo(), 'baz')
+    end)
+
+  end)
+  
+  context( 'Metamethods', function()
+    
+    test('__index should throw an error', function()
+      local NonIndexable = class('NonIndexable')
+      
+      assert_error(function() function NonIndexable:__index(name) end end)
+    end)
+
+    context('Custom Metamethods', function()
+      -- Tests all metamethods. Note that __len is missing (lua makes table length unoverridable)
+      -- I'll use a() to note the length of vector "a" (I would have preferred to use #a, but it's not possible)
+      -- I'll be using 'a' instead of 'self' on this example since it is shorter
+      local Vector= class('Vector')
+      function Vector.initialize(a,x,y,z) a.x, a.y, a.z = x,y,z end
+      function Vector.__tostring(a) return a.class.name .. '[' .. a.x .. ',' .. a.y .. ',' .. a.z .. ']' end
+      function Vector.__eq(a,b)     return a.x==b.x and a.y==b.y and a.z==b.z end
+      function Vector.__lt(a,b)     return a() < b() end
+      function Vector.__le(a,b)     return a() <= b() end
+      function Vector.__add(a,b)    return Vector:new(a.x+b.x, a.y+b.y ,a.z+b.z) end
+      function Vector.__sub(a,b)    return Vector:new(a.x-b.x, a.y-b.y, a.z-b.z) end
+      function Vector.__div(a,s)    return Vector:new(a.x/s, a.y/s, a.z/s) end
+      function Vector.__unm(a)      return Vector:new(-a.x, -a.y, -a.z) end
+      function Vector.__concat(a,b) return a.x*b.x+a.y*b.y+a.z*b.z end
+      function Vector.__call(a)     return math.sqrt(a.x*a.x+a.y*a.y+a.z*a.z) end
+      function Vector.__pow(a,b)
+        return Vector:new(a.y*b.z-a.z*b.y,a.z*b.x-a.x*b.z,a.x*b.y-a.y*b.x)
+      end
+      function Vector.__mul(a,b)
+        if type(b)=="number" then return Vector:new(a.x*b, a.y*b, a.z*b) end
+        if type(a)=="number" then return Vector:new(a*b.x, a*b.y, a*b.z) end
+      end
+
+      local a = Vector:new(1,2,3)
+      local b = Vector:new(2,4,6)
+
+      for metamethod,values in pairs({
+        __tostring = { tostring(a), "Vector[1,2,3]" },
+        __eq =       { a,    a},
+        __lt =       { a<b,  true },
+        __le =       { a<=b, true },
+        __add =      { a+b,  Vector(3,6,9) },
+        __sub =      { b-a,  Vector(1,2,3) },
+        __div =      { b/2,  Vector(1,2,3) },
+        __unm =      { -a,   Vector(-1,-2,-3) },
+        __concat =   { a..b, 28 },
+        __call =     { a(), math.sqrt(14) },
+        __pow =      { a^b,  Vector(0,0,0) },
+        __mul =      { 4*a,  Vector(4,8,12) }--,
+        --__index =    { b[1], 3 }
+      }) do
+        test(metamethod .. ' should work', function()
+          assert_equal(values[1], values[2])
+        end)
+      end
+      
+      context('Inherited Metamethods', function()
+        local Vector2= class('Vector2', Vector)
+        function Vector2:initialize(x,y,z) Vector.initialize(self,x,y,z) end
+        
+        local c = Vector2:new(1,2,3)
+        local d = Vector2:new(2,4,6)
+        for metamethod,values in pairs({
+          __tostring = { tostring(c), "Vector2[1,2,3]" },
+          __eq =       { c, c },
+          __lt =       { c<d,  true },
+          __le =       { c<=d, true },
+          __add =      { c+d,  Vector(3,6,9) },
+          __sub =      { d-c,  Vector(1,2,3) },
+          __div =      { d/2,  Vector(1,2,3) },
+          __unm =      { -c,   Vector(-1,-2,-3) },
+          __concat =   { c..d, 28 },
+          __call =     { c(), math.sqrt(14) },
+          __pow =      { c^d,  Vector(0,0,0) },
+          __mul =      { 4*c,  Vector(4,8,12) }
+        }) do
+          test(metamethod .. ' should work', function()
+            assert_equal(values[1], values[2])
+          end)
+        end
+      end)
+      
+    end)
+
+    context('Default Metamethods', function() 
+      local Peter = class('Peter')
+      local peter = Peter()
+      
+      context('A Class', function()
+        test('should have a tostring metamethod', function()
+          assert_equal(tostring(Peter), 'class Peter')
+        end)
+        test('should have a call metamethod', function()
+          assert_true(instanceOf(Peter, peter))
+        end)
+      end)
+
+      context('An instance', function()
+        test('should have a tostring metamethod, different from Object.__tostring', function()
+          assert_not_equal(Peter.__tostring, Object.__tostring)
+          assert_equal(tostring(peter), 'instance of Peter')
+        end)
+      end)
+    end)
+ 
+  end)
+
+end)
+
+context( 'class', function()
+
+  context( 'When creating a class', function()
+
+    context( 'using class("name")', function()
+      local TheClass = class('TheClass')
+
+      test( 'should have the correct name', function()
+        assert_equal(TheClass.name, 'TheClass')
+      end)
+
+      test( 'should have Object as their superclass', function()
+        assert_equal(TheClass.superclass, Object)
+      end)
+    end)
+
+    context( 'using class("name", AClass)', function()
+      local TheSuperClass = class('TheSuperClass')
+      local TheSubClass = class('TheSubClass', TheSuperClass)
+
+      test( 'should have the correct superclass', function()
+       assert_equal(TheSubClass.superclass, TheSuperClass)
+      end)
+    end)
+
+    context( 'using no name', function()
+      test( 'class() should throw an error', function()
+        assert_error(class)
+      end)
+    end)
+  
+  end)
+    
+
+end)
+
+
+context( 'includes', function()
+
+  context( 'Primitives', function()
+    local o = Object:new()
+    local primitives = {nil, 1, 'hello', {}, function() end}
+    
+    for _,primitive in pairs(primitives) do
+      local theType = type(primitive)
+      context('A ' .. theType, function()
+        
+        local f1 = function() return includes(Object, primitive) end
+        local f2 = function() return includes(primitive, o) end
+        local f3 = function() return includes(primitive, primitive) end
+        
+        context('should not throw errors', function()
+          test('includes(Object, '.. theType ..')', function()
+            assert_not_error(f1)
+          end)
+          test('includes(' .. theType .. ', Object:new())', function()
+            assert_not_error(f2)
+          end)
+          test('includes(' .. theType .. ',' .. theType ..')', function()
+            assert_not_error(f3)
+          end)
+        end)
+        
+        test('should make includes return false', function()
+          assert_false(f1())
+          assert_false(f2())
+          assert_false(f3())
+        end)
+
+      end)
+    end -- for
+
+  end)
+
+  context( 'A class', function()
+
+    local Class1 = class('Class1')
+    local Class2 = class('Class2', Class1)
+    local Class3 = class('Class3', Class2)
+    local UnrelatedClass = class('Unrelated')
+    
+    local hasFoo = { foo=function() return 'foo' end }
+    Class1:include(hasFoo)
+    
+    test('should return true if it includes a mixin', function()
+      assert_true(includes(hasFoo, Class1))
+    end)
+    
+    test('should return true if its superclass includes a mixin', function()
+      assert_true(includes(hasFoo, Class2))
+      assert_true(includes(hasFoo, Class3))
+    end)
+    
+    test('should return false otherwise', function()
+      assert_false(includes(hasFoo, UnrelatedClass))
+    end)
+
+  end)
+
+end)
+
+context( 'instanceOf', function()
+
+  context( 'Primitives', function()
+    local o = Object:new()
+    local primitives = {nil, 1, 'hello', {}, function() end}
+    
+    for _,primitive in pairs(primitives) do
+      local theType = type(primitive)
+      context('A ' .. theType, function()
+        
+        local f1 = function() return instanceOf(Object, primitive) end
+        local f2 = function() return instanceOf(primitive, o) end
+        local f3 = function() return instanceOf(primitive, primitive) end
+        
+        context('should not throw errors', function()
+          test('instanceOf(Object, '.. theType ..')', function()
+            assert_not_error(f1)
+          end)
+          test('instanceOf(' .. theType .. ', Object:new())', function()
+            assert_not_error(f2)
+          end)
+          test('instanceOf(' .. theType .. ',' .. theType ..')', function()
+            assert_not_error(f3)
+          end)
+        end)
+        
+        test('should make instanceOf return false', function()
+          assert_false(f1())
+          assert_false(f2())
+          assert_false(f3())
+        end)
+
+      end)
+    end -- for
+
+  end)
+
+  context( 'An instance', function()
+    local Class1 = class('Class1')
+    local Class2 = class('Class2', Class1)
+    local Class3 = class('Class3', Class2)
+    local UnrelatedClass = class('Unrelated')
+    
+    local o1, o2, o3 = Class1:new(), Class2:new(), Class3:new()
+    
+    test('should be instanceOf(Object)', function()
+      assert_true(instanceOf(Object, o1))
+      assert_true(instanceOf(Object, o2))
+      assert_true(instanceOf(Object, o3))
+    end)
+    
+    test('should be instanceOf its class', function()
+      assert_true(instanceOf(Class1, o1))
+      assert_true(instanceOf(Class2, o2))
+      assert_true(instanceOf(Class3, o3))
+    end)
+    
+    test('should be instanceOf its class\' superclasses', function()
+      assert_true(instanceOf(Class1, o2))
+      assert_true(instanceOf(Class1, o3))
+      assert_true(instanceOf(Class2, o3))
+    end)
+    
+    test('should not be an instanceOf its class\' subclasses', function()
+      assert_false(instanceOf(Class2, o1))
+      assert_false(instanceOf(Class3, o1))
+      assert_false(instanceOf(Class3, o2))
+    end)
+    
+    test('should not be an instanceOf an unrelated class', function()
+      assert_false(instanceOf(UnrelatedClass, o1))
+      assert_false(instanceOf(UnrelatedClass, o2))
+      assert_false(instanceOf(UnrelatedClass, o3))
+    end)
+
+  end)
+
+
+end)
+
+
+context( 'subclassOf', function()
+
+  context( 'Primitives', function()
+    local primitives = {nil, 1, 'hello', {}, function() end}
+    
+    for _,primitive in pairs(primitives) do
+      local theType = type(primitive)
+      context('A ' .. theType, function()
+        
+        local f1 = function() return subclassOf(Object, primitive) end
+        local f2 = function() return subclassOf(primitive, o) end
+        local f3 = function() return subclassOf(primitive, primitive) end
+        
+        context('should not throw errors', function()
+          test('subclassOf(Object, '.. theType ..')', function()
+            assert_not_error(f1)
+          end)
+          test('subclassOf(' .. theType .. ', Object:new())', function()
+            assert_not_error(f2)
+          end)
+          test('subclassOf(' .. theType .. ',' .. theType ..')', function()
+            assert_not_error(f3)
+          end)
+        end)
+        
+        test('should make subclassOf return false', function()
+          assert_false(f1())
+          assert_false(f2())
+          assert_false(f3())
+        end)
+
+      end)
+    end
+
+  end)
+  
+  context( 'Any class (except Object)', function()
+    local Class1 = class('Class1')
+    local Class2 = class('Class2', Class1)
+    local Class3 = class('Class3', Class2)
+    local UnrelatedClass = class('Unrelated')
+    
+    test('should be subclassOf(Object)', function()
+      assert_true(subclassOf(Object, Class1))
+      assert_true(subclassOf(Object, Class2))
+      assert_true(subclassOf(Object, Class3))
+    end)
+    
+    test('should be subclassOf its direct superclass', function()
+      assert_true(subclassOf(Class1, Class2))
+      assert_true(subclassOf(Class2, Class3))
+    end)
+    
+    test('should be subclassOf its ancestors', function()
+      assert_true(subclassOf(Class1, Class3))
+    end)
+    
+    test('should not be an subclassOf its class\' subclasses', function()
+      assert_false(subclassOf(Class2, Class1))
+      assert_false(subclassOf(Class3, Class1))
+      assert_false(subclassOf(Class3, Class2))
+    end)
+    
+    test('should not be an subclassOf an unrelated class', function()
+      assert_false(subclassOf(UnrelatedClass, Class1))
+      assert_false(subclassOf(UnrelatedClass, Class2))
+      assert_false(subclassOf(UnrelatedClass, Class3))
+    end)
+
+  end)
+
+end)
+]]
+
+