މޮޑިއުލް:Middleclass/doc: Difference between revisions

<div dir=ltr>

 

If you are familiar with Object Orientation in other languages (C++, Java, Ruby … ) then you will probably find this library very easy to use.

== Quick Example ==

 

local class = require('Module:Middleclass').class

 

mw.log(p1:speak())

mw.log(p2:speak())

 

Output:

You can compare classes and objects with the built-in methods <code>isInstanceOf</code>, <code>isSubclassOf</code>, and <code>includes</code>.

 

obj:isInstanceOf(MyClass)

aClass:isSubclassOf(Object)

aClass:includes(aMixin)

 

Caution: this code will throw an error if obj is not an object, or if aClass is not a class (since they will not implement isInstanceOf, isSubclassOf or includes). If you are unsure of whether obj and aClass are an object or a class, you can use the methods in Object. This is a special object that can be obtained from the class object.

It is possible to get a special object ''Object'' from the class function.

 

local middleclass = require('Module:Middleclass')

local class = middleclass.class

 

print(Object) -- prints 'class Object'

 

The methods in Object are prepared to work with random types, not just classes and instances:

 

Object.isInstanceOf(obj, MyClass)

Object.isSubclassOf(aClass, Object)

Object.includes(aClass, aMixin)

 

== Metamethods ==

Let’s make an example with <code>__tostring</code>

 

Point = class('Point')

 

mw.log(p1)

mw.log(p2)

 

Output:

The complete list of supported methods can be seen on middleclass’ source code:

 

'__add', '__call', '__concat', '__div', '__le', '__lt', '__mod', '__mul', '__pow', '__sub', '__tostring', '__unm'

 

You may notice that <code>__index</code> is missing. That metamethod is reserved for the lib and can’t be used. On middleclass 1.x there was a way around this (via a mixin) but for now I don’t recommend using this metamethod with classes. You will probably be better off using a pure Lua table instead, if you need that.

Mixins can be used for sharing methods between classes, without requiring them to inherit from the same father.

 

local class = require 'middleclass'

HasWings = { -- HasWings is a module, not a class. It can be "included" into classes

mw.log(bee:fly())

mw.log(bat:fly())

 

Output:

Mixins can provide a special function called 'included'. This function will be invoked when the mixin is included on a class, allowing the programmer to do actions. The only two parameters are the mixin (normally implicit) and the class.

 

local class = require('Module:Middleclass').class

DrinksCoffee = {}

mw.log(juan:drink(5))

mw.log(juan:drink(6))

 

Output:

* One exception to this rule is when classes are declared inside packages in that case, they can be declared as follows:

 

MyClass = class('package.MyClass')

 

* Another exception is for internal classes (classed declared inside classes)

 

MyClass = class('package.MyClass')

MyClass.InternalClass = class('package.MyClass.InternalClass')

 

=== Attributes, instances and constants ===

* Instance methods should be declared using the colons, so they have an implicit ‘self’ parameter:

 

function MyClass:setX(x)

self.x = x

end

 

* Class methods should use the special property ‘static’ for being defined:

 

function MyClass.static:classMethod()

return 'I am the ' .. self.name .. ' class. I am awesome'

end

 

* Private methods should be preceded with an underscore: <code>_myPrivateMethod</code>

The simplest one is just to precede your attributes with underscores. This is actually written on the Lua 5.1 reference, section 2.1, “Lexical conversions”, as a way to say “this is here, but please don’t use it”.

 

local class = require('middleclass')

MyClass = class('MyClass')

self.publicStuff = 2

end

 

However, this isn’t really making the properties “hidden”.

Example:

 

-- File 'MyClass2.lua'

local class = require('middleclass')

return(_internalClassCounter)

end

 

The scope of local declarations on a lua file is the file itself. If you declare something “local” in one file it is not available on others, even if they “require” that file.

 

-- File 'main.lua'

 

 

mw.log(MyClass2:getCount()) -- prints "0"

 

Let me explain what happens here. The _internalClassCounter = 4 line is, in reality, creating a new global variable called internalClassCounter, and assigning it 4. The “really internal” one is “out of reach” on main.lua (unless someone does really tricky stuff with the environments). So getCount() works as expected.

It is also possible to declare private methods. The trick here is not to “include” them on the class definition. On the following example, we will not declare it on <code>Class3:secretMethod</code>; instead we’ll create a local function. Since we’re not using the : operator any more, we have to make the “self” parameter explicit. Also, since we have to make it local, we have to deviate from the “usual” way of declaring Lua functions (the “usual” way of declaring functions makes them global):

 

-- File 'MyClass3.lua'

local class = require('middleclass')

return _secretMethod(self) .. ' You will never know it!'

end

 

 

-- File 'Main.lua'

require('MyClass3')

 

mw.log(_secretMethod(peter)) -- throws an error - _secretMethod is nil here.

 

This technique also allows the creation of private class methods. In MiddleClass, there’s really no difference between class methods and instance methods; the difference comes from what you pass to their ‘self’ parameter. So if you invoke _secretMethod like this: _secretMethod(MyClass3) it will be a class method.

A slightly more efficient way of creating a class method would be getting rid of the ‘self’ parameter and use MyClass3 directly on the method’s body:

 

MyClass3 = class('MyClass3')

 

return( 'Being a public class named ' .. theClass.name .. ' is not a bad thing.' )

end

 

This gives a bit more of flexibility when overriding public class methods on subclasses.

Finally, a subtle point regarding recursive private methods. If you need to create a private method that calls himself, you will need to declare the variable first, and then (on the next line) initialize it with the function value. Otherwise the variable will not be available when the function is created

 

MyClass3 = class('MyClass3')

 

m = MyClass3:new()

m:recurseOver(5)

 

Output:

-By the way, the following example also shows how you can do “read-only-ish attributes”: you make them private, and make getters for them, but not setters.

 

-- File 'MyClass4.lua'

local class = require('middleclass')

return _private[self].gender

end

 

 

-- File 'main.lua'

 

mw.log(stewie:getGender()) -- 'male'

mw.log(stewie.gender) -- 'female'

 

=== Private members on the same file ===

Just create an artificial scope with do … end, and declare private members as ‘local’ inside that block. Only the methods inside that block will have access to them:

 

-- File 'MyClass3.lua'

local class = require('middleclass')

 

-- functions outside the do-end will not 'see' secretMethod, but they will see MyClass3.shout (because they see MyClass3)

 

== MIT License ==