From 9b2883030a5c96d0b2ea8042779706aec71a953d Mon Sep 17 00:00:00 2001
From: BuckarooBanzay <BuckarooBanzay@users.noreply.github.com>
Date: Tue, 28 Mar 2023 07:56:52 +0200
Subject: [PATCH] storage format docs

---
 gui.lua            |  3 ---
 storage.lua        | 44 +++++++++++++++++++++++++++++++++++++++++++-
 util/normalize.lua |  6 ------
 3 files changed, 43 insertions(+), 10 deletions(-)

diff --git a/gui.lua b/gui.lua
index 00521ad..c3faff9 100644
--- a/gui.lua
+++ b/gui.lua
@@ -116,7 +116,6 @@ function mail.show_inbox(name)
 
 	if messages[1] then
 		for _, message in ipairs(messages) do
-			mail.ensure_new_format(message, name)
 			if mail.getMessageStatus(name, message.id) == "unread" then
 				if not mail.player_in_list(name, message.to) then
 					formspec[#formspec + 1] = ",#FFD788"
@@ -454,13 +453,11 @@ function mail.show_compose(name, defaultto, defaultsubj, defaultbody, defaultcc,
 end
 
 function mail.reply(name, message)
-	mail.ensure_new_format(message)
 	local replyfooter = "Type your reply here.\n\n--Original message follows--\n" ..message.body
 	mail.show_compose(name, message.sender, "Re: "..message.subject, replyfooter)
 end
 
 function mail.replyall(name, message)
-	mail.ensure_new_format(message)
 	local replyfooter = "Type your reply here.\n\n--Original message follows--\n" ..message.body
 
 	-- new recipients are the sender plus the original recipients, minus ourselves
diff --git a/storage.lua b/storage.lua
index ff8e9d2..df1d450 100644
--- a/storage.lua
+++ b/storage.lua
@@ -5,7 +5,8 @@ function mail.get_storage_entry(playername)
 		return {
 			contacts = {},
 			inbox = {},
-			outbox = {}
+			outbox = {},
+			lists = {}
 		}
 	else
 		-- deserialize existing entry
@@ -13,6 +14,47 @@ function mail.get_storage_entry(playername)
 	end
 end
 
+--[[
+Mail format (inbox, outbox):
+{
+	-- sending player name
+	sender = "",
+	-- receiving player name
+	to = "",
+	-- carbon copy (optional)
+	cc = "",
+	-- blind carbon copy (optional)
+	bcc = "",
+	-- mail subject
+	subject = "",
+	-- mail body
+	body = "",
+	-- timestamp (os.time())
+	time = 1234,
+	-- read-flag (true: player has read the mail, inbox only)
+	read = true
+}
+
+Contact format:
+{
+	-- name of the player
+	name = "",
+	-- note
+	note = ""
+}
+
+Mail-list format:
+{
+	-- name of the maillist
+	name = "",
+	-- description
+	description = "",
+	-- player list (delimited by newline)
+	players = ""
+}
+
+--]]
+
 function mail.set_storage_entry(playername, entry)
 	mail.storage:get_string(playername, minetest.write_json(entry))
 end
diff --git a/util/normalize.lua b/util/normalize.lua
index 5b19a3c..b817068 100644
--- a/util/normalize.lua
+++ b/util/normalize.lua
@@ -59,9 +59,3 @@ function mail.player_in_list(name, list)
     end
     return false
 end
-
-function mail.ensure_new_format(message, name)
-    if message.to == nil then
-        message.to = name
-    end
-end