lume/README.md

Lume

A collection of functions for Lua, geared towards game development.

Installation

The lume.lua file should be dropped into an existing project and required by it:

lume = require "lume"

Function Reference

lume.clamp(x, min, max)

Returns the number x clamped between the numbers min and max

lume.round(x [, increment])

Rounds x to the nearest integer; rounds away from zero if we're midway between two integers. If increment is set then the number is rounded to the nearest increment.

lume.round(2.3) -- Returns 2
lume.round(123.4567, .1) -- Returns 123.5

lume.sign(x)

Returns 1 if x is 0 or above, returns -1 when x is negative.

lume.lerp(a, b, amount)

Returns the linearly interpolated number between a and b, amount should be in the range of 0 - 1; if amount is outside of this range it is clamped.

lume.lerp(100, 200, .5) -- Returns 150

lume.smooth(a, b, amount)

Similar to lume.lerp() but uses cosine interpolation instead of linear interpolation.

lume.pingpong(x)

Ping-pongs the number x between 0 and 1.

lume.distance(x1, y1, x2, y2 [, squared])

Returns the distance between the two points. If squared is true then the squared distance is returned -- this is faster to calculate and can still be used when comparing distances.

lume.angle(x1, y1, x2, y2)

Returns the angle between the two points.

lume.random([a [, b]])

Returns a random number between a and b. If only a is supplied a number between 0 and a is returned. If no arguments are supplied a random number between 0 and 1 is returned.

lume.randomchoice(t)

Returns a random value from array t. If the array is empty an error is raised.

lume.randomchoice({true, false}) -- Returns either true or false

lume.weightedchoice(t)

Takes the argument table t where the keys are the possible choices and the value is the choice's weight. A weight should be 0 or above, the larger the number the higher the probability of that choice being picked. If the table is empty, a weight is below zero or all the weights are 0 then an error is raised.

lume.weightedchoice({ ["cat"] = 10, ["dog"] = 5, ["frog"] = 0 })
-- Returns either "cat" or "dog" with "cat" being twice as likely to be chosen.

lume.shuffle(t)

Shuffles the values of array t in place, returns the array.

lume.array(...)

Iterates the supplied iterator and returns an array filled with the values.

lume.array(pairs({a = 1, b = 2})) -- Returns {"a", "b"}

lume.each(t, fn, ...)

Iterates the table t and calls the function fn on each value followed by the supplied additional arguments; if fn is a string the method of that name is called for each value. The function returns t unmodified.

lume.each({1, 2, 3}, print) -- Prints "1", "2", "3" on separate lines
lume.each({a, b, c}, "move", 10, 20) -- Does x:move(10, 20) on each value

lume.map(t, fn)

Applies the function fn to each value in table t and returns a new table with the resulting values.

lume.map({1, 2, 3}, function(x) return x * 2 end) -- Returns {2, 4, 6}

lume.all(t [, fn])

Returns true if all the values in t table are true. If a fn function is supplied it is called on each value, true is returned if all of the calls to fn return true.

lume.all({1, 2, 1}, function(x) return x == 1 end) -- Returns false

lume.any(t [, fn])

Returns true if any of the values in t table are true. If a fn function is supplied it is called on each value, true is returned if any of the calls to fn return true.

lume.any({1, 2, 1}, function(x) return x == 1 end) -- Returns true

lume.reduce(t, fn [, first])

Applies fn on two arguments cumulative to the items of the array t, from left to right, so as to reduce the array to a single value. If a first value is specified the accumulator is initialised to this, otherwise the first value in the array is used. If the array is empty and no first value is specified an error is raised,

lume.reduce({1, 2, 3}, function(a, b) return a + b end) -- Returns 6

lume.set(t [, retainkeys])

Returns a copy of the t table with all the duplicate values removed. If retainkeys is true the table is not treated as an array and retains its original keys.

lume.set({2, 1, 2, "cat", "cat"}) -- Returns {1, 2, cat}

lume.filter(t, fn [, retainkeys])

Calls fn on each value of t table. Returns a new table with only the values where fn returned true. If retainkeys is true the table is not treated as an array and retains its original keys.

lume.filter({1, 2, 3, 4}, function(x) return x % 2 == 0 end) -- Returns {2, 4}

lume.merge(t, t2 [, retainkeys])

Merges all the values from the table t2 into t in place. If retainkeys is true the table is not treated as an array and retains its original keys; if t and t2 have a conflicting key, the value from t2 is used.

lume.merge({2, 3}, {4, 5}) -- Returns {2, 3, 4, 5}

lume.find(t, value)

Returns the index/key of value in t. Returns nil if that value does not exist in the table.

lume.find({"a", "b", "c"}, "b") -- Returns 2

lume.slice(t [, i [, j]])

Mimics the behaviour of Lua's string.sub, but operates on an array rather than a string. Creates and returns a new array of the given slice.

lume.slice({"a", "b", "c", "d", "e"}, 2, 4) -- Returns {"b", "c", "d"}

lume.invert(t)

Returns a copy of the table where the keys have become the values and the values the keys.

lume.invert({a = "x", b = "y"}) -- returns {x = "a", y = "b"}

lume.clone(t)

Returns a shallow copy of the table t.

lume.fn(fn, ...)

Creates a wrapper function around function fn, automatically inserting the arguments into fn which will persist every time the wrapper is called. Any arguments which are passed to the returned function will be inserted after the already existing arguments passed to fn.

local f = lume.fn(print, "Hello")
f("world") -- Prints "Hello world"

lume.once(fn, ...)

Returns a wrapper function to fn which takes the supplied arguments. The wrapper function will call fn on the first call and do nothing on any subsequent calls.

local f = lume.once(print, "Hello")
f() -- Prints "Hello"
f() -- Does nothing

lume.time(fn, ...)

Inserts the arguments into function fn and calls it. Returns the time in seconds the function fn took to execute followed by fn's returned values.

lume.time(function(x) return x end, "hello") -- Returns 0, "hello"

lume.lambda(str)

Takes a string lambda and returns a function. str should be a list of comma-separated parameters, followed by ->, followed by the expression which will be evaluated and returned.

local f = lume.lambda "x,y -> 2*x+y"
f(10, 5) -- Returns 25

lume.serialize(x)

Serializes the argument x into a string which can be loaded again using lume.deserialize(). Only booleans, numbers, tables and strings can be serialized. Circular references are not handled; all nested tables are serialized as unique tables.

lume.serialize({a = "test", b = {1, 2, 3}, false})
-- Returns "{[1]=false,["a"]="test",["b"]={[1]=1,[2]=2,[3]=3,},}"

lume.deserialize(str)

Deserializes a string created by lume.serialize() and returns the resulting value. This function should not be run on an untrusted string.

lume.deserialize("{1, 2, 3}") -- Returns {1, 2, 3}

lume.split(str [, sep])

Splits the string str into words and returns a table of the sub strings. If sep is provided the string will be split at any of the characters in sep instead of on whitespace.

lume.split("One two three") -- Returns {"One", "two", "three"}

lume.trim(str [, chars])

Trims the whitespace from the start and end of the string str and returns the new string. If a chars value is set the characters in chars are trimmed instead of whitespace.

lume.trim("  Hello  ") -- Returns "Hello"

lume.format(str [, vars])

Returns a formatted string. The values of keys in the table vars can be inserted into the string by using the form "{key}" in str; numerical keys can also be used.

lume.format("{b} hi {a}", {a = "mark", b = "Oh"}) -- Returns "Oh hi mark"
lume.format("Hello {1}!", {"world"}) -- Returns "Hello world!"

lume.trace(...)

Prints the current filename and line number followed by each argument separated by a space.

-- Assuming the file is called "example.lua" and the next line is 12:
lume.trace("hello", 1234) -- Prints "[example.lua:12] hello 1234"

lume.dostring(str)

Executes the lua code inside str.

lume.dostring("print('Hello!')") -- Prints "Hello!"

lume.hotswap(modname)

Reloads an already loaded module in place, allowing you to immediately see the effects of code changes without having to restart the program. modname should be the same string used when loading the module with require(). In the case of an error the global environment is restored and nil plus an error message is returned.

lume.hotswap("lume") -- Reloads the lume module
assert(lume.hotswap("inexistant_module")) -- Raises an error

lume.rgba(color)

Takes the 32bit integer color argument and returns 4 numbers, one for each channel, with a range of 0 - 255. The returned values can be used as the arguments to LÖVE's setColor() function.

lume.rgba(0xFF304050) -- Returns 48, 64, 80, 255

License

This library is free software; you can redistribute it and/or modify it under the terms of the MIT license. See LICENSE for details.