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
//! # IMAP protocol library
//!
//! imap-codec provides complete and detailed parsing and construction of [IMAP4rev1] commands and responses.
//! It is based on [imap-types] and extends it with parsing support using [nom].
//!
//! The main codecs are
//! [`GreetingCodec`](crate::GreetingCodec) (to parse the first message from a server),
//! [`CommandCodec`](crate::CommandCodec) (to parse commands from a client), and
//! [`ResponseCodec`](crate::ResponseCodec) (to parse responses or results from a server).
//!
//! Note that IMAP traces are not guaranteed to be UTF-8.
//! Thus, be careful when using code like `from_utf8(...)`.
//!
//! ## Decoding
//!
//! Decoding is provided through the [`Decoder`](`crate::decode::Decoder`) trait.
//! Every parser takes an input (`&[u8]`) and produces a remainder and a parsed value.
//!
//! **Note:** Decoding IMAP traces is more elaborate than it seems on a first glance.
//! Please consult the [`decode`](`crate::decode`) module documentation to learn how to handle real-world decoding.
//!
//! ### Example
//!
//! ```rust
//! # use imap_codec::{
//! # decode::Decoder,
//! # imap_types::{
//! # core::Text,
//! # response::{Code, Greeting, GreetingKind},
//! # },
//! # GreetingCodec,
//! # };
//! let (remaining, greeting) = GreetingCodec::default()
//! .decode(b"* OK [ALERT] Hello, World!\r\n<remaining>")
//! .unwrap();
//!
//! assert_eq!(
//! greeting,
//! Greeting {
//! kind: GreetingKind::Ok,
//! code: Some(Code::Alert),
//! text: Text::try_from("Hello, World!").unwrap(),
//! }
//! );
//! assert_eq!(remaining, &b"<remaining>"[..])
//! ```
//!
//! ## Encoding
//!
//! Encoding is provided through the [`Encoder`](`crate::encode::Encoder`) trait.
//!
//! **Note:** Encoding IMAP traces is more elaborate than it seems on a first glance.
//! Please consult the [`encode`](`crate::encode`) module documentation to learn how to handle real-world encoding.
//!
//! ### Example
//!
//! ```rust
//! # use imap_codec::{
//! # encode::Encoder,
//! # imap_types::{
//! # core::Text,
//! # response::{Code, Greeting, GreetingKind},
//! # },
//! # GreetingCodec,
//! # };
//! let greeting = Greeting {
//! kind: GreetingKind::Ok,
//! code: Some(Code::Alert),
//! text: Text::try_from("Hello, World!").unwrap(),
//! };
//!
//! let bytes = GreetingCodec::default().encode(&greeting).dump();
//!
//! assert_eq!(bytes, &b"* OK [ALERT] Hello, World!\r\n"[..]);
//! ```
//!
//! ## Features
//!
//! imap-codec forwards many features to imap-types. See [imap-types features] for a comprehensive list.
//!
//! In addition, imap-codec defines the following features:
//!
//! | Feature | Description | Enabled by default |
//! |-----------------------|--------------------------------|--------------------|
//! | quirk_crlf_relaxed | Make `\r` in `\r\n` optional. | No |
//! | quirk_rectify_numbers | Rectify (invalid) numbers. | No |
//! | quirk_missing_text | Rectify missing `text` element.| No |
//!
//! ## Quirks
//!
//! Features starting with `quirk_` are used to cope with existing interoperability issues.
//! Unfortunately, we already observed some standard violations, such as, negative numbers, and missing syntax elements.
//! Our policy is as follows: If we see an interoperability issue, we file an issue in the corresponding implementation.
//! If, for any reason, the issue cannot be fixed, *and* the implementation is "important enough", e.g., because a user of
//! imap-codec can't otherwise access their emails, we may add a `quirk_` feature to quickly resolve the problem.
//! Of course, imap-codec should never violate the IMAP standard itself. So, we need to do this carefully.
//!
//! [imap-types]: https://docs.rs/imap-types/latest/imap_types
//! [imap-types features]: https://docs.rs/imap-types/latest/imap_types/#features
//! [IMAP4rev1]: https://tools.ietf.org/html/rfc3501
//! [parse_command]: https://github.com/duesee/imap-codec/blob/main/examples/parse_command.rs
pub use *;
// Re-export.
pub use imap_types;