Merge remote-tracking branch 'origin/master'

async.lua

@@ -27,12 +27,22 @@ function async:new()
 end
 
 --add a task to the kernel
-function async:call(f, args, cb, error_cb)
+function async:call(f, args, callback, error_callback)
 	table.insert(self.tasks, {
 		coroutine.create(f),
-		args,
-		cb,
-		error_cb,
+		args or false,
+		callback or false,
+		error_callback or false,
+	})
+end
+
+--add an already-existing coroutine to the kernel
+function async:add(co, args, callback, error_callback)
+	table.insert(self.tasks, {
+		co,
+		args or false,
+		callback or false,
+		error_callback or false,
 	})
 end
 
@@ -51,13 +61,10 @@ function async:update()
 		end
 	end
 	--run a step
-	local co, args, cb, error_cb = td[1], td[2], td[3], td[4]
-	--(reuse these 8 temps)
-	local a, b, c, d, e, f, g, h
-	if args then
-		a, b, c, d, e, f, g, h = unpack(args)
-	end
-	local success, a, b, c, d, e, f, g, h = coroutine.resume(co, a, b, c, d, e, f, g, h)
+	--(using unpack because coroutine is also nyi and it's core to this async model)
+	local co, args, cb, error_cb = unpack(td)
+	--(8 temps rather than table churn capturing varargs)
+	local success, a, b, c, d, e, f, g, h = coroutine.resume(co, args and unpack(args))
 	--error?
 	if not success then
 		if error_cb then

readme.md

@@ -13,27 +13,30 @@ Examples [in another repo](https://github.com/1bardesign/batteries-examples) to
 - `class` - Single-inheritance oo in a single function.
 - `mathx` - Mathematical extensions. Alias `math`.
 - `tablex` - Table handling extensions. Alias `table`.
+- `stringx` - String handling extensions. Alias `string`.
 - `stable_sort` - A stable sorting algorithm that is also, as a bonus, often faster than table.sort under luajit.
 - `functional` - Functional programming facilities. `map`, `reduce`, `any`, `match`, `minmax`, `mean`...
 - `sequence` - An oo wrapper on sequential tables, so you can do `t:insert(i, v)` instead of `table.insert(t, i, v)`. Also supports method chaining for the `functional` interface above, which can save a lot of typing!
+- `state_machine` - Finite state machine implementation with state transitions and all the rest. Useful for game states, ai, cutscenes...
+- `async` - Async operations as coroutines.
+- `manual_gc` - Get GC out of your update/draw calls. Useful when trying to get accurate profiling information; moves "randomness" of GC. Requires you to think a bit about your garbage budgets though.
+- `colour` - Colour conversion routines. Alias `color`.
+- `unique_mapping` - Generate a unique mapping from arbitrary lua values to numeric keys - essentially making up a consistent ordering for unordered data. Niche, but can be used to optimise draw batches for example, as you can't sort on textures without it.
 - `vec2` - 2d vectors with method chaining, garbage saving interface. A bit of a mouthful at times, but you get used to it.
 - `vec3` - 3d vectors as above.
 - `intersect` - 2d intersection routines, a bit sparse at the moment
-- `unique_mapping` - Generate a unique mapping from arbitrary lua values to numeric keys - essentially making up a consistent ordering for unordered data. Niche, but useful for optimising draw batches for example, as you can't sort on textures without it.
-- `state_machine` - Finite state machine implementation with state transitions and all the rest. Useful for game states, ai, cutscenes...
-- `async` - Async operations as coroutines. 
-- `manual_gc` - Get GC out of your update/draw calls. Really good when trying to get accurate profiling information; no more spikes. Requires you to think a bit about your garbage budgets though.
-- `colour` - Colour conversion routines. Alias `color`.
+
+Aliases are provided at both the `batteries` level and globally when exported.
 
 # Todo/WIP list
 
 Endless, of course :)
 
-- `stringx` - As for `tablex` and `mathx`, would be good to have a more filled out string handling API.
-- `colour` - Bidirectional hsv conversion and friends would fit nicely here.
+- `stringx` - Needs extension, very minimal currently.
+- `colour` - Bidirectional hsv/hsl/etc conversion would fit nicely here.
 - Geometry:
 	- `vec3` - Needs more fleshing out for serious use.
-	- `matrix` - A geometry focussed matrix module would made 3d work nicer. Possibly just `mat4`.
+	- `matrix` - A geometry focussed matrix module would made 3d work a lot nicer. Possibly just `mat4`.
 	- `intersect` - More routines, more optimisation :)
 - Network:
 	- Various helpers for networked systems, game focus of course.
@@ -58,19 +61,19 @@ You are strongly encouraged to use the library in a "fire and forget" manner thr
 
 This eases consumption later on - you don't have to remember if say, `table.remove_value` is built in to lua or not, or get used to accessing the builtin table functions through `batteries.table` or `tablex`.
 
-While this will likely sit badly with anyone who's had "no globals!" hammered into them, I believe for `batteries` (and many foundational libraries) it makes sense to just import once at boot. You're going to be pulling it in almost everywhere anyway; why bother making yourself jump through more hoops.
+While this will likely sit badly with anyone who's had "no globals!" hammered into them, I believe for `batteries` (and many foundational libraries) it makes sense to just import once at boot. You're going to be pulling it in almost everywhere anyway; why bother making yourself jump through more hoops?
 
-You can of course use the separate modules on their own, either with a single require for all of `batteries`, and use through something like `batteries.functional.map`, or requiring individual modules explicitly. This more careful approach _will_ let you be more clear about your dependencies, at the cost of more setup work needing to re-require batteries everywhere, or expose it as a global in the first place.
+You can of course use the separate modules on their own, either with a single require for all of `batteries`, with use through something like `batteries.functional.map`; or requiring individual modules explicitly. This more careful approach _will_ let you be more clear about your dependencies, at the cost of more setup work needing to re-require batteries everywhere, or expose it as a global in the first place.
 
 I'd strongly recommend that if you find yourself frustrated with the above, stop and think why/if you really want to avoid globals for a library intended to be commonly used across your entire codebase! You may wish to reconsider, and save yourself typing `batteries` a few hundred times :)
 
 # Stripping down `batteries`
 
-Many of the modules "just work" on their own if you just want to vendor in something specific.
+Many of the modules "just work" on their own if you just want to grab something specific.
 
 There are some inter-dependencies in the more complex modules, which should be straightforward to detect and figure out the best course of action (include or strip out) if you want to make a stripped-down version for distribution.
 
-Currently the lib is 30kb or so compressed, including the readme, so think carefully whether you really need to worry!
+Currently the lib is 30kb or so compressed, including the readme, so do think carefully whether you really need to worry!
 
 # License
 

tablex.lua

@@ -242,11 +242,11 @@ end
 function tablex.copy(t, deep_or_into)
 	assert(type(t) == "table", "table.copy - argument 't' must be a table")
 	local is_bool = type(deep_or_into) == "boolean"
-	local istablex = type(deep_or_into) == "table"
+	local is_table = type(deep_or_into) == "table"
 
-	local deep = (is_bool and deep_or_into) or istablex
-	local into = istablex and deep_or_into or {}
-	for k,v in pairs(t) do
+	local deep = is_bool and deep_or_into or is_table
+	local into = is_table and deep_or_into or {}
+	for k, v in pairs(t) do
 		if deep and type(v) == "table" then
 			if type(v.copy) == "function" then
 				v = v:copy()
@@ -269,6 +269,29 @@ function tablex.overlay(to, from)
 	return to
 end
 
+--collapse the first level of a table into a new table of reduced dimensionality
+--will collapse {{1, 2}, 3, {4, 5, 6}} into {1, 2, 3, 4, 5, 6}
+--useful when collating multiple result sets, or when you got 2d data when you wanted 1d data.
+--in the former case you may just want to append_inplace though :)
+--note that non-tabular elements in the base level are preserved,
+--	but _all_ tables are collapsed; this includes any table-based types (eg a batteries.vec2),
+--	so they can't exist in the base level
+--	(... or at least, their non-ipairs members won't survive the collapse)
+function tablex.collapse(t)
+	assert(type(t) == "table", "table.collapse - argument 't' must be a table")
+	local r = {}
+	for _, v in ipairs(t) do
+		if type(v) == "table" then
+			for _, v in ipairs(v) do
+				table.insert(r, v)
+			end
+		else
+			table.insert(r, v)
+		end
+	end
+	return r
+end
+
 --faster unpacking for known-length tables up to 8
 --gets around nyi in luajit
 --note: you can use a larger unpack than you need as the rest