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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
//! Archives: values written to bytes and read back exactly, in this
//! process or another (what pickling a figure rests on).
//!
//! A type is archivable when it implements [`Archive`]: it writes itself
//! to an [`Encoder`] and reads itself back from a [`Decoder`]. The format
//! is positional and compact: integers as LEB128 varints, floats as their
//! bits, strings and sequences with their length first, enum variants as
//! their index. Archives are read by the pltrs build that wrote them
//! ([`to_bytes`] heads them with the format and the crate version, which
//! [`from_bytes`] checks).
//!
//! * Plain types implement [`Archive`] with
//! [`archive_struct!`](crate::archive_struct) and
//! [`archive_enum!`](crate::archive_enum), which list their fields so
//! that a field added later fails to compile until it is archived too.
//! * Shared values keep their sharing: an [`Rc`](std::rc::Rc) reached
//! twice is written once and read back as one value, so state shared
//! through `Rc<RefCell<_>>` stays shared.
//! * Trait objects (`Box<dyn Trait>`, `Rc<dyn Trait>`) archive the
//! concrete type behind them, named by a tag
//! ([`archive_kinds!`](crate::archive_kinds)); a type of the program's
//! that pltrs does not know is archived by the program, through the
//! [`ProgramKinds`] it hands the encoder and the decoder.
//! * A value of the program's that the archive cannot hold (a Python
//! object, for pltrs's Python package) is an [`External`]: the archive
//! holds its index in the list of externals, which the program archives
//! in its own way beside the bytes.
//!
//! Reading never panics on malformed bytes: it fails with an
//! [`ArchiveError`], and nesting deeper than [`MAX_DEPTH`] is refused.
//!
//! ```
//! use pltrs_core::archive::{self, NoProgram};
//! use pltrs_core::{Bbox, Point};
//!
//! #[derive(Debug, PartialEq)]
//! struct Marker {
//! at: Point,
//! label: Option<String>,
//! }
//! pltrs_core::archive_struct!(Marker { at, label });
//!
//! let marker = Marker { at: Point::new(1.0, 2.0), label: Some("a".into()) };
//! let (bytes, externals) = archive::to_bytes(&marker, &NoProgram)?;
//! let back: Marker = archive::from_bytes(&bytes, &externals, &NoProgram)?;
//! assert_eq!(back, marker);
//! # Ok::<(), archive::ArchiveError>(())
//! ```
pub use ;
pub use Encoder;
pub use ArchiveError;
pub use ;
/// The bytes every archive starts with.
const MAGIC: & = b"PLTRSARC";
/// The version of the archive format itself, raised whenever the
/// encoding of a primitive or of the header changes.
const FORMAT: u64 = 1;
/// A value that writes itself to an archive and reads itself back.
///
/// `decode` reads exactly what `encode` wrote, in the same order. Types
/// with invariants check them when they are read, as their constructors
/// do, since the bytes may come from anywhere.
/// A value an [`Rc`](std::rc::Rc) shares in an archive (see
/// [`Encoder::shared`]): any [`Archive`] value, a string or slice, or a
/// trait object whose kinds [`archive_kinds!`](crate::archive_kinds)
/// lists.
/// Archives `value`: the bytes, headed by the format and pltrs's version,
/// and the externals they refer to, in the order of their indices.
/// `program` archives the program's types pltrs does not know.
/// Reads back a value archived by [`to_bytes`] with the externals it
/// returned (as the program restored them) and the same `program`.