Sethome: Create global functions set_home, go_home and get_home

- Modify game_api.txt (documentation)
- Add three global functions in sethome : go_home, set_home and get_home, thus providing an already working home system for modders
- Clean and improve some pieces of the original code

game_api.txt

@@ -160,6 +160,32 @@ on_rotate(pos, node, user, mode, new_param2)
 ^ use on_rotate = screwdriver.disallow to always disallow rotation
 ^ use on_rotate = screwdriver.rotate_simple to allow only face rotation
 
+Sethome's API
+--------------
+The Sethome API allows modders to use sethome's system in their own mods with the help of three functions :
+
+home.set(name, pos)
+ -> Sets the home position for player 'name' to the given position 'pos' or the player's
+    current position of pos is 'nil' or something other than a table, and only if that
+    player exists and is logged in when the function is used
+ -> name: String which is the name of the player whose home position will be changed
+ -> pos: Standard 'pos' table : {x = x, y = y, z = z}
+ -> Returns true when it has succeeded, false when it has failed, and a message meant to be send to
+    the player
+
+home.go(name)
+ -> Teleports the player 'name' to their home position. If no home position is known
+    for player 'name' then the function will return false
+ -> name: String which is the name of the player to teleport
+ -> Returns true when it has succeeded, false when it has failed, along with a message meant to be
+    sent to the player
+
+home.get(name)
+ -> Returns the home position of player 'name' within the form of a standard 'pos' table : 
+    {x = x, y = y, z = z}
+ -> If no position is know for the player then the function will return nil
+ -> name: String which is the name of the player whose home position will be returned
+
 Stairs API
 ----------
 The stairs API lets you register stairs and slabs and ensures that they are registered the same way as those

mods/sethome/init.lua

@@ -1,3 +1,4 @@
+home = {} -- Global namespace
 local homes_file = minetest.get_worldpath() .. "/homes"
 local homepos = {}
 
@@ -24,42 +25,59 @@ loadhomes()
 
 minetest.register_privilege("home", "Can use /sethome and /home")
 
-local changed = false
+function home.go(name)
+	local player = minetest.get_player_by_name(name)
+	if not player then
+		-- just a check to prevent the server crashing
+		return false, "Player " .. name .. " not found"
+	end
+	if homepos[name] then
+		player:setpos(homepos[name])
+		return true, "Teleported to home!"
+	else
+		return false, "Set a home using /sethome"
+	end
+end
 
 minetest.register_chatcommand("home", {
-    description = "Teleport you to your home point",
-    privs = {home=true},
-    func = function(name)
-        local player = minetest.get_player_by_name(name)
-        if player == nil then
-            -- just a check to prevent the server crashing
-            return false
-        end
-        if homepos[player:get_player_name()] then
-            player:setpos(homepos[player:get_player_name()])
-            minetest.chat_send_player(name, "Teleported to home!")
-        else
-            minetest.chat_send_player(name, "Set a home using /sethome")
-        end
-    end,
+	description = "Teleport you to your home point",
+	privs = {home=true},
+	func = function(name)
+		return home.go(name)
+	end,
 })
 
+function home.set(name, pos)
+	if type(pos) ~= "table" then
+		local player = minetest.get_player_by_name(name)
+		if not player then
+			return false, "No position given and player is offline"
+		end
+		pos = player:getpos()
+	end
+
+	homepos[name] = pos
+
+	local output, err = io.open(homes_file, "w")
+	if output then
+		for i, v in pairs(homepos) do
+			output:write(v.x.." "..v.y.." "..v.z.." "..i.."\n")
+		end
+		output:close()
+	else
+		minetest.log("warning", "Couldn't open sethome's home file for saving positions : " .. err)
+	end
+	return true, "Home set!"
+end
+
 minetest.register_chatcommand("sethome", {
-    description = "Set your home point",
-    privs = {home=true},
-    func = function(name)
-        local player = minetest.get_player_by_name(name)
-        local pos = player:getpos()
-        homepos[player:get_player_name()] = pos
-        minetest.chat_send_player(name, "Home set!")
-        changed = true
-        if changed then
-        	local output = io.open(homes_file, "w")
-            for i, v in pairs(homepos) do
-                output:write(v.x.." "..v.y.." "..v.z.." "..i.."\n")
-            end
-            io.close(output)
-            changed = false
-        end
-    end,
+	description = "Set your home point",
+	privs = {home=true},
+	func = function(name)
+		return home.set(name)
+	end,
 })
+
+function home.get(name)
+	return homepos[name]
+end