collum 0.1.0

A crate for cleanly describing and parsing bit-wide data structures
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# Collum

The name comes from the anatomical neck or cervix, which connect the head to the rest of the body.
Although this crate does not fully focus on headers, it is one of the core reasons this crate came
to be. Thus, coming back to the etymology of the name, this crate aims to allow users to parse the
head(er) of a packet from the rest of its body, essentially serving as a way to analyze the
connection between the two.

# What does it do?

When using the `derive` feature of the crate (currently using the `syn` crate) one can define a
data type with elementary types and derive the Collum trait (note that the `collum::Sized` trait is
also needed and can also be derived).

Once these traits are defined or derived, the main functionality lies in `Collum::from_bytes`, which
allows us to parse a byte stream into the defined data structure.

# Examples

A primary example here is the TCP/IP stack. As a start we'll take a look at the UDP header, which
does not require any manipulation at the bit-level.

```rust
use collum::{Collum, Sized};

#[derive(Collum, Sized, Debug, PartialEq)]
#[collum(endian(big))] // This tells Collum that every primitive integer type is in big-endian.
struct UdpHeader {
    src: u16,
    dst: u16,
    len: u16,
    checksum: u16,
}

assert_eq!(
    UdpHeader::from_bytes(&[0x01, 0xbb, 0xbf, 0xe5, 0x00, 0x21, 0x00, 0x00]),
    Some(UdpHeader {
        src: 443,
        dst: 49125,
        len: 33,
        checksum: 0,
    })
);
```