# 📫 mml-lib
Rust implementation of the *Emacs MIME message Meta Language*, as known as [MML](https://www.gnu.org/software/emacs/manual/html_node/emacs-mime/Composing.html).
## Features
- Compiles MML to MIME messages
- Interprets MIME messages as MML
- Supports multiple parts `<#multipart>…<#/multipart>`
- Supports inline part `<#part text=mime/type>…<#/part>`
- Supports attachment `<#part disposition=attachment filename=/path/to/attachment.ext><#/part>`
- Supports comment `<#!part>This will not be compiled<#!/part>`
- Supports **tokio** and **async-std** async runtimes
- Supports **rustls** and **native-tls** crypto libs
- Supports **PGP**: shell commands, GPG bindings or native implem with [`pgp-lib`](https://crates.io/crates/pgp-lib)
- Retrieves PGP secret keys and passphrases from shell commands or global keyring via [`secret-lib`](https://crates.io/crates/secret-lib)
- Supports **serde** (de)serialization
The library comes with 13 [cargo features](https://doc.rust-lang.org/cargo/reference/features.html), including 4 default ones:
- **`tokio`**: enables the [tokio](https://crates.io/crates/tokio) async runtime
- `async-std`: enables the [async-std](https://crates.io/crates/async-std) async runtime
- **`rustls`**: enables the [rustls](https://crates.io/crates/rustls) crypto
- `native-tls`: enables the [native-tls](https://crates.io/crates/native-tls) crypto
- **`compiler`**: enables MML to MIME compilation
- **`interpreter`**: enables MIME to MML interpretation
- `pgp-commands`: enables PGP using [shell commands](https://crates.io/crates/process-lib)
- `pgp-gpg`: enables PGP using [GPG bindings](https://crates.io/crates/gpgme)
- `pgp-native`: enables native PGP using [`pgp-lib`](https://crates.io/crates/pgp-lib)
- `command`: enables command-based [secrets](https://crates.io/crates/secret-lib) for `pgp-native`
- `keyring`: enables keyring-based [secrets](https://crates.io/crates/secret-lib) for `pgp-native`
- `derive`: enables [serde](https://crates.io/crates/serde) support
- `vendored`: compiles and statically link to a copy of non-Rust vendors like OpenSSL
## Definition
From the [Emacs documentation](https://www.gnu.org/software/emacs/manual/html_node/emacs-mime/MML-Definition.html):
> Creating a MIME message is boring and non-trivial. Therefore, a library called mml has been defined that parses a language called MML (MIME Meta Language) and generates MIME messages.
>
> The MML language is very simple. It looks a bit like an SGML application, but it’s not.
>
> The main concept of MML is the part. Each part can be of a different type or use a different charset. The way to delineate a part is with a ‘<#part ...>’ tag. Multipart parts can be introduced with the ‘<#multipart ...>’ tag. Parts are ended by the ‘<#/part>’ or ‘<#/multipart>’ tags. Parts started with the ‘<#part ...>’ tags are also closed by the next open tag.
>
> […]
>
> Each tag can contain zero or more parameters on the form ‘parameter=value’. The values may be enclosed in quotation marks, but that’s not necessary unless the value contains white space. So ‘filename=/home/user/#hello$^yes’ is perfectly valid.
## Examples
```eml
From: alice@localhost
To: bob@localhost
Subject: MML examples
This is a plain text part.
<#part type=text/html>
This is a HTML part.
<#/part>
<#part description="This is an attachment." filename=./examples/attachment.png><#/part>
```
compiles to:
```eml
MIME-Version: 1.0
From:
To:
Subject: MML examples
Message-ID: <17886a741feef4a2.f9706245cd3a3f97.3b41d60ef9e2fbfb@soywod>
Date: Tue, 26 Sep 2023 09:58:26 +0000
Content-Type: multipart/mixed;
boundary="17886a741fef2cb2_97a7dbff4c84bbac_3b41d60ef9e2fbfb"
--17886a741fef2cb2_97a7dbff4c84bbac_3b41d60ef9e2fbfb
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
This is a plain text part.
--17886a741fef2cb2_97a7dbff4c84bbac_3b41d60ef9e2fbfb
Content-Type: text/html; charset="utf-8"
Content-Transfer-Encoding: 7bit
This is a HTML part.
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="attachment.png"
Content-Transfer-Encoding: base64
iVBORw0KGgo…
--17886a741fef2cb2_97a7dbff4c84bbac_3b41d60ef9e2fbfb--
```
Other examples can be found at [`./examples`](https://github.com/pimalaya/core/tree/master/mml/examples):
```sh
cargo run --example
```
*See the full API documentation on [docs.rs](https://docs.rs/mml-lib/latest/mml/).*
## Sponsoring
[](https://nlnet.nl/)
Special thanks to the [NLnet foundation](https://nlnet.nl/) and the [European Commission](https://www.ngi.eu/) that helped the project to receive financial support from various programs:
- [NGI Assure](https://nlnet.nl/project/Himalaya/) in 2022
- [NGI Zero Entrust](https://nlnet.nl/project/Pimalaya/) in 2023
- [NGI Zero Core](https://nlnet.nl/project/Pimalaya-PIM/) in 2024 *(still ongoing)*
If you appreciate the project, feel free to donate using one of the following providers:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/soywod)
[](https://www.buymeacoffee.com/soywod)
[](https://liberapay.com/soywod)
[](https://thanks.dev/soywod)
[](https://www.paypal.com/paypalme/soywod)