serde_resp/lib.rs
1//! # serde-RESP
2//! Redis RESP protocol serialization and deserialization with serde.
3//! [Read Specification](https://redis.io/topics/protocol)
4//!
5//! ## Usage
6//! **IMPORTANT: Do NOT (de)serialize with any other types besides `RESP/RESPType`! You may get panic or incorrect results!**
7//! [Why?](https://github.com/DEDZTBH/serde-RESP/blob/master/README.md#why-resptype-wrapper)
8//!
9//! Here are the RESP types and their corresponding Rust types for (de)serialize operations.
10//!
11//! - `Simple String`
12//! + [RESP::SimpleString(String)](RESPType::SimpleString)
13//! - `Error`
14//! + [RESP::Error(String)](RESPType::Error)
15//! - `Integer`
16//! + [RESP::Integer(i64)](RESPType::Integer)
17//! - `Bulk String`
18//! + [RESP::BulkString(Option<Vec<u8>>)](RESPType::BulkString)
19//! + Use `None` for null bulk strings and `Some` for non-null ones.
20//! - `Array`
21//! + [RESP::Array(Option<Vec<RESP>>)](RESPType::Array)
22//! + Use `None` for null arrays and `Some` for non-null ones.
23//!
24//! To serialize, use [ser::to_string](ser::to_string) or [ser::to_writer](ser::to_writer).
25//!
26//! To deserialize, use [de::from_str](de::from_str) or [de::from_reader](de::from_reader) or [de::from_buf_reader](de::from_buf_reader).
27//!
28//! For usage examples, refer to [RESP](RESP)
29//!
30//! ## Macros
31//!
32//! Since 0.3.0, you can start using very handy macros! Here is a demo:
33//! ```
34//! use serde_resp::{array, array_null, bulk, bulk_null, de, err_str, int, ser, simple, RESP};
35//! let resp_array = array![
36//! simple!("simple string".to_owned()),
37//! err_str!("error string".to_owned()),
38//! int!(42),
39//! bulk!(b"bulk string".to_vec()),
40//! bulk_null!(),
41//! array![
42//! simple!("arrays of arrays!".to_owned()),
43//! array![simple!("OK ENOUGH!".to_owned())],
44//! ],
45//! array_null!(),
46//! ];
47//! let serialized = ser::to_string(&resp_array).unwrap();
48//! assert_eq!(
49//! "*7\r\n+simple string\r\n-error string\r\n:42\r\n$11\r\nbulk string\r\n$-1\r\n*2\r\n+arrays of arrays!\r\n*1\r\n+OK ENOUGH!\r\n*-1\r\n",
50//! serialized
51//! );
52//! let deserialized = de::from_str(&serialized).unwrap();
53//! assert_eq!(resp_array, deserialized);
54//! ```
55
56pub mod de;
57mod error;
58mod macros;
59pub mod ser;
60
61pub use error::{Error, Result};
62
63/// This enum creates a one-to-one type mapping with RESP types.
64/// Please only use variants of this type for (de)serialize operations.
65#[derive(Eq, PartialEq, Clone, Debug)]
66pub enum RESPType {
67 /// Correspond to simple string in RESP.
68 /// Also refer to [simple!](simple!) macro.
69 ///
70 /// # Examples
71 /// ```
72 /// use serde_resp::{de, ser, simple, RESP};
73 ///
74 /// /// Serialization
75 /// let obj = simple!("OK".to_owned()); // equivalent to RESP::SimpleString("OK".to_owned());
76 /// let serialized = ser::to_string(&obj).unwrap();
77 /// assert_eq!("+OK\r\n".to_owned(), serialized);
78 ///
79 /// /// Deserialization
80 /// let deserialized: RESP = de::from_str("+OK\r\n").unwrap();
81 /// assert_eq!(simple!("OK".to_owned()), deserialized);
82 /// ```
83 SimpleString(String),
84 /// Correspond to error string in RESP.
85 /// Also refer to [err_str!](err_str!) macro.
86 ///
87 /// # Examples
88 /// ```
89 /// use serde_resp::{de, err_str, ser, RESP};
90 ///
91 /// /// Serialization
92 /// // Example 1
93 /// let obj = err_str!("ERR unknown command 'foobar'".to_owned()); // equivalent to RESP::Error(...)
94 /// let serialized = ser::to_string(&obj).unwrap();
95 /// assert_eq!("-ERR unknown command 'foobar'\r\n".to_owned(), serialized);
96 ///
97 /// // Example 2
98 /// let obj = err_str!("WRONGTYPE Operation against a key holding the wrong kind of value".to_owned());
99 /// let serialized = ser::to_string(&obj).unwrap();
100 /// assert_eq!(
101 /// "-WRONGTYPE Operation against a key holding the wrong kind of value\r\n".to_owned(),
102 /// serialized
103 /// );
104 ///
105 /// /// Deserialization
106 /// let deserialized: RESP = de::from_str("-ERR unknown command 'foobar'\r\n").unwrap();
107 /// assert_eq!(err_str!("ERR unknown command 'foobar'".to_owned()), deserialized);
108 /// ```
109 Error(String),
110 /// Correspond to integer in RESP.
111 /// Also refer to [int!](int!) macro.
112 ///
113 /// # Examples
114 /// ```
115 /// use serde_resp::{de, int, ser, RESP};
116 ///
117 /// /// Serialization
118 /// // Regular Example
119 /// let obj = int!(1000); // equivalent to RESP::Integer(1000);
120 /// let serialized = ser::to_string(&obj).unwrap();
121 /// assert_eq!(":1000\r\n".to_owned(), serialized);
122 ///
123 /// /// Deserialization
124 /// let deserialized: RESP = de::from_str(":1000\r\n").unwrap();
125 /// assert_eq!(int!(1000), deserialized);
126 /// ```
127 Integer(i64),
128 /// Correspond to bulk string in RESP. Use `None` for null bulk string and Some for non-null ones.
129 /// Also refer to [bulk!](bulk!) macro and [bulk_null!](bulk_null!) macro.
130 ///
131 /// According to specification, bulk string is binary-safe so it is NOT recommended to use [ser::to_string](ser::to_string) (may cause [Error::FromUtf8](Error::FromUtf8)).
132 /// Use [ser::to_writer](ser::to_writer) to write to a byte buffer instead.
133 ///
134 /// # Examples
135 /// ```
136 /// use serde_resp::{bulk, bulk_null, de, ser, RESP};
137 ///
138 /// /// Serialization
139 /// // Regular Example
140 /// let obj = bulk!(b"foobar".to_vec()); // equivalent to RESP::BulkString(Some(...))
141 /// let serialized = ser::to_string(&obj).unwrap();
142 /// assert_eq!("$6\r\nfoobar\r\n".to_owned(), serialized);
143 ///
144 /// // Empty
145 /// let obj = bulk!(b"".to_vec());
146 /// let serialized = ser::to_string(&obj).unwrap();
147 /// assert_eq!("$0\r\n\r\n".to_owned(), serialized);
148 ///
149 /// // Null
150 /// let obj = bulk_null!(); // equivalent to RESP::BulkString(None)
151 /// let serialized = ser::to_string(&obj).unwrap();
152 /// assert_eq!("$-1\r\n".to_owned(), serialized);
153 ///
154 /// /// Deserialization
155 /// // Regular Example
156 /// let deserialized: RESP = de::from_str("$6\r\nfoobar\r\n").unwrap();
157 /// assert_eq!(bulk!(b"foobar".to_vec()), deserialized);
158 ///
159 /// // Empty
160 /// let deserialized: RESP = de::from_str("$0\r\n\r\n").unwrap();
161 /// assert_eq!(bulk!(b"".to_vec()), deserialized);
162 ///
163 /// // Null
164 /// let deserialized: RESP = de::from_str("$-1\r\n").unwrap();
165 /// assert_eq!(bulk_null!(), deserialized);
166 /// ```
167 BulkString(Option<Vec<u8>>),
168 /// Correspond to array in RESP. Use None for null array and Some for non-null ones.
169 /// Also refer to [array!](array!) macro and [array_null!](array_null!) macro.
170 ///
171 /// Mixed type, arrays of arrays are allowed.
172 ///
173 /// # Examples
174 /// ```
175 /// use serde_resp::{array, array_null, bulk, bulk_null, de, err_str, int, ser, simple, RESP};
176 ///
177 /// /// Serialization
178 /// // Empty
179 /// let obj = array![]; // equivalent to RESP::Array(Some(vec![]))
180 /// let serialized = ser::to_string(&obj).unwrap();
181 /// assert_eq!("*0\r\n".to_owned(), serialized);
182 ///
183 /// // Regular Example
184 /// let obj = array![
185 /// bulk!(b"foo".to_vec()),
186 /// bulk!(b"bar".to_vec()),
187 /// ]; // equivalent to RESP::Array(Some(vec![bulk!(...), bulk!(...)]))
188 /// let serialized = ser::to_string(&obj).unwrap();
189 /// assert_eq!("*2\r\n$3\r\nfoo\r\n$3\r\nbar\r\n".to_owned(), serialized);
190 ///
191 /// // Another Regular Example
192 /// let obj = array![
193 /// int!(1),
194 /// int!(2),
195 /// int!(3),
196 /// ];
197 /// let serialized = ser::to_string(&obj).unwrap();
198 /// assert_eq!("*3\r\n:1\r\n:2\r\n:3\r\n".to_owned(), serialized);
199 ///
200 /// // Mixed Type
201 /// let obj = array![
202 /// int!(1),
203 /// int!(2),
204 /// int!(3),
205 /// int!(4),
206 /// bulk!(b"foobar".to_vec()),
207 /// ];
208 /// let serialized = ser::to_string(&obj).unwrap();
209 /// assert_eq!(
210 /// "*5\r\n:1\r\n:2\r\n:3\r\n:4\r\n$6\r\nfoobar\r\n".to_owned(),
211 /// serialized
212 /// );
213 ///
214 /// // Null Array
215 /// let obj = array_null!(); // equivalent to RESP::Array(None)
216 /// let serialized = ser::to_string(&obj).unwrap();
217 /// assert_eq!("*-1\r\n".to_owned(), serialized);
218 ///
219 /// // Arrays of Arrays
220 /// let obj = array![
221 /// array![
222 /// int!(1),
223 /// int!(2),
224 /// int!(3),
225 /// ],
226 /// array![
227 /// simple!("Foo".to_owned()),
228 /// err_str!("Bar".to_owned()),
229 /// ],
230 /// ];
231 /// let serialized = ser::to_string(&obj).unwrap();
232 /// assert_eq!(
233 /// "*2\r\n*3\r\n:1\r\n:2\r\n:3\r\n*2\r\n+Foo\r\n-Bar\r\n".to_owned(),
234 /// serialized
235 /// );
236 ///
237 /// // Null elements in Arrays
238 /// let obj = array![
239 /// bulk!(b"foo".to_vec()),
240 /// bulk_null!(),
241 /// bulk!(b"bar".to_vec()),
242 /// ];
243 /// let serialized = ser::to_string(&obj).unwrap();
244 /// assert_eq!(
245 /// "*3\r\n$3\r\nfoo\r\n$-1\r\n$3\r\nbar\r\n".to_owned(),
246 /// serialized
247 /// );
248 ///
249 /// /// Deserialization
250 /// // Null
251 /// let deserialized: RESP = de::from_str("*-1\r\n").unwrap();
252 /// assert_eq!(array_null!(), deserialized);
253 ///
254 /// // Mixed Type
255 /// let deserialized: RESP = de::from_str("*2\r\n:1\r\n$6\r\nfoobar\r\n").unwrap();
256 /// let expected = array![
257 /// int!(1),
258 /// bulk!(b"foobar".to_vec()),
259 /// ];
260 /// assert_eq!(expected, deserialized);
261 ///
262 /// // Arrays of Arrays with Null Bulk String
263 /// let deserialized: RESP = de::from_str("*3\r\n*3\r\n:1\r\n:2\r\n:3\r\n$-1\r\n*2\r\n+Foo\r\n-Bar\r\n").unwrap();
264 /// let expected = array![
265 /// int!(1),
266 /// bulk!(b"foobar".to_vec()),
267 /// ];
268 /// let expected = array![
269 /// array![
270 /// int!(1),
271 /// int!(2),
272 /// int!(3),
273 /// ],
274 /// bulk_null!(),
275 /// array![
276 /// simple!("Foo".to_owned()),
277 /// err_str!("Bar".to_owned()),
278 /// ],
279 /// ];
280 /// assert_eq!(expected, deserialized);
281 /// ```
282 Array(Option<Vec<RESPType>>),
283}
284
285/// Refer to [RESPType](RESPType). This is just an alias.
286pub type RESP = RESPType;