1 - About Lunary

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.

To do

Here are some points that I'm going to improve in the near future:

2 - Download

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

3 - Installation

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:

Note than many other libraries have similar functionality. I wouldn't mind adding support for some of these, just ask.