# Serialization and Archives Internals

This document explains the internal design of the `uLib` serialization system, which is built on top of **Boost.Serialization**. It provides custom archive implementations for various formats (XML, Text, Logging) and introduces **Human Readable Pairs (HRP)** for metadata-rich serialization.

---

## Architecture Overview

The `uLib` archive system extends the standard `boost::archive` templates to add domain-specific features. The main components are:

1.  **Custom Interface Layer**: Extends the default Boost archive API with additional operators and utilities.
2.  **Specialized Archive Implementations**: Specialized classes for XML, Text, and Logging.
3.  **HRP Support**: First-class support for `hrp` (Human Readable Pair) wrappers, which carry units, ranges, and descriptions.
4.  **Static Registration System**: Macros and explicit instantiations to handle polymorphic types and compilation isolation.

---

## Custom Interface Layer

All `uLib` archives use a custom interface defined in `Archives.h` via `uLib_interface_iarchive` and `uLib_interface_oarchive`. These templates add several key features:

| Feature | Operator/Method | Description |
|---|---|---|
| **Mapping Operator** | `operator==` | Aliased to `operator&` (Boost's standard mapping operator). |
| **Trace Operator** | `operator!=` | Used for trace/debug output of strings during serialization. |
| **Type Registration** | `register_type<T>()` | Registers a class type with the archive's internal serializer map. |
| **Standard IO** | `operator<<` / `operator>>` | Standard redirect for saving and loading. |

These interfaces are applied to the archives using template specialization of `boost::archive::detail::interface_iarchive` and `interface_oarchive`.

---

## Archive Variants

### XML Archives (`xml_iarchive`, `xml_oarchive`)
These inherit from `boost::archive::xml_iarchive_impl` and `xml_oarchive_impl`. 
- **Internals**: They override `load_override` and `save_override` to handle `boost::serialization::hrp<T>` specifically. 
- **XML Mapping**: When saving an `hrp`, it uses `save_start(name)` and `save_end(name)` to wrap the value in a named XML tag.

### Text Archives (`text_iarchive`, `text_oarchive`)
Standard text-based archives used for compact serialization. They use `StringReader` to consume decorative text markers during loading.

### Human Readable Text (`hrt_iarchive`, `hrt_oarchive`)
These are "naked" text archives that suppress most of Boost's internal metadata (object IDs, class IDs, versions).
- **Goal**: Produce text output that is easy for humans to read and edit.
- **Internals**: All overrides for Boost internal types (like `object_id_type`, `version_type`, etc.) are implemented as no-ops.

### Log Archive (`log_archive`)
An XML-based output archive specifically for debug logging.
- **Internals**: It forces every object into a Name-Value Pair (NVP) even if not provided by the user, and strips all technical metadata to keep the logs clean.

---

## HRP (Human Readable Pair) Integration

`hrp` is a core `uLib` wrapper (defined in `Serializable.h`) that extends Boost's `nvp`:

```cpp
// Example of HRP usage
ar & HRP2("Energy", m_energy, "MeV").range(0, 100);
```

### Internal Handling in Archives
Archives in `Archives.h` provide specific `save_override`/`load_override` for `hrp<T>`:
- **XML**: Maps the `name()` to an XML tag.
- **HRT**: Formats as `name: value [units]\n`.
- **Log**: Converts it to a standard Boost `nvp` for consistent XML logging.

---

## Registration and Polymorphism

### Registration Macro
The `ULIB_SERIALIZATION_REGISTER_ARCHIVE(Archive)` macro is crucial for polymorphic serialization. It instantiates the necessary template machinery to link the custom `Archive` type with any `Serializable` class exported via `BOOST_CLASS_EXPORT`.

### Explicit Instantiation
To reduce compilation times and provide a single point of failure for link-time issues, `uLib` uses explicit instantiations in `src/Core/Archives.cpp`. This file includes the `.ipp` implementation files from Boost and instantiates the `archive_serializer_map` and implementation classes for all `uLib` archive types.

---

## Utility: StringReader
The `StringReader` utility is used internally by text-based archives to parse and skip literals. For example:
- When loading a string literal from a text archive, `StringReader` consumes whitespace and ensures the stream matches the expected string, failing if there is a mismatch.
- This is vital for maintaining the structure of human-readable formats.