GNU Mailutils
	General-Purpose Mail Package	Official GNU Software

• Main
• Downloads
• Documentation
• Wiki

3.11 guimb — A Mailbox Scanning and Processing Language

Guimb is an experimental tool that iterates over messages in a mailbox (or several mailboxes), applying a Scheme function to each of them.

A user-defined scheme module that supplies the function to apply is specified using the --source or --file option. The module must define at least the following function:

User function: guimb-message msg

Processes message msg. This function can alter the message using Guile primitives supplied by mailutils.

The following function definitions are optional:

User function: guimb-getopt args

If defined, this function is called after guimb has finished processing the command line. args is a list of unconsumed command line arguments.

The function is intended to provide a way of configuring the module from the command line.

User function: guimb-end

If defined, this function is called after all mailboxes have been processed.

In the following example we define a module that prints information about each message is the input mailbox, in a way similar to frm utility:

(define-module (frm)
  :export (guimb-message))

(use-modules (mailutils mailutils))
             
(define (guimb-message msg)
  (display (mu-message-get-sender msg))
  (display " ")
  (display (mu-message-get-header msg "subject"))
  (newline))

The modules are looked up in directories listed in the global variable %load-path. New directories can be added to that variable on the fly using the -L (--load-path) option. For example, if the sample module above was saved in a file frm.scm somewhere in the load path, it can be applied to the current user inbox by running the following command:

guimb --file frm

Specifying Scheme Program to Execute

Specifying Scheme Program to Execute

The Scheme module that defines message processing functions is given via the following options:

-s module

--source module

Load Scheme code from module.

This option stops further argument processing, and passes all remaining arguments as the value of args argument to the guimb-getopt function, if it is defined.

-f module

--file module

Load Scheme source code from module. The remaining arguments are processed in the usual way. When using this option, you can pass additional options and or arguments to the module by enclosing them in -{ and -} options (see Passing Options to Scheme).

An experimental option is provided, that evaluates a supplied Scheme expression right after loading the module:

-e expr

--expression expr

Evaluate scheme expression.

Specifying Mailboxes to Operate Upon

Specifying Mailboxes to Operate Upon

There are four basic ways of passing mailboxes to guimb.

guimb [options] [mailbox...]

The resulting mailbox is not saved, unless the user-supplied scheme program saves it.

guimb [options] --mailbox defmbox

The contents of defmbox is processed and is replaced with the resulting mailbox contents. Useful for applying filters to user’s mailbox.

guimb [options] --mailbox defmbox mailbox [mailbox...]

The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to defmbox.

guimb [options] --user username [mailbox...]

The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to the user’s system mailbox. This makes it possible to use guimb as a mail delivery agent.

If no mailboxes are specified in the command line, guimb reads and processes the system mailbox of the current user.

Passing Options to Scheme

Passing Options to Scheme

Sometimes it is necessary to pass some command line options to the scheme procedure. There are three ways of doing so.

When using --source (-s) option, the rest of the command line following the option’s argument is passed as the args argument to the guimb-getopt function, if such function is defined. This allows for making guimb scripts executable by the shell. If your system supports ‘#!’ magic at the start of scripts, add the following two lines to the beginning of your script to allow for its immediate execution:

#! /usr/local/bin/guimb -s
!#

(replace ‘/usr/local/bin/’ with the actual path to the guimb).

Otherwise, if you use the --file option, the additional arguments can be passed to the Scheme program -g (--guile-arg) command line option. For example:

guimb --guile-arg -opt --guile-arg 24 --file progfile

In this example, the guimb-getopt function will get the following argument

( '-opt' 24 )

Finally, if there are many arguments to be passed to Scheme, it is more convenient to enclose them in -{ and -} escapes:

guimb -{ -opt 24 -} --file progfile

Command Line Option Summary

Command Line Option Summary

This is a short summary of the command line options available to guimb.

-d

--debug

Start with debugging evaluator and backtraces.

-e expr

--expression expr

Execute given Scheme expression.

-L dir

--load-path dir

Insert dir at the beginning of the %load-path list. The argument is either a single directory name, or a list of such names, delimited by ‘:’ characters.

-m path

--mail-spool=path

Set path to the mailspool directory

-f progfile

--file progfile

Read Scheme program from progfile.

-g arg

--guile-command arg

Append arg to the command line passed to Scheme program.

-{ ... -}

Pass all command line options enclosed between -{ and -} to Scheme program.

-m

--mailbox mbox

Set default mailbox name.

-u

--user name

Act as local MDA for user name.

-h

--help

Display help message.

-v

--version

Display program version.