Crate bin_io

Welcome!

bin_io is a crate inspired greatly by nom and other parser combinator libraries. But bin_io differs from those crates since it aims at providing both reading and writing facilities at the same time, with fewer code.

Example

use std::io::Cursor;
use bin_io::{ boilerplate, seq, read, write };
use bin_io::numbers::{ be_u8, be_u16 };
 
#[derive(Clone, Debug, PartialEq, Eq)]
struct Thing {
    a: u8,
    b: u16
}
 
boilerplate!(
    fn thing_parser() -> Thing {
        seq!(
            Thing { a, b },
            a: be_u8() =>
            b: be_u16() =>
        )
    }
);
 
let mut vec = Vec::new();
let mut cursor = Cursor::new(vec);
 
let my_thing = Thing {
    a: 0x10, b: 0x20
};
 
write(&mut cursor, &my_thing, thing_parser())
    .unwrap();
 
cursor.set_position(0);
 
let other_thing = read(&mut cursor, thing_parser())
    .unwrap();
 
assert_eq!(other_thing, my_thing);

Big change in 0.2

In 0.2 bin_io had a massive change, it now uses references while writing, and no longer needs an owned copy. This meant that some things needed to change from the last version, but everything should still work fine (with minor code changes, seq! in particular), so check out the documentation!

nom or bin_io?

bin_io is at a very early stage of development, so you might want to prefer nom over bin_io for its well developed stage. But still bin_io offers some unique features, and if you fell that it's missing something, I'm open to contrubutions!

What's happening under the hood?

Every function that return a parser (such as be_u8) returns a tuple of closure, one for reading and one for writing. Every time you apply some other function (for example bind) the tuple is split and a new tuple is created (with each part calling the old closure respectively). Once you call read or write not only is the correct closure called, but the other type is erased, this is why once you call read you can no longer call write and viceversa, and you always want to wrap you parser in a function.

Re-exports

pub use utils::*;

pub use error::BinError;

Modules

error	Contains error related definitions.
numbers	Contains number related functions.
strings	Contains string related functions.
utils	Various utility functions.

Macros

boilerplate	Macro used to remove boilerplate code from a function definition.
seq	Macro used to generate a write/read tuple from sequence of operations.

Traits

ReadFn	Trait representing a read closure.
WriteFn	Trait representing a write closure.

Functions

read	Reads from a read/write tuple.
write	Writes to a read/write tuple.