imported>Nagaralage at 02:59, 22 November 2024

2024-11-22T02:59:11Z

New page

'''Construct''' is a [[Python (programming_language)|Python]] library for the construction and deconstruction of [[data structures]] in a [[Declarative programming|declarative]] fashion. In this context, construction, or building, refers to the process of converting ([[Serialization|serializing]]) a programmatic object into a binary representation.

Deconstruction, or parsing, refers to the opposite process of converting (deserializing) binary data into a programmatic object. Being declarative means that user code defines the data structure, instead of the convention of writing [[procedural code]] to accomplish the goal. Construct can work seamlessly with [[bit]]- and [[byte]]-level data granularity and various [[Endianness|byte-ordering]].

==Benefits==
Using declarative code has many benefits. For example, the same code that can parse can also build (symmetrical), debugging and testing are much simpler (provable to some extent), creating new constructs is easy (wrapping components), and many more.{{cn|date=August 2023}} If one is familiar with the [[C (programming language)]], one can think of constructs as [[Type conversion|casting]] from <code>char *</code> to <code>struct foo *</code> and vice versa, rather than writing code that unpacks the data.

==Example==
The following example show how a [[TCP/IP]] [[protocol stack]] might be defined using Construct. Some code is omitted for brevity and simplicity. Also note that the following code is just Python code that creates objects.

First, the [[Ethernet]] [[Ethernet_frame#Header|header]] (layer 2):

<syntaxhighlight lang="python">
ethernet = Struct(
"destination" / Bytes(6),
"source" / Bytes(6),
"type" / Enum(Int16ub,
IPv4=0x0800,
ARP=0x0806,
RARP=0x8035,
X25=0x0805,
IPX=0x8137,
IPv6=0x86DD,
),
)
</syntaxhighlight>

Next, the [[Internet_Protocol|IP]] header (layer 3):
<syntaxhighlight lang="python">
ip = Struct(
"header" / BitStruct(
"version" / Const(Nibble, 4),
"header_length" / Nibble,
),
"tos" / BitStruct(
"precedence" / Bytes(3),
"minimize_delay" / Flag,
"high_throuput" / Flag,
"high_reliability" / Flag,
"minimize_cost" / Flag,
Padding(1),
),
"total_length" / Int16ub,
# ...
)
</syntaxhighlight>
And finally, the [[Transmission Control Protocol|TCP]] header (layer 4):
<syntaxhighlight lang="python">
tcp = Struct(
"source" / Int16ub,
"destination" / Int16ub,
"seq" / Int32ub,
"ack" / Int32ub,
# ...
)
</syntaxhighlight>

Now define the hierarchy of the protocol stack. The following code "binds" each pair of adjacent protocols into a separate unit. Each such unit will "select" the proper next layer based on its contained protocol.
<syntaxhighlight lang="python">
layer4tcp = Struct(
tcp,
# ... payload
)

layer3ip = Struct(
ip,
"next" / Switch(this.protocol,
{
"TCP" : layer4tcp,
}
),
)

layer2ethernet = Struct(
ethernet,
"next" / Switch(this.type,
{
"IP" : layer3ip,
}
),
)
</syntaxhighlight>

At this point, the code can parse captured TCP/IP frames into "packet" objects and build these packet objects back into binary representation.
<syntaxhighlight lang="python">
tcpip_stack = layer2ethernet
packet = tcpip_stack.parse(b"...raw captured packet...")
raw_data = tcpip_stack.build(packet)
</syntaxhighlight>

==Ports and spin-offs==

===Perl===
Data::ParseBinary<ref>{{Cite web |last= |first= |title=Data::ParseBinary - Yet Another parser for binary structures - metacpan.org |url=https://metacpan.org/pod/Data::ParseBinary |access-date=2023-08-29 |website=metacpan.org}}</ref> is a [[CPAN]] module that originated as a port of Construct to the [[Perl|Perl programming language]]. (see [https://metacpan.org/module/Data::ParseBinary its main POD document] for its inspiration). Since the initial version, some parts of the original API have been deprecated.

===Java===
A port to Java is available on GitHub.<ref>{{Citation |last=Ziglioli |first=Emanuele |title=ZiglioUK/construct |date=2022-12-29 |url=https://github.com/ZiglioUK/construct |access-date=2023-08-29}}</ref> Examples in Java, the [[Ethernet]] header (layer 2):

<syntaxhighlight lang="java">
Construct ethernet_header = Struct("ethernet_header",
MacAddress("destination"),
MacAddress("source"),
Enum(UBInt16("type"),
"IPv4", 0x0800,
"ARP", 0x0806,
"RARP", 0x8035,
"X25", 0x0805,
"IPX", 0x8137,
"IPv6", 0x86DD,
"_default_", Pass
));
</syntaxhighlight>

==See also==
* [[Natural Language Toolkit]]

==References==
<references/>

==External links==
*[https://construct.readthedocs.org/en/latest/ Construct's Documentation]
*[https://github.com/construct/construct Construct's Repository]
*[https://datasciencepartners.nl/ Python Training]

[[Category:Python (programming language) libraries]]
[[Category:Parser generators]]

Construct (Python library) - Revision history

imported>Nagaralage at 02:59, 22 November 2024