mail-headers

为 mail 库提供特定头部功能

该软件包为 mail 库提供特定头部功能。这包括

• HeaderName、Header 和 HeaderMap，作为通用 API 的一部分
• HeaderTryFrom、HeaderTryInto，因为 TryFrom/TryInto 特性不稳定，但我们需要类似的功能。
• 许多头部，如 _To、_From、Sender、Subject 等（注意，_To 和 _From 前面带有下划线 _，以防止在导入时发生名称冲突，即导入 _From as From 将会覆盖 std::convert::From，这可能导致极其令人烦恼的错误）。
• 许多组件，用于表示头部字段的正文内容/字段体，例如 MailboxList 或 Email。它们位于 components 模块中。
• 一个 headers! 宏，用于简化创建带有多个头部的 HeaderMap 的过程。
• 一个 def_headers! 宏，用于定义新的自定义头部

示例（HeaderMap）

一个头部映射是一个表示特定顺序中多个邮件头部的集合。可以创建如下

#[macro_use]
extern crate mail_headers;

// just import all headers
use mail_headers::*;
use mail_headers::error::ComponentCreationError;

fn create_headers() -> Result<HeaderMap, ComponentCreationError> {
    headers!{
        // from and to can have multiple values
        // until specialization is stable is array
        // is necessary
        _From: [("My Fancy Display Name", "[email protected]")],
        _To: [ "[email protected]", ],
        Subject: "Who are you?"
    }
}

fn main() {
    let headers = create_headers().unwrap();
    assert_eq!(headers.len(), 3);

    if let Some(subject) = headers.get_single(Subject) {
        // as long a you don't play around with custom headers AND
        // don't mix multiple implementations for the same header
        // `.unwrap()` is just fine.
        let subject = subject.expect("mixed different Subject header implementations");
        println!("found subject: {}", subject);
    }
}

示例（自定义头部）

如果需要，mail 库的用户可以创建自己的头部，但这应该谨慎进行。

请注意，第二个字段（即 unchecked { <name> }），期望一个特定的命名方案，自动生成的测试会检查是否违反了这个方案，但如果你只运行代码并忽略失败的测试，可能会出现奇怪的错误。（方案是将每个单词的首字母大写，其余字母小写，例如 X-Id 是可以的，但 X-ID 则不行）。这是因为头文件在字段查找时的方式。虽然这并不理想，但对于大多数用例来说，没有必要生成自定义头文件，而在将来这可能会通过使用 proc-derive 自动生成名称来规避。

#[macro_use]
extern crate mail_headers;

use mail_headers::components;

// this will define two headers `XFooEmail` and `XBarMailbox`
// the first will add a header field named `X-Foo-Email` with
// a value which is an `components::Email` and the second will
// add field with a value which is an `components::Mailbox`.
//
// Note that through the way they are defined `XFooEmail` can
// at most appear 1 time in an header map, while `XBarMailbox`
// can appear multiple times. Be aware that this is checked through
// so called validators which needs to be explicitly run, which they
// are if this header map is used to create a mail (running them
// when adding fields would be a mess as you would have to add
// transactions which can add/remove multiple fields at once, and
// implementing auto-generation for some fields which are required if
// some other fields are given in a certain way would be harder too).

// If in scope both can be used in the `headers!` macro,
// like any other header.
//
def_headers! {
    // the name of the auto-generated test
    test_name: validate_header_names,

    // the scope from which all components should be imported
    // E.g. `DateTime` refers to `components::DateTime`.
    scope: components,

    // definitions of the headers or the form
    // <type_name>, unchecked { <filed_name> }, <component>, <validator>
    XFooEmail, unchecked { "X-Foo-Email"      }, Email ,   maxOne,
    XBarMailbox, unchecked { "X-Bar-Mailbox" }, Mailbox, None
}

fn main() {
    let headers = headers! {
        XFooEmail: "[email protected]",
        XBarMailbox: ("My Funy Name", "[email protected]"),
        XBarMailbox: "[email protected]"
    }.unwrap();
}

文档

文档可以在 docs.rs 上查看。（一旦发布 ;) ）

许可证

根据您选择以下任意一种许可证

• Apache License，版本 2.0，（LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT 许可证（LICENSE-MIT 或 http://opensource.org/licenses/MIT）

由您选择。

贡献

除非您明确表示，否则根据 Apache-2.0 许可证定义的，您有意提交的任何旨在包含在作品中的贡献，都将根据上述内容双许可，不附加任何额外条款或条件。