Permalink
Browse files

Commenting lua code

  • Loading branch information...
1 parent b993eeb commit 2917e41165c9b2386070cad52218b42f7d7f6f8d @ludamad committed Apr 4, 2013
Showing with 137 additions and 38 deletions.
  1. +20 −2 res/InstanceBox.lua
  2. +18 −4 res/InstanceGroup.lua
  3. +27 −7 res/InstanceLine.lua
  4. +23 −6 res/utils.lua
  5. +10 −4 res/utils_draw.lua
  6. +27 −14 res/utils_general.lua
  7. +12 −1 res/utils_math.lua
View
@@ -3,34 +3,50 @@
require "utils"
require "InstanceGroup"
+--- A layout consisting of objects placed on a grid.
+-- Each object can be placed with an origin, as well as an optional offset.
+-- Objects that are stored should have 'step' and 'draw' methods that take a position, as well as a 'size' member.
+-- @usage InstanceBox.create({ size = {640,480} })
InstanceBox = newtype()
+--- Initializes a new InstanceBox.
+-- @usage InstanceBox.create({ size = {640,480} })
function InstanceBox:init(params)
self._instances = InstanceGroup.create()
self.size = params.size
end
+--- Calls step on all contained objects.
function InstanceBox:step(xy)
self._instances:step(xy)
end
+--- Calls draw on all contained objects.
function InstanceBox:draw(xy)
self._instances:draw(xy)
DEBUG_BOX_DRAW(self, xy)
end
+--- Removes the contained object 'obj'.
function InstanceBox:remove(obj)
self._instances:remove(obj)
end
+--- Removes all contained objects.
function InstanceBox:clear()
self._instances:clear()
end
-function InstanceBox:instances(xy)
+--- Return an iterable that iterates over all objects and their positions.
+-- @param xy <i>optional, default {0,0}</i>
+-- @usage for obj, xy in instance_box:instances({100,100}) do ... end
+function InstanceBox:instances( --[[Optional]] xy)
return self._instances:instances(xy)
end
+--- Add an object to this container.
+-- @param origin the origin to align against, eg LEFT_TOP, RIGHT_BOTTOM.
+-- @param offset <i>optional, default {0,0}</i> a position offset for the object.
function InstanceBox:add_instance(obj, origin, --[[Optional]] offset)
assert( origin_valid(origin), "InstanceBox: Expected origin coordinates between [0,0] and [1,1]")
@@ -45,10 +61,12 @@ function InstanceBox:add_instance(obj, origin, --[[Optional]] offset)
self._instances:add_instance( obj, xy )
end
+--- Whether the mouse is within the InstanceBox.
function InstanceBox:mouse_over(xy)
return mouse_over(xy, self.size)
end
+--- A simple string representation for debugging purposes.
function InstanceBox:__tostring()
return "[InstanceBox " .. toaddress(self) .. "]"
-end
+end
View
@@ -2,17 +2,25 @@
-- Keeps track of instances + relative positions
-- Tries to store & resolve relative positions in a somewhat efficient manner
+--- A layout utility that stores relative positions of objects.
+-- Each object can be placed with an origin, as well as an optional offset.
+-- Objects that are stored should have 'step' and 'draw' methods that take a position.
+-- @usage InstanceGroup.create()
InstanceGroup = newtype()
+--- Initializes a new instance group.
+-- @usage InstanceGroup.create()
function InstanceGroup:init()
self._instances = {}
end
--- Requires 'obj' to have 'size' member if 'origin' is specified
+--- Add an object to this container.
+-- @param xy the origin to align against, eg LEFT_TOP, RIGHT_BOTTOM.
function InstanceGroup:add_instance(obj, xy )
self._instances[#self._instances + 1] = { obj, xy }
end
+--- Calls step on all contained objects.
function InstanceGroup:step(xy)
local step_xy = {} -- shared array for performance
@@ -26,14 +34,17 @@ function InstanceGroup:step(xy)
end
end
--- Iterate the values in a fairly implementation-change-proof way
+--- Return an iterable that iterates over all objects and their positions.
+-- @param xy <i>optional, default {0,0}</i>
+-- @usage for obj, xy in instance_group:instances({100,100}) do ... end
function InstanceGroup:instances(xy)
xy = xy or {0,0}
local adjusted_xy = {} -- shared array for performance
local iter = values(self._instances)
+ -- Iterate the values in a fairly future-proof way, via a helper closure
return function()
local val = iter()
@@ -50,6 +61,7 @@ function InstanceGroup:instances(xy)
end
end
+--- Removes the contained object 'obj'.
function InstanceGroup:remove(obj)
local insts = self._instances
@@ -63,10 +75,12 @@ function InstanceGroup:remove(obj)
return false
end
+--- Removes all contained objects.
function InstanceGroup:clear()
self._instances = {}
end
+--- Calls draw on all contained objects.
function InstanceGroup:draw(xy)
local draw_xy = {} -- shared array for performance
@@ -80,7 +94,7 @@ function InstanceGroup:draw(xy)
end
end
-
+--- A simple string representation for debugging purposes.
function InstanceGroup:__tostring()
return "[InstanceGroup " .. toaddress(self) .. "]"
-end
+end
View
@@ -2,8 +2,17 @@
require "InstanceGroup"
-InstanceLine = newtype( )
-
+--- A layout consisting of objects placed on one or multiple lines.
+-- Each object can be placed with an optional offset.
+-- Objects that are stored should have 'step' and 'draw' methods that take a position, as well as a 'size' member.
+-- @usage For example, InstanceLine.create( {dx = 32} ) or InstanceLine.create( {dx = 32, per_row = 3, dy = 32} )
+InstanceLine = newtype()
+
+--- Initializes a new InstanceLine. Takes an argument table.
+-- params.force_size overrides the size the layout is considered. Otherwise it is dynamic.
+-- params.dx is manditory, specifying spacing of elements on the line.
+-- params.per_row & params.dy must be passed together or not at all, and specify how to arrange elements into a grid.
+-- @usage For example, InstanceLine.create( {dx = 32} ) or InstanceLine.create( {dx = 32, per_row = 3, dy = 32} )
function InstanceLine:init(params)
assert( params.dx,
"InstanceLine.create expects a 'dx' member to indicate spacing of elements.")
@@ -23,6 +32,12 @@ function InstanceLine:init(params)
self.per_row = --[[Optional]] params.per_row or false
end
+--- Removes the contained object 'obj'
+function InstanceLine:remove(obj)
+ self._instances:remove(obj)
+end
+
+--- Removes all contained objects.
function InstanceLine:clear()
self._instances:clear()
self.position = {0, 0}
@@ -32,20 +47,18 @@ function InstanceLine:clear()
end
end
-function InstanceLine:remove(obj)
- self._instances:remove(obj)
-end
-
+--- Calls step on all contained objects.
function InstanceLine:step(xy)
self._instances:step(xy)
end
+--- Calls draw on all contained objects.
function InstanceLine:draw(xy)
self._instances:draw(xy)
DEBUG_BOX_DRAW(self, xy)
end
--- Moves the next location
+--- Moves to the next location, as if an instance were added.
function InstanceLine:skip_location()
local nx, ny = unpack(self.position)
@@ -59,10 +72,15 @@ function InstanceLine:skip_location()
end
end
+--- Return an iterable that iterates over all objects and their positions.
+-- @param xy <i>optional, default {0,0}</i>
+-- @usage for obj, xy in instance_line:instances({100,100}) do ... end
function InstanceLine:instances(xy)
return self._instances:instances(xy)
end
+--- Add an object to the current line, starting a new one if per_row was passed and has been exceeded.
+-- @param offset <i>optional, default {0,0}</i> a position offset for the object.
function InstanceLine:add_instance(obj, --[[Optional]] offset)
local x, y = unpack(offset or {0,0})
@@ -79,10 +97,12 @@ function InstanceLine:add_instance(obj, --[[Optional]] offset)
self:skip_location()
end
+--- Whether the mouse is within the InstanceLine.
function InstanceLine:mouse_over(xy)
return mouse_over(xy, self.size)
end
+--- A simple string representation for debugging purposes.
function InstanceLine:__tostring()
return "[InstanceLine " .. toaddress(self) .. "]"
end
View
@@ -1,24 +1,41 @@
+-- Use this include when you want util_* functions.
+-- As well as including those, it defines some additional ad-hoc utility functions.
+
require "utils_general"
require "utils_math"
require "utils_draw"
-- More ad hoc utilities without a home, yet:
+--- Return whether the mouse is within a bounding box.
function bbox_mouse_over(bbox, origin)
- return bbox_contains( shift_origin(bbox, origin or LEFT_TOP), mouse_xy )
+ return bbox_contains( shift_origin(bbox, origin or LEFT_TOP), mouse_xy )
end
+--- Return whether the mouse is within a bounding box defined by xy and size.
function mouse_over(xy, size, origin)
return bbox_mouse_over(bbox_create(xy, size), origin)
end
+--- Return a dummy sound or music object if the given file does not exist.
+-- Otherwise return the result of 'loader' on the file.
+local function snd_optional_load(file, loader)
+ if not file_exists(file) then
+ return {
+ play = function() end,
+ loop = function() end
+ }
+ end
+ return loader(file)
+end
--- Returns a dummy object if the file doesn't exist
+--- Returns a dummy object if the file doesn't exist
function music_optional_load(file)
- return optional_load(file, music_load)
+ return snd_optional_load(file, music_load)
end
--- Returns a dummy object if the file doesn't exist
+
+--- Returns a dummy object if the file doesn't exist
function sound_optional_load(file)
- return optional_load(file, sound_load)
-end
+ return snd_optional_load(file, sound_load)
+end
View
@@ -1,6 +1,7 @@
require "utils_general" -- for 'memoized'
--- Draw parts of text colored differently
+--- Draw parts of text colored differently
+-- @usage draw_colored_parts(font, LEFT_TOP, {0,0}. {COL_RED, "hi "}, {COL_BLUE, "there"} )
function draw_colored_parts(font, origin, xy, ...)
local rx, ry = 0, 0
@@ -28,26 +29,31 @@ function draw_colored_parts(font, origin, xy, ...)
return rx -- return final width for further chaining
end
+--- Load a font, first checking if it exists in a cache
font_cached_load = memoized(font_load)
+--- Load an image, first checking if it exists in a cache
image_cached_load = memoized(image_load)
-local DEBUG_FONT = font_cached_load(settings.menu_font, 10)
-
+-- Used for debug information overlay
function DEBUG_BOX_DRAW(self, xy)
+ debug_font = font_cached_load(settings.menu_font, 10)
if DEBUG_LAYOUTS then
local mouse_is_over = mouse_over(xy, self.size)
local color = mouse_is_over and COL_PALE_BLUE or COL_YELLOW
local line_width = mouse_is_over and 5 or 2
local alpha = mouse_is_over and 0.5 or 0.25
if mouse_is_over then
- DEBUG_FONT:draw( { color = COL_WHITE, origin = LEFT_BOTTOM }, xy, tostring(self) )
+ debug_font:draw( { color = COL_WHITE, origin = LEFT_BOTTOM }, xy, tostring(self) )
end
draw_rectangle_outline(with_alpha(color, alpha), bbox_create(xy, self.size), line_width )
end
end
+--- Takes a color, and returns a color with a transparency of 'alpha'
+-- Colors that already have an alpha will be made more transparent.
+-- @usage with_alpha(COL_WHITE, 0.5)
function with_alpha(col, alpha) -- Don't mutate, we might be passed a colour constant!
local copy = { unpack(col) }
-- Assume we have at least 3 components, but may have 4
View
@@ -1,11 +1,20 @@
--- General lua utility code.
+-- Utility code that can apply to lua programming in general.
-function do_nothing()
- -- does nothing
-end
+--- Does nothing.
+--@usage dummy_object = { step = do_nothing, draw = do_nothing }
+function do_nothing() end
+--- Wraps a function around a memoizing weak table.
+-- Function results will be stored until they are no longer referenced.
--
-function memoized(func, separator)
+-- Note: This is intended for functions returning heavy-weight objects,
+-- such as images. Functions that return primitives will not interact
+-- correctly with the garbage collection.
+--
+-- @param func the function to memoize, arguments must be strings or numbers
+-- @param separator <i>optional, default ';'</i>, the separator used when joining arguments to form a string key
+-- @usage new_load = memoized(load)
+function memoized(func, --[[Optional]] separator)
local cache = {}
setmetatable( cache, {__mode = "kv"} ) -- Make table weak
@@ -22,12 +31,20 @@ function memoized(func, separator)
end
end
+--- Return whether a file with the specified name exists.
+-- More precisely, returns whether the given file can be opened for reading.
function file_exists(name)
local f = io.open(name,"r")
if f ~= nil then io.close(f) end
return f ~= nil
end
+--- Get a human-readable string from a lua value. The resulting value is generally valid lua.
+-- Note that the paramaters should typically not used directly, except for perhaps 'packed'.
+-- @param val the value to pretty-print
+-- @param tabs <i>optional, default 0</i>, the level of indentation
+-- @param packed <i>optional, default false</i>, if true, minimal spacing is used
+-- @param quote_strings <i>optional, default true</i>, whether to print strings with spaces
function pretty_tostring(val, --[[Optional]] tabs, --[[Optional]] packed, --[[Optional]] quote_strings)
tabs = tabs or 0
quote_strings = (quote_strings == nil) or quote_strings
@@ -71,16 +88,12 @@ function pretty_tostring(val, --[[Optional]] tabs, --[[Optional]] packed, --[[Op
return table.concat(parts)
end
+--- Get a human-readable string from a lua value. The resulting value is generally valid lua.
+-- Note that the paramaters should typically not used directly, except for perhaps 'packed'.
+-- @param val the value to pretty-print
+-- @param tabs <i>optional, default 0</i>, the level of indentation
+-- @param packed <i>optional, default false</i>, if true, minimal spacing is used
function pretty_print(val, --[[Optional]] tabs, --[[Optional]] packed)
print(pretty_tostring(val, tabs, packed))
end
-function optional_load(file, loader)
- if not file_exists(file) then
- return {
- play = function() end,
- loop = function() end
- }
- end
- return loader(file)
-end
Oops, something went wrong.

0 comments on commit 2917e41

Please sign in to comment.