Chapter 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 word ``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 `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 create a interactively 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.

Summaries

Top

Frames and Windows