Tcl Library Source Code

mime - Mime
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2018 Conference, Houston/TX, US, Oct 15-19
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Aug 20.

[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

mime(n) 1.6 tcllib "Mime"

Name

mime - Manipulation of Internet messages

Description

Provides commands to create and manipulate Internet messages.

::mime::initialize ?-canonical type/subtype? ?-params dictionary? ?-encoding value? ?-headers dictionary? ?(-chan name | -file name | -string value | -parts parts)?

Parses a message and returns a token for the message. One of -chan, -file, or -string must be provided as the source of the input. If -canonical is provided the input is the body only and is already formatted according to the provided type/subtype, and therefore should not be parsed. If parts is provided it is a list of tokens for messages that comprise a multipart/mixed message body. -params is a multidict (a dictionary where the keys may not be unique) of parameters for the Content-Type header. -headers is a multidict of headers.

-encoding sets the Content-Transfer-Encoding.

::mime::body token ?-decode? ?-blocksize octets?"

Returns as a string in canonical form the body of the message corresponding to token.

If -blocksize is provided, returns a command that itself returns up to the next octets of the message each time it's called, and returns a code of break when finished, deleting itself as well. If octets is the empty string, a default value is used. Pauses the current coroutine as needed to wait for input.

-decode converts the message body from the character set it is encoded in.

::mime::datetime (time | -now) property

Returns the property of time, which 822-style date-time value.

Available properties and their ranges are:

hour

0 .. 23

lmonth

January, February, ..., December

lweekday

Sunday, Monday, ... Saturday

mday

1 .. 31

min

0 .. 59

mon

1 .. 12

month

Jan, Feb, ..., Dec

proper

822-style date-time specification

rclock

elapsed seconds between then and now

sec

0 .. 59

wday

0 .. 6 (Sun .. Mon)

weekday

Sun, Mon, ..., Sat

yday

1 .. 366

year

1900 ...

zone

-720 .. 720 (minutes east of GMT)

::mime::finalize token ?-subordinates all | dynamic | none?

Destroys the message corresponding to token and returns the empty string.

-subordinates specifies which messages comprising the body should also be destroyed. The default value is dynamic, which destroys all component messages that were created by ::mime::initialize.

::mime::header serialize value parameters

Serialize a header.

::mime::header get token ?key | -names?

Returns the header of a message as a multidict where each value is a list containing the header value and any parameters for that value.

If name is provided returns a list of values for that name, without regard to case.

If -names is provided, returns a list of all header names.

::mime::header set token name value ?parameters ?-mode write | append | delete??

If append is provided, creates a new header named name with the value of value is added. If write is provided, deletes any existing headers whose names match key and then creates a new header named key with the value of value. If delete is provided, deletes any existing header having a name that matches key. parameters is a dictionary of parameters for the header. Returns a list of strings containing the previous value associated with the key.

The value for -mode is one of:

write

The key/value is either created or overwritten (the default).

append

Appends a new key/value.

delete

Removes all values associated with the key. value is ignored.

::mime::property token ?name | -names?

Returns a dictionary of message properties. If name is provided, only the corresponding value is returned. If -names is provided, a list of all property names is returned.

properties:

content

The type/subtype of the content

encoding

The "Content-Transfer-Encoding"

params

A list of "Content-Type" parameters

parts

A list of tokens for messages that should comprise a multipart body. Only exists if there are any such messages.

size

The approximate size of the unencoded content.

::mime::serialize token ?-chan channel?

Return the serialization of the message corresponding to token. If -chan is provided, write the message to channel and return the empty string. Pauses the current coroutine as needed to wait for input to become available.

::mime::parseaddress addresses

Returns a list of describing the comma-separated 822-style addresses.

Each dictionary contains the following keys, whose values may be the empty string:

address

local@domain

comment

822-style comment

domain

the domain part (rhs)

error

non-empty on a parse error

group

this address begins a group

friendly

user-friendly rendering

local

the local part (lhs)

memberP

this address belongs to a group

phrase

the phrase part

proper

822-style address specification

route

822-style route specification (obsolete)

::mime::mapencoding encoding_name

Maps Tcl encodings onto the proper names for their MIME charset type. This is only done for encodings whose charset types were known. The remaining encodings return "" for now.

::mime::reversemapencoding charset_type

Maps MIME charset types onto tcl encoding names. Those that are unknown return "".

KNOWN BUGS

Tcllib Bug #447037

This problem affects only people which are using Tcl and Mime on a 64-bit system. The currently recommended fix for this problem is to upgrade to Tcl version 8.4. This version has extended 64 bit support and the bug does not appear anymore.

The problem could have been generally solved by requiring the use of Tcl 8.4 for this package. We decided against this solution as it would force a large number of unaffected users to upgrade their Tcl interpreter for no reason.

See Ticket 447037 for additional information.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category mime of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

Category

Text processing