SIFT-TCL(1)

NAME

SYNOPSIS

DESCRIPTION

SETUP

      |/usr/local/bin/sift-tcl -spool

In order to use sift-tcl to interpret mail processing scripts, it need only be available on the system and is invoked with the -f option to specify the program file.

OPTIONS

-log

Causes a log of actions and errors to be written to the log file .siftlog in your home directory. It also causes any activity reporting specified in the Sift-Tcl program to be executed. All errors are written to the standard error stream as well as to the log.

-spool

For use in a .forward file where sift-tcl is passed a message and must assume responsibility for its delivery. The -spool option will cause sift-tcl to read a message from the standard input and execute the Sift-Tcl program in the file .sift-tcl in your home directory on it. An alternate Sift-Tcl program can be specified with the -f option. If there are any errors executing the Tcl code, the mail message will be written directly in to the inbox. If this can't be done because of further errors, it exits with a non-zero exit code to signal the mail delivery system that the message could not be delivered. This gives responsibility for delivering the message back to the delivery system. In this case some delivery systems will attempt to write the message to the inbox while others will return the message to the sender. The -spool option also implies the -log option.

-v

Causes a log of all actions to be written to the standard output. This is independent of the -log option. That is, the -v option will not cause .siftlog file to be written.

-f file

Specifies the Sift-Tcl code to execute. This must be given unless the -spool option is given. It can also be given along with the -spool option to override the default file.

OPERATION

The -spool options enables additional error processing which is described above. This is intended for use when sift-tcl is invoked in a .forward file. This options also turns on the -log flag.

Aside from the Tcl code in the program file, there may be meta-information embedded in Tcl-format comments that specify an activity report be generated. The report is generated when the Tcl program exits and is mailed to the user. The format of the meta-comments is specified below. When the Sift-Tcl program is generated by the sift-mail program, further meta-information is embedded in comments. This is completely ignored by sift-tcl. Note that if programs generated by sift-mail are edited manually, it should be done very carefully so the file can still be manipulated by sift-mail.

SIFT-TCL COMMANDS

Several functions operate on a message and require that it be specified. The whole text of the message can be given as an argument with the -body option. A folder handle and a message number can be given with the -folder and -number options. Folder handles are strings usually returned from the folder open function. In addition, a single message may be read from the standard input by specifying the folder handle as stdin and the message number as 1.

A number of the commands below operate on MIME format multi-part message format. Generation of outgoing MIME messages is supported, but parsing and access to sub-parts of received MIME messages is not (support is planned in a future version).

When interpreting the Sift-Tcl code, the Tcl variable inbox is set to the fully qualified name of the user's inbox.

SiftTcl_getheader field ?-body body? ?-folder handle -number number?

Returns the requested header field from the specified message or an empty string if the field does not exist. The string returned will include all continuation lines of the header (those lines following the header that begin with blank space).

SiftTcl_getheaders ?-body body? ?-folder handle -number number?

Returns a list with an element for each header in the specified mail message. Each header is returned as a list with two elements, the header field name and the contents of the header field. If the same header occurs several times it will be in the list several times.

SiftTcl_getaddrs string

Parses string for e-mail addresses and returns the result as a list. The addresses are assumed to be separated by commas, unless the comma is embedded in RFC-822 quoting ("" marks). The result is a list even if only one address is returned.

SiftTcl_getaddrprop address property

Parses the given RFC-822 address and returns the requested property. If an empty address is given, the properties returned are for the user's address. The properties follow:

proper

Official 822 rendering: Full Name <user@do.ma.in>

friendly

Returns the full name or the address if there is no full name

address

The user name and host: user@do.ma.in

domain

The domain part of the address: do.ma.in

mymbox

Returns "1" if address is the recipient's,otherwise "0"

phrase

The full name or phrase part

SiftTcl_getbodyprop part_num property ?-body body? ?-folder folder -number number?

Returns a specified part of a specified message. Part_num must be "1" for the current version. The properties are as follows:

all

The full unparsed message header and text

headers

The unparsed message headers

size

The size of the message (this is only approximate)

value

The unparsed body of the message

SiftTcl_open folder ?option?

Open the named folder and return a handle. Returns an error if the folder doesn't exist. Use SiftTcl_mail_append to create a new folder. See the section below on mail folder naming. Option may be either rw or ro to open the mail folder read-write or read-only. If the option is not given the folder will be open read-write. An error occurs if an attempt is made to open a folder read-write and there is no write access to the folder.

SiftTcl_close handle

Closes the folder open on handle. This saves any message status changes and unlocks the folder if the folder format supports locking. All folders are automatically closed when sift-tcl exits.

SiftTcl_check handle

Saves any changes made to a mail folder and incorporates any new mail added to the folder since it was opened or the last check. The only changes that may have been made to a mail folder are changes in message status flags. Messages are appended to a mail folder without opening the folder and are saved immediately. New mail is incorporated for mail folders open read-only as well as read-write.

SiftTcl_count handle

Returns the number of messages in the folder open on handle.

SiftTcl_getflags ?-body body? ?-folder folder -number number?

Returns a list of the status flags that are set for the specified message. The possible flags are "DELETED", "ANSWERED", "SEEN", and "FLAGGED". The "SEEN" flag is automatically set when the body of the message is fetched. The others have to be set explicitly. Different mail file storage formats may support different flags and support them in different ways.

SiftTcl_setflag flag ?-body body? ?-folder folder -number number?

Set the given flag for the given mail message.

SiftTcl_clearflag flag?-body body? ?-folder folder -number number?

Clear the given flag for the given mail message.

SiftTcl_mail_append folder ?-body body? ?-folder folder -number number?

Appends the specified mail message to the given folder. The folder is created if it doesn't exist. See the section below on how the mail folders are named.

SiftTcl_makebody content-type ?-id string? ?-parameter string? ?-description string? value ?encoding?

This constructs a single MIME entity or body and returns it as a Tcl string. The entity can be sent with SiftTcl_sendmessage or used as a component of a multipart message constructed by calling SiftTcl_makebody again. If the content-type argument is empty then text/plain is used. The -id argument specifies the Content-ID header and will be generated automatically if not specified. The -description argument can be used to specify the Content-Description field. A MIME parameter string for parameters specific to the type of body/entity being created can be given with the -parameter argument. The parameter string should be a string including the parameter name, "=", and the value, properly quoted. Last, the content encoding can be specified (e.g. "base64"). The actual encoding of the body is not done here and must be done before hand (SiftTcl_encode will be included in a future version for this).

SiftTcl_makebody multipart-content-type ?-id string? ?-parameter string? ?-description string? body ...

This format is used to construct a multipart MIME entity out of a set of other MIME entities (which may be multipart entities too). The multipart-content-type must begin multipart/.

SiftTcl_sendmessage -to addrlist -subject string -body body ?-cc addrlist? ?-auxheader name value?

This sends a message. The three arguments -to, -body and -subject are required. The -to and -cc fields are lists of addresses to which the message is to be sent. The -body option gives the body of the message and includes the text, attachments and other sub-parts. It is usually generated with SiftTcl_makebody. The -auxheader allows any additional headers to be created. These might include Reply-to:, Resent-to: and X-loop:. The message will be sent using the local delivery service (usually invoking sendmail, but is platform dependent).

SiftTcl_localaddrs address address addres...

Sets the list of addresses that are considered to be the local recipient's by SiftTcl_getaddrprop.

SiftTcl_Year

Returns the current year, e.g., 1995.

SiftTcl_Month

Returns the current month number with January being 1.

SiftTcl_Day

Returns the current day of the month.

SiftTcl_logmisc string

Places an entry in the log for the most recently retrieved message.

SiftTcl_logerror string

Places an error entry in the log for the most recently retrieved message.

SiftTcl_logdisposition disp

Sets the end log disposition for the message most recently retrieved. The disposition is not used by Sift-Tcl itself, but it is used by Sift-Tcl programs and the report generator. Currently it can be unset or set to "FiledInInbox" in order to distinguish messages that were filed in the user's inbox for the sifting report.

MAIL FOLDER NAMES

Local file system

Explicitly selected driver formats

The Carmel syntax is "#carmel#folder" or "#carmel#user#folder". The Carmel format stores mail under the .vmail directory and is a compatibility driver for a proprietary mail file format.

IMAP access

IMAP servers usually require authentication with a user name and password. This is not supported by sift-tcl presently so the authentication must be done with rimap. For this to work, rimap must be enabled on the server and the .rhosts file on the server must allow rsh access for the user.

USENET News

Non-fully-qualfied names

Other Drivers

SIFT-TCL LIBRARIES

day_of_year year month day

compare_dates date1 date2

Returns a number less than 0, 0, or greater than 0 if date1 is less than, equal to, or greater than date2. The dates are both lists in the form {year month day}.

check_activation act_d deact_d

Returns 1 if the current date is between act_d and deact_d, and 0 otherwise. The dates are lists in the form {year month day}.

check_4_daemon addresses

Check a set of addresses against a known set of addresses used by mailer daemons. If any of the addresses match then 1, is returned. Otherwise 0 is returned. The check is only a heuristic as there is no standard address for a mailer daemon. The addresses are matched by a complex regular expression which will match "root", "postmaster", "MAILER-DAEMON" and similar strings in the mailbox part of the address, or the full name part.

check_4_list folder_handle message_number

Checks the message specified by the folder_handle (e.g., as returned by SiftTcl_open) and message_number to see if it is from a mailing list. This is by heuristic as the check for the mailer daemon is, since there is no standard for tagging such messages. It checks the Precedence: header for "junk", "bulk", or "list". It also checks the address headers for the strings "Multiple Recipients" and "Discussion List." Capitalization is ignored in all comparisons. 1 is returned if a match is found, and 0 otherwise.

wrap_text text

Given a string (e.g. text of an outgoing message), return a string with all lines wrapped at the first space after 72 characters. The wrapped string is returned. This is used to wrap the lines of outgoing messages.

generate_reply_addr folder_handle message_numer property

The address database is used to keep track of addresses to which an out-of-town notification message has been sent. Multiple databases can be created and maintained. The records in the databases are keyed by the address and can include additional data for each record. A likely use for the data may be the date the last message was sent to the particular address. Each database is stored in a file beginning with .sift-tcl-addr-db in the user's home directory.

SiftTcl_addrdb_newid

This returns an id for a new database.

SiftTcb_addrdb_delete db_id

Deletes the whole database given by db_id.

SiftTcl_addrdb_save db_id address ?data?

Write an entry into the given database. Address must not have any spaces in it. (e.g., as returned by SiftTcl_getaddrprop for the "address" property). Data may not have newlines in it.

SiftTcl_addrdb_lookup db_id address

Returns an empty string if address is not in the database. Otherwise returns the concatenation of the address and the data fields.

LOGFILE FORMAT

REPORT GENERATION META-COMMENTS

# HEADER-BEGIN
# auto_report_on_off: on|off
# last_report_sent: yyyy.mm.dd
# days_between_reports: nn
# days_in_auto_report: nn
# HEADER-END

The report is generated from the .siftlog file. If it doesn't exist, any empty report will be generated. The report is generated from log entries generated by invoking sift-tcl with the -spool or -log options. Also, the -log or -spool option must be given in addition to having the report configuration meta-comments or the report will not be generated.

Note that if you have sift-tcl invoked in your .forward file you should not specify the -log (or -spool) option when you write and execute other Sift-Tcl programs or the statistics in the report will be inaccurate due to additional unrelated log entries.

The configuration settings are as follows:

auto_report_on_off

May be set to on or off to enable or disable report generation.

last_report_sent

Records the date the last report was sent.

days_between_reports

The number of days between reports

days_in_auto_report

The number of days to go back from the current date and include in the report.

SAMPLE CODE

Open folder "inbox" and print message subjects and sender

    set f [SiftTcl_open inbox ro]
    puts "Count: [SiftTcl_count $f]"
    for {set n 1} {$n <= [SiftTcl_count $f]} {incr n 1} {
        puts "[SiftTcl_getheader to -folder $f -number $n]\
            [SiftTcl_getheader subject -folder $f -number $n]"
    }
    SiftTcl_close $f

Send a message with text "foooo"

    set b [SiftTcl_makebody text/plain "foooo"]
    SiftTcl_sendmessage -to lgl@island-resort.com\
                        -subject "Testing send"\
                        -body $b

CAVEATS

Some of the logging functions do not include the message id in the log entries when they could be included.

Sift-tcl interpreted programs cannot accept command line arguments like tclsh.

FILES

$HOME/.forward

Specifies actions for local mail delivery agent

$HOME/.sift-tcl

Default Sift-Tcl code to execute for sifting

$HOME/.siftlog

Logs all mail processed by sift-tcl

$HOME/.sift-tcl-addr-db-xxx

Address data-base for out-of-town notification sifters.

SEE ALSO

Crocker, D. Standard For the Format of ARPA Internet Text Messages. IETF RFC 822. 1982.

Borenstein, N. and Freed, N. Multipart Internet Mail Extensions (MIME). IETF RFC-1521. 1993.

Borenstein, N. and Rose, M.T. MIME Extensions for Mail-Enabled Applications: application/safe-tcl and multipart/enabled-mail. White paper, First Virtual Holdings, Carmel Ca. 1993.

AUTHOR

SIFT-TCL(1)