From 86f6923b7270cf10dc49051abb0df5e314b151e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20P=C3=A9rez-Cerezo?= <gabriel@gpcf.eu>
Date: Fri, 16 Feb 2018 14:24:27 +0100
Subject: Added reason to unban, documented API changes

---
 README.md        |  4 ++--
 doc/API.md       | 37 +++++++++++++++++++++++++++++++++++--
 doc/dbformat.txt |  2 ++
 init.lua         | 10 +++++-----
 4 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 90eed0d..0f39ec3 100644
--- a/README.md
+++ b/README.md
@@ -47,9 +47,9 @@ up. For example, `1Y3M3D7h` will ban for 1 year, 3 months, 3 days and 7 hours.
 
 Unbans a player.
 
-**Usage:** `/xunban <player_or_ip>`
+**Usage:** `/xunban <player_or_ip> <reason>`
 
-**Example:** `/xunban Joe`
+**Example:** `/xunban Joe has promised not to grief again`
 
 ### `xban_record`
 
diff --git a/doc/API.md b/doc/API.md
index bee7c42..2353cb4 100644
--- a/doc/API.md
+++ b/doc/API.md
@@ -16,14 +16,47 @@ Ban a player and all of his/her alternative names and IPs.
 
 ### unban_player
 
-`xban.unban_player(player_or_ip, source)`
+`xban.unban_player(player_or_ip, source, reason)`
+
+Unban a player and all of his/her alternative names and IPs.  A reason
+may be given for this unbanning, so other moderators can follow your
+thoughts.
 
-Unban a player and all of his/her alternative names and IPs.
 
 #### Arguments:
 
 * `player_or_ip` - Player to search for and unban.
 * `source` - Source of the ban. See note 2 below.
+* `reason` - Reason for unbanning.
+
+### add_record:
+
+`xban.add_record(player, record)`
+
+Adds a record to the player's criminal record.
+
+#### Arguments:
+
+* `player` - Name of a player
+* `record` - a xban record (see below)
+
+### Player record format:
+
+
+	local record = {
+      source = "admin",
+      time = os.time(),
+      expires = nil,
+      reason = "bad behaviour",
+      type = "ban",
+	}
+
+* `source` - who issued the record
+* `time` - time at which the record was issued
+* `expires` - time at which the record expires, `nil` for never
+* `reason` - reason for record
+* `type` - type of record.
+
 
 ### Notes
 
diff --git a/doc/dbformat.txt b/doc/dbformat.txt
index 71b25a5..a16737d 100644
--- a/doc/dbformat.txt
+++ b/doc/dbformat.txt
@@ -29,11 +29,13 @@ Each entry contains following fields:
 			reason = "qwerty",
 			time = 12341234,
 			expires = 43214321,
+			type = "ban"
 		},
 		[1] = {
 			source = "asdf",
 			reason = "Unbanned",  -- When unbanned
 			time = 12341234,
+			type = "unban"
 		},
 	},
 }
diff --git a/init.lua b/init.lua
index 91c03be..fb132d0 100644
--- a/init.lua
+++ b/init.lua
@@ -123,7 +123,7 @@ function xban.ban_player(player, source, expires, reason) --> bool, err
 	return true
 end
 
-function xban.unban_player(player, source) --> bool, err
+function xban.unban_player(player, source, reason) --> bool, err
 	local e = xban.find_entry(player)
 	if not e then
 		return nil, "No such entry"
@@ -131,7 +131,7 @@ function xban.unban_player(player, source) --> bool, err
 	local rec = {
 		source = source,
 		time = os.time(),
-		reason = "Unbanned",
+		reason = (reason or ""),
 		type = "unban"
 	}
 	table.insert(e.record, rec)
@@ -260,16 +260,16 @@ minetest.register_chatcommand("xtempban", {
 
 minetest.register_chatcommand("xunban", {
 	description = "XUnBan a player",
-	params = "<player_or_ip>",
+	params = "<player_or_ip> <reason>",
 	privs = { ban=true },
 	func = function(name, params)
-		local plname = params:match("%S+")
+		local plname, reason = params:match("(%S+)%s+(.+)")
 		if not plname then
 			minetest.chat_send_player(name,
 			  "Usage: /xunban <player_or_ip>")
 			return
 		end
-		local ok, e = xban.unban_player(plname, name)
+		local ok, e = xban.unban_player(plname, name, reason)
 		return ok, ok and ("Unbanned %s."):format(plname) or e
 	end,
 })
-- 
cgit v1.2.3