Expand description

mailcap

mailcap is a parsing library for mailcap files.

Mailcap files are a format documented in RFC 1524, “A User Agent Configuration Mechanism For Multimedia Mail Format Information.” They allow the handling of MIME types by software aware of those types. For example, a mailcap line of text/html; qutebrowser '%s'; test=test -n "$DISPLAY" would instruct the software to open any HTML file with qutebrowser if you are running a graphical session, with the file replacing the '%s'.

mailcap is a parsing library that looks at either a present $MAILCAPS env variable or cycles through the four paths where a mailcap file would be found in ascending order of importance: /usr/local/etc/mailcap, /usr/etc/mailcap, /etc/mailcap, and $HOME/.mailcap. It builds the mailcap from all available files, with duplicate entries being squashed with newer lines, allowing $HOME/.mailcap to be the final decider.

The entries that make up the mailcap include only those that are relevant i.e. those that have passed the test field (if present). With the above text/html example, that test would fail if run through SSH, and unless another existing text/html entry (or text/*) exists that doesn’t require a display server, no entry would exist for that mime type.

Usage

use mailcap::{Mailcap, MailcapError};

fn main() -> Result<(), MailcapError> {
    let cap = Mailcap::new()?;
    if let Some(i) = cap.get("text/html") {
        let command = i.viewer("/var/www/index.html");
        assert_eq!(command, "qutebrowser '/var/www/index.html'");
    }
    Ok(())
}

Wildcard fallbacks are also supported.

use mailcap::{Mailcap, MailcapError};

fn main() -> Result<(), MailcapError> {
    let cap = Mailcap::new()?;
    if let Some(i) = cap.get("video/avi") {
        // if no video/avi MIME entry available
        let mime_type = i.mime();
        assert_eq!(mime_type, "video/*");
    }
    Ok(())
}

Structs

Parsed mailcap line. Each mailcap entry consists of a number of fields, separated by semi-colons. The first two fields are required, and must occur in the specified order. The remaining fields are optional, and may appear in any order.

Meta representation of all available mailcap files and their combined lines.

Enums

The error type for mailcap.