escnul 0.2.0

NUL-safe byte escaping for embedding in shell scripts
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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

#![cfg_attr(not(feature = "std"), no_std)]
#![doc = include_str!("../README.md")]
#![warn(missing_docs)]
extern crate alloc;

use alloc::{vec, vec::Vec};
use core::fmt;

pub mod escape;
pub use escape::{OnePassEscapeEngine, ShellDecodeMode, TrSedEngine, TwoPassEscapeEngine, TR_SED};

/// Error type returned by encoding and decoding operations.
#[derive(Debug, Clone, PartialEq, thiserror::Error)]
pub enum EscnulError {
    /// The output buffer was too small to hold the full result.
    #[error("Buffer too small")]
    BufferTooSmall(Progress),
    /// The input ended in the middle of an escape sequence.
    #[error("Truncated input")]
    TruncatedInput(Progress),
    /// The provided escape byte was invalid (must not be 0x00 or 0x01).
    #[error("Bad escape byte: {0:#04x}")]
    BadEscapes(u8),
}

/// Progress info returned by `EscnulError::BufferTooSmall` and
/// `EscnulError::TruncatedInput`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Progress {
    /// Number of bytes processed from the input buffer.
    pub processed: usize,
    /// Number of bytes written to the output buffer.
    pub written: usize,
}

impl fmt::Display for Progress {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "processed={}, written={}", self.processed, self.written)
    }
}

/// Trait for encoding a byte stream into a pre-allocated output buffer.
pub trait Encode {
    /// Encode `input` into `output`, returning the number of bytes written.
    ///
    /// # Errors
    ///
    /// - [`EscnulError::BadEscapes`] if the engine’s escape byte is invalid.
    /// - [`EscnulError::BufferTooSmall`] if `output` is too small.  The
    ///   contained [`Progress`] tells you how many bytes were produced
    ///   before running out of space.
    fn encode_slice<T: AsRef<[u8]>>(
        &self,
        input: T,
        output: &mut [u8],
    ) -> Result<usize, EscnulError>;

    /// Encode `input` into a newly allocated `Vec<u8>`.
    fn encode<T: AsRef<[u8]>>(&self, input: T) -> Vec<u8> {
        let mut output = vec![0; input.as_ref().len() * 2];
        let n = self.encode_slice(input, &mut output).unwrap();
        output.truncate(n);
        output
    }
}

/// Trait for decoding an escaped byte stream into its original bytes.
pub trait Decode {
    /// Decode `input` into `output`, returning the number of bytes written.
    ///
    /// # Errors
    ///
    /// - [`EscnulError::BadEscapes`] if the engine’s escape byte is invalid.
    /// - [`EscnulError::BufferTooSmall`] if `output` is too small.
    /// - [`EscnulError::TruncatedInput`] if `input` ends mid-escape.
    fn decode_slice<T: AsRef<[u8]>>(
        &self,
        input: T,
        output: &mut [u8],
    ) -> Result<usize, EscnulError>;

    /// Decode `input` into a newly allocated `Vec<u8>`.
    fn decode<T: AsRef<[u8]>>(&self, input: T) -> Vec<u8> {
        let mut output = vec![0; input.as_ref().len()];
        let n = self.decode_slice(input, &mut output).unwrap();
        output.truncate(n);
        output
    }
}

/// Marker trait for types that implement both [`Encode`] and [`Decode`].
pub trait Engine: Encode + Decode {}

#[cfg(feature = "std")]
/// Error type returned by the stream-oriented encoding helpers.
#[derive(Debug, thiserror::Error)]
pub enum StreamEncodeError {
    /// An I/O error occurred while streaming input or output.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// An escnul encoding error occurred while processing a chunk.
    #[error(transparent)]
    Escnul(#[from] EscnulError),
}