[comment {-*- tcl -*- doctools manpage}]
[manpage_begin mime n 1.6]
[see_also ftp]
[see_also http]
[see_also pop3]
[see_also smtp]
[keywords email]
[keywords internet]
[keywords mail]
[keywords mime]
[keywords net]
[keywords {rfc 821}]
[keywords {rfc 822}]
[keywords {rfc 2045}]
[keywords {rfc 2046}]
[keywords {rfc 2049}]
[keywords smtp]
[copyright {1999-2000 Marshall T. Rose}]
[copyright {2018 Poor Yorick}]
[moddesc {Mime}]
[titledesc {Manipulation of Internet messages}]
[category {Text processing}]
[require Tcl 8.5]
[require mime [opt 1.6]]
[description]
[para]
Provides commands to create and manipulate Internet messages.
[list_begin definitions]
[call [cmd ::mime::.new] [arg name] [opt [arg options]]]
Parses a message, creates an routine named [arg name] as a handle for the
message, and returns the name of the new routine. If [arg name] is the empty
string, a name is automatically generated. One and only one of [
option -chan
], [
option -file
], or [
option -string
] must be provided as the source of the input. Optional arguments are
processed such that later arguments override earlier arguments. For example,
provide [option -addcontentid] [const 1] after [option "-spec [const http]"] has disabled
that option. The optional arguments are
[list_begin definitions]
[def "[option -addcontentid] [arg boolean]"]
Indicates whether a [const Content-ID] header field should be added to
the message. By default, this header is added to non-canonical
messages.
[def "[option -addmimeversion] [arg boolean]"]
Indicates whether a [const MIME-Version] header should be added to
non-canonical messages. By default, this header is added to
non-canonical messages.
[def "[option -canonical] [arg type/subtype]"]
The input message is the body only and is in the format
specified by the provided [
arg type/subtype
], and therefore should not be parsed.
[def "[option -chan] [arg channel]"]
The name of an ensemble command providing the standard channel commands.
[def "[option -encoding] [arg encoding]"]
sets the [const Content-Transfer-Encoding].
[def "[option -file] [arg string]"]
The file providing the input message.
[def "[option -headers] [arg headers]"]
[arg headers] is a multidict of headers.
[def "[option -spec] [arg spec]"]
[arg spec] is one of [const mime] (the default) or [const http],
indicating what specification to conform to. For [const mime], the
default [const Content-Type] is [const text/plain] and the character
set is assumed to be [const US-ASCII]. For [const http], the default
[const Content-Type] is [const text/html], the [const charset] is
[const utf-8], and [const MIME-Version] and [const Content-ID] headers
are by default not automatically added.
[def "[option -params] [arg params]"]
[arg params] is a multidict (a dictionary where the keys may not be
unique) of parameters for the [
const Content-Type
] header.
[def "[option -parts] [arg parts]"]
[arg parts] is list of tokens for messages that comprise a [
const multipart/mixed
] message body.
[def "[option -string] [arg string]"]
The string providing the input message.
[list_end]
[call [arg message] [method body] [opt [option -decode]] [opt "[option -blocksize] [arg octets]"]"]
Sets to [const 0] the cursor for the channel holding the body of the message
and returns the name of a channel command for that channel.
[para]
If [option -blocksize] is provided, returns a command that itself returns up to
the next [arg octets] of the message each time it's called, and returns a code
of [const break] when finished, deleting itself as well. If [arg octets] is
the empty string, a default value is used.
[para]
[option -decode] converts the message body from the character set it is encoded
in.
[call [arg message] [method {cookie delete}] [arg args]]
Deletes the specifed cookie. [arg args] is the same as for
[method {cookie set}], except that [arg -value] is not needed and
[arg -expires] is ignored.
[call [arg message] [method {cookie set}] [arg name] [arg value] [arg args]]
Sets a cookie header.
[arg args] is a dictionary options:
[list_begin definitions]
[def "[option expires] [arg date]"]
[def "[option path] [arg {path restriction}]"]
[def "[option domain] [arg {domain restriction}]"]
[list_end]
[call [arg message] [method .destroy] [opt "[option -subordinates] [const all] | [const dynamic] | [const none]"]]
Destroys the message and returns the empty string.
[para]
[option -subordinates] specifies which messages comprising the body should also
be destroyed. The default value of [const dynamic] indicates all component
messages that were created while parsing a message. [const all] indicates
all component messages. [const none] indicates that no component messages should be
destroyed.
[call [arg message] [method header] [method serialize] [arg value] [arg parameters]]
Returns the the serialization of a header.
[call [arg message] [method header] [method get] [opt "[arg key] | [option -names]"]]
Returns the header of a message as a multidict where each value is a list
containing the header value and a dictionary of parameters for that header.
[para]
If [arg name] is provided, returns the value and parameters of the last entry
matching that name, without regard to case.
[para]
If [option -names] is provided, returns a list of all header names.
[call [arg message] [method header] [method set] [arg {name value}] [ \
opt "[arg parameters] [opt "[option -mode] [const write] | [\
const append] | [const delete]"]"]]
[arg parameters] is a dictionary of parameters for the header. If parameters
contains an odd number of items, the last item is a list of flag parameters.
If [const append] is provided, creates a new header named [arg name] with the
value of [arg value] and any provided [arg parameters].
If [const write] is provided, first deletes any existing headers matching
[arg name].
If [const delete] is provided, deletes any existing header matching [arg name].
Returns a list of strings containing the previous value associated with the
key.
[para]
The value for [option -mode] is one of:
[list_begin definitions]
[def [const write]]
The [arg key]/[arg value] is either created or overwritten (the default).
[def [const append]]
Appends a new [arg key]/[arg value].
[def [const delete]]
Removes all values associated with the key. [arg value] is ignored.
[list_end]
[call [arg message] [method property] [opt "[arg name] | [option -names]"]]
Returns a dictionary of message properties. If [arg name] is provided, only
the corresponding value is returned. If [option -names] is provided, a list
of all property names is returned.
[para]
properties:
[list_begin definitions]
[def [const content]]
The type/subtype of the content
[def [const encoding]]
The "Content-Transfer-Encoding"
[def [const params]]
A list of "Content-Type" parameters
[def [const parts]]
A list of tokens for messages that comprise a multipart body. Only exists if
there are any such messages.
[def [const size]]
The approximate size of the unencoded content.
[list_end]
[call [arg message] [method serialize] [opt [option -level]] [
opt "[option -chan] [arg channel]"]]
Returns the serialization of the message. If
[option -chan] is provided, writes the serialization to [arg channel] and returns the
empty string. [option -level], if provided, indicates the level of the part
in the message hierarchy. The [const MIME-Version] header is only included at
level [const 0].
[call [cmd ::mime::datetime] ([arg time] | [option -now]) [arg property]]
Returns the [arg property] of [arg time], which is an 822-style date-time
value.
[para]
Available properties and their ranges are:
[list_begin definitions]
[def [const hour]]
0 .. 23
[def [const lmonth]]
January, February, ..., December
[def [const lweekday]]
Sunday, Monday, ... Saturday
[def [const mday]]
1 .. 31
[def [const min]]
0 .. 59
[def [const mon]]
1 .. 12
[def [const month]]
Jan, Feb, ..., Dec
[def [const proper]]
822-style date-time specification
[def [const rclock]]
elapsed seconds between then and now
[def [const sec]]
0 .. 59
[def [const wday]]
0 .. 6 (Sun .. Mon)
[def [const weekday]]
Sun, Mon, ..., Sat
[def [const yday]]
1 .. 366
[def [const year]]
1900 ...
[def [const zone]]
-720 .. 720 (minutes east of GMT)
[list_end]
[call [cmd ::mime::parseaddress] [arg addresses]]
Returns a list describing the comma-separated 822-style [arg addresses].
[para]
Each dictionary contains the following keys, whose values may be the empty
string:
[list_begin definitions]
[def [const address]]
local@domain
[def [const comment]]
822-style comment
[def [const domain]]
the domain part (rhs)
[def [const error]]
non-empty on a parse error
[def [const group]]
this address begins a group
[def [const friendly]]
user-friendly rendering
[def [const local]]
the local part (lhs)
[def [const memberP]]
this address belongs to a group
[def [const phrase]]
the phrase part
[def [const proper]]
822-style address specification
[def [const route]]
822-style route specification (obsolete)
[list_end]
[call [cmd ::mime::mapencoding] [arg 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.
[call [cmd ::mime::reversemapencoding] [arg charset_type]]
Maps MIME charset types onto tcl encoding names. Those
that are unknown return "".
[list_end]
[vset CATEGORY mime]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
