User defined procedures

TkRat software and its included text is Copyright 1996-1999 by Martin Forssén. The full text of the legal notices is contained in the file called COPYRIGHT, included with this distribution.

User defined procedures is a way for the user to have more control over certain features. The procedures are ordinary tcl procedures (i.e. they are written in tcl7.5). None of the procedures must exist, they will be used only if they exists.

The user may define procedures in the ~/.ratatosk/userproc file (or whatever the userproc option is set to). If the procedures need any global varaibles these must start with "ratUP_". The following procedures may be defined:

RatUP_IsMe mailbox domain personal adl
mailboxMailbox name
domainThe domain part
personalThe personal name phrase (if any)
adlAt-domain-list source route
This procedure should determine if the address is pointing to me or not. It should return a boolean value, which should be true if the address is pointing at me.
RatUP_Translate mailbox domain personal adl
mailboxMailbox name
domainThe domain part
personalThe personal name phrase (if any)
adlAt-domain-list source route (probably empty)
When we are replying to a message all addresses we are sending it to are run through this procedure. It is expected to return a list with four elements {mailbox domain personal adl}.
RatUP_Signature message
messageThe name of a global array which may contain information about the message the signature will be appended to
This function should return a text string which will later be appended to the first text part of the message. The message argument is the name of a global array which MAY contain information about the message. See the section on RatSend in the interface-file. Note that this routine gets called before the user has had any chance to edit the message so there will not be any interesting information available at all for new messages. It only contains interesting things for replies and forwards.
RatUP_Bell
This function should notify the user that new mail has arrived. If this function does not exist then the terminal bell is rung.
RatUP_ShowURL url
urlAn URL to show
This function may get called when the user presses the left mousebutton over an URL in a message. It is expected to invoke a browser (in the background).
RatUP_Citation message
messageThe handler for the message which is being cited
This function should return a string which will be prepended to all lines in the body of the cited message. It wil be called when you reply to a message.
RatUP_NetsyncFolder spec user prot
specA network folder specification {host:port}mailbox
userUser to connect as
protProtocol (currently always imap)
This function is should return a boolean value which indicates if the disconnected folder given as arguments should be synchronized at this moment or not. Tht means that this function will be called once for each disconnected mailbox when you select "Network Sync" from the menu. It will NOT be called when you select "Network sync. folder" from the admin menu to synchronize the current folder.

Example

#
# This file contains examples of a couple of userprocs. These are ways you
# can extend the functionality of TkRat in a couple of areas. You usersprocs
# should be placed in ~/.ratatosk/userproc
#

# RatUP_IsMe --
#
#	Checks if a mail address really points at myself.
#
# Arguments
#	mailbox		Mailbox name
#	domain		The domain part of the mail address
#	personal	The personal name phrase (if any)
#	adl		At-domain-list source route (probably empty)
# Results
#	Should return true or false (1 or 0) depending on if the indicated
#	address points at the user or not.

proc RatUP_IsMe {mailbox domain personal adl} {
    # Here we do it easy for ourselves. Since regexp already returns a
    # boolean value we can use that as the return value directly.

    return [regexp {(maf|ratatosk.+)@.+.chalmers.se} $mailbox@$domain]

    # This expression matches everything that is sent to maf or
    # ratatosk(plus something) at a domain under chalmers.se.
    # That means that it will match maf@dtek.chalmers.se,
    # maf@math.chalmers.se, raratosk-request@dtek.chalmers.se
    # and even maf@no_such_domain.chalmers.se. The latter is an
    # unfortunate side effect of the expression but I do not care.
    # Note that the expression will not match ratatosk@dtek.chalmers.se
    # since there must be something between ratatosk and the '@'.
}



# RatUP_Translate --
#
#	Translate outgoing addresses
#
# Arguments
#	mailbox		Mailbox name
#	domain		The domain part of the mail address
#	personal	The personal name phrase (if any)
#	adl		At-domain-list source route (probably empty)
# Results
#	Should return a list with four elemnts {mailbox domain personal adl}

proc RatUP_Translate {mailbox domain personal adl} {
    # Set up a list of addresses we consider local
    set isLocal {root foo driftavd}

    # Here we do the test, check if the mailbox is one of the local ones
    # and if the domain is under chalmers.se. If so is the case then we
    # skip the domain part. This is really just another way of doing a
    # similar test as we did in RatUP_IsMe above.
    if {-1 != [lsearch $isLocal $mailbox] &&
            [regexp {[^.]+.chalmers.se} $domain]} {
        return [list $mailbox {} $personal $adl]
    }

    # If the above cause did not match we should return the address
    # unharmed.
    return [list $mailbox $domain $personal $adl]
}


# RatUP_Citation --
#
#	Figures out a good citation
#
# Arguments
#	message		Handler to message we should figure out citation for
#			reply to
# Results
#	Should return the desired citation

proc RatUP_Citation {message} {
   # Ignore any addresses but the first in from
   set from [lindex [$message get from] 0]

   # Check that we really have an address
   if [string length $from] {
       # See if we have a full name
       set fn [$from get name]
       if [string length $fn] {
	   # Use the initals as citation
           set initials ""
           foreach n $fn {
               set initials $initials[string $n 0]
           }
           return "$initals> "
       }
       # No initials were available so use the first part of the mail address
       return "[lindex [split [$from get mail] {._@}] 0]> "
   }
   # Default value which is used if no from address was found
   return "> "
}

# RatUP_NetsyncFolder --
#
#	Determines if a folder should be synchronized at this moment or not
#
# Arguments
#	spec	A folde specification {host:port}mailbox
#	user	User to connect as
#	prot	Protocol to use
#
# Results
#	Should return a boolean value

proc RatUP_NetsyncFolder {spec user prot} {
    # This example checks if the host is reachable first

    # Extract host and port from folder specification
    regexp {\{([^:\}]+)(:([0-9]+))?\}} $spec unused host unused port

    # Try to open a socket (do it asynchronously so we do not have
    # to wait a long time for failure
    if [catch {socket -async $host $port} s] {
	return 0
    }
    fconfigure $s -blocking no

    # Wait half a second, we assume that the host always replies within this
    # time when it is up
    after 500

    # Try to read one character. If this fails the connection failed
    if [catch {gets $s 1}] {
	return 0
    }

    # If we are blocked here we assume that the host is unreachanble (it
    # has not replied within the allowed time) and the connection attempt
    # still hangs.
    if [fblocked $s] {
	catch {close $s}
	return 0
    } else {
	catch {close $s}
	return 1
    }
}