Crate escnul 

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

no_std support

escnul supports no_std with alloc.

• default features: std
• no_std build: disable default features

[dependencies]
escnul = { version = "0.2", default-features = false }

The core escaping APIs work in no_std + alloc.

• Encode
• Decode
• OnePassEscapeEngine
• TwoPassEscapeEngine
• ShellDecodeMode::decoder_fragment
• TrSedEngine

The stream-oriented APIs require std and are only available with the std feature.

• StreamEncodeError
• TwoPassEscapeEngine::choose_shell_decode_mode_reader
• ShellDecodeMode::encode_reader

Overview

• escape module provides a low-overhead, reversible byte-escaping scheme for transforming 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.
• ShellDecodeMode exposes the low-level shell decode plan used for embedding payloads into POSIX shell scripts.
• ShellDecodeMode::encode_reader supports streaming Read -> Write encoding without buffering the whole payload in memory.
• 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);

Shell-oriented usage:

use escnul::{ShellDecodeMode, escape::TWO_PASS_SED};

let data = b"hello\0world";
let mode = TWO_PASS_SED.choose_shell_decode_mode(data);
assert!(matches!(mode, ShellDecodeMode::TrSed { .. }));

let fragment = mode.decoder_fragment(data.len() as u64);
assert!(fragment.contains("sed"));

Re-exports

pub use escape::OnePassEscapeEngine;

pub use escape::ShellDecodeMode;

pub use escape::TR_SED;

pub use escape::TrSedEngine;

pub use escape::TwoPassEscapeEngine;

Modules

escape

escnul – NUL-safe shell-friendly byte escaping

Structs

Progress

Progress info returned by EscnulError::BufferTooSmall and EscnulError::TruncatedInput.

Enums

EscnulError

Error type returned by encoding and decoding operations.

StreamEncodeError

Error type returned by the stream-oriented encoding helpers.

Traits

Decode

Trait for decoding an escaped byte stream into its original bytes.

Encode

Trait for encoding a byte stream into a pre-allocated output buffer.

Engine

Marker trait for types that implement both Encode and Decode.