---@meta
---@diagnostic disable: missing-return, unused-local

---@module 'bitstring'

---@alias format string

---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:
---```lua
---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' ]
---```
---
---Example:
---```lua
----- parse-radius.lua
----- This example demonstrates parsing and creation of RADIUS protocol messages
----- using bitstring.pack and bitstring.unpack. It also uses bitstring.hexstream
----- and bitstring.fromhexstream utility functions that ease on debugging.
----- RADIUS protocol is defined in RFC 2865.
----- ---------------------------------------
---
----- copied from wireshark
---packet = "01e40088abe03a1b2b38bbd7edcf08b26334f417010867696f7261300c06000005781e10303034302e393661302e343931301f10303034302e393662312e653036330606000000015012efbdb1bd5e4fe4147a95a78d001c51844f0d0202000b0167696f7261303d06000000130506000044f504060a383e83200f63642d617031313230622d3031"
---
---radis_message = bitstring.fromhexstream(packet)
---
----- parse radius message
---code, identifier, message_length, authenticator, attributes =
---    bitstring.unpack("8:int, 8:int, 16:int:big, 16:bin, rest:bin", radis_message)
---
---attribute_list = {}
---while(#attributes > 0) do
---    number, length, attributes = bitstring.unpack("8:int, 8:int, rest:bin", attributes)
---    value, attributes  = bitstring.unpack((length - 2) .. ":bin, rest:bin", attributes)
---    table.insert(attribute_list, {number = number, length = length, value = value})
---end
---
----- compose radius message
---attributes = {}
---for i, a in ipairs(attribute_list) do
---    attribute = bitstring.pack("8:int, 8:int, all:bin", a.number, a.length, a.value)
---    table.insert(attributes, attribute)
---end
---attributes = table.concat(attributes)
---
---composed_message_length = 20 + #attributes
---composed_radius_message = bitstring.pack("8:int, 8:int, 16:int:big, 16:bin, all:bin",
---    code, identifier, composed_message_length, authenticator, attributes)
---
----- print results
---print("parsed radius message")
---print("code: ", code)
---print("identifier: ", identifier)
---print("radius message length: ", message_length)
---print("authenticator: ", bitstring.hexstream(authenticator))
---print("attributes:")
---
---for i, attribute in ipairs(attribute_list) do
---    print("--------------------------------------")
---    print("   number: ", attribute.number)
---    print("   length: ", attribute.length)
---    print("   value: ", bitstring.hexstream(attribute.value))
---end
---print("--------------------------------------")
---
---print("composed radius message")
---print(bitstring.hexstream(composed_radius_message))
---assert(composed_radius_message == radis_message)
---```
---@class bitstring
---@field pack fun(format: format, bitmatch:...) : string? Pack one or more elements as specified by format or by bitmatch into regular Lua string.
---@field unpack fun(format: format, bitstring: string) : ...? 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.
---@field compile fun(format: format) : ...? Compiles format into bitmatch object.
---@field bindump fun(string: string, start?, end?) : string? Dump string into multi line “offset – binary digits - text” similar to xxd -b output. Useful for visually validating UTF-8 inpu
---@field hexdump fun(string: string, start?, end?) : string? Dumps string into multi line, similar to xxd output.
---@field binstream fun(string: string, start?, end?) : string? Dumps string into single line binary digit stream.
---@field hexstream fun(string: string, start?, end?) : string? Dumps string into single line hexadecimal digit stream.
---@field frombinstream fun(string: string, start?, end?) : string? Convert hexadecimal stream of bytes to regular Lua string.
---@field fromhexstream fun(string: string, start?, end?) : string? Convert hexadecimal stream of bytes to regular Lua string.
bitstring = {}
