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}