Lua bitstring
Bitstring is useful for network protocol programming and for manipulation of bit based file formats. It provides conversion of strings to binary and hexadecimal formats.
Usage
To use the bitstring module, add the following line to your script:
require "bitstring"
Substring Parameters
Substring parameters allow you to handle different parts of the same string parameter in consecutive invocations, thus making most parsing tasks more efficient.
Substring parameters specify substring that starts at start and ends at end inclusively. Parameters may be negative. 1, -1 specify the whole string.
Substring parameters behave similarly to string.sub parameters; however, it is illegal for start or end to be out of bounds.
Format Specification
The format string passed to pack / unpack function consists of elements separated by a coma and optional white space. Each element specifies a value that is packed or unpacked, its size, type, and endianess. These element parts are delimited by ':'. Examples of this would include:
format ::= element | element-list
--
element ::= size ':' type ':' [endianess]
--
size ::= number | all | rest
--
type ::= int | bin | float
--
endianess ::= big | little
--
element-list ::= element element-delimiter element-list [ element-delimiter ]
--
element-delimiter ::= [' ' | '\t' | '\n' ] ',' [' ' | '\t' | '\n' ]Pack one or more elements as specified by format or by bitmatch into regular Lua string.
Syntax
bitstring.pack(format, arg1 [, arg2, argn])
bitstring.pack(bitmatch, arg1 [, arg2, argn])
Arguments
format: Packs one or more elements as specified by format.
bitmatch: Packs one or more elements as specified by bitmatch.
Returns
Returns a regular Lua string.
Returns nil in case of error.
Example
local data = bitstring.pack( "8:int, 8:int, 8:int, 8:int, 8:int", v1, v2, v3, v4, v5).Note: v1-v5 are variables.
bitstring.unpack()Unpack one or more elements as specified by format or by bitmatch and return them as multiple values. Substring of s may be specified by start and end parameters.
Syntax
bitstring.pack(format, arg1 [, arg2, argn])
bitstring.pack(bitmatch, arg1 [, arg2, argn])
Arguments
format: Packs one or more elements as specified by format.
bitmatch: Packs one or more elements as specified by bitmatch.
Returns
Returns result1 [, result2, resultn]
Returns nil in case of error.
Example
local v1, v2, v3, v4, v5 = bitstring.unpack( "1:int, 7:int, 9:int, 1:int, 6:int", data )Compiles format into bitmatch object.
Syntax
bitstring.compile(format)
Arguments
format: Compiles format into bitmatch object.
Returns
Returns bitmatch.
Returns nil in case of error.
bitstring.bindump()Dump string into multi line “offset – binary digits - text” similar to xxd -b output. Useful for visually validating UTF-8 input.
Syntax
bitstring.bindump(s [, start, end])
Note: Lines are separated by '\n'.
Arguments
s: Dump string s into multi line “offset – binary digits - text” similar to xxd -b output.
start: Substring parameter specifying start.
end: Substring parameter specifying end.
Returns
Returns a Lua string.
Returns nil in case of error.
bitstring.hexdump()Dumps string into multi line, similar to xxd output.
Syntax
bitstring.hexdump(s [, start, end])
Arguments
s: Dump string s into multi line "offset - hexadecimal bytes - text".
start: Substring parameter specifying start.
end: Substring parameter specifying end.
Returns
Returns a Lua string.
Returns nil in case of error.
Example
print(bitstring.hexstream( status ))Dumps string into single line binary digit stream.
Syntax
bitstring.binstream(s [, start, end])
Arguments
s: Dump string s into single line binary digit stream.
start: Substring parameter specifying start.
end: Substring parameter specifying end.
Returns
Returns a Lua string.
Returns nil in case of error.
bitstring.hexstream()Dumps string into single line hexadecimal digit stream.
Syntax
bitstring.hexstream(s [, start, end])
Arguments
s: Dump string s into single line hexadecimal digit stream.
start: Substring parameter specifying start.
end: Substring parameter specifying end.
Returns
Returns a Lua string.
Returns nil in case of error.
bitstring.frombindstream()Convert hexadecimal stream of bytes to regular Lua string.
Syntax
bitstring.fombinstream(s [, start, end])
Arguments
s: Convert string s into hexadecimal stream of bytes to regular Lua string.
start: Substring parameter specifying start.
end: Substring parameter specifying end.
Returns
Returns a Lua string.
Returns nil in case of error.
bitstring.fromhexdstream()Convert hexadecimal stream of bytes to regular Lua string.
Syntax
bitstring.fomhexstream(s [, start, end])
Arguments
s: Convert string s into hexadecimal stream of bytes to regular Lua string.
start: Substring parameter specifying start.
end: Substring parameter specifying end.
Returns
Returns a Lua string.
Returns nil in case of error.
Portions of this topic are reprinted under permission of the Lua Bitstring license.
