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