A simple module to dump Lua values to strings and files
A simple module to dump Lua values to strings and files
The prtr-dump module is a simple Lua module that pretty-prints some Lua values in such a way that they are human-readable, while still being valid Lua source to be reloaded by the Lua interpreter.
The name dump is not original, but it reflects the purpose of the library. The prtr- prefix (a contraction for piratery.net, the website domain) is used in case some other Linux bindings emerge with the same naming problems.
All support is done through the Lua mailing list.
Feel free to ask for further developments. I can't guarantee that I'll develop everything you ask, but I want my code to be as useful as possible, so I'll do my best to help you. You can also send me request or bug reports (for code and documentation) directly at jerome.vuarand@gmail.com.
This module is written and maintained by Jérôme Vuarand.
It is available under a MIT-style license.
prtr-dump sources are available in its Mercurial repository:
hg clone http://hg.piratery.net/dump/
Tarballs of the latest code can be downloaded directly from there: as gz, bz2 or zip.
Finally, I published some rockspecs:
luarocks install prtr-dump
This module is very basic, it exposes two functions, tostring and tofile, that both take a value parameter. The following Lua types are supported: boolean, number, string and table. For tables, additional restrictions apply. The table keys must be booleans, numbers or strings. The values can be any type supported by this library.
Tables are printed with indentation, recursively. Key-value pairs are ordered in a predictable way so that two identical tables will always be serialized to the same string or file. The key-value pairs are also ordered in a sensible way to improve reading of the data by a human (string keys come first, integer keys are omitted when compatible with an array constructor).
Note that no reference comparison is done during the dump, so if a sub-table is referenced at several points inside a table structure, at re-loading time several identical but unrelated tables will be created. Also if the input table contain reference loops, the dump functions will recurse infinitely (and probably be interrupted by a stack overflow error).
Finally very large tables will be serialized in a special way to avoid the limit on the number of constants in a Lua chunk. By default the key-value pairs will be grouped in chunks of 10 000. This may however be too large if the values are moderately large tables themselves. You can change the dump.groupsize variable dynamically to adjust that behaviour.
To use this module:
local dump = require 'dump'
The tostring function takes a value as parameter, and returns an equivalent string:
local value = {
attribute = 42,
'foo',
37,
}
local s = dump.tostring(value)
The tofile function takes a value and a file object or a filename string as parameters. The file object can be any value that has a write method that takes a single string as parameter, for example the file objects of the Lua io library. If a string is passed as a second parameter, it is considered as a filename that will be open, written to and closed. The serialized value is prefixed with the string "return ", so that executing the file with for example dofile will return the equivalent value.
local file = io.open('value.lua')
dump.tofile(value, file)
file:close()
dump.tofile(value, 'value.lua')