A binary format I/O framework for Lua
Lunary is a framework to read and write structured binary data from and to files or network connections. The aim is to provide an easy to use interface to describe any complex binary format, and allow translation to Lua data structures. The focus is placed upon the binary side of the transformation, and further processing may be necessary to obtain the desired Lua structures. On the other hand Lunary should allow reading and writing of any binary format, and bring all the information available to the Lua side.
All built-in data types preserve all the information they read from the streams. This allows reserializing an object even if it's not manipulable by Lua (e.g. an uint64
not fitting in a Lua number
will be represented by a string
, an enum
which integer value is not named will be passed as a number
).
The Lunary name is based on the contraction of Lua and binary, and it sounds moon-themed (it is close to the lunar adjective).
All support is done through the Lua mailing list.
Feel free to ask for further developments, especially new data types. 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.
Lunary is available under a MIT-style license.
Here are some points that I'm going to improve in the near future:
Lunary sources are available in its Mercurial repository:
hg clone http://hg.piratery.net/lunary/
Tarballs of the latest code can be downloaded directly from there: as gz, bz2 or zip.
Finally, I published some rockspecs. To get a full Lunary (with optional dependencies), simply run:
luarocks install lunary
If you're on a platform without a C compiler, and no pre-built rocks are available, you can still get most of the Lunary functionality with its pure-Lua core:
luarocks install lunary-core
Lunary consists of two Lua modules named serial
and serial.util
. There is a also an optional serial.optim
binary module which replace some functions of serial.util
with optimized alternatives to improve Lunary performance.
A simple makefile is provided. The build
target builds the serial.optim
binary module. The install
target installs all the Lunary modules to the PREFIX
installation path, which is defined in the Makefile and can be overridden with an environment variable. The installpure
target only install pure Lua modules, it can be used on platforms where compiling or using C modules is problematic.
Finally note that Lunary has some optional dependencies. If the dependency is not available, the data types using them will not be available to Lunary users. Here are the data types with dependencies:
double
data type uses Roberto Ierusalimschy's struct library to serialize native floating point numbers. The library is available at http://www.inf.puc-rio.br/~roberto/struct/.flags
data type use the BitOp library for bit-wise boolean operations on Lua 5.1. The library is available at http://bitop.luajit.org/. On Lua 5.2 the standard bit32
library will be used.Note than many other libraries have similar functionality. I wouldn't mind adding support for some of these, just ask.