Direct port of the struct module that provides access to
packed structures in strings. Very useful for network protocol packing/unpacking. The docs are directly converted from the original. Review feedback Fix typo
This commit is contained in:
philip
parent
2c687313de
commit
0e9a0d43d4
|
|
@ -38,6 +38,7 @@
|
|||
#define LUA_USE_MODULES_RTCTIME
|
||||
#define LUA_USE_MODULES_SNTP
|
||||
#define LUA_USE_MODULES_SPI
|
||||
//#define LUA_USE_MODULES_STRUCT
|
||||
#define LUA_USE_MODULES_TMR
|
||||
#define LUA_USE_MODULES_TSL2561
|
||||
#define LUA_USE_MODULES_U8G
|
||||
|
|
|
|||
|
|
@ -0,0 +1,425 @@
|
|||
/*
|
||||
** {======================================================
|
||||
** Library for packing/unpacking structures.
|
||||
** $Id: struct.c,v 1.4 2012/07/04 18:54:29 roberto Exp $
|
||||
** See Copyright Notice at the end of this file
|
||||
** =======================================================
|
||||
*/
|
||||
// Original: http://www.inf.puc-rio.br/~roberto/struct/
|
||||
// This was ported to NodeMCU by Philip Gladstone, N1DQ
|
||||
/*
|
||||
** Valid formats:
|
||||
** > - big endian
|
||||
** < - little endian
|
||||
** ![num] - alignment
|
||||
** x - pading
|
||||
** b/B - signed/unsigned byte
|
||||
** h/H - signed/unsigned short
|
||||
** l/L - signed/unsigned long
|
||||
** T - size_t
|
||||
** i/In - signed/unsigned integer with size `n' (default is size of int)
|
||||
** cn - sequence of `n' chars (from/to a string); when packing, n==0 means
|
||||
the whole string; when unpacking, n==0 means use the previous
|
||||
read number as the string length
|
||||
** s - zero-terminated string
|
||||
** f - float
|
||||
** d - double
|
||||
** ' ' - ignored
|
||||
*/
|
||||
|
||||
|
||||
#include <assert.h>
|
||||
#include <ctype.h>
|
||||
#include <limits.h>
|
||||
#include <stddef.h>
|
||||
#include <string.h>
|
||||
#include "module.h"
|
||||
|
||||
|
||||
#include "lua.h"
|
||||
#include "lauxlib.h"
|
||||
|
||||
|
||||
/* basic integer type */
|
||||
#if !defined(STRUCT_INT)
|
||||
#define STRUCT_INT long
|
||||
#endif
|
||||
|
||||
typedef STRUCT_INT Inttype;
|
||||
|
||||
/* corresponding unsigned version */
|
||||
typedef unsigned STRUCT_INT Uinttype;
|
||||
|
||||
|
||||
/* maximum size (in bytes) for integral types */
|
||||
#ifdef LUA_NUMBER_INTEGRAL
|
||||
#ifdef LUA_INTEGRAL_LONGLONG
|
||||
#define MAXINTSIZE 8
|
||||
#else
|
||||
#define MAXINTSIZE 4
|
||||
#endif
|
||||
#else
|
||||
#define MAXINTSIZE 32
|
||||
#endif
|
||||
|
||||
/* is 'x' a power of 2? */
|
||||
#define isp2(x) ((x) > 0 && ((x) & ((x) - 1)) == 0)
|
||||
|
||||
/* dummy structure to get alignment requirements */
|
||||
struct cD {
|
||||
char c;
|
||||
double d;
|
||||
};
|
||||
|
||||
|
||||
#define PADDING (sizeof(struct cD) - sizeof(double))
|
||||
#define MAXALIGN (PADDING > sizeof(int) ? PADDING : sizeof(int))
|
||||
|
||||
|
||||
/* endian options */
|
||||
#define BIG 0
|
||||
#define LITTLE 1
|
||||
|
||||
|
||||
static union {
|
||||
int dummy;
|
||||
char endian;
|
||||
} const native = {1};
|
||||
|
||||
|
||||
typedef struct Header {
|
||||
int endian;
|
||||
int align;
|
||||
} Header;
|
||||
|
||||
|
||||
static int getnum (const char **fmt, int df) {
|
||||
if (!isdigit(**fmt)) /* no number? */
|
||||
return df; /* return default value */
|
||||
else {
|
||||
int a = 0;
|
||||
do {
|
||||
a = a*10 + *((*fmt)++) - '0';
|
||||
} while (isdigit(**fmt));
|
||||
return a;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
#define defaultoptions(h) ((h)->endian = native.endian, (h)->align = 1)
|
||||
|
||||
|
||||
|
||||
static size_t optsize (lua_State *L, char opt, const char **fmt) {
|
||||
switch (opt) {
|
||||
case 'B': case 'b': return sizeof(char);
|
||||
case 'H': case 'h': return sizeof(short);
|
||||
case 'L': case 'l': return sizeof(long);
|
||||
case 'T': return sizeof(size_t);
|
||||
#ifndef LUA_NUMBER_INTEGRAL
|
||||
case 'f': return sizeof(float);
|
||||
case 'd': return sizeof(double);
|
||||
#endif
|
||||
case 'x': return 1;
|
||||
case 'c': return getnum(fmt, 1);
|
||||
case 'i': case 'I': {
|
||||
int sz = getnum(fmt, sizeof(int));
|
||||
if (sz > MAXINTSIZE)
|
||||
luaL_error(L, "integral size %d is larger than limit of %d",
|
||||
sz, MAXINTSIZE);
|
||||
return sz;
|
||||
}
|
||||
default: return 0; /* other cases do not need alignment */
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
** return number of bytes needed to align an element of size 'size'
|
||||
** at current position 'len'
|
||||
*/
|
||||
static int gettoalign (size_t len, Header *h, int opt, size_t size) {
|
||||
if (size == 0 || opt == 'c') return 0;
|
||||
if (size > (size_t)h->align)
|
||||
size = h->align; /* respect max. alignment */
|
||||
return (size - (len & (size - 1))) & (size - 1);
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
** options to control endianess and alignment
|
||||
*/
|
||||
static void controloptions (lua_State *L, int opt, const char **fmt,
|
||||
Header *h) {
|
||||
switch (opt) {
|
||||
case ' ': return; /* ignore white spaces */
|
||||
case '>': h->endian = BIG; return;
|
||||
case '<': h->endian = LITTLE; return;
|
||||
case '!': {
|
||||
int a = getnum(fmt, MAXALIGN);
|
||||
if (!isp2(a))
|
||||
luaL_error(L, "alignment %d is not a power of 2", a);
|
||||
h->align = a;
|
||||
return;
|
||||
}
|
||||
default: {
|
||||
const char *msg = lua_pushfstring(L, "invalid format option '%c'", opt);
|
||||
luaL_argerror(L, 1, msg);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
static void putinteger (lua_State *L, luaL_Buffer *b, int arg, int endian,
|
||||
int size) {
|
||||
lua_Number n = luaL_checknumber(L, arg);
|
||||
Uinttype value;
|
||||
char buff[MAXINTSIZE];
|
||||
if (n < 0)
|
||||
value = (Uinttype)(Inttype)n;
|
||||
else
|
||||
value = (Uinttype)n;
|
||||
if (endian == LITTLE) {
|
||||
int i;
|
||||
for (i = 0; i < size; i++) {
|
||||
buff[i] = (value & 0xff);
|
||||
value >>= 8;
|
||||
}
|
||||
}
|
||||
else {
|
||||
int i;
|
||||
for (i = size - 1; i >= 0; i--) {
|
||||
buff[i] = (value & 0xff);
|
||||
value >>= 8;
|
||||
}
|
||||
}
|
||||
luaL_addlstring(b, buff, size);
|
||||
}
|
||||
|
||||
|
||||
static void correctbytes (char *b, int size, int endian) {
|
||||
if (endian != native.endian) {
|
||||
int i = 0;
|
||||
while (i < --size) {
|
||||
char temp = b[i];
|
||||
b[i++] = b[size];
|
||||
b[size] = temp;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
static int b_pack (lua_State *L) {
|
||||
luaL_Buffer b;
|
||||
const char *fmt = luaL_checkstring(L, 1);
|
||||
Header h;
|
||||
int arg = 2;
|
||||
size_t totalsize = 0;
|
||||
defaultoptions(&h);
|
||||
lua_pushnil(L); /* mark to separate arguments from string buffer */
|
||||
luaL_buffinit(L, &b);
|
||||
while (*fmt != '\0') {
|
||||
int opt = *fmt++;
|
||||
size_t size = optsize(L, opt, &fmt);
|
||||
int toalign = gettoalign(totalsize, &h, opt, size);
|
||||
totalsize += toalign;
|
||||
while (toalign-- > 0) luaL_addchar(&b, '\0');
|
||||
switch (opt) {
|
||||
case 'b': case 'B': case 'h': case 'H':
|
||||
case 'l': case 'L': case 'T': case 'i': case 'I': { /* integer types */
|
||||
putinteger(L, &b, arg++, h.endian, size);
|
||||
break;
|
||||
}
|
||||
case 'x': {
|
||||
luaL_addchar(&b, '\0');
|
||||
break;
|
||||
}
|
||||
#ifndef LUA_NUMBER_INTEGRAL
|
||||
case 'f': {
|
||||
float f = (float)luaL_checknumber(L, arg++);
|
||||
correctbytes((char *)&f, size, h.endian);
|
||||
luaL_addlstring(&b, (char *)&f, size);
|
||||
break;
|
||||
}
|
||||
case 'd': {
|
||||
double d = luaL_checknumber(L, arg++);
|
||||
correctbytes((char *)&d, size, h.endian);
|
||||
luaL_addlstring(&b, (char *)&d, size);
|
||||
break;
|
||||
}
|
||||
#endif
|
||||
case 'c': case 's': {
|
||||
size_t l;
|
||||
const char *s = luaL_checklstring(L, arg++, &l);
|
||||
if (size == 0) size = l;
|
||||
luaL_argcheck(L, l >= (size_t)size, arg, "string too short");
|
||||
luaL_addlstring(&b, s, size);
|
||||
if (opt == 's') {
|
||||
luaL_addchar(&b, '\0'); /* add zero at the end */
|
||||
size++;
|
||||
}
|
||||
break;
|
||||
}
|
||||
default: controloptions(L, opt, &fmt, &h);
|
||||
}
|
||||
totalsize += size;
|
||||
}
|
||||
luaL_pushresult(&b);
|
||||
return 1;
|
||||
}
|
||||
|
||||
|
||||
static lua_Number getinteger (const char *buff, int endian,
|
||||
int issigned, int size) {
|
||||
Uinttype l = 0;
|
||||
int i;
|
||||
if (endian == BIG) {
|
||||
for (i = 0; i < size; i++) {
|
||||
l <<= 8;
|
||||
l |= (Uinttype)(unsigned char)buff[i];
|
||||
}
|
||||
}
|
||||
else {
|
||||
for (i = size - 1; i >= 0; i--) {
|
||||
l <<= 8;
|
||||
l |= (Uinttype)(unsigned char)buff[i];
|
||||
}
|
||||
}
|
||||
if (!issigned)
|
||||
return (lua_Number)l;
|
||||
else { /* signed format */
|
||||
Uinttype mask = (Uinttype)(~((Uinttype)0)) << (size*8 - 1);
|
||||
if (l & mask) /* negative value? */
|
||||
l |= mask; /* signal extension */
|
||||
return (lua_Number)(Inttype)l;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
static int b_unpack (lua_State *L) {
|
||||
Header h;
|
||||
const char *fmt = luaL_checkstring(L, 1);
|
||||
size_t ld;
|
||||
const char *data = luaL_checklstring(L, 2, &ld);
|
||||
size_t pos = luaL_optinteger(L, 3, 1) - 1;
|
||||
defaultoptions(&h);
|
||||
lua_settop(L, 2);
|
||||
while (*fmt) {
|
||||
int opt = *fmt++;
|
||||
size_t size = optsize(L, opt, &fmt);
|
||||
pos += gettoalign(pos, &h, opt, size);
|
||||
luaL_argcheck(L, pos+size <= ld, 2, "data string too short");
|
||||
luaL_checkstack(L, 1, "too many results");
|
||||
switch (opt) {
|
||||
case 'b': case 'B': case 'h': case 'H':
|
||||
case 'l': case 'L': case 'T': case 'i': case 'I': { /* integer types */
|
||||
int issigned = islower(opt);
|
||||
lua_Number res = getinteger(data+pos, h.endian, issigned, size);
|
||||
lua_pushnumber(L, res);
|
||||
break;
|
||||
}
|
||||
case 'x': {
|
||||
break;
|
||||
}
|
||||
#ifndef LUA_NUMBER_INTEGRAL
|
||||
case 'f': {
|
||||
float f;
|
||||
memcpy(&f, data+pos, size);
|
||||
correctbytes((char *)&f, sizeof(f), h.endian);
|
||||
lua_pushnumber(L, f);
|
||||
break;
|
||||
}
|
||||
case 'd': {
|
||||
double d;
|
||||
memcpy(&d, data+pos, size);
|
||||
correctbytes((char *)&d, sizeof(d), h.endian);
|
||||
lua_pushnumber(L, d);
|
||||
break;
|
||||
}
|
||||
#endif
|
||||
case 'c': {
|
||||
if (size == 0) {
|
||||
if (!lua_isnumber(L, -1))
|
||||
luaL_error(L, "format `c0' needs a previous size");
|
||||
size = lua_tonumber(L, -1);
|
||||
lua_pop(L, 1);
|
||||
luaL_argcheck(L, pos+size <= ld, 2, "data string too short");
|
||||
}
|
||||
lua_pushlstring(L, data+pos, size);
|
||||
break;
|
||||
}
|
||||
case 's': {
|
||||
const char *e = (const char *)memchr(data+pos, '\0', ld - pos);
|
||||
if (e == NULL)
|
||||
luaL_error(L, "unfinished string in data");
|
||||
size = (e - (data+pos)) + 1;
|
||||
lua_pushlstring(L, data+pos, size - 1);
|
||||
break;
|
||||
}
|
||||
default: controloptions(L, opt, &fmt, &h);
|
||||
}
|
||||
pos += size;
|
||||
}
|
||||
lua_pushinteger(L, pos + 1);
|
||||
return lua_gettop(L) - 2;
|
||||
}
|
||||
|
||||
|
||||
static int b_size (lua_State *L) {
|
||||
Header h;
|
||||
const char *fmt = luaL_checkstring(L, 1);
|
||||
size_t pos = 0;
|
||||
defaultoptions(&h);
|
||||
while (*fmt) {
|
||||
int opt = *fmt++;
|
||||
size_t size = optsize(L, opt, &fmt);
|
||||
pos += gettoalign(pos, &h, opt, size);
|
||||
if (opt == 's')
|
||||
luaL_argerror(L, 1, "option 's' has no fixed size");
|
||||
else if (opt == 'c' && size == 0)
|
||||
luaL_argerror(L, 1, "option 'c0' has no fixed size");
|
||||
if (!isalnum(opt))
|
||||
controloptions(L, opt, &fmt, &h);
|
||||
pos += size;
|
||||
}
|
||||
lua_pushinteger(L, pos);
|
||||
return 1;
|
||||
}
|
||||
|
||||
/* }====================================================== */
|
||||
|
||||
|
||||
|
||||
static const LUA_REG_TYPE thislib[] = {
|
||||
{LSTRKEY("pack"), LFUNCVAL(b_pack)},
|
||||
{LSTRKEY("unpack"), LFUNCVAL(b_unpack)},
|
||||
{LSTRKEY("size"), LFUNCVAL(b_size)},
|
||||
{LNILKEY, LNILVAL}
|
||||
};
|
||||
|
||||
|
||||
NODEMCU_MODULE(STRUCT, "struct", thislib, NULL);
|
||||
|
||||
/******************************************************************************
|
||||
* Copyright (C) 2010-2012 Lua.org, PUC-Rio. All rights reserved.
|
||||
*
|
||||
* Permission is hereby granted, free of charge, to any person obtaining
|
||||
* a copy of this software and associated documentation files (the
|
||||
* "Software"), to deal in the Software without restriction, including
|
||||
* without limitation the rights to use, copy, modify, merge, publish,
|
||||
* distribute, sublicense, and/or sell copies of the Software, and to
|
||||
* permit persons to whom the Software is furnished to do so, subject to
|
||||
* the following conditions:
|
||||
*
|
||||
* The above copyright notice and this permission notice shall be
|
||||
* included in all copies or substantial portions of the Software.
|
||||
*
|
||||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
******************************************************************************/
|
||||
|
||||
|
|
@ -0,0 +1,172 @@
|
|||
# struct module
|
||||
|
||||
This module offers basic facilities to convert Lua values to and from C
|
||||
structs. Its main functions are `struct.pack`, which packs multiple Lua
|
||||
values into a struct-like string; and `struct.unpack`, which unpacks
|
||||
multiple Lua values from a given struct-like string.
|
||||
|
||||
The first argument to both functions is a *format string*, which
|
||||
describes the layout of the structure. The format string is a sequence
|
||||
of conversion elements, which respect the current endianess and the
|
||||
current alignment requirements. Initially, the current endianess is the
|
||||
machine's native endianness and the current alignment requirement is 1
|
||||
(meaning no alignment at all). You can change these settings with
|
||||
appropriate directives in the format string.
|
||||
|
||||
Note that the float and double conversions are only available with
|
||||
a floating point NodeMCU build.
|
||||
|
||||
### Format String
|
||||
|
||||
The elements in the format string are as follows:
|
||||
|
||||
- `" "` (empty space) ignored.
|
||||
- `"!n"` flag to set the current alignment requirement to *n*
|
||||
(necessarily a power of 2); an absent *n* means the machine's native
|
||||
alignment.
|
||||
- `">"` flag to set mode to big endian.
|
||||
- `"<"` flag to set mode to little endian.
|
||||
- `"x"` a padding zero byte with no corresponding Lua value.
|
||||
- `"b"` a signed `char`.
|
||||
- `"B"` an unsigned `char`.
|
||||
- `"h"` a signed `short` (native size).
|
||||
- `"H"` an unsigned `short` (native size).
|
||||
- `"l"` a signed `long` (native size).
|
||||
- `"L"` an unsigned `long` (native size).
|
||||
- `"T"` a `size_t` (native size).
|
||||
- `"in"` a signed integer with *n* bytes. An absent *n* means the
|
||||
native size of an `int`.
|
||||
- `"In"` like `"in"` but unsigned.
|
||||
- `"f"` a `float` (native size).
|
||||
- `"d"` a `double` (native size).
|
||||
- `"s"` a zero-terminated string.
|
||||
- `"cn"` a sequence of exactly *n* chars corresponding to a single Lua
|
||||
string. An absent *n* means 1. When packing, the given string must
|
||||
have at least *n* characters (extra characters are discarded).
|
||||
- `"c0"` this is like `"cn"`, except that the *n* is given by other
|
||||
means: When packing, *n* is the length of the given string; when
|
||||
unpacking, *n* is the value of the previous unpacked value (which
|
||||
must be a number). In that case, this previous value is not
|
||||
returned.
|
||||
|
||||
#### Examples
|
||||
|
||||
To pack and unpack the structure
|
||||
|
||||
struct Str {
|
||||
char b;
|
||||
int i[4];
|
||||
};
|
||||
|
||||
you can use the string `"<!4biiii"`.
|
||||
|
||||
To pack a string with its length coded in its first byte, use the
|
||||
following code:
|
||||
|
||||
x = struct.pack("Bc0", string.len(s), s)
|
||||
|
||||
To unpack that string, do as follows:
|
||||
|
||||
s = struct.unpack("Bc0", x)
|
||||
|
||||
Note that the length (read by the element `"B"`) is not returned.
|
||||
|
||||
To pack a string in a fixed-width field of 10 characters padded with
|
||||
blanks, do as follows:
|
||||
|
||||
x = struct.pack("c10", s .. string.rep(" ", 10))
|
||||
|
||||
|
||||
## struct.pack()
|
||||
|
||||
Returns a string containing the values `d1`, `d2`, etc. packed
|
||||
according to the format string `fmt`.
|
||||
|
||||
#### Syntax
|
||||
|
||||
`struct.pack (fmt, d1, d2, ...)`
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `fmt` The format string in the format above
|
||||
- `d1` The first data item to be packed
|
||||
- `d2` The second data item to be packed etc.
|
||||
|
||||
#### Returns
|
||||
|
||||
The packed string.
|
||||
|
||||
#### Example
|
||||
|
||||
```
|
||||
s = struct.pack("I", 0x41424344)
|
||||
print(s)
|
||||
```
|
||||
|
||||
## struct.unpack()
|
||||
|
||||
Returns the values packed in string `s` according to the format
|
||||
string `fmt`. An optional `i` marks where in `s` to start reading
|
||||
(default is 1). After the read values, this function also returns
|
||||
the index in `s` where it stopped reading, which is also where you
|
||||
should start to read the rest of the string.
|
||||
|
||||
#### Syntax
|
||||
|
||||
`struct.unpack (fmt, s[, offset])`
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `fmt` The format string in the format above
|
||||
- `s` The string holding the data to be unpacked
|
||||
- `offset` The position to start in the string (default is 1)
|
||||
|
||||
#### Returns
|
||||
|
||||
All the unpacked data.
|
||||
|
||||
#### Example
|
||||
|
||||
Suppose we have to decode a string `s` with an unknown number of
|
||||
doubles; the end is marked by a zero value. We can use the following
|
||||
code:
|
||||
|
||||
local a = {}
|
||||
local i = 1 -- index where to read
|
||||
while true do
|
||||
local d
|
||||
d, i = struct.unpack("d", s, i)
|
||||
if d == 0 then break end
|
||||
a[#a + 1] = d
|
||||
end
|
||||
|
||||
## struct.size()
|
||||
|
||||
Returns the size of a string formatted according to the format
|
||||
string `fmt`. The format string should contain neither the option
|
||||
`s` nor the option `c0`.
|
||||
|
||||
#### Syntax
|
||||
|
||||
`struct.size (fmt)`
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `fmt` The format string in the format above
|
||||
|
||||
#### Returns
|
||||
|
||||
The size of the string that would be output in a pack operation with this format string.
|
||||
|
||||
#### Example
|
||||
|
||||
```
|
||||
print(struct.size("i"))
|
||||
```
|
||||
|
||||
This prints the size of the native integer type.
|
||||
|
||||
### License
|
||||
|
||||
This package is distributed under the MIT license. See copyright notice
|
||||
at the end of file `struct.c`.
|
||||
|
|
@ -54,6 +54,7 @@ pages:
|
|||
- 'rtcfifo': 'en/modules/rtcfifo.md'
|
||||
- 'sntp': 'en/modules/sntp.md'
|
||||
- 'spi': 'en/modules/spi.md'
|
||||
- 'struct': 'en/modules/struct.md'
|
||||
- 'tmr': 'en/modules/tmr.md'
|
||||
- 'tsl2561': 'en/modules/tsl2561.md'
|
||||
- 'u8g': 'en/modules/u8g.md'
|
||||
|
|
|
|||
Loading…
Reference in New Issue