Camel.FilterDriver

CamelFilterDriver manages the filtering process. Given a set of filter rules, which consist of matching expressions and action expressions, and a set of messages, it will process each rule against all messages.

See the api documentation and source-code for the exact details, here I will just list some information not contained there.

Filter rules

There are two s-expressions for each filter rule. The message-matching expressions are explained in Evolution/Camel.Search#Camel.FilterSearch, and the message-action expressions below.

The matching expression will just return a boolean to indicate if the message matches. The action expression will normally consist of a begin block with each action to be performed.

All expressions are evaluated using Evolution/EDS.ESexp.

Status functions

The stauts functions alter the state of the message in question.

'(' 'delete' ')'

Marks the message for deletion. It depends on the backend as to whether the message is still available after it is deleted (for further actions).

'(' 'set-colour' string ')'

Sets the colour of the message. This is actually just a user-tag of colour set to a 24-bit colour using #RRGGBB hexadecimal syntax. As such this function is redundant ...

'(' 'set-score' integer ')' '(' 'adjust-score integer ')'

Sets or adjusts the score value (adjust adds to the score). Again this is just a user-tag called score, so is redundant, and could be implemented using lower-level functions.

'(' 'set-system-flag system-flag ')' '(' 'unset-system-flag system-flag ')'

 system-flag = 'answered' | 'deleted' | 'draft' | 'flagged' | 'seen'
              | 'attachments' | 'junk' | 'secure'

Sets or clears an individual system flag by name.

Movement functions

'(' 'copy-to' string * ')'

Will copy the message to each folder listed. Each folder is identified by a Evolution/Camel.Service folder URI. The get_folder callback will be invoked to resolve the URI.

'(' 'move-to' string * ')'

Will move the message to each folder listed, deleting on the last move. This will also terminate the rule action processing, preventing additional rules from being processed on this message.

'(' 'forward-to' ')'

This is unimplemented.

Processing functions

'(' 'beep' ')'

Will beep, using the application-supplied callback.

'(' 'play-sound' string ')'

Will call an application-supplied callback that should play a sound identified by the string (normally a filename).

'(' 'shell' string * ')'

Executes a shell command, using the application-supplied shell callback. I'm not sure why this needs to be an application-supplied callback ... very strange. The command is given no data from the message.

'(' 'pipe-message' string * ')'

Not to be confused with the search pipe-message command. This will execute the supplied command, passing the message content to stdin. It will also read stdout of the command, and use that to build a new message. This allows an external program to manipulate and modify the content of the message, for further stages of processing.

Control functions

'(' 'stop' ')'

Will cause processing to terminate after this action is finished. No further rules are checked.

'(' 'only-once' string string ')'

Will only run the expression once. Unfortunately the expression is implemented using a string, rather than an embedded expression, which it should have been implemented as. The first string is used as an expression key - allowing multiple calls to the same only-once expression to be treated as one.

Notes

The colour and score functions should be replaced with more generic set-user-flag and set-user-tag functions. This could mean that non-code changes would let filters set labels, among other extremely useful abilities.

The only-once stuff is implemented messily. It should probably be a non-immediate expression and not have to re-parse the sub-string.

shell should probably be implemented internally, it should probably also be passed the current content of the message.

play-sound and beep really do the same thing, and they both just pass to application callbacks anyway.