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
Table of Contents
- Install
- Using the collection
- Attribute and Thread Pool
- Spell Error Checks And More
- Type Validation
- enum
- struct
- Class
- Interface
- Serialization
- 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