14. Virtual Folders

A virtual folder is a mapping of messages from one or more real folders into a container that in most ways acts like a real folder but has no real existence outside of VM. You can have a virtual folder that contains a subset of messages in a real folder or several real folders. A virtual folder can also contain a subset of messages from another virtual folder.

A virtual folder is defined by its name, the folders that it contains and its selectors. The variable vm-virtual-folder-alist is a list of the definitions of all named virtual folders. In order to visit a virtual folder with the vm-visit-virtual-folder (V V) command, a virtual folder must have an entry in vm-virtual-folder-alist.

Each virtual folder definition should have the following form:

(VIRTUAL-FOLDER-NAME
  ( (FOLDER-NAME ...)
    (SELECTOR [ARG ...]) ... )
  ... )

VIRTUAL-FOLDER-NAME is the name of the virtual folder being defined. This is the name by which you and VM will refer to this folder.

FOLDER-NAME should be the name of a real folder. There may be more than one FOLDER-NAME listed, the SELECTORs within that sublist will apply to them all. If FOLDER-NAME is a directory, VM will assume this to mean that all the folders in that directory should be searched.

The SELECTOR is a Lisp symbol that tells VM how to decide whether a message from one of the folders specified by the FOLDER-NAMEs should be included in the virtual folder. Some SELECTORs require an argument ARG; unless otherwise noted ARG may be omitted.

author

matches message if ARG matches the author; ARG should be a regular expression.

author-or-recipient

matches message if ARG matches the author of the message or any of its recipients; ARG should be a regular expression.

and

matches the message if all its argument selectors match the message. Example:

(and (author "Derek McGinty") (new))

matches all new messages from Derek McGinty. and takes any number of arguments.

any

matches any message.

deleted

matches message if it is flagged for deletion.

edited

matches message if it has been edited.

filed

matches message if it has been saved with its headers.

forwarded

matches message if it has been forwarded using a variant of vm-forward-message or vm-send-digest.

header

matches message if ARG matches any part of the header portion of the message; ARG should be a regular expression.

header-or-text

matches message if ARG matches any part of the headers or the text portion of the message; ARG should be a regular expression.

label

matches message if message has a label named ARG.

less-chars-than

matches message if message has less than ARG characters. ARG should be a number.

less-lines-than

matches message if message has less than ARG lines. ARG should be a number.

more-chars-than

matches message if message has more than ARG characters. ARG should be a number.

more-lines-than

matches message if message has more than ARG lines. ARG should be a number.

marked

matches message if it is marked, as with vm-mark-message.

new

matches message if it is new.

not

matches message only if its selector argument does NOT match the message. Example:

(not (deleted))

matches messages that are not deleted.

or

matches the message if any of its argument selectors match the message. Example:

(or (author "Dave Weckl") (subject "drum"))

matches messages from Dave Weckl or messages with the string "drum" in their Subject header. or takes any number of arguments.

read

matches message if it is neither new nor unread.

recent

matches message if it is new.

recipient

matches message if ARG matches any part of the recipient list of the message. ARG should be a regular expression.

redistributed

matches message if it has been redistributed using vm-resend-message.

replied

matches message if it has been replied to.

sent-after

matches message if it was sent after the date ARG. A fully specified date looks like this:

``31 Dec 1999 23:59:59 GMT''

although the parts can appear in any order. You can leave out any part and it will default to the current date's value for that part, with the exception of the `hh:mm:ss' part which defaults to midnight.

sent-before

matches message if it was sent before the date ARG. A fully specified date looks like this:

``31 Dec 1999 23:59:59 GMT''

although the parts can appear in any order. You can leave out any part and it will default to the current date's value for that part, with the exception of the hh:mm:ss part which defaults to midnight.

subject

matches message if ARG matches any part of the message's subject; ARG should be a regular expression.

text

matches message if ARG matches any part of the text portion of the message; ARG should be a regular expression.

unanswered

matches message if it has not been replied to. Same as the unreplied selector.

undeleted

matches message if it has not been deleted.

unedited

matches message if it has not been edited.

unfiled

matches message if it has not been saved with its headers.

unforwarded

matches message if it has not been forwarded using vm-forward-message or vm-send-digest or one of their variants.

unread

matches message if it is not new and hasn't been read.

unseen

matches message if it is not new and hasn't been read. Same as the unread selector.

unredistributed

matches message if it has not been redistributed using vm-resend-message.

unreplied

matches message if it has not been replied to.

virtual-folder-member

matches message if the message is already a member of some virtual folder currently being visited.

written

matches message if it has been saved without its headers.

Here is an example that you may find useful as a template to create virtual folder definitions.

(setq vm-virtual-folder-alist
   '(
     ;; start virtual folder definition
     ("virtual-folder-name"
      (("/path/to/folder" "/path/to/folder2")
       (header "foo")
       (header "bar")
      )
      (("/path/to/folder3" "/path/to/folder4")
       (and (header "baz") (header "woof"))
      )
     )
     ;; end of virtual folder definition
   )
)

Again, you visit virtual folders you have defined in vm-virtual-folder-alist with V V. Once you've visited a virtual folder most VM commands work as they do in a normal folder. There are exceptions. If you use S (vm-save-folder, the folder save command will be invoked on each real folder in turn. Similarly if you use g (vm-get-new-mail in a virtual folder, mail is retrieved from the spool files associated with each of the real folders. If any of the retrieved messages are matched by the virtual folder's selector, they will be added to the virtual folder.

These commands will signal an error when invoked if the current folder is a virtual folder:

    vm-save-buffer
    vm-write-file
    vm-change-folder-type
    vm-expunge-imap-messages
    vm-expunge-pop-messages

Normally messages in a virtual folder share attributes with the underlying real messages. For example, if you delete a message in a virtual folder, it is also flagged as deleted in the real folder. If you then run vm-expunge-folder in the virtual folder, the deleted message is expunged from the virtual folder and from the real folder. Labels are shared between virtual and real messages. However virtual folders have their own set of message marks.

To make virtual folders not share message attributes with real folders by default, set the variable vm-virtual-mirror to nil. This should be done in your VM init file and you should use setq-default, as this variable is automatically local to all buffers.

(setq-default vm-virtual-mirror nil)

If you want to change whether the currently visited virtual folder shares attributes with the underlying real folders, use the command vm-toggle-virtual-mirror (bound to V M). If the virtual folder is currently sharing attributes it will no longer be. If it is not sharing attributes with the underlying folders then it will be.

The command vm-create-virtual-folder (bound to V C) lets you interactively create a virtual folder from the messages of the current folder, using exactly one selector to choose the messages. If you type V C header RET pigs, VM will create a folder containing only those messages that contain the string `pigs' in the header.

The command vm-apply-virtual-folder (bound to V X) tries the selectors of a named virtual folder against the messages of the current folder and creates a virtual folder containing the matching messages.

The keys V S and V A invoke vm-create-virtual-folder-same-subject and vm-create-virtual-folder-same-author which create virtual folders containing all the messages in the current folder with the same subject or author as the current message.