Implements and documents API

README.md

@@ -67,6 +67,7 @@ One announcement consists of an id, a message, an owner, a runtime and a frequen
 ```
 {
     announcement_id = 1,
+    creation_date = os.time(),
     message = "[EVENT] Don't forget to join the event tonight!",
     owner = "Admin",
     runtime = 1000000,
@@ -78,9 +79,9 @@ Those announcements sit in a table with `announcement_id` as index:
 
 ```
 {
-    1 = {},
+    1 = {announcement},
-    2 = {},
+    2 = {announcement},
-    ["5"] = {}
+    ["5"] = {announcement}
 }
 ```
 
@@ -136,7 +137,7 @@ Use the following public functions to get, set, list and remove announcements
 yl_announcements.get(announcement_id)
 ```
 
-Returns a table with the values of this announcement_id or `nil`, if it does not exist
+Returns a table with the values of this announcement_id. Returns `nil`, if it does not exist. Returns `false, "errormessage"` if an error occurred.
 
 ```
 yl_announcements.set(message, frequency, runtime, owner)
@@ -148,7 +149,7 @@ Adds this announcement to the list and returns `true, announcement_id` if accept
 yl_announcements.formspec(announcement_id)
 ```
 
-Returns a formspec with the `/announcement_add` string, so it can be easily copied from.
+Returns `true, formspecstring` if an announcement was found, with formspecstring including the `/announcement_add` string, so it can be easily copied from. Returns `false, errormessage` if an error occurred.
 
 ```
 yl_announcements.delete(announcement_id)
@@ -160,13 +161,13 @@ Returns `true, {announcement}` if one task was successfully removed, `false, "er
 yl_announcements.list()
 ```
 
-Returns `true, {announcement_id, announcement_id, ... }` if one or more announcements were found or `false, {}` if none were found.
+Returns `true, { id = {announcement}, ... }` if one or more announcements were found or `false, {}` if none were found.
 
 ```
-yl_announcements.say({announcement_id, announcement_id, ... })
+yl_announcements.say(announcement_id)
 ```
 
-Returns `true, {announcement_id, announcement_id, ... }` if one or more announcements were found or `false, {}` if none were found.
+Returns `true, {announcement}` if one announcement was found or `false, {}` if none were found.
 
 ## Limitations
 

api.lua

@@ -1,42 +1,160 @@
-function yl_announcements.get_all_anncouncements()
+function yl_announcements.list()
-    return yl_announcements.data or {}
+    if next(yl_announcements.data) ~= nil then
-end
+        return true, yl_announcements.data
-
-function yl_announcements.get_announcement(a_id)
-    local announcements = yl_announcements.get_all_anncouncements()
-    for _, announcement in pairs(announcements) do
-        if announcement.id == a_id then
-            return announcement
-        end
     end
-    return yl_announcements.error
+    return false, {}
 end
 
-function yl_announcements.delete(a_id)
+function yl_announcements.get(announcement_id)
-    local announcements = yl_announcements.get_all_anncouncements()
+
-    local data = {}
+    -- Check announcement_id
+    if (type(announcement_id) ~= "number") then
+        return false, "Announcement ID is not a number"
+    end
+    if (announcement_id <= 0) then
+        return false, "Announcement ID cannot be zero or negative"
+    end
+
+    local success, data = yl_announcements.list()
+    if ((success == true) and (data[announcement_id] ~= nil)) then
+        return table.copy(data[announcement_id])
+    end
+    return nil
+end
+
+function yl_announcements.set(message, frequency, runtime, owner)
+
+    -- Check message
+    if (type(message) ~= "string") then return false, "message not a string" end
+
+    -- Check frequency
+    if (type(frequency) ~= "number") then
+        return false, "frequency not a number"
+    end
+    if (frequency <= 0) then
+        return false, "Frequency cannot be zero or negative"
+    end
+
+    -- Check runtime
+    if (type(runtime) ~= "number") then return false, "Runtime not a number" end
+    if (runtime <= 0) then return false, "Runtime cannot be zero or negative" end
+
+    -- Check owner
+    if (type(owner) ~= "string") then return false, "Owner not a string" end
+    if (owner == "") then return false, "Owner cannot be empty" end
+
+    local index = 1
+    while yl_announcements.data[index] ~= nil do index = index + 1 end
+
+    local content = {
+        id = index,
+        creation_date = os.time(),
+        message = message,
+        frequency = frequency,
+        runtime = runtime,
+        owner = owner
+    }
+
+    yl_announcements.data[index] = content
+
+    local success = yl_announcements.save_json(index, content)
+
+    if (success == true) then return true, index end
+    return false, "Could not store announcement"
+end
+
+-- /announcement_add message$frequency in minutes$runtime in minutes
+function yl_announcements.formspec(announcement_id)
+
+    -- Check announcement_id
+    if (type(announcement_id) ~= "number") then
+        return false, "Announcement ID is not a number"
+    end
+    if (announcement_id <= 0) then
+        return false, "Announcement ID cannot be zero or negative"
+    end
+
+    local announcement = yl_announcements.get(announcement_id)
+
+    if (announcement == nil) then return false, "No announcement" end
+
+    local m = announcement.message or "message"
+    local f = announcement.frequency or "frequency"
+    local r = announcement.runtime or "runtime"
+
+    local c = "/announcement_add " .. m .. "$" .. f .. "$" .. r
+    local content = minetest.formspec_escape(c .. "\n" .. dump(announcement))
+    local formspec = "formspec_version[6]" .. "size[16,2]" ..
+                         "button_exit[15.4,0.1;0.5,0.5;X;X]" ..
+                         "textarea[0.05,0.05;15.3,1.9;;;" .. content .. "]"
+    return true, formspec
+end
+
+function yl_announcements.delete(announcement_id)
+
+    -- Check announcement_id
+    if (type(announcement_id) ~= "number") then
+        return false, "Announcement ID is not a number"
+    end
+    if (announcement_id <= 0) then
+        return false, "Announcement ID cannot be zero or negative"
+    end
+
+    local success, data = yl_announcements.list()
+
+    if ((success == false) or (data == nil)) then
+        return false, "Could not retrieve list"
+    end
+
+    local announcement = table.copy(data[announcement_id]) or
+                             "No data available"
+
+    if (announcement ~= nil) then
+        data[announcement_id] = nil
+        local success_f, err = yl_announcements.remove_file(announcement_id)
+        if (success_f == nil) then return false, err end
+        success = true
+    end
+
+    if (success ~= true) then
+        announcement = "Could not find announcement with id " ..
+                           dump(announcement_id)
+    end
+    return success, announcement
+end
+
+function yl_announcements.say(announcement_id, target)
+
+    -- Check announcement_id
+    if (type(announcement_id) ~= "number") then
+        return false, "Announcement ID is not a number"
+    end
+    if (announcement_id <= 0) then
+        return false, "Announcement ID cannot be zero or negative"
+    end
+
+    -- No check for target, it is optional
+
     local success = false
-    for _, announcement in pairs(announcements) do
-        if announcement.id ~= a_id then
-            table.insert(data,announcement)
-        else
-            success = true
-        end
-    end
-    if success ~= true then
-        data = "Could not find announcement with id " .. a_id
-    end
-    return success, data
-end
 
-function yl_announcements.copy(a_id)
+    local announcement = yl_announcements.data[announcement_id]
-    local announcement = yl_announcements.get_announcement(a_id)
+
-    local content = minetest.formspec_escape(dump(announcement))
+    if (announcement ~= nil) then
-	local formspec = "formspec_version[6]" ..
+        local color = yl_announcements.settings.colour
-	"size[16,2]" ..
+        local message = announcement.message
-	"button_exit[15.4,0.1;0.5,0.5;X;X]" ..
+        local content = minetest.colorize(color, message)
-	"textarea[0.05,0.05;15.3,1.9;;;" .. 
+
-	content ..
+        if ((target == "*") or (target == nil)) then
-	"]"
+            minetest.chat_send_all(content)
-	return formspec or ""
+        else
-end
+            minetest.chat_send_player(target, content)
+        end
+        success = true
+    end
+
+    if (success ~= true) then
+        announcement = "Could not find announcement with id " ..
+                           dump(announcement_id)
+    end
+    return success, announcement
+end