lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

vstruct 2.0 for Lua 5.1/5.2 and LuaJIT is now available!

You can get it on github:

And report issues there as well:

Note that (per the major version number increase) this is a BREAKING CHANGE; existing code that uses vstruct will need some (minor) changes to continue working. See the README for details on compatibility with earlier versions, and the CHANGES file for a detailed changelist (and notes on planned future features).

Highlights of the changes since 1.1 include new API functions for iterating over arrays of records and "splicing" between format strings, an overhauled and hopefully slightly better API, and massive internal refactoring.

	What is it?

A library for packing and unpacking binary data. If you've used lpack, struct, or the string.pack built into 5.3, you're already familiar with the concept. It's written in pure Lua and supports a variety of advanced features.

	Why use it?

There's already plenty of other libraries that serve this purpose. What makes vstruct different? Well, here's a quick overview of what it supports:

  * Signed and unsigned integers, strings (fixed-width, null-
    terminated, and length-prefixed), fixed and floating point values,
    bitmasks, and booleans.
  * Bit-packed versions of most of these (e.g. four 4-bit ints packed
    into 16 bits).
  * Arbitrary sizes, such as 24-bit ints or 128-bit bitfields; it's not
    limited to C types.
  * Big and little endian data.
  * Widechar strings.
  * Operations on both files and strings.
  * Written entirely in Lua; runs anywhere Lua 5.1 or 5.2 do, and has
    no external dependencies.

And vstruct's "killer feature":

  * Named fields and support for repetition and nested structs, allowing
    you to describe not just the format on disk of your data, but how it
    should be shaped once loaded into Lua.

	Why NOT use it?

There's only one caveat here, but it's a big one: being written in pure Lua, vstruct is both slower and more memory-hungry than C equivalents. It is not suitable for applications where high speed decoding or minimizing memory footprint are priorities.

It is possible to easily replace parts of the library with C implementations, or versions that use luajit's FFI or 5.2's bit32 library to speed up common operations, but this is still an experimental work in progress.

	Where is it used?

I know at least some people use it because I get the occasional bug report and patch, and it's mentioned once or twice a year on this list. That said, the only usage I *know* about is my own:

See, for example, ss1/map/tiles.lua for an example of a complicated format string including multiple nested structs and bitpacks.