New PtokaX Lua scripting interface

[PPK]

Here in plain-text or here as html is 0.6 version of draft for new Lua scripting interface. Idea is to create few metatables similar to PtokaX classes and clean api. Maybe is something missing, or is here something that is not needed. Discussion about this needed

[bastya_elvtars]

Will defllood be like Deflood.ChatDeflood.iAction?

[PPK]

No, here will not be deflood table as was here before anymore.

[bastya_elvtars]

Where is GetItemByName()?

[PPK]

For online user it is Core.GetUser(sNick), for registered user it is RegMan.GetRegUser(sNick)

[bastya_elvtars]

For online user it is Core.GetUser(sNick), for registered user it is RegMan.GetRegUser(sNick)

OK, sorry, I did not want to read through function names, just did not find that particular one. I'll come up with more stuff, be warned. :-)

[Madman]

GetBool(iBoolId, 0/1)
SetBool(iBoolId)
GetNumber(iNumberId, iNumber)
SetNumber(iNumberId, iNumber)
GetString(iStringId, sString)
SetString(iStringId, sString)      - | is not allowed.

I don't understand, what are they supposed to change?
And shouldn't 0/1 be in the SetBool and not in GetBool?

[PPK]

I don't understand, what are they supposed to change?

PtokaX have 3 types of setting values.. Bools, Numbers and Strings. Every type have list of Ids for values, for example ID 0 in bools is "Anti Moglo description", ID 5 in numbers is "Min slots limit", ID 10 in strings is "Hub topic"...
List of IDs is missing in draft for now.

And shouldn't 0/1 be in the SetBool and not in GetBool?

Yes, fixed  Draft updated. Added Version, SendToProfile and SendPmToProfile to core. Added few things to BanMan. More api cleanup and is more documented. Added IDs for permissions and all settings. Maybe few other things. Feedback needed !

[bastya_elvtars]

OK, I do not understand or maybe I have missed it. For SetMan will there be Getnumber(), GetBool(), GetString() too so the actual settings can be fetched via lua?
Nevermind, got it. Missed as usual. :-)

[Thor]

Can it be possible to re-implement (or don't remove, that's still exist) GetProfilePermission(iProfileNumber) in ProfMan? Because than it can be added to the remote control too.

[PPK]

Another update, another cleanup, another few changes. Added link to html version of document.

2Hungarista
Permissiona table is available in profile table :

Updated to version 0.4. Removed all functions from user table and added similar functions to Core metatable where first parameter is user table.

Question for scripters:
What values you need in user table everytime? User table is created on every arrival, on every call to function returning user table(s) and because user table have many values that use very much cpu.
Idea is to have only few needed values (for me it is sNick and for PtokaX uptr) and other have on request. One function will add all values to user table (Core.GetAllUserData(tUser)), and another function will add only requested value (Core.GetUserData(tUser, iValueId)).

[Rincewind]

sNick and iProfile are the initial values that spring to mind as being most useful to be initially in user table.

Out of interest, if you needed say three other values, would it be quicker/more efficient to use Core.GetAllUserData(tUser) or to do 3 Core.GetUserData(tUser, iValueId)?

[bastya_elvtars]

Updated to version 0.4. Removed all functions from user table and added similar functions to Core metatable where first parameter is user table.

Now that's an idea. It's just insane to hold a Kick() function for every single user in memory. This will result in significant mem and CPU usage decrease.

Question for scripters:
What values you need in user table everytime? User table is created on every arrival, on every call to function returning user table(s) and because user table have many values that use very much cpu.
Idea is to have only few needed values (for me it is sNick and for PtokaX uptr) and other have on request. One function will add all values to user table (Core.GetAllUserData(tUser)), and another function will add only requested value (Core.GetUserData(tUser, iValueId)).

I think you should pass a nick only and scripters would decide whether to handle the nick only or fetch all data belonging to it.

Another request: how about splitting the data in Arrival()'s? It would be faster if the C code did it directly.

Out of interest, if you needed say three other values, would it be quicker/more efficient to use Core.GetAllUserData(tUser) or to do 3 Core.GetUserData(tUser, iValueId)?

I think #2 is heavier:
- 3 function calls
- the user has to be parsed anyway

[PPK]

Out of interest, if you needed say three other values, would it be quicker/more efficient to use Core.GetAllUserData(tUser) or to do 3 Core.GetUserData(tUser, iValueId)?

When you need more values then imho will be quicker to use Core.GetAllUserData(tUser).

Another request: how about splitting the data in Arrival()'s?

I am not sure if this is possible, PtokaX don't split all command. Maybe is now possible to add splitted data for arrivals where PtokaX split them, and functions to split others.

[Thor]

My opinion: as in VerliHub, maybe profile, nick and $MyINFO string is the most important things. From MyINFO, every data could be splitted with little functions. And, maybe an another call, which do this, the mentioned GetAllUserData(). I don't know if it would be useful, because we like PtokaX cause it's clean and big API. And splitting gave me an another idea: would it be possible to add one new parameter to ToArrival? Like ToArrival(toUser,fromUser,data)

[PPK]

Another request: how about splitting the data in Arrival()'s? It would be faster if the C code did it directly.

I am checked all arrivals and here is result:
SupportsArrival - PtokaX split it but it will need many modifications to be able to send it splitted to lua. And i don't think that is too important to have supports splitted in lua.
ChatArrival - Here is nothing to split, in lua you know nick and nick length of sender and with this you can simply found where is start of message
KeyArrival - Again nothing to split.
ValidateNickArrival - Same as before.
PasswordArrival - And again.
VersionArrival - And again.
GetNickListArrival - And again (it is starting to be boring ;D).
MyINFOArrival - You can get parts of myinfo from user table.
GetINFOArrival - Nothing to split, it is like in chat you know nick and nick length and you can use them to get other nick here.
SearchArrival - PtokaX don't split it, this command is too much complicated and here is no reason to split it to parts on hub. Is known searched string, because is checked for length limit.
MultiSearchArrival - Similar to previous.
ToArrival - Is splitted by PtokaX, is possible to send it splitted to lua arrival.
ConnectToMeArrival - Is splitted by PtokaX, is possible to send it splitted to lua arrival.
MultiConnectToMeArrival - Same as previous.
RevConnectToMeArrival - Nothing to split, again like in chat you know nick and nick length and you can use them to get other nick here.
SRArrival - PtokaX don't split it, another complicated command like $Search. Known is to nick.
UDPSRArrival - PtokaX don't make any actions on this, only simply send it to lua.
KickArrival - Nothing to split.
OpForceMoveArrival - PtokaX split it and is possible to send splitted parts to lua.
UnknownArrival - No action by PtokaX, simply is send to lua.
BotINFOArrival - Nothing to split.
CloseArrival - Nothing to split.

I think that is good to have original arrivals with data as they are received from user. Maybe add arrivals for splitted data is good idea...

ToArrivalSplitted(tUser, sToNick, sMessage)
ConnectToMeArrivalSplitted(tUser, sToNick, sIP+Port)
MultiConnectToMeArrivalSplitted(tUser, sToNick, sIP+Port)
OpForceMoveArrivalSplitted(tUser, sWho, sWhere, sMessage)

and maybe

SearchArrivalSplitted(tUser, sSearchString)
MultiSearchArrivalSplitted(tUser, sSearchString)

My opinion: as in VerliHub, maybe profile, nick and $MyINFO string is the most important things.

Sorry but i don't see anything too much important on $MyINFO to have it in every created user table.

From MyINFO, every data could be splitted with little functions.

Why to waste cpu on it, when you have everything splitted by PtokaX (and much faster than you can do it in lua).

And splitting gave me an another idea: would it be possible to add one new parameter to ToArrival? Like ToArrival(toUser,fromUser,data)

Maybe...Updated to version 0.5. Standard User table contains only sNick and uptr, other values are available after call. Added two functions for this to core table. Added UDPDebug metatable.

[Madman]

Is there any diffrens between Core.SendPmToUser(tUser, sFromNick, sData) and Core.SendPmToNick(sToNick, sFromNick, sData)?

[PPK]

Yes it is, in first case first parameter is user table (it is replacement for old user:SendPM), in second case is first parameter nick. First case is much faster when you call it from function where you have this user table given as first parameter by PtokaX (arrivals, newuser/opconnected...).

[amenay]

Cheers to the lighter user object, definitely a high point among the changes (and something I've been longing for). Looks like Christmas might come early this year.

Where did the decision come to make Core.GetUserData return 1 (on success) instead of returning the updated value? I'm aware that you can use something like this:

Core.GetUser( user.sNick ).sIP

to retrieve such values (for one time use, argument passing, or a limited local assignment), but let's say for the sake of discussion that Core.GetUserData returns the requested value on success, and nil on failure. Wouldn't the following call be faster?

Core.GetUserData( user, 0 )

Or perhaps a separate function should be made.. (edit: part of the above assumes that Core.GetUser returns the full object..)

A question concerning Core.SendToUser (and the other functions this applies to) Will we need to prepend the senders <nick> to the beginning of sData (FromNick as it's been called in the current versions API doc), or is this an oversight?

Meaning this:

Core.SendToUser( tUser, sData, sFrom )

vs.
Current:

SendToUser( tUser, sData )

I can see good reason to remove it (rather, very little reason to keep it), but had to ask anyhow.

[PPK]

Where did the decision come to make Core.GetUserData return 1 (on success) instead of returning the updated value?

When it returns value then this value will be created twice.. first in user table and second as returning value. In string case it will be much slower. Thas is reason why wanted value is not returned as result of this call.

A question concerning Core.SendToUser (and the other functions this applies to) Will we need to prepend the senders <nick> to the beginning of sData (FromNick as it's been called in the current versions API doc), or is this an oversight?

sData can be any protocol command, if you want to send chat then yes you need to include <nick> on begin of data.

[amenay]

When it returns value then this value will be created twice.. first in user table and second as returning value. In string case it will be much slower. Thas is reason why wanted value is not returned as result of this call.sData can be any protocol command, if you want to send chat then yes you need to include <nick> on begin of data.

As, I thought. No reason to have parsing for one specific command on a multi-command function. Makes sense

When it returns value then this value will be created twice.. first in user table and second as returning value. In string case it will be much slower. Thas is reason why wanted value is not returned as result of this call.sData can be any protocol command, if you want to send chat then yes you need to include <nick> on begin of data.

Thought that might be the case, hence thinking maybe there would need to be a separate function. Maybe this wouldn't be worth adding, but I might as well bring it up.  Short example using the current draft proposal.

ChatArrival = function( user, data )
  	local cmd, msg = data:match( "%b<>%s" .. sPre .. "(%w+)%s+(.*)|$" );
	if tCommandArrivals[ cmd ] then
		Core.GetUserData( user, 17 ); --Just need iProfile for a profile check in the tCommandArrivals[ cmd ] function.
		Core.SendToUser( user, "<" .. Core.GetBot( ).sNick .. "> " .. tCommandArrivals[ cmd ]( user, msg ) );
		return 1;
	end
end

Question, could there be a way to push a value directly into Lua without indexing it into the user table? If so would it be worth it? For example:

Core.SendToUser( user, "<" .. Core.GetBot( ).sNick .. "> " .. tCommandArrivals[ cmd ]( Core.GetUserValue( user, 17 ), msg ) )
--No reason to update the user table, since I only need the value for this call.

Core.GetUserValue would just return the value directly, you're not using sNick as you do with Core.GetUser so it's faster than GetUser(sNick).iProfile, since you're using a known user object.  (plus it doesn't initialize a table like Core.GetUser)

As it stands Core.GetUserData to update the value then a statement/assignment to access the value is the fastest way (and what you'll want to user if you need a value several times in the user objects span). But having a function that pushes the value directly and returns it to Lua would be faster yet in situations of one time use, since you're accessing it that one time anyway. Also, it creates some added flexibility when it comes to larger functions with which you might not want to update the entire user table, but just have the value for a smaller scope within the function. (this is a lesser point as you can just assign nil to the variable as nil whenever you don't need it, still worth mentioning..)

[Thor]

Just an idea: Core.GetScripts(), which return an array like:
{chatstat.lua,something.lua,useful.lua,stupid.lua}
Or a hash with status:
{chatstat.lua = 1,something.lua = 1, useful.lua = 1, stupid.lua = nil}
(I think the second one would be better)
Ohh, and an another thing what I really don't understand: is GUI metatable useful? Setting up the cmd and chat-trace is useful, just when you see the GUI. If you see the GUI, you can check it yourself... I know it was requested, just I don't see the reason...

[CrazyGuy]

I second the idea of Core.GetScripts() returning a hash like { scriptname = status , scriptname = status }.
But i'd say status should be 1 or 0 and not nil because when going through a table, an invalid scriptname would also return nil.

To be complete, this is my idea of returned values

tScripts = {
	["ActiveScript"] = 1,
	["DisabledScript"] = 0,
	["NonExistingScript"] = nil,
}

Maybe here is also a possibility for Core.StartScript(sScript) and Core.StopScript(sScript) with return value 1 on success and nil on failure ?

[Thor]

Yes, CrazyGuy has right, as always. We spoke about it with PPK on the PtokaX Admins Hub, there's a problem with StopScript, but maybe it'll be added I started to write a converter application, and I find a missing function:
frmHub:GetNickLenRedir() and frmHub:SetNickLenRedir(0/1) isn't in the new API: not mentioned in the (G/S)etBool table... And, I mentioned yesterday the duplicated GetShare, but not Core, SetMan There is SetMan.GetMinShare and Core.GetNumber(2). One of it is un-useful I think (IMHO SetMan.GetMinShare()) The others seems ok, but the deflood object won't be converted (the least problem, not really used, main problem with removed user:methos-s )

[PPK]

Here is actual (maybe final for next PtokaX release) version of Lua api, i don't think that anything that is done now will be changed. Only new things will come to it in future.
Text version: http://www.ptokax.org/files/Docs/Scripting-Interface.txt
Html version: http://www.ptokax.org/files/Docs/Scripting-Interface.html/index.htmlUpdate...
New metatable ScriptMan having few script related functions.
Core.RestartScripts() was changed to ScriptMan.Restart()