Rust implementation of the TPK format.
This repository contains the work-in-progress code of a Rust implementation for the TPK data format.
At the time of writing, the specification is not finalized, nor is this implementation fully compliant anyway. Therefore, I strongly advise to not use this crate, or even TPK data for that matter, for any important project.
At the moment, only manual writing/reading of elements is supported. This means that markers, folders and elements all need to be written and read manually.
For example, to write the TPK equivalent of the following JSON structure:
json
{
"format": "TPK",
"version": {
"name": "First Development Release",
"major": 0,
"minor": 1,
"patch": 0
}
}
you would need to do the following:
```rust use tpk::{Element, TpkWriter};
fn main() {
// "output" is an already created Write implementor
let mut writer = TpkWriter::new(output);
writer.writeelement(&Element::Marker("format".into()));
writer.writeelement(&Element::String("TPK".into()));
writer.writeelement(&Element::Marker("version".into()));
writer.writeelement(&Element::Folder);
writer.writeelement(&Element::Marker("name".into()));
writer.writeelement(&Element::String("First Development Release".into()));
writer.writeelement(&Element::Marker("major".into()));
writer.writeelement(&Element::UInteger8(0));
writer.writeelement(&Element::Marker("minor".into()));
writer.writeelement(&Element::UInteger8(1));
writer.writeelement(&Element::Marker("patch".into()));
writer.writeelement(&Element::UInteger8(0));
}
```
This looks quite verbose. Reading is even worse:
```rust use tpk::{Element, TpkReader};
fn main() {
// "input" is an already created Read implementor
let mut reader = TpkReader::new(input);
// At the moment end of file = syntax error, so let's treat errors as EOF
let mut in_version = false;
while let Ok(element) = reader.read_element() {
if in_version {
match element {
Element::Marker(name) if name == "name" => {
print_string("version name", reader.read_element().unwrap());
}
Element::Marker(name) if name == "major" => {
print_uint8("major version", reader.read_element().unwrap());
}
Element::Marker(name) if name == "minor" => {
print_uint8("minor version", reader.read_element().unwrap());
}
Element::Marker(name) if name == "patch" => {
print_uint8("patch version", reader.read_element().unwrap());
}
_ => panic!("Unrecognized entry"),
}
} else {
match element {
Element::Marker(name) if name == "format" => {
print_string("format", reader.read_element().unwrap());
}
Element::Marker(name) if name == "version" => {
in_version = true;
// Oops, we're not checking that version is a folder!
reader.read_element().unwrap();
}
_ => panic!("Unrecognized entry"),
};
}
}
}
fn print_string(name: &'static str, element: Element) { match element { Element::String(string) => println!("The {} is {}", name, string), _ => panic!("Expected string element, got something else"), }; }
fn print_uint8(name: &'static str, element: Element) { match element { Element::UInteger8(number) => println!("The {} is {}", name, number), _ => panic!("Expected unsigned integer element, got something else"), }; } ```
Ouch, that's rough! And we're not even supporting all edge cases... We could easily panic on some valid TPK data for this format (for example, a .. or / folder marker), or miss invalid data (for example, another element than a folder for version).
This way of writing and reading a file is called "element-mode". This is the lowest-level way of dealing with TPK data and should only be used by tools that need to manipulate raw TPK metadata. This is also the only way supported by tpk-rust, for now.
If your need is to casually and easily read and write data to and from TPK files, for example, it is best to wait for the entry-mode, tree-mode or even serde support to be implemented.
Since tpk-rust is planned to be the reference implementation for the TPK data format, major and minor releases will follow those of the specification.