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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
//! Encoding and decoding text plantuml diagrams to facilitate communication of them through URL.
//!
//! ## Overview
//!
//! Consider the next plain text plantuml diagram:
//!
//! ```plantuml
//! @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](https://www.plantuml.com/plantuml/uml/0IO0sVz0StHXSdHrRMmAK5LDJ20jFY1ILLDKEY18HKnCJo0AG6LkP7LjR000).
//!
//! Also, it can be decoded in the opposite direction.
//!
//! Plantuml [declares support](https://plantuml.com/text-encoding) for the following compression algorithms:
//!
//! * [deflate](https://en.wikipedia.org/wiki/Deflate)
//! * [brotli](https://en.wikipedia.org/wiki/Brotli)
//! * [hex](https://en.wikipedia.org/wiki/Hexadecimal)
//!
//! But in fact, plantuml supports only `deflate` (with [additional transformations close to base64](https://plantuml.com/text-encoding)) and `hex` (with [additional prefix `~h`](https://plantuml.com/text-encoding)). [`brotli` is turned off](https://forum.plantuml.net/15341/encoding-does-brotli-not-work-anymore-programatically-curl?show=15349). 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`:
//!
//! ```toml
//! [dependencies]
//! plantuml_encoding = "2.0.3"
//! ```
//!
//! ## Article
//!
//! There is an [article](https://maksugr.com/posts/plantuml-encoding-in-rust-using-tdd) very close describing the library under the hood.
//!
//! ## Examples
//!
//! ```rust
//! 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:
//!
//! ```console
//! --- 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.
pub use crate;
pub use crate FromPlantumlError;
pub use crate;