Crate omnom

Streaming parser extensions for BufRead.

This is a one-off experiment to see if we can extend the std::io::BufRead traits with better parsing capabilities. The name is a riff on the nom parser, which you should probably check out.

Why?

The purpose of this crate is to make authoring streaming parsers easier. And the way we do this is by providing more operations that decouple “looking at bytes” from “consuming bytes”. So hence we introduce fill_ counterparts for read_until and read_exact. And two new methods: read_while and fill_while that read bytes into a buffer based on a predicate.

Together this should make it easier to parse bytes from streams.

Methods

• BufReadExt::read_while reads bytes based on a predicate, consumes bytes.
• BufReadExt::skip Skip the first n bytes.
• BufReadExt::skip_until Skip bytes until the delimiter byte or EOF is reached.
• BufReadExt::skip_while Skip bytes while a predicate is true.
• ReadExt::read_be reads bytes as big-endian from a reader, consumes bytes.
• ReadExt::read_le reads bytes as little-endian from a reader, consumes bytes.
• ReadExt::read_ne reads bytes using native endianness from a reader, consumes bytes.
• WriteExt::write_be write bytes as big-endian to a writer.
• WriteExt::write_le write bytes as little-endian to a writer.
• WriteExt::write_ne write bytes using native endianness to a writer.

Todos

• AsyncRead support.

Examples

Read and write integers from IO streams with a chosen endianness:

use std::io::{Cursor, Seek, SeekFrom};
use omnom::prelude::*;

let mut buf = Cursor::new(vec![0; 15]);

let num = 12_u16;
buf.write_le(num).unwrap();

buf.seek(SeekFrom::Start(0)).unwrap();
let num: u16 = buf.read_le().unwrap();
assert_eq!(num, 12);

Modules

• prelude
  The omnom prelude.

Traits

• BufReadExt
  Extend BufRead with methods for streaming parsing.
• ReadBytes
  Trait to enable writing bytes to a reader.
• ReadExt
  Extension trait to Read to read bytes using endianness.
• WriteBytes
  Trait to enable writing bytes to a writer.
• WriteExt
  Extension trait to Write to write bytes using endianness.