[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]
