tabletrack.lua

Contents

• Functions

Modules

• tabletrack

Topics

• readme

Module tabletrack

tabletrack

A module to help transparently track table accesses.

Usecase: renaming a core structure and every field inside it for a large codebase. Hence this utility was created to track every access, as well as catching potential typos in fieldnames.

Limitation: the implementation is limited by the possibilities of intercepting __index and __newindex meta-methods. And hence not every access might initially be caught.

Info:

• Copyright: 2018 Thijs Schreijer
• License: MIT
• Author: Thijs Schreijer

Functions

get_trace (opts)	Retuns a single line stack-trace.
parse_file (filename)	parses a log file with data into a Lua table structure.
track_access (t, opts)	enables tracking table access.
track_type (mt, opts)	Track a type, by tracking its metatable.

Functions

get_trace (opts)

Retuns a single line stack-trace. Call this from the tracker callback function to get the proper stacktrace.

Parameters:

• opts the options table

Returns:

a single line stacktrace string

parse_file (filename)

parses a log file with data into a Lua table structure. It only parses the format as generated by the default callback.

Parameters:

• filename (optional) the name of the logfile to parse (default “./table_tracker_output”)

Returns:

table with the parsed results

track_access (t, opts)

enables tracking table access.

Parameters:

• t table to track access to
• opts table with options

Returns:

t, the table to track

Usage:

local t = track_access({}, {
  name = "t-name", -- table name as a unique identifier, default: tostring(t)
  cb = function(opts, type, key)          -- callback on access
         -- opts = options table
         -- type = access type: "get", "set", "exists"
         -- key = the key being accesses
  end,
  proxy = nil,      -- using a proxy drops iterators, but catches more
  full_trace = nil, -- full stack track, or only the last call
  -- options for the default callback:
  filename = "./tabletrack.stats.out"  -- filename where to store the data
})

track_type (mt, opts)

Track a type, by tracking its metatable. Same as track_access except that in this case the metatable is provided, such that all instances using this metatable will be tracked.

Parameters:

• mt the metatable whose instances to track
• opts table with options, see track_access

Returns:

the metatable