escnul – NUL-safe byte escaping for embedding in shell scripts

Overview

• [escape] module provides a low-overhead, reversible byte-escaping scheme inspired by the original arx/shdat tools. It lets you transform arbitrary binary data into a stream that can be safely embedded in a Bourne-shell script and decoded later with only tr+sed (or via the provided Rust APIs).
• [OnePassEscapeEngine] performs a single-pass encode/decode using a user-chosen escape byte.
• [TwoPassEscapeEngine] scans your data first, then either copies it raw (if no NULs) or picks a rare escape byte and delegates to [OnePassEscapeEngine].
• All engines implement the [Encode], [Decode], and [Engine] traits for zero-allocation streaming into pre-allocated buffers.

Example

use escnul::{Encode, Decode, OnePassEscapeEngine, TwoPassEscapeEngine, Engine, escape::TWO_PASS_SED};

// 1-pass encode/decode with user-chosen escape '@'
let data = b"hello\0world";
let mut buf = vec![0u8; data.len() * 2];
let m = OnePassEscapeEngine::new(b'@').encode_slice(data, &mut buf).unwrap();
assert_eq!(&buf[..m], b"hello\x01world");

// 2-pass engine: chooses raw copy if no NUL, else escapes
let engine = TWO_PASS_SED;
let enc = engine.encode(data);
assert_eq!(&enc[1..], b"hello\x01world");
let dec = engine.decode(enc);
assert_eq!(dec, data);