by kurapica

kurapica /PLoop

Prototype Lua object-oriented program system, with many modern features like attribute, overload, et...

145 Stars 26 Forks Last release: about 1 month ago (v1.6.11) MIT License 782 Commits 17 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Prototype Lua Object-Oriented Program System


PLoop is a C# like style object-oriented program system for lua. It support Lua 5.1 and above versions, also include the luajit. It's also designed to be used on multi-os thread platforms like the OpenResty.

It provide the usage of enum, struct, interface and class. Also provide common useful features like thread, collection, serialization , data entity framework, web framework and etc.

You can also find useful features for enterprise development like code organization, type validation and etc.

You can find more details in the Docs

Table of Contents


After install the Lua, download the PLoop and save it to LUA_PATH, or you can use

package.path = package.path .. ";PATH TO PLOOP PARENT FOLDER/?/init.lua;PATH TO PLOOP PARENT FOLDER/?.lua"

require "PLoop"

to load the PLoop. If you need to load files by yourself, you could check the PLoop/init.lua for more details.

Using the collection

The collection classes will provide useful stream works like

require "PLoop"

-- Generate a list from 1 to 10, choose all even numbers, square them and join them by "," -- The result is "4,16,36,64,100" print( PLoop.System.Collections.List(10):Range(2, -1, 2):Map("x=>x^2"):Join(",") )

-- Get all the keys from the _G whose value is a table, sort them and join them by "," -- The result is "_G,arg,coroutine,debug,io,math,os,package,string,table" print( PLoop.System.Collections.XDictionary(_G):Filter("k,v=>type(v)=='table'").Keys:ToList():Sort():Join(",") )

Attribute and Thread Pool

We have see how to use classes in the previous example, for the second example, I'll show special usage of the PLoop:

require "PLoop"

PLoop(function(_ENV) Iterator() function iter(i, j) for k = i, j do coroutine.yield(k) end end

-- print 1-10 for each line
for i in iter(1, 10) do


The PLoop can used to call a function with

as its first arguments, this is used to make sure the code in the function will be processed in a special environment provided by the PLoop, in here, you can use List instead the PLoop.System.Collections.List. The best part is you can use the attribute for functions.

Unlike the

, the PLoop environments are very sensitive about new variables, when the iter is defiend, the system will check if there is any attributes should be applied on the function, here we have the


is an attribute class defined in System.Threading, when we use it to create an object, the object is registered to the system, and waiting for the next attribute target(like function, class and etc) that should be defined. The attributes are used to modify or attach data to the attribute targets.


is used to wrap the target function, so it'll be used as an iterator that runs in a corotuine, and we can use coroutine.yield to return values:
require "PLoop"

PLoop(function(_ENV) -- Calculate the Fibonacci sequence Iterator() function Fibonacci(maxn) local n0, n1 = 1, 1

    coroutine.yield(0, n0)
    coroutine.yield(1, n1)

    local n = 2

    while n <= maxn  do
        n0, n1 = n1, n0 + n1
        coroutine.yield(n, n1)
        n = n + 1

-- 1, 1, 2, 3, 5, 8
for i, v in Fibonacci(5) do print(v) end

-- you also can pass the argument later
-- the iterator will combine all arguments
-- 1, 1, 2, 3, 5, 8
for i, v in Fibonacci(), 5 do print(v) end


The collection object method also using the coroutines, so it don't need to generate any cache or anonymous function to do the jobs, since those coroutines are recycled automatically, there is no cost compares to other solutions.

Spell Error Checks And More

There are a lots of troubles in the Lua debugging, if the lua error can be triggered, it's still easy to fix it, but for codes like

if a == ture then
, ture is a non-existent variable, Lua treate it as nil so the checking will still working, but the result can't be right.

We'll see how to solve it in the PLoop.

Read un-existed global variables

Before rquire the PLoop, we can create a PLOOPPLATFORMSETTINGS table to toggle the PLoop's system settings:


require "PLoop"

PLoop(function(_ENV) local a = ture -- Error: The global variable "ture" can't be nil.

if a then


Turn off the ENVALLOWGLOBALVARBE_NIL will apply a strict mode for all PLoop private environment, so no nil variables can be accessed, so you can locate those errors.

Write to illegal global variables

If we missing the

, we may create unwanted global variables. But the system can't diff the wanted and unwanted global variable, we can add filter in the platform settings to do the job, so we can remove the filter when we don't need it:
    GLOBAL_VARIABLE_FILTER = function(key, value)
        -- Don't allow the lowercase key with non-function value
        if type(key) == "string" and key:match("^%l") and type(value) ~= "function" then
            return true

require "PLoop"

PLoop(function(_ENV) Test = 1

class "A" (function(_ENV)
    function Test(self)
        ch = 2 -- error: There is an illegal assignment for "ch"



If the filter return true, the assignment will trigger an error, so the code'll be stopped, if we only need a warning, we can add a setting like:

    GLOBAL_VARIABLE_FILTER = function(key, value)
        -- Don't allow the lowercase key with non-function value
        if type(key) == "string" and key:match("^%l") and type(value) ~= "function" then
            return true

require "PLoop"

PLoop(function(_ENV) Test = 1

class "A" (function(_ENV)
    function Test(self)
        ch = 2 -- [PLoop: Warn]There is an illegal assignment for "ch"@path_to_file\file.lua:18



You also can use the filter as a record, with another setting, the call line'll be passed in as the 3rd argument:

    GLOBAL_VARIABLE_FILTER = function(key, value, path)
        print("Assign '" .. key .. "'" .. path )

require "PLoop"

PLoop(function(_ENV) Test = 1 -- Assign 'Test'@path_to_file\file.lua:11

class "A" (function(_ENV)
    function Test(self)
        ch = 2 -- Assign 'ch'@path_to_file\file.lua:15



To use the get call line, the

must exist.

Access un-existed object fields

We also can block the accessing of un-existed object fields:


require "PLoop"

PLoop(function(_ENV) -- Define a class with Name and Age property class "Person" (function(_ENV) property "Name" { type = String } property "Age" { type = Number } end)

o = Person()

o.Name = "King" -- Ok = "Ann"  -- Error: The object can't accept field that named "name"

print(   -- Error: The object don't have any field that named "name"


This three settings will help authors to avoid many spell errors during the development. You shouldn't use those settings when you release the project since the access speeding should be slightly increased.

Type Validation

PLoop make the Lua as a strong type language, there are many type validation features to stop the errors spread to far so too hard to be tracked.

The function validation is always a complex part, we need to do many checks before the function's main logic for the arguments so we can tell the caller where and what is failed. And when the project is released, those check should be removed since we already test them.

Within the PLoop, it'll be a small problem:

require "PLoop"

PLoop(function(_ENV) Arguments{ String, Number } function SetInfo(name, age) end

-- Error: Usage: SetInfo(System.String, System.Number) - the 2nd argument must be number, got boolean
SetInfo("Ann", true)



is an attribute class defined in the System, it associated the argument name, type, default value and etc to the argument, also wrap those functions with the argument validation.

The String and Number are struct types used to validate values, we'll see them at the introduction of struct.

If we need to release the project, there is also no need to remove those

, you can change the platform setting( not all type validation would be removed, but just leave them to the system):

require "PLoop"

PLoop(function(_ENV) Arguments{ String, Number } function SetInfo(name, age) end

-- No error now
SetInfo("Ann", true)


To achieve a whole type validation system, we need more types to describe the datas. In PLoop, there are four types: enum, struct, interface and class.


the enumeration is a data type consisting of a set of named values called elements, The enumerator names are usually identifiers that behave as constants.

To define an enum within the PLoop, the syntax is

enum "name" { -- key-value pairs }

In the table, for each key-value pair, if the key is string, the key would be used as the element's name and the value is the element's value. If the key is a number and the value is string, the value would be used as both the element's name and value, othwise the key-value pair will be ignored.


to fetch the enum element's value, also can use
to fetch the element name from value.

Also can use the element name directly where the enum is defined or imported.

Here is an example :

require "PLoop"

PLoop(function(_ENV) namespace "TestNS"

enum "Direction" { North = 1, East = 2, South = 3, West = 4 }

print(Direction.South) -- 3
print(Direction.NoDir) -- nil
print(Direction(3))    -- South

print(East)            -- 2


PLoop(function(_ENV) import "TestNS.Direction"

print(South)           -- 3


Since the element value is indexed, we also can define it like

require "PLoop"

PLoop(function(_ENV) AutoIndex{ North = 1, South = 5 } enum "Direction" { "North", "East", "South", "West", }

print(East) -- 2
print(West) -- 6



attribute will give each element an auto-increase index based on the config tables.

Another special enum is the flags enumeration type, the element value should be 2^n(0 is also allowed), so the element value can be used together :

require "PLoop"

PLoop(function(_ENV) Flags() enum "Days" { "SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", }


-- SUNDAY  1
-- MONDAY  2
-- FRIDAY  32
for name, val in Days(v) do
    print(name, val)

print(Enum.ValidateFlags(MONDAY, v)) -- true
print(Enum.ValidateFlags(SATURDAY, v)) -- false



The structures are types for basic and complex organized datas and also the data contracts for value validation. There are three struct types:


The basic data types like number, string and more advanced types like nature number. Take the Number as an example:

require "PLoop" (function(_ENV)
    v = Number(true)  -- Error : the value must be number, got boolean

There system have provide many fundamental custom struct types like :

Custom Type

System.Any represents any value
System.Boolean represents boolean value
System.String represents string value
System.Number represents number value
System.Function represents function value
System.Table represents table value
System.Userdata represents userdata value
System.Thread represents thread value
System.AnyBool represents anybool value
System.NEString represents nestring value
System.RawTable represents rawtable value
System.Integer represents integer value
System.NaturalNumber represents natural number value
System.NegativeInteger represents negative interger value
System.NamespaceType represents namespace type
System.EnumType represents enum type
System.StructType represents struct type
System.InterfaceType represents interface type
System.ClassType represents class type
System.AnyType represents any validation type
System.Lambda represents lambda value
System.Callable represents callable value, like function, callable objecct, lambda
System.Guid represents Guid value


The member structure represent tables with fixed fields of certain types. Like

require "PLoop"

PLoop(function(_ENV) struct "Location" (function(_ENV) x = Number y = Number end)

loc = Location{ x = "x" }    -- Error: Usage: Location(x, y) - x must be number
loc = Location(100, 20)
print(loc.x, loc.y)          -- 100  20


So the Location struct has two members : x, y all are numbers, we can use it to validate the tables with the special structure.

it also can be used as value constructor(and only the member struct can be used as constructor), the argument order is the same order as the declaration of it members.


The array structure represent tables that contains a list of same type items. Here is an example to declare an array:

require "PLoop"

PLoop(function(_ENV) struct "Location" (function(_ENV) x = Number y = Number end)

struct "Locations" { Location }

v = Locations{ {x = true} } -- Usage: Locations(...) - the [1].x must be number


So the Locations should contains several Location values.

The enum and struct are all data types, normally used for type validation. The interface and class types is the core system of the PLoop.


The dictionary structure represent tables that contains a specific type keys and specific type value pairs.

require "PLoop"

PLoop(function(_ENV) struct "NameAge" { [String] = Number }

v = NameAge{ ann = 2, ben = 3 }



The classes are types that abstracted from a group of similar objects. The objects generated by the classes are tables with fixed meta-tables.

A class can be defined within several parts: constructor, meta-method, object method, property and event:

require "PLoop"

PLoop(function(_ENV) class "Imaginary" (function(_ENV) -- event event "OnRealChanged" event "OnImgChanged"

    -- property
    property "Real"      { type = Number, default = 0 }
    property "Imaginary" { type = Number, default = 0 }

    -- method
    function AddReal(self, rel)
        self.Real = self.Real + rel

    function AddImg(self, img)
        self.Imaginary = self.Imaginary + img

    -- constructor
    function Imaginary(self, real, img)
        self.Real = real
        self.Imaginary = img

    -- meta-method
    function __add(self, another)
        return Imaginary(self.Real + another.Real, self.Imaginary + another.Imaginary)

    function __tostring(self)
        return ("%d + %di"):format(self.Real, self.Imaginary)

a = Imaginary(1, 2)

a.OnRealChanged = a.OnRealChanged + function(self)
    print("New real is " .. self.Real)

-- New real is 4

-- 7 + -2i
print(a + Imaginary(3, -4))



The interfaces are abstract types of functionality, it also provided the multi-inheritance mechanism to the class. It works like the class, just can't be used to create objects.

A class can only have one super class, but can extend no limit interfaces.

You could find the details in


With the System.Serialization, we can serialize objects to data of target format, or deserialize the data to objects.

JSON Format

To use the JSON format, we need load PLoop.System.Web besides the PLoop.

require "PLoop"
require "PLoop.System.Web"

PLoop(function(_ENV) import "System.Serialization" import "System.Web"

json = [==[
    "debug": "on\toff",
    "nums" : [1,7,89,4,5,6,9,3,2,1,1,9,3,0,11]

-- deserialize json data to lua table
data = Serialization.Deserialize(JsonFormatProvider(), json)

-- Serialize lua table to string with indent
-- {
--      debug = "on off",
--      nums = {
--          [1] = 1,
--          [2] = 7,
--          [3] = 89,
--          [4] = 4,
--          [5] = 5,
--          [6] = 6,
--          [7] = 9,
--          [8] = 3,
--          [9] = 2,
--          [10] = 1,
--          [11] = 1,
--          [12] = 9,
--          [13] = 3,
--          [14] = 0,
--          [15] = 11
--      }
-- }
print(Serialization.Serialize(StringFormatProvider{Indent = true}, data))


The example is using System.Serialization deserialize a json string to lua data by using System.Web.JsonFormatProvider, then use System.Serialization.StringFormatProvider to serialize the data to a string.

You can find more in

Data Entity

With the Systm.Data lib, we can define data entity classes that represents a data base

require "PLoop"
require "PLoop.System.Data"

PLoop(function(_ENV) import "System.Data"

__DataContext__()  -- Represents the data base
class "TestDBContext" (function(_ENV)
    -- Init the connection when a context object is created
    function __ctor(self)
        self.Connection = MySQLConnection { }

    -- Represents the data table
        name         = "department",
        indexes      = {
            { fields = { "id" },   primary = true },
    class "Department" (function(_ENV)
        -- Represents the data field
        __DataField__{ autoincr = true }
        property "id"           { type = NaturalNumber }

        __DataField__{ notnull = true, unique = true }
        property "name"         { type = String }

-- Operations for CRUD
with( TestDBContext() )(function(ctx)
    -- Query the data table department with id, take the first result
    local dept = ctx.Departments:Query{ id = 1 }:First()

    if not dept then
        -- create it if not existed
        with( ctx.Transaction )(function(trans)
            dept =  ctx.Departments:Add{
                name = "temp",

            -- save all changes to the data base


So we can only use the Lua codes to avoid sql operations. You can find the details in

Web FrameWork

The System.Web provide the abstract layer for web development, you can find the implementation for Openresty at NgxLua, there is an example project at PLoop.Browser which can be used to browser the types of the PLoop.

With the web framework we can create any web service with a simple format

require "PLoop.System.Web"

-- Create a web application Application "TestWebApp" (function(_ENV) Route("/jsonhandler", HttpMethod.GET) -- bind the route Json() -- the return value will be converted to JSON format as response function JsonHandler(context) return { Data = { { Name = "Ann", Age = 12}, { Name = "King", Age = 32}, { Name = "July", Age = 22}, { Name = "Sam", Age = 30}, } } end end)

The web framework also provide a powerful template system and MVC framework, you can find the details in

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.