Review/std.serialization
Contents
Description
std.serialization is a package authored by Jacob Carlborg and based on his Orange library. It enables saving any D data type to customizable format (using "archiver") and loading it back from serialized input.
Current state
This package has been under several reviews and is still being updated to match last comments
Review 1
Result
voting delayed, needs improved proposal integration in Phobos
Description
Lot of discussion during the first review was about stripping Orange of non-Phobos dependencies and adapting it as part of Phobos source tree. It has pretty much ended with consensus that more integrated source needs to be provided before further review.
Review 2
Result
voting delayed, critical design issues need to be addressed
Changelog
- Sources has been integrated into Phobos source tree - DDOC documentation has been provided in a form it should look like on dlang.org - Most utility functions/template code depends on have been inlined. Remaining `package` utility modules:
* std.serialization.archives.xmldocument * std.serialization.attribute * std.serialization.registerwrapper
Description
This time discussion was more focused on specific API decision and choices that need to be made before approval. Most important blocker was identified as lack of range-based interface that will fit into existing Phobos approach.
Other critical comments:
- Lack of simple practical examples to catch up fast
- Lack of clear definition of package goals and use cases
- Should use recent `documented unitttest` feature
- pre-UDA API should remain in Orange
- several naming and styling comments
- unclear requirements for binary archives (aka strict serializing vs permissive with reordering)
- should provide simple procedural wrappers for common operations
- Serializable interface too inflexible (and related functionality)
Lack of Phobos guidelines that needs to be addressed by upstream:
- Placement of package-wise / functional tests
- Placement of package-wise documentation / examples (package.d ?)
Jacob plans after review
My todo list looks like this: - write an overview documentation - improve the documentation for std.serialization.serializable to indicate it's not required - implement a convenience function for serializing - implement a convenience function for serializing to a file - remove Serializeable - check only for "toData" when serializing - check only for "fromData" when deserializing - split Serializer in to two parts - make the parts structs - possibly provide class wrappers - split Archive in two parts - add range interface to Serializer and Archive - rename all archives to archivers - replace ddoc comments with regular comments for all package protected symbols