Skip to main content

buffa/text/
mod.rs

1//! Textproto (text format) encoding and decoding.
2//!
3//! The protobuf text format is a human-readable debug representation:
4//!
5//! ```text
6//! name: "Alice"
7//! id: 42
8//! address {
9//!   street: "1 High St"
10//!   city: "London"
11//! }
12//! tags: "a"
13//! tags: "b"
14//! ```
15//!
16//! It is **not** a stable wire format — the spec permits implementations to
17//! vary whitespace, field ordering, and float formatting. Use binary or JSON
18//! for interchange. Textproto is for config files, golden-file tests, and
19//! logging.
20//!
21//! # Usage
22//!
23//! Generated message types implement [`TextFormat`] when the `text` feature
24//! is enabled in codegen. The convenience functions cover the common cases:
25//!
26//! ```ignore
27//! use buffa::text::{encode_to_string, decode_from_str};
28//!
29//! let s = encode_to_string(&my_msg);
30//! let parsed: MyMsg = decode_from_str(&s)?;
31//! ```
32//!
33//! For streaming or reuse, use [`TextEncoder`] / [`TextDecoder`] directly.
34//!
35//! # `no_std`
36//!
37//! Fully `no_std` + `alloc`. No external dependencies beyond the runtime
38//! crate itself.
39
40mod decoder;
41mod encoder;
42mod error;
43mod string;
44mod token;
45
46pub use decoder::TextDecoder;
47pub use encoder::TextEncoder;
48pub use error::{ParseError, ParseErrorKind};
49pub use string::{escape_bytes, escape_str, unescape, unescape_str, UnescapeError};
50pub use token::{NameKind, ScalarKind, Token, TokenKind, Tokenizer};
51
52use alloc::string::String;
53
54/// Textproto serialization for a [`Message`](crate::Message) type.
55///
56/// Implemented by generated code when the `text` feature is enabled in
57/// codegen. Hand-implementation is possible but — as with
58/// [`Message`](crate::Message) itself — discouraged outside of tests.
59///
60/// The trait is deliberately minimal: one method per direction, taking a
61/// mutable encoder/decoder. The encoder/decoder own all formatting and
62/// parsing state; the impl just dispatches on field names.
63pub trait TextFormat: crate::Message {
64    /// Write this message's fields to `enc`.
65    ///
66    /// Implementations call [`TextEncoder::write_field_name`] followed by
67    /// the appropriate `write_*` value method for each set field. Unset
68    /// singular fields and empty repeated fields are skipped.
69    ///
70    /// # Errors
71    ///
72    /// Propagates [`core::fmt::Error`] from the encoder's sink. When writing
73    /// to a `String`, this is always `Ok`.
74    fn encode_text(&self, enc: &mut TextEncoder<'_>) -> core::fmt::Result;
75
76    /// Merge fields from `dec` into this message.
77    ///
78    /// Implementations loop on [`TextDecoder::read_field_name`] until it
79    /// returns `None`, dispatching each name to the matching `read_*` call.
80    /// Generated implementations reject unknown names with
81    /// [`unknown_field`](TextDecoder::unknown_field). Hand-written
82    /// implementations can explicitly call
83    /// [`skip_value`](TextDecoder::skip_value) when lenient parsing is needed.
84    ///
85    /// # Errors
86    ///
87    /// Any [`ParseError`] from the decoder.
88    fn merge_text(&mut self, dec: &mut TextDecoder<'_>) -> Result<(), ParseError>;
89}
90
91/// Encode a message as a single-line textproto string.
92///
93/// Fields are separated by single spaces; no trailing newline.
94#[must_use]
95pub fn encode_to_string<M: TextFormat>(msg: &M) -> String {
96    let mut out = String::new();
97    let mut enc = TextEncoder::new(&mut out);
98    // Writing to a String never fails.
99    let _ = msg.encode_text(&mut enc);
100    out
101}
102
103/// Encode a message as a multi-line textproto string with 2-space indent.
104///
105/// One field per line; nested messages are indented. A trailing newline is
106/// appended when the output is non-empty, matching `txtpbfmt` and POSIX
107/// text-file conventions.
108#[must_use]
109pub fn encode_to_string_pretty<M: TextFormat>(msg: &M) -> String {
110    let mut out = String::new();
111    let mut enc = TextEncoder::new_pretty(&mut out);
112    let _ = msg.encode_text(&mut enc);
113    if !out.is_empty() {
114        out.push('\n');
115    }
116    out
117}
118
119/// Decode a message from a textproto string.
120///
121/// # Errors
122///
123/// Any [`ParseError`] — syntax errors, unknown field names, type
124/// mismatches, depth limit exceeded, or
125/// [`ParseErrorKind::ElementMemoryLimitExceeded`] when the repeated and map
126/// elements would materialize more than
127/// [`DEFAULT_ELEMENT_MEMORY_LIMIT`](crate::DEFAULT_ELEMENT_MEMORY_LIMIT).
128/// Use [`decode_from_str_with_element_memory_limit`] to raise that bound.
129pub fn decode_from_str<M: TextFormat + Default>(s: &str) -> Result<M, ParseError> {
130    let mut msg = M::default();
131    merge_from_str(&mut msg, s)?;
132    Ok(msg)
133}
134
135/// Merge a textproto string into an existing message.
136///
137/// Proto merge semantics: scalar fields are overwritten, repeated fields are
138/// appended, message fields are recursively merged.
139///
140/// # Errors
141///
142/// As [`decode_from_str`].
143pub fn merge_from_str<M: TextFormat>(msg: &mut M, s: &str) -> Result<(), ParseError> {
144    let mut dec = TextDecoder::new(s);
145    msg.merge_text(&mut dec)
146}
147
148/// Decode a message from a textproto string under a caller-supplied
149/// element-memory budget, in bytes.
150///
151/// [`decode_from_str`] applies
152/// [`DEFAULT_ELEMENT_MEMORY_LIMIT`](crate::DEFAULT_ELEMENT_MEMORY_LIMIT),
153/// which bounds what the parse materializes rather than what it reads. Raise
154/// it for trusted input that legitimately carries very many repeated
155/// elements; pass `usize::MAX` to disable.
156///
157/// # Errors
158///
159/// As [`decode_from_str`], plus
160/// [`ParseErrorKind::ElementMemoryLimitExceeded`]
161/// when the budget is exhausted.
162pub fn decode_from_str_with_element_memory_limit<M: TextFormat + Default>(
163    s: &str,
164    element_memory_limit: usize,
165) -> Result<M, ParseError> {
166    let mut msg = M::default();
167    let mut dec = TextDecoder::new(s).with_element_memory_limit(element_memory_limit);
168    msg.merge_text(&mut dec)?;
169    Ok(msg)
170}
171
172#[cfg(test)]
173mod map_entry_tests {
174    use super::*;
175
176    // Quick sanity check that the closure-taking map-entry methods on
177    // TextEncoder / TextDecoder produce and consume the expected syntax.
178    // The real exercise is in buffa-test via generated code on Inventory.
179
180    #[test]
181    fn encode_map_entry() {
182        let mut s = String::new();
183        let mut enc = TextEncoder::new(&mut s);
184        enc.write_field_name("m").unwrap();
185        let k = 42i32;
186        let v = "hello";
187        enc.write_map_entry(|enc| {
188            enc.write_field_name("key")?;
189            enc.write_i32(k)?;
190            enc.write_field_name("value")?;
191            enc.write_string(v)?;
192            Ok(())
193        })
194        .unwrap();
195        assert_eq!(s, r#"m {key: 42 value: "hello"}"#);
196    }
197
198    #[test]
199    fn decode_map_entry() {
200        let mut dec = TextDecoder::new(r#"m { key: 42 value: "hello" }"#);
201        assert_eq!(dec.read_field_name().unwrap(), Some("m"));
202        let mut k: Option<i32> = None;
203        let mut v: Option<String> = None;
204        dec.merge_map_entry(|d| {
205            while let Some(n) = d.read_field_name()? {
206                match n {
207                    "key" => k = Some(d.read_i32()?),
208                    "value" => v = Some(d.read_string()?.into_owned()),
209                    _ => d.skip_value()?,
210                }
211            }
212            Ok(())
213        })
214        .unwrap();
215        assert_eq!(k, Some(42));
216        assert_eq!(v.as_deref(), Some("hello"));
217    }
218}