Home

Awesome

Serpent

Lua serializer and pretty printer.

Features

Usage

local serpent = require("serpent")
local a = {1, nil, 3, x=1, ['true'] = 2, [not true]=3}
a[a] = a -- self-reference with a table as key and value

print(serpent.dump(a)) -- full serialization
print(serpent.line(a)) -- single line, no self-ref section
print(serpent.block(a)) -- multi-line indented, no self-ref section

local fun, err = loadstring(serpent.dump(a))
if err then error(err) end
local copy = fun()

-- or using serpent.load:
local ok, copy = serpent.load(serpent.dump(a))
print(ok and copy[3] == a[3])

Functions

Serpent provides three functions that are shortcuts to the same internal function, but set different options by default:

Note that line and block functions return pretty-printed data structures and if you want to deserialize them, you need to add return before running them through loadstring. For example: loadstring('return '..require('mobdebug').line("foo"))() == "foo".

While you can use loadstring or load functions to load serialized fragments, Serpent also provides load function that adds safety checks and reports an error if there is any executable code in the fragment.

Similar to pcall and loadstring calls, load returns status as the first value and the result or the error message as the second value.

Options

These options can be provided as a second parameter to Serpent functions.

block(a, {fatal = true})
line(a, {nocode = true, valignore = {[arrayToIgnore] = true}})
function todiff(a) return dump(a, {nocode = true, indent = ' '}) end

Serpent functions set these options to different default values:

Metatables with __tostring and __serialize methods

If a table or a userdata value has __tostring or __serialize method, the method will be used to serialize the value. If __serialize method is present, it will be called with the value as a parameter. if __serialize method is not present, but __tostring is, then tostring will be called with the value as a parameter. In both cases, the result will be serialized, so __serialize method can return a table, that will be serialize and replace the original value.

Sorting

A custom sort function can be provided to sort the contents of tables. The function takes 2 parameters, the first being the table (a list) with the keys, the second the original table. It should modify the first table in-place, and return nothing. For example, the following call will apply a sort function identical to the standard sort, except that it will not distinguish between lower- and uppercase.

local mysort  = function(k, o) -- k=keys, o=original table
  local maxn, to = 12, {number = 'a', string = 'b'}
  local function padnum(d) return ("%0"..maxn.."d"):format(d) end
  local sort = function(a,b)
    -- this -vvvvvvvvvv- is needed to sort array keys first
    return ((k[a] and 0 or to[type(a)] or 'z')..(tostring(a):gsub("%d+",padnum))):upper()
         < ((k[b] and 0 or to[type(b)] or 'z')..(tostring(b):gsub("%d+",padnum))):upper()
  end
  table.sort(k, sort)
end

local content = { some = 1, input = 2, To = 3, serialize = 4 }
local result = require('serpent').block(content, {sortkeys = mysort})

Formatters

Serpent supports a way to provide a custom formatter that allows to fully customize the output. The formatter takes four values:

For example, the following call will apply `Foo{bar} notation to its output (used by Metalua to display ASTs):

print((require "serpent").block(ast, {comment = false, custom =
  function(tag,head,body,tail)
    local out = head..body..tail
    if tag:find('^lineinfo') then
      out = out:gsub("\n%s+", "") -- collapse lineinfo to one line
    elseif tag == '' then
      body = body:gsub('%s*lineinfo = [^\n]+', '')
      local _,_,atag = body:find('tag = "(%w+)"%s*$')
      if atag then
        out = "`"..atag..head.. body:gsub('%s*tag = "%w+"%s*$', '')..tail
        out = out:gsub("\n%s+", ""):gsub(",}","}")
      else out = head..body..tail end
    end
    return tag..out
  end}))

Limitations

Performance

A simple performance test against serialize.lua from metalua, pretty.write from Penlight, and tserialize.lua from lua-nucleo is included in t/bench.lua.

These are the results from one of the runs:

Serpent does additional processing to escape \010 and \026 characters in strings (to address http://lua-users.org/lists/lua-l/2007-07/msg00362.html, which is already fixed in Lua 5.2) and to check all numbers for math.huge. The seconds number excludes this processing to put it on an equal footing with other modules that skip these checks (nucleo still checks for math.huge).

Author

Paul Kulchenko (paul@kulchenko.com)

License

See LICENSE file.

History

v0.30 (Sep 01 2017)

v0.28 (May 06 2015)

v0.27 (Jan 11 2014)

v0.26 (Nov 05 2013)

v0.25 (Sep 29 2013)

v0.24 (Jun 12 2013)

v0.23 (Mar 24 2013)

v0.22 (Jan 15 2013)

v0.21 (Jan 08 2013)

v0.19 (Nov 16 2012)

v0.18 (Sep 13 2012)

v0.17 (Sep 12 2012)

v0.16 (Aug 28 2012)

v0.15 (Jun 17 2012)

v0.14 (Jun 13 2012)

v0.13 (Jun 13 2012)

v0.12 (Jun 12 2012)

v0.10 (Jun 03 2012)