melib: include README.md as preamble of crate rustdocs
Signed-off-by: Manos Pitsidianakis <manos@pitsidianak.is>
This commit is contained in:
Manos Pitsidianakis
parent
12de82e7b4
commit
4a61a4b857
2 changed files with 43 additions and 25 deletions
|
|
@ -1,30 +1,41 @@
|
|||
<!-- SPDX-License-Identifier: EUPL-1.2 OR GPL-3.0-or-later -->
|
||||
# melib
|
||||
|
||||
[](https://github.com/meli/meli/blob/master/COPYING) [](https://crates.io/crates/melib) [](https://docs.rs/melib)
|
||||
|
||||
Library for handling email for email clients.
|
||||
|
||||
## Optional Features
|
||||
## Cargo Compile-time Features
|
||||
|
||||
| Feature flag | Dependencies | Notes |
|
||||
|---------------|--------------------------------------------------|------------------------------------------------------|
|
||||
| `maildir` | `notify` crate | Provides the *maildir* backend |
|
||||
| `mbox-notify` | `notify` crate | Provides notification support for the *mbox* backend |
|
||||
| `notmuch` | `maildir` feature | Provides the *notmuch* backend |
|
||||
| `imap` | `imap-codec` crate, `tls` feature | Provides the *IMAP* backend |
|
||||
| `jmap` | `http` feature, `url` crate with `serde` feature | Provides the *JMAP* backend |
|
||||
| `nntp` | `tls` feature | Provides the *NNTP* (Usenet) backend |
|
||||
| `smtp` | `tls` feature | Integrated async *SMTP* client |
|
||||
| `sqlite3` | `rusqlite` crate with `bundled-full` feature | Used in caches |
|
||||
| `gpgme` | | *GPG* use by dynamically loading `libgpgme.so` |
|
||||
| `http` | `isahc` crate | Used for *HTTP* client needs, notably JMAP` |
|
||||
| `tls` | `native-tls` crate | |
|
||||
| `http-static` | `isahc` crate with `static-curl` feature | Links with `curl` statically |
|
||||
| `tls-static` | `native-tls` crate with `vendored` feature | Links with `OpenSSL` statically where it's used |
|
||||
| `imap-trace` | `imap` feature | Connection trace logs on the `trace` logging level |
|
||||
| `jmap-trace` | `jmap` feature | Connection trace logs on the `trace` logging level |
|
||||
| `nntp-trace` | `nntp` feature | Connection trace logs on the `trace` logging level |
|
||||
| `smtp-trace` | `smtp` feature | Connection trace logs on the `trace` logging level |
|
||||
`melib` supports opting in and out of features at compile time with cargo features.
|
||||
|
||||
The contents of the `default` feature are:
|
||||
|
||||
```toml
|
||||
default = ["imap", "nntp", "maildir", "mbox-notify", "smtp"]
|
||||
```
|
||||
|
||||
A list of all the features and a description for each follows:
|
||||
|
||||
| Feature flag | Dependencies | Notes |
|
||||
|-------------------------------------------------|--------------------------------------------------|------------------------------------------------------|
|
||||
| <a name="maildir-feature">`maildir`</a> | `notify` crate | Provides the *maildir* backend |
|
||||
| <a name="mbox-notify-feature">`mbox-notify`</a> | `notify` crate | Provides notification support for the *mbox* backend |
|
||||
| <a name="notmuch-feature">`notmuch`</a> | `maildir` feature | Provides the *notmuch* backend |
|
||||
| <a name="imap-feature">`imap`</a> | `imap-codec` crate, `tls` feature | Provides the *IMAP* backend |
|
||||
| <a name="jmap-feature">`jmap`</a> | `http` feature, `url` crate with `serde` feature | Provides the *JMAP* backend |
|
||||
| <a name="nntp-feature">`nntp`</a> | `tls` feature | Provides the *NNTP* (Usenet) backend |
|
||||
| <a name="smtp-feature">`smtp`</a> | `tls` feature | Integrated async *SMTP* client |
|
||||
| <a name="sqlite3-feature">`sqlite3`</a> | `rusqlite` crate with `bundled-full` feature | Used in caches |
|
||||
| <a name="gpgme-feature">`gpgme`</a> | | *GPG* use by dynamically loading `libgpgme.so` |
|
||||
| <a name="http-feature">`http`</a> | `isahc` crate | Used for *HTTP* client needs, notably JMAP` |
|
||||
| <a name="tls-feature">`tls`</a> | `native-tls` crate | |
|
||||
| <a name="http-static-feature">`http-static`</a> | `isahc` crate with `static-curl` feature | Links with `curl` statically |
|
||||
| <a name="tls-static-feature">`tls-static`</a> | `native-tls` crate with `vendored` feature | Links with `OpenSSL` statically where it's used |
|
||||
| <a name="imap-trace-feature">`imap-trace`</a> | `imap` feature | Connection trace logs on the `trace` logging level |
|
||||
| <a name="jmap-trace-feature">`jmap-trace`</a> | `jmap` feature | Connection trace logs on the `trace` logging level |
|
||||
| <a name="nntp-trace-feature">`nntp-trace`</a> | `nntp` feature | Connection trace logs on the `trace` logging level |
|
||||
| <a name="smtp-trace-feature">`smtp-trace`</a> | `smtp` feature | Connection trace logs on the `trace` logging level |
|
||||
|
||||
## Example: Parsing bytes into an `Envelope`
|
||||
|
||||
|
|
@ -33,7 +44,7 @@ and body structure. Addresses in `To`, `From` fields etc are parsed into
|
|||
`Address` types.
|
||||
|
||||
```rust
|
||||
use melib::{Attachment, Envelope};
|
||||
use melib::{email::attachment_types::Text, Attachment, Envelope};
|
||||
|
||||
let raw_mail = r#"From: "some name" <some@example.com>
|
||||
To: "me" <myself@example.com>
|
||||
|
|
@ -80,15 +91,19 @@ ouiijDaaCCGQRgrpH3q4QYYXWDihxBE+7KCDDjnUIEVAADs=
|
|||
|
||||
let envelope = Envelope::from_bytes(raw_mail.as_bytes(), None).expect("Could not parse mail");
|
||||
assert_eq!(envelope.subject().as_ref(), "gratuitously encoded subject");
|
||||
assert_eq!(&envelope.message_id().display_bracket().to_string(), "<h2g7f.z0gy2pgaen5m@example.com>");
|
||||
assert_eq!(envelope.message_id(), "h2g7f.z0gy2pgaen5m@example.com");
|
||||
assert_eq!(&envelope.message_id().display_brackets().to_string(), "<h2g7f.z0gy2pgaen5m@example.com>");
|
||||
|
||||
let body = envelope.body_bytes(raw_mail.as_bytes());
|
||||
assert_eq!(body.content_type().to_string().as_str(), "multipart/mixed");
|
||||
|
||||
let body_text = body.text();
|
||||
let body_text = body.text(Text::Plain);
|
||||
assert_eq!(body_text.as_str(), "hello world.");
|
||||
|
||||
let subattachments: Vec<Attachment> = body.attachments();
|
||||
assert_eq!(subattachments.len(), 3);
|
||||
assert_eq!(subattachments[2].content_type().name().unwrap(), "test_image.gif");
|
||||
assert_eq!(
|
||||
subattachments[2].content_type().name().unwrap(),
|
||||
"test_image.gif"
|
||||
);
|
||||
```
|
||||
|
|
|
|||
|
|
@ -78,7 +78,10 @@
|
|||
* - [tag:VERIFY] Verify whether this is the correct way to do something
|
||||
* - [tag:DEBT] Technical debt
|
||||
*/
|
||||
|
||||
#![doc = include_str!("../README.md")]
|
||||
//!
|
||||
//! ## Description
|
||||
//!
|
||||
//! A crate that performs mail client operations such as
|
||||
//! - Hold an [`Envelope`] with methods convenient for mail client use. (see
|
||||
//! module [`email`])
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue