Crate plantuml_encoding
source · [−]Expand description
Encoding and decoding text plantuml diagrams to facilitate communication of them through URL.
Overview
Consider the next plain text plantuml diagram:
@startuml
PUML -> RUST: HELLO
@enduml
It can be encoded to 0IO0sVz0StHXSdHrRMmAK5LDJ20jFY1ILLDKEY18HKnCJo0AG6LkP7LjR000
and with the help of the plantuml server (https://www.plantuml.com/plantuml/uml/
) it can be shared through URL.
Also, it can be decoded in the opposite direction.
Plantuml declares support for the following compression algorithms:
But in fact, plantuml supports only deflate
(with additional transformations close to base64) and hex
(with additional prefix ~h
). brotli
is turned off. So the crate supports only deflate
and hex
too.
Installation
In order to use this crate, you have to add it under [dependencies]
to your Cargo.toml
:
[dependencies]
plantuml_encoding = "2.0.3"
Article
There is an article very close describing the library under the hood.
Examples
use plantuml_encoding::{
decode_plantuml_deflate, decode_plantuml_hex,
encode_plantuml_deflate, encode_plantuml_hex,
FromPlantumlError,
};
fn main() -> Result<(), FromPlantumlError> {
// original puml
println!("--- Original puml ---");
let puml = "@startuml\nPUML -> RUST\n@enduml";
println!("Original puml:\n{}\n", puml);
// deflate
println!("--- Deflate ---");
let encoded_deflate = encode_plantuml_deflate(puml)?;
let decoded_deflate = decode_plantuml_deflate(&encoded_deflate)?;
println!("Encoded deflate: {}", encoded_deflate);
println!("Decoded deflate:\n{}\n", decoded_deflate);
// hex
println!("--- Hex ---");
let encoded_hex = encode_plantuml_hex(puml)?;
let decoded_hex = decode_plantuml_hex(&encoded_hex)?;
println!("Encoded hex: {}", encoded_hex);
println!("Decoded hex:\n{}\n", decoded_hex);
// deflate errors
println!("--- Deflate errors ---");
let empty_encoded_deflate = "";
let decoded_deflate = decode_plantuml_deflate(empty_encoded_deflate)
.unwrap_or_else(|_| "It's not decoded deflate".to_string());
println!("Decoded deflate error:\n{}\n", decoded_deflate);
let decoded_deflate = match decode_plantuml_deflate(empty_encoded_deflate) {
Ok(plantuml) => plantuml,
Err(FromPlantumlError(err)) => {
eprintln!("Decoded deflate error: {:?}", err);
String::from("Result from deflate error")
}
};
println!("Match decoded deflate error result:\n{}\n", decoded_deflate);
// hex errors
println!("--- Hex errors ---");
let decoded_hex = match decode_plantuml_hex("12345") {
Ok(plantuml) => plantuml,
Err(FromPlantumlError(err)) => {
eprintln!("Decoded hex error: {:?}", err);
String::from("Result from hex error")
}
};
println!("Match decoded hex error result:\n{}", decoded_hex);
Ok(())
}
And console output after cargo run
for these examples:
--- Original puml ---
Original puml:
@startuml
PUML -> RUST
@enduml
--- Deflate ---
Encoded deflate: SoWkIImgAStDuGe8zVLHqBLJ20eD3k5oICrB0Ge20000
Decoded deflate:
@startuml
PUML -> RUST
@enduml
--- Hex ---
Encoded hex: ~h407374617274756d6c0a50554d4c202d3e20525553540a40656e64756d6c
Decoded hex:
@startuml
PUML -> RUST
@enduml
--- Deflate errors ---
Decoded deflate error:
It's not decoded deflate
Decoded deflate error: "there is a problem during deflate decoding: `deflate decompression error`"
Match decoded deflate error result:
Result from deflate error
--- Hex errors ---
Decoded hex error: "there is a problem during hex decoding: `Odd number of digits`"
Match decoded hex error result:
Result from hex error
Also, you can consider tests inside the files.
Structs
If error appear, the crate always faults to error type FromPlantumlError
.
All other error types converted to this one.
No panic is expected.
Functions
Decode plantuml with deflate compression (with additional transformations close to base64)
Decode plantuml from hex
(with additional prefix ~h
)
Encode plantuml with deflate compression (with additional transformations close to base64)
Encode plantuml to hex
(with additional prefix ~h
)