/zoeplat

-- Section: Globals

-- Variable: the
-- This is a repository table for the current app, view, keys, and mouse.
-- You can use this for other objects that are useful to track. This should
-- be considered read-only; references here are for convenience and changing
-- things here will have no effect.
the = {}

-- Constant: STRICT
-- If set to true, then Zoetrope will do some extra checking for obvious
-- errors at the expense of some performance. Some of these checks will
-- throw errors, while others will simply print a warning to the console.
-- If you are going to use this, make sure to do so before your project's
-- require 'zoetrope' statement.

-- Constant: DEBUG
-- If set to true, Zoetrope's debug console will be enabled. If you are
-- going to use this, make sure to do so before your project's require
-- 'zoetrope' statement.

-- Constant: NEARLY_ZERO
-- Any number less than this is considered 0 by Zoetrope.
NEARLY_ZERO = 0.0001

-- Constant: UP
-- Directional constant corresponding to up.
UP = 'up'

-- Constant: DOWN
-- Directional constant corresponding to down.
DOWN = 'down'

-- Constant: LEFT
-- Directional constant corresponding to left.
LEFT = 'left'

-- Constant: RIGHT
-- Directional constant corresponding to right.
RIGHT = 'right'


-- Function: trim
-- trim() implementation for strings via http://lua-users.org/wiki/stringtrim
-- 
-- Arguments:
-- 		source - source string
--
-- Returns:
-- 		string trimmed of leading and trailing whitespace

function trim (source)
	return source:gsub("^%s*(.-)%s*$", "%1")
end

-- Function: split
-- split() implementation for strings via http://lua-users.org/wiki/splitjoin
--
-- Arguments:
--		source - source string
--		pattern - Lua pattern to split on, see http://www.lua.org/pil/20.1.html
--
-- Returns:
-- 		table of split strings	

function split (source, pattern)
	assert(type(source) == 'string', 'source must be a string')
	assert(type(pattern) == 'string', 'pattern must be a string')
	
	local result = {}
	local searchStart = 1
	local splitStart, splitEnd = string.find(source, pattern, searchStart)
	
	while splitStart do
		table.insert(result, string.sub(source, searchStart, splitStart - 1))
		searchStart = splitEnd + 1
		splitStart, splitEnd = string.find(source, pattern, searchStart)
	end
	
	table.insert(result, string.sub(source, searchStart))
	return result
end

-- Function: tovalue
-- Coerces, if possible, a string to a boolean or number value.
-- If the string cannot be coerced to either of these types, this
-- returns the same string passed.
--
-- Arguments:
--		source - string to coerce
--
-- Returns:
--		number, boolean, or string

function tovalue (source)
	if source == 'true' then return true end
	if source == 'false' then return false end

	return tonumber(source) or source
end

-- Function: sound
-- Loads a sound but does not play it. It's important to use the hint property
-- appropriately; if set incorrectly, it can cause sound playback to stutter or lag.
--
-- Arguments:
--		path - string pathname to sound
--		hint - either 'short' or 'long', depending on length of sound; default 'short'
--
-- Returns:
--		LOVE sound source, see https://love2d.org/wiki/Source

function sound (path, hint)
	return love.audio.newSource(Cached:sound(path, hint or 'short'))
end

-- Function: playSound
-- Plays a sound once. This is the easiest way to play a sound. It's important
-- to use the hint property appropriately; if set incorrectly, it can cause sound
-- playback to stutter or lag.
--
-- Arguments:
--		path - string pathname to sound
--		volume - volume to play at, from 0 to 1; default 1
--		hint - either 'short' or 'long', depending on length of sound; default 'short'
--
-- Returns:
--		LOVE sound source, see https://love2d.org/wiki/Source

function playSound (path, volume, hint)
	volume = volume or 1
	local source = sound(path, hint)
	source:setVolume(volume)
	source:play()
	return source
end

-- Function: searchTable
-- Returns the index of a value in a table. If the value
-- does not exist in the table, this returns nil.
--
-- Arguments:
--		table - table to search
--		search - value to search for
--
-- Returns:
--		integer index or nil

function searchTable (table, search)
	for i, value in ipairs(table) do
		if value == search then return i end
	end

	return nil
end

-- Function: copyTable
-- Returns a superficial copy of a table. If it contains a 
-- reference to another table in one of its properties, that
-- reference will be copied shallowly. 
--
-- Arguments:
-- 		source - source table
--
-- Returns:
-- 		new table

function copyTable (source)
	assert(type(source) == 'table', "asked to copy a non-table")

	local result = {}
	setmetatable(result, getmetatable(source))
	
	for key, value in pairs(source) do
		result[key] = value
	end
	
	return result
end

-- Function: shuffleTable
-- Shuffles the contents of a table in place.
-- via http://www.gammon.com.au/forum/?id=9908
--
-- Arguments:
--		table - table to shuffle
--
-- Returns:
--		table passed

function shuffleTable (table)
  local n = #table
 
  while n >= 2 do
    -- n is now the last pertinent index
    local k = math.random(n) -- 1 <= k <= n
    -- Quick swap
    table[n], table[k] = table[k], table[n]
    n = n - 1
  end
 
  return table
end

-- Function: dump
-- Returns a string representation of a variable in a way
-- that can be reconstituted via loadstring(). Yes, this
-- is basically a serialization function, but that's so much
-- to type :) This ignores any userdata, functions, or circular
-- references.
-- via http://www.lua.org/pil/12.1.2.html
--
-- Arguments:
--		source - variable to describe
--		ignore - a table of references to ignore (to avoid cycles),
--				 defaults to empty table. This uses the references as keys,
--				 *not* as values, to speed up lookup.
--
-- Returns:
--		string description

function dump (source, ignore)
	ignore = ignore or { source = true }
	local sourceType = type(source)
	
	if sourceType == 'table' then
		local result = '{ '

		for key, value in pairs(source) do
			if not ignore[value] then
				local dumpValue = dump(value, ignore)

				if dumpValue ~= '' then
					result = result .. '["' .. key .. '"] = ' .. dumpValue .. ', '
				end

				if type(value) == 'table' then
					ignore[value] = true
				end
			end
		end

		if result ~= '{ ' then
			return string.sub(result, 1, -3) .. ' }'
		else
			return '{}'
		end
	elseif sourceType == 'string' then
		return string.format('%q', source)
	elseif sourceType ~= 'userdata' and sourceType ~= 'function' then
		return tostring(source)
	else
		return ''
	end
end

bind = function (...)
	return Cached:bind(...)
end