Enhanced OO wrapper for Mudlet Trigger, Timer, Event and Stopwatch objects

Share your scripts and packages with other Mudlet users.
Post Reply
fordpinto
Posts: 34
Joined: Wed Sep 25, 2019 4:59 pm

Enhanced OO wrapper for Mudlet Trigger, Timer, Event and Stopwatch objects

Post by fordpinto »

I find object-oriented syntax to be oftentimes more readable, but the reason I ended up making this package is much more practical. When creating "temporary", i.e. dynamic Mudlet triggers and timers I found it very annoying that they keep hanging around even when I do not need them. I was more than once buried in the avalanche of responses from a bunch of identical triggers :) Luckily, I thought of a way to properly garbage-collect them when no longer in use, which I think is the main functional advantage of using this library as opposed to native API. It relies on a feature introduced in Lua 5.2 which I think is reason enough to ponder moving to 5.2, but that's another story. Fortunately there is an undocumented bit put into Lua 5.1 that allows for a workable kludge (see __gc.lua shared library available from luarocks). Another useful enhancement of this library is that it keeps track of enabled/disabled state of the timers and triggers.

ENABLING THE LIBRARY:

Code: Select all

local MLObj = require "MLObj"
Adding the line above should be enough as long as the "MLObj.lua" and "__gc.lua" files are visible to Lua (for example, are in the profile directory).

DEFINING A TIMER:

Code: Select all

-- defining all the parameters of a Timer object
timerDef1s = {
	timerLabel = "my 1 second timer",
	interval = 1.0,
	code = function() echo("Another second passed!\n") end,
	repeating = true
}
timerLabel (and triggerLabel below) are ways to keep track of the objects in a human-readable and searchable way. Labels are not required to be unique, but it could help when keeping track of the objects. In present form the library keeps a list of the timer/trigger objects that are created through its code, and there is a way to search that list. I see this as a debug feature that may fade away, or kept, depending on how useful it is.

DEFINING A TRIGGER:

Code: Select all

-- supported trigger types: SUBSTRING, REGEX, PROMPT, LINE, EXACT, HEAD, COLOR
-- unsupported: COMPLEX (the code is commented out because I saw some issues with underlying Mudlet API mentioned)
triggerDef2 = {
	triggerLabel = "Super useful trigger from levitation module",
	triggerType = "REGEX",
	regex = "^Some regex to (fire|FIRE) the trigger on$",
	code = function() echo("Something super useful just happened...\n") end,
	-- if the definition table doesn't have "expireAfter" defined in it,
	-- the trigger is understood as perpetual, it will exist until disabled/deleted
 	expireAfter = 100,
}
I was actually debating if it makes sense to include support SUBSTRING, EXACT and HEAD types. After all, their functionality is easily covered by REGEX type trigger. Maybe supported but discouraged?

CREATING TRIGGER AND TIMER

Code: Select all

timer1s = MLObj.Timer:new(timerDef1s)
triggerSuper = MLObj.Trigger:new(triggerDef2)
SEARCHING EXISTING TRIGGERS AND TIMERS

Code: Select all

trigList = MLObj.Trigger:getList("^Super")
-- trigList now contains a table of all trigger labels that start with the word "Super", indexed by their triggerid
This could be useful for debugging, especially if one has some sort of convention for trigger labels. For example, all triggers from the same logical code portion could share same prefix in their label string.

ENABLING AND DISABLING

Code: Select all

timer1s:enable() -- enables the timer
triggerSuper:disable() -- disables the trigger
CHECKING ON ENABLED STATUS

Code: Select all

if triggerSuper:isEnabled() then
	echo("Super trigger is watching you!\n")
end
DELETING

Code: Select all

-- triggerSuper will be killed and deleted in the next garbage collection cycle
triggerSuper = nil
-- if one needs to incapacitate the object immediately, use :disable, like this
timer1s:disable()
timer1s = nil
-- Mudlet object existence has the same scope as the variable that references it
do
	local sometimer = MLObj.Timer:new(sometimerDef)
	...
	...
end
-- the timer created by code will disappear shortly after the block execution
Attachments
MLObjLean.lua
(7.49 KiB) Downloaded 256 times
MLObj.lua
(11.25 KiB) Downloaded 262 times
Last edited by fordpinto on Fri Mar 13, 2020 9:39 pm, edited 1 time in total.

User avatar
Vadi
Posts: 5035
Joined: Sat Mar 14, 2009 3:13 pm

Re: Enhanced OO wrapper for Mudlet Trigger and Timer objects

Post by Vadi »

This is neat! Thanks for sharing :) OO wrappers for Mudlet primitives is something we have a history of and support - see Vyzor, Geyser, and others for the UI functions.

> After all, their functionality is easily covered by REGEX type trigger. Maybe supported but discouraged?

Not if you want better performance ;) regex I'd say is the slowest of those.

fordpinto
Posts: 34
Joined: Wed Sep 25, 2019 4:59 pm

Re: Enhanced OO wrapper for Mudlet Trigger, Timer, Event and Stopwatch objects

Post by fordpinto »

I realized that I needed Event objects as well, so added it. Added Stopwatch for good measure, but not all of Mudlet API fits within the OO object structure (more comments in a second). Also improved on some logic details (a bit more assert()). Included both the debug and the lean version. Lean version does not include object list maintenance, so the core code is more clear I think.

fordpinto
Posts: 34
Joined: Wed Sep 25, 2019 4:59 pm

Re: Enhanced OO wrapper for Mudlet Trigger, Timer, Event and Stopwatch objects

Post by fordpinto »

Added Event object:

Code: Select all

-- creating Event definition
eventDef = {
	name = "My special event",
	eventLabel = "Handler object for my special event", -- this is ignored by the lean version,
	-- and can be omitted in full version (taken as "")
	code = function() echo("My special event just happened!\n") end,
	oneshot = true -- omitting this definition element is the same as setting it to false
}
-- creating and activating event object
myEvent = MLObj.Event:new(eventDef)
...
...
-- deleting event object
myEvent = nil
Logic-wise would be nice to also have API functions to enable and disable event handlers, but it works fine like this as well.

fordpinto
Posts: 34
Joined: Wed Sep 25, 2019 4:59 pm

Re: Enhanced OO wrapper for Mudlet Trigger, Timer, Event and Stopwatch objects

Post by fordpinto »

Added Stopwatch object:

Code: Select all

mySwDef = {
	stopwatchLabel = "Fight stopwatch" -- only one parameter is needed, and by the "debug" version at that.
	-- syntax kept for compatibility with other MLObj types
}
-- creating Stopwatch object
-- NOTE: Stopwatch object is always created in a stopped state, I think it's cleaner and easier to read the code
-- when creation step is distinct and separate from activation
myStopwatch = MLObj.Stopwatch:new(mySwDef) -- can omit the argument, then the label is assumed to be ""
-- start the stopwatch
myStopwatch:start()
-- get stopwatch time
local time = myStopwatch:getTime()
-- reset the stopwatch
myStopwatch:reset()
-- subtract 2 seconds from the stopwatch time
myStopwatch:adjustBy(-2)
-- stop the stopwatch
myStopwatch:stop()
-- delete the stopwatch
myStopwatch = nil
The new persistent Stopwatch types are not supported, I simply could find a way to seamlessly fit it into the same framework. I think this is because the whole concept of MLObj is based on the dynamic creation and deletion. The name string controls the behavior of a persistent timer, but the rest of this wrapper class the corresponding Lua object controls the behavior. So this feature is left out until there is clarity on how to seamlessly integrate.

User avatar
SlySven
Posts: 1019
Joined: Mon Mar 04, 2013 3:40 pm
Location: Deepest Wiltshire, UK
Discord: SlySven#2703

Re: Enhanced OO wrapper for Mudlet Trigger, Timer, Event and Stopwatch objects

Post by SlySven »

FTR The main reason I added the persistent feature is so that they could be used to time RL things outside of the profile session. If stopped when the profile is saved they will still be there (under the same NAME but not necessarily the same ID number) with the same stored time when the profile is reopened; if they are running when the profile is saved they again will still be there (same name, not necessarily same number) with the time incrementing and including the time elapsed between two profile sessions as if the break in play had not occurred.

HTH.

User avatar
Vadi
Posts: 5035
Joined: Sat Mar 14, 2009 3:13 pm

Re: Enhanced OO wrapper for Mudlet Trigger, Timer, Event and Stopwatch objects

Post by Vadi »

I think that deserves a chapter on its own in documentation, just the API documentation on this feature doesn't do it justice. Could you add one?

Post Reply