API.md

WARNING

this is VERY OUT OF DATE. this is a mod for my (flux's) personal use, and maintaining documentation outside the code isn't worth the time. if other people start using this, i'll reconsider that position.

classes

• futil.class1(super) a simple class w/ optional inheritance
• futil.class(...) a less simple class w/ multiple inheritance and is_a support

data structures

• futil.Deque

  a deque. supported methods:

  • Deque:size()
  • Deque:push_front(value)
  • Deque:push_back(value)
  • Deque:pop_front()
  • Deque:pop_back()

• futil.PairingHeap

  a pairing heap. supported methods:

  • PairingHeap:size()
  • PairingHeap:peek_max()
  • PairingHeap:delete(value)
  • PairingHeap:delete_max()
  • PairingHeap:get_priority(value)
  • PairingHeap:set_priority(value, priority)

• futil.DefaultTable

  a table in which missing keys are automatically filled in. example usage:

  local default_table = futil.DefaultTable(function(key) return {} end)
  default_table.foo.bar = 100 -- foo is automatically created as a table

general routines

• futil.check_call(func)

  wraps func in a pcall. if no error occurs, returns the results. otherwise, logs and returns nil.

• futil.memoize1(f)

  memoize a single-argument function

• futil.memoize_dumpable(f)

  memoize a function if the arguments produce a unique result when dump()-ed

• futil.memoize1_modstorage(id, func)

  memoize a function and store the results in modstorage, so they persist between sessions.

• futil.truncate(s, max_length, suffix)

  if the string is longer than max_length, truncate it and append suffix. suffix is optional, defaults to "..."

• futil.lc_cmp(a, b)

  case-insensitive comparator

• futil.table.set_all(t1, t2)

  sets all key/value pairs of t2 in t1

• futil.table.pairs_by_value(t, sort_function)

  iterator which returns key/value pairs, sorted by value

• futil.table.pairs_by_key(t, sort_function)

  iterator which returns key/value pairs, sorted by key

• futil.table.size(t)

  gets the size of a table

• futil.table.is_empty(t)

  returns true if the table is empty

• futil.equals(a, b)

  returns true if the tables (or other values) are equivalent. do not use w/ recursive structures. currently does not inspect metatables.

• futil.table.count_elements(t)

  given a table in which some values may repeat, returns a table mapping values to their count.

• futil.table.sets_intersect(set1, set2)

  returns true if set1 and set2 have any keys in common.

• futil.table.iterate(t)

  iterates the values of an array-like table

• futil.table.reversed(t)

  returns a reversed copy of the table.

• futil.table.contains(t, value)

  returns true if value is in table

• futil.table.keys(t)

  returns a table of the keys in the given tables.

• futil.table.values(t)

  returns a table of the values in the given tables.

• futil.table.sort_keys(t, sort_function)

  returns a table of the sorted keys of the given table.

• futil.wait(n)

  busy-waits n microseconds

• futil.file_exists(path)

  returns true if the path points to a file that can be opened

• futil.load_file(filename)

  returns the contents of the file if it exists, otherwise nil.

• futil.write_file(filename, contents)

  writes to a file. returns true if success, false if not.

• futil.path_concat(...)

  concatenates part of a file path.

• futil.path_split(path)

  splits a path into parts.

• futil.string.truncate(s, max_length, suffix)

  truncate a string if it is longer than max_length, adding suffix (default "...").

• futil.string.lc_cmp(a, b)

  compares the lower-case values of strings a and b.

• futil.seconds_to_interval(time)

  transforms a time (in seconds) to a format like "[[[[:]:]:]:]"p

• futil.format_utc(timestamp)

  formats a timestamp in UTC.

predicates

• futil.is_nil(v)

  true if v is nil

• futil.is_boolean(v)

  true if v is a boolean.

• futil.is_number(v)

  true if v is a number.

• futil.is_string(v)

  true if v is a string.

• futil.is_userdata(v)

  true if v is userdata.

• futil.is_function(v)

  true if v is a function.

• futil.is_thread(v)

  true if v is a thread.

• futil.is_table(v)

  true if v is a table.

functional

• futil.functional.noop()

  the NOTHING function does nothing.

• futil.functional.identity(x)

  returns x

• futil.functional.izip(...)

  zips iterators.

• futil.functional.zip(...)

  zips tables.

• futil.functional.imap(func, ...)

  maps a function to a sequence of iterators. the first arg to func is the first element of each iterator, etc.

• futil.functional.map(func, ...)

  maps a function to a sequence of tables. the first arg to func is the first element of each table, etc.

• futil.functional.apply(func, t)

  for all keys k, set t[k] = func(t[k])

• futil.functional.reduce(func, t, initial)

  applies binary function func to successive elements in t and a "total". supply initial if possibly #t == 0. e.g. local sum = function(values) return reduce(function(a, b) return a + b end, values, 0) end.

• futil.functional.partial(func, ...)

  curries func. `partial(func, a, b, c)(d, e, f) == func(a, b, c, d, e, f)

• futil.functional.compose(a, b)

  binary operator which composes two functions. compose(a, b)(x) == a(b(x))

• futil.functional.ifilter(pred, i)

  returns an interator which returns the values of iterator i which match predicate pred

• futil.functional.filter(pred, t)

  returns an interator which returns the values of table t which match predicate pred

• futil.functional.iall(i)

  given an iterator, returns true if all non-nil values of the iterator are not false.

• futil.functional.all(t)

  given a table, returns true if the table doesn't contain any false values

• futil.functional.iany(i)

  given an iterator, returns true if the iterator produces any non-false values.

• futil.functional.any(t)

  given a table, returns true if it contains any non-false values.

iterators

• futil.iterators.range(...)

  • one arg: return an iterator from 1 to x.
  • two args: return an iterator from x to y
  • three args: return an iterator from x to y, incrementing by z

• iterators.repeat_(value, times)

  • times = nil: return value forever
  • times = positive number: return value times times

• futil.iterators.chain(...)

  given a sequence of iterators, return an iterator which will return the values from each in turn.

• futil.iterators.count(start, step)

  returns an infinite iterator which counts from start by step. if step is not specified, counts by 1.

• futil.iterators.values(t)

  returns an iterator of the values in the table.

• futil.list(iterator)

  given an iterator, returns a table of the values of the iterator.

• futil.list_multiple(iterator)

  given an iterator which returns multiple values on each step, create a table of tables of those values.

math

• futil.math.idiv(a, b)

  returns the whole part of a division and the remainder, e.g. math.floor(a/b), a%b.

• futil.math.bound(m, v, M)

  if v is less than m, return m. if v is greater than M, return M. else return v.

• futil.math.in_bounds(m, v, M)

  return true if m <= v and v <= M

• futil.math.is_integer(v)

  returns true if v is an integer.

• futil.math.is_u8(i)

  returns true if i is a valid unsigned 8 bit value.

• futil.math.is_u16(i)

  returns true if i is an unsigned 16 bit value.

• futil.math.sum(t, initial)

  given a table, get the sum of the values in the table. initial is the value from which to start counting. if initial is nil and the table is empty, will return nil.

• futil.math.isum(i, initial)

  like the above, but given an iterator.

minetest-specific routines

• futil.add_groups(itemstring, new_groups)

  new_groups should be a table of groups to add to the item's existing groups

• futil.remove_groups(itemstring, ...)

  ... should be a list of groups to remove from the item's existing groups

• futil.get_items_with_group(group)

  returns a list of itemstrings which belong to the specified group

• futil.get_location_string(inv)

  given an InvRef, get a location string suitable for use in formspec

• futil.resolve_item(item)

  given an itemstring or ItemStack, follows aliases until it finds the real item. returns an itemstring.

• futil.items_equals(item1, item2)

  returns true if two itemstrings/stacks represent identical stacks.

• futil.get_blockpos(pos)

  converts a position vector into a blockpos

• futil.get_block_bounds(blockpos)

  gets the bound vectors of a blockpos

• futil.formspec_pos(pos)

  convert a position into a string suitable for use in formspecs

• futil.iterate_area(minp, maxp)

  creates an iterator for every point in the volume between minp and maxp

• futil.iterate_volume(pos, radius)

  like the above, given a position and radius (L∞ metric)

• futil.serialize(x)

  turns a simple lua data structure (e.g. a table no userdata or functions) into a string

• futil.deserialize(data)

  the reverse of the above. not safe; do not use w/ untrusted data

• futil.strip_translation(msg)

  strips minetest's translation escape sequences from a message

• futil.get_safe_short_description(item)

  gets a short description which won't contain unmatched translation escapes

• futil.escape_texture(texturestring)

  escapes a texture modifier, for use within another modifier

• futil.get_horizontal_speed(player)

  get's a player's horizontal speed.

• futil.is_on_ground(player)

  returns true if a player is standing on the ground. NOTE: this is currently unfinished, and doesn't report correctly if a player is standing on things with complex collision boxes which are rotated via paramtype2="facedir" or similar.

fake inventory

this is useful for testing multiple actions on an inventory without having to worry about changing the inventory or reverting it. this is a better solution than a detached inventory, as actions on a detached inventory are still sent to clients. fake inventories support all the regular methods of a minetest inventory object, with some additions.

• futil.FakeInventory()

  create a fake inventory.

• futil.FakeInventory.create_copy(inv)

  copy all the inventory lists from inv into a new fake inventory. will also create a copy of another fake inventory.

• futil.FakeInventory.room_for_all(inv, listname, items)

  create a copy of inv, then tests if all items in the list items can be inserted into listname.

globalstep

implements common boilerplate for globalsteps which are intended to execute every so often.

futil.register_globalstep({
    period = 1,  -- the globalstep should be run every <period> seconds
    catchup = "single", -- whether to "catch up" if lag prevents the callback from running
                        -- if not specified, no catchup will be attempted.
                        -- if "single", the callback will be run at most once per server-step until we've caught up.
                        -- if "full", will re-run the callback within the current step until we've caught up.
    func = function(dtime) end,  -- code to execute
})

hud manager

code to manage HUDs

local hud = futil.define_hud("my_hud", {
    period = nil,  -- if a number is given, will automatically update the hud for all players every <period> seconds.
    name_field = nil, -- which hud field to use to store an identifier. this should be a field not used by the given
                      -- hud_elem_type. defaults to "name", which is good for most types. waypoints are an exception.
    get_hud_def = function(player) return {} end,  -- return the expected hud definition for the player.
                                                   -- if nil is returned, the hud will be removed.
    enabled_by_default = false, -- whether the hud should be enabled by default.
})

local player = minetest.get_player_by_name("flux")
if hud:toggle_enabled(player) then
    print("hud now enabled")
else
    print("hud now disabled")
end

print("hud is " .. (hud:is_enabled(player) and "enabled" or "disabled"))

hud:update(player)  -- calls hud.get_hud_def(player) and updates the players hud