Prototype Lua Object-Oriented Program System

中文版请点击README-zh.md

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.

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

Install
Using the collection
Attribute and Thread Pool
Spell Error Checks And More
Type Validation
enum
struct
- Custom
- Member
- Array
- Dictionary
Class
Interface
Serialization
- JSON Format
Data Entity
Web FrameWork

Install

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
		print(i)
	end
end)

The PLoop can used to call a function with _ENV 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 _G, 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 __Iterator__().

The __Iterator__ 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.

The __Iterator__ 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
		end
	end

	-- 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
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 PLOOP_PLATFORM_SETTINGS table to toggle the PLoop's system settings:

PLOOP_PLATFORM_SETTINGS = { ENV_ALLOW_GLOBAL_VAR_BE_NIL = false }

require "PLoop"

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

	if a then
		print("ok")
	end
end)

Turn off the ENV_ALLOW_GLOBAL_VAR_BE_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 local, 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:

PLOOP_PLATFORM_SETTINGS = {
	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
		end
	end,
}

require "PLoop"

PLoop(function(_ENV)
	Test = 1

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

	A():Test()
end)

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:

PLOOP_PLATFORM_SETTINGS = {
	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
		end
	end,
	GLOBAL_VARIABLE_FILTER_USE_WARN = 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
		end
	end)

	A():Test()
end)

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

PLOOP_PLATFORM_SETTINGS = {
	GLOBAL_VARIABLE_FILTER = function(key, value, path)
		print("Assign '" .. key .. "'" .. path )
	end,
	GLOBAL_VARIABLE_FILTER_GET_CALLLINE = true,
}

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
		end
	end)

	A():Test()
end)

To use the get call line, the debug.getinfo must exist.

Access un-existed object fields

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

PLOOP_PLATFORM_SETTINGS = { OBJECT_NO_RAWSEST = true, OBJECT_NO_NIL_ACCESS = true }

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

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

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

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)
end)

The __Arguments__ 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 __Arguments__, you can change the platform setting( not all type validation would be removed, but just leave them to the system):

PLOOP_PLATFORM_SETTINGS = { TYPE_VALIDATION_DISABLED = true }

require "PLoop"

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

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

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.

enum

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.

Use enumeration[elementname] to fetch the enum element's value, also can use enumeration(value) 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
end)

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

	print(South)           -- 3
end)

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
end)

The __AutoIndex__ 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",
	}

	v = SUNDAY + MONDAY + FRIDAY

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

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

struct

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

Custom

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
end)

There system have provide many fundamental custom struct types like :

Custom Type	Description
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

Member

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
end)

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.

Array

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
end)

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.

Dictionary

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 }
end)

Class

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
			OnRealChanged(self)
		end

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

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

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

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

	a = Imaginary(1, 2)

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

	-- New real is 4
	a:AddReal(3)

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

Interface

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 006.class.md

Serialization

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

JSON Format

Here is a full example to use the Serialization:

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

	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))
end)

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

You can find more in 009.serialization.md

To simply use the JsonFormatProvider, you can use Toolset.json(data[, type]) to serialize the data or object into json, or use Toolset.parsejson(json[, type]) to deserialize the json to the data or object.

For the StringFormatProvider, also we can use Toolset.tostring(data[, type[, pretty]]) to serialize the data or object into string, or use Toolset.parsestring(str[, type]) deserialize the string to the data or object.

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 { }
		end

		-- Represents the data table
		__DataTable__{
			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 }
		end)
	end)

	-- 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
				ctx:SaveChanges()
			end)
		end
	end)
end)

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

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 020.web.md

Contancts

QQ Group: 107045813 https://discord.gg/6hD4sdUtgp

kurapica/PLoop