A binary format I/O framework for Lua
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). User application or custom formats are required to remove themselves any unnecessary information (invalid value, ordering of entries in a set or a map, etc.).
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. If the traffic becomes too important a specialized mailing list will be created.
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:
float and double data types 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 uses the BitOp library for bit-wise boolean operations. The library is available at http://bitop.luajit.org/.Note than many other libraries have similar functionality. I wouldn't mind adding support for some of these, just ask.