Improved documentation. Added util.lua

ludobits/m/app.lua

@@ -1,6 +1,7 @@
 --- Module to simplify the use of several of the engine listeners.
 -- The module allows the user to define multiple listeners for the iac, iap,
 -- push and window listeners.
+--
 -- @usage
 -- local app = require "ludobits.app"
 --

ludobits/m/broadcast.lua

@@ -1,4 +1,4 @@
---- Module to simplify sending a message to multiple receivers
+--- Module to simplify sending of a message to multiple receivers
 --
 -- @usage
 --
@@ -7,6 +7,7 @@
 --	local broadcast = require "ludobits.m.broadcast"
 --
 --	function init(self)
+--		-- this script should react to "foo" and "bar" messages
 --		broadcast.register("foo")
 --		broadcast.register("bar", function(message, sender)
 --			-- handle message
@@ -35,6 +36,7 @@
 --
 --	function update(self, dt)
 --		if some condition then
+--			-- broadcast a "foo" message to anyone listening
 --			broadcast.send("foo")
 --		end
 --	end

ludobits/m/file.lua

@@ -2,10 +2,23 @@
 
 local M = {}
 
+--- Fix a filename to ensure that it doesn't contain any illegal characters
+-- @param filename
+-- @return Filename with illegal characters replaced
 function M.fix(filename)
 	filename = filename:gsub("([^0-9a-zA-Z%._ ])", function(c) return string.format("%%%02X", string.byte(c)) end)
 	filename = filename:gsub(" ", "+")
 	return filename
 end
 
-return M
+--- Get an application specific save file path to a filename. The path will be
+-- based on the sys.get_save_file() function and the project title (with whitespace)
+-- replaced by underscore
+-- @param filename
+-- @return Save file path
+function M.get_save_file_path(filename)
+	local path = sys.get_save_file(M.fix(sys.get_config("project.title"):gsub(" ", "_")), filename)
+	return path
+end
+
+return M

ludobits/m/listener.lua

@@ -5,26 +5,31 @@
 --
 --	-- a.script
 --	local listener = require "ludobits.m.listener"
---	
+--
 --	local l = listener.create()
 --
 --	local function handler1(message_id, message)
---		-- will get mymessage1, mymessage2, mymessage3 and foobar
+--		print(message_id)
 --	end
 --
 --	local function handler2(message_id, message)
---		-- will get mymessage1 and mymessage2
+--		print(message_id)
 --	end
 --
+--	-- add listener function handler1 and listen to all messages
 --	l.add(handler1)
+--	-- add listener function handler2 and only listen to "mymessage1" and "mymessage2"
 --	l.add(handler2, "mymessage1")
 --	l.add(handler2, "mymessage2")
 --
+--	-- add listener url "#myscript1" and listen to all messages
 --	l.add(msg.url("#myscript1"))
+--	-- add listener url "#myscript2" and only listen to "mymessage1" and "mymessage2"
 --	l.add(msg.url("#myscript2"), "mymessage1")
 --	l.add(msg.url("#myscript2"), "mymessage2")
 --
 --
+--	-- trigger some messages
 --	l.trigger(hash("mymessage1"), { text = "lorem ipsum" })
 --	l.trigger(hash("mymessage2"), { text = "lorem ipsum" })
 --	l.trigger(hash("mymessage3"), { text = "lorem ipsum" })
@@ -33,12 +38,12 @@
 --
 --	-- myscript1.script
 --	function on_message(self, mesage_id, message, sender)
---		-- will get mymessage1, mymessage2, mymessage3 and foobar
+--		print(message_id)
 --	end
 --
 --	-- myscript2.script
 --	function on_message(self, mesage_id, message, sender)
---		-- will get mymessage1 and mymessage2
+--		print(message_id)
 --	end
 --
 
@@ -62,12 +67,12 @@ end
 function M.create()
 	local any_listeners_url = {}
 	local listeners = {}
-	
+
 	local instance = {}
-	
+
 	--- Add a function or url to invoke when the listener is triggered
 	-- @param url_or_fn_to_add URL or function to call. Can be nil in which case the current URL is used.
-	-- @param message_id Optional message id to filter on 
+	-- @param message_id Optional message id to filter on
 	function instance.add(url_or_fn_to_add, message_id)
 		url_or_fn_to_add = url_or_fn_to_add or msg.url()
 		message_id = message_id and ensure_hash(message_id) or nil
@@ -88,7 +93,7 @@ function M.create()
 		message_id = message_id and ensure_hash(message_id) or nil
 
 		local is_url = type(url_or_fn_to_remove) == "userdata"
-		
+
 		for url_fn,url_fn_listeners in pairs(listeners) do
 			-- make sure to only check against urls if we are removing a url and vice versa
 			if (is_url and type(url_fn) == "userdata") or (not is_url and type(url_fn) ~= "userdata") then
@@ -109,7 +114,7 @@ function M.create()
 			end
 		end
 	end
-	
+
 	--- Trigger this listener
 	-- @param message_id Id of message to trigger
 	-- @param message The message itself (can be nil)
@@ -125,9 +130,9 @@ function M.create()
 			end
 		end
 	end
-	
+
 	return instance
 end
 
 
-return M
+return M

ludobits/m/savefile.lua

@@ -14,18 +14,13 @@ local file = require "ludobits.m.file"
 
 local M = {}
 
-function M.get_path(filename)
-	local path = sys.get_save_file(file.fix(sys.get_config("project.title"):gsub(" ", "_")), filename)
-	return path
-end
-
 --- Open a file for reading and writing using the io.* functions
 -- @param filename
 -- @return file instance
 function M.open(filename)
-	local path = M.get_path(filename)
+	local path = file.get_save_file_path(filename)
 	local instance = {}
-	
+
 	--- Load the table stored in the file
 	-- @return contents File contents or nil if something went wrong
 	-- @return error_message Error message if something went wrong while reading
@@ -36,7 +31,7 @@ function M.open(filename)
 		end
 		return f:read("*a")
 	end
-	
+
 	--- Save string to the file
 	-- @param s The string to save
 	-- @return success
@@ -50,10 +45,10 @@ function M.open(filename)
 		f:write(s)
 		return true
 	end
-	
+
 	return instance
 end
 
 
 
-return M
+return M

ludobits/m/savetable.lua

@@ -15,24 +15,19 @@ local file = require "ludobits.m.file"
 
 local M = {}
 
-function M.get_path(filename)
-	local path = sys.get_save_file(file.fix(sys.get_config("project.title"):gsub(" ", "_")), filename)
-	return path
-end
-
 --- Open a file for reading and writing using sys.save and sys.load
 -- @param filename
 -- @return file instance
 function M.open(filename)
-	local path = M.get_path(filename)
+	local path = file.get_save_file_path(filename)
 	local instance = {}
-	
+
 	--- Load the table stored in the file
 	-- @return File contents
 	function instance.load()
 		return sys.load(path)
 	end
-	
+
 	--- Save table to the file
 	-- @param t The table to save
 	-- @return success
@@ -45,10 +40,10 @@ function M.open(filename)
 		end
 		return true
 	end
-	
+
 	return instance
 end
 
 
 
-return M
+return M

ludobits/m/simple_input.lua

@@ -1,9 +1,38 @@
+-- Simple input handler for gui nodes. Register nodes and pass any call to
+-- on_input() to this module and it will automatically do picking and invoke
+-- a registered callback. Example:
+--
+-- local simple_input = require "ludobits.m.simple_input"
+--
+-- function init(self)
+-- 		simple_input.acquire()
+--
+-- 		simple_input.register(gui.get_node("blue"), function()
+-- 			print("blue")
+-- 		end)
+--
+-- 		simple_input.register("green", function()
+-- 			print("green")
+-- 			local scale = math.random(1, 5)
+-- 			gui.set_scale(gui.get_node("blue"), vmath.vector3(scale, scale, 1))
+-- 		end)
+-- end
+--
+-- function final(self)
+-- 		simple_input.release()
+-- end
+--
+-- function on_input(self, action_id, action)
+-- 		simple_input.on_input(action_id, action)
+-- end
+
+
 local M = {}
 
 local registered_nodes = {}
 
 local function ensure_node(node_or_node_id)
-	return type(node_or_node_id) == "string" and gui.get_node(node_or_node_id) or node_or_node_id 
+	return type(node_or_node_id) == "string" and gui.get_node(node_or_node_id) or node_or_node_id
 end
 
 --- Convenience function to acquire input focus
@@ -86,4 +115,4 @@ function M.on_input(action_id, action)
 	return false
 end
 
-return M
+return M

ludobits/m/util.lua

@@ -0,0 +1,23 @@
+local M = {}
+
+
+function M.lerp(a, b, t)
+	return a + (b - a) * t
+end
+
+
+function M.shuffle(t)
+	local size = #t
+	for i = size, 1, -1 do
+		local rand = math.random(size)
+		t[i], t[rand] = t[rand], t[i]
+	end
+	return t
+end
+
+
+function M.random(list)
+	return list[math.random(1, #list)]
+end
+
+return M