middleclass/README.textile

h1. MiddleClass

Lua OOP classes usually end being:

* multi-file libraries, too difficult to understand
* very small libraries, not very powerful

Middleclass attemps to be a mid-sized library (~130 lines of code, on a single file), with clean, easy to understand code, and yet powerful enough to be used in most cases.

h1. Documentation

See the "github wiki page":https://github.com/kikito/middleclass/wiki for examples & documentation.

h1. Features

  * ~140 lines of code
  * top-level Object class
  * all methods are virtual
  * instance.class returns the instance's class
  * @Class.name@ returns the class name (a string)
  * @Class.super@ returns its super class
  * Class methods can be defined with Class.static.methodname
  * Subclassing:
  ** @class(name)@ creates a subclass of @Object@
  ** @class(name, Superclass)@ creates a subclass of the class @SuperClass@
  ** @SuperClass:subclass(name)@ also creates a subclass of the class @SuperClass@
  * Instantiation:
  ** Classes can define an @initialize@ method for initializing new instances. They can accept an arbitrary number of params.
  ** Instances are created by doing @Class:new(params)@ or also @Class(params)@
  ** SuperClass' methods can be used by using this syntax: @SuperClass.initialize(self, params)@.
  * support for Lua metamethods: just define a method called @__tostring@, @__add@, etc. and your instances will be able to use it.
  * Mixins:
  ** A very simple mechanism for sharing functionality among a group of classes that are otherwise non-related.
  ** Mixins are just simple lua tables with functions inside them.
  ** @Class:include(mixin)@ will copy the function definitions of @mixin@ to @class@
  ** If @mixin@ contains a function, called @included@, that function will be invoked right after the functions have been copied. It allows for modifying the class more profoundly.
  * The function @instanceOf(class, instance)@ returns @true@ if @instance@ is an instance of the class @Class@
  * The function @subclassOf(Superclass, Class)@ returns @true@ if @Class@ is a subclass of @SuperClass@
  * The function @includes(mixin, Class)@ returns @true@ if @Class@ (or one of its superclasses) includes @mixin@.

Features left out:

  * metaclasses
  * classes are not Objects (instances are)
  * simulating a 'super' keyword (for performance concerns)

h1. Installation

Just copy the middleclass.lua file wherever you want it (for example on a lib/ folder). Then write this in any Lua file where you want to use it:

<pre>require 'middleclass'</pre>

The @package.path@ variable must be configured so that the folder in which middleclass.lua is copied is available, of course.

Please make sure that you read the license, too (for your convenience it's now included at the beginning of the middleclass.lua file).

h1. Specs

This project uses "telescope":https://github.com/norman/telescope for its specs. If you want to run the specs, you will have to install telescope first. Then just execute the following from the root inspect folder:

<pre>
tsc -f spec/*
</pre>

h1. Performance tests

Middleclass also comes with a small performance test suit. Just run the following commant:

<pre>
lua performance/run.lua
</pre>