kobold_xml/lib.rs
1//! # kobold-xml
2//!
3//! A **clean-room, Rust-native COBOL-data XML layer**. It turns a decoded COBOL record (a tree of named
4//! fields with values) into deterministic XML, and is **independent of GnuCOBOL/libcob** -- it links no
5//! COBOL runtime and reproduces no runtime's exact bytes.
6//!
7//! > **Not a GnuCOBOL parity claim.** This is a forward-looking interchange layer: *what a safe Rust-native
8//! > COBOL XML layer should do*, not *what GnuCOBOL 3.2 does*. Its evidence is the `EXT.XML.*` court
9//! > namespace.
10//!
11//! ## v0.1 -- XML GENERATE
12//!
13//! ```
14//! use kobold_xml::{CobolField, record_to_xml, generate, GenerateOptions};
15//!
16//! let rec = CobolField::group("ACCOUNT", vec![
17//! CobolField::alnum("NAME", &b"JANE "[..]),
18//! CobolField::numeric("BALANCE", &b"104277"[..], 2, false), // 1042.77
19//! ]);
20//! let xml = generate(&record_to_xml(&rec), &GenerateOptions::default());
21//! assert_eq!(xml, "<ACCOUNT><NAME>JANE</NAME><BALANCE>1042.77</BALANCE></ACCOUNT>");
22//! ```
23//!
24//! - [`generate`] serializes an explicit [`XmlElement`] tree to deterministic XML (`EXT.XML.GENERATE.1`),
25//! with explicit text/attribute escaping (`EXT.XML.ESCAPE.1`).
26//! - [`record_to_xml`] maps a [`CobolField`] record tree to that XML tree (`FILLER` omitted; v0.1 value
27//! policy documented on the [`cobol`] module).
28//!
29//! ## v0.2 (planned) -- XML PARSE
30//!
31//! A real event stream + generate->parse round-trip (`EXT.XML.PARSE.1` / `EXT.XML.ROUNDTRIP.1`).
32#![forbid(unsafe_code)]
33
34pub mod generate;
35pub mod cobol;
36
37pub use cobol::{record_to_xml, sanitize_name, CobolField, CobolValue};
38pub use generate::{escape_attr, escape_text, generate, GenerateOptions, XmlElement, XmlNode};
39
40/// The extension court namespace -- never `GNURUST.*`. So a reader can never mistake this crate's evidence
41/// for a GnuCOBOL parity claim.
42pub const COURT_NAMESPACE: &str = "EXT.XML";