summaryrefslogtreecommitdiff
path: root/doc/texinfo/programs/guimb.texi
blob: ca8de0bb61801195cdfcd960cd78ecdf4f6d285e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999-2020 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@pindex guimb

@command{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 @dfn{scheme module} that supplies the function to apply
is specified using the @option{--source} or @option{--file} option.
The module must define at least the following function:

@deffn {User function} guimb-message @var{msg}
Processes message @var{msg}.  This function can alter the message
using Guile primitives supplied by mailutils.
@end deffn

The following function definitions are optional:

@deffn {User function} guimb-getopt @var{args}
If defined, this function is called after @command{guimb} has finished
processing the command line.  @var{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.
@end deffn

@deffn {User function} guimb-end
If defined, this function is called after all mailboxes have been processed.
@end deffn

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

@example
@group
(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))
@end group
@end example

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

@example
guimb --file frm
@end example

@menu
* Specifying Scheme Program to Execute::
* Specifying Mailboxes to Operate Upon::
* Passing Options to Scheme::
* Command Line Option Summary::
@end menu

@node Specifying Scheme Program to Execute
@subheading Specifying Scheme Program to Execute

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

@table @option
@item -s @var{module}
@itemx --source @var{module}
Load Scheme code from @var{module}.

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

@item -f @var{module}
@itemx --file @var{module}
Load Scheme source code from @var{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
@option{-@{} and @option{-@}} options (@pxref{Passing Options to Scheme}).
@end table

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

@table @option
@item -e @var{expr}
@itemx --expression @var{expr}
Evaluate scheme expression.
@end table

@node Specifying Mailboxes to Operate Upon
@subheading Specifying Mailboxes to Operate Upon

There are four basic ways of passing mailboxes to @command{guimb}.

@table @code
@item guimb [@var{options}] [@var{mailbox}...]
The resulting mailbox is not saved, unless the user-supplied
scheme program saves it.
@item guimb [@var{options}] --mailbox @var{defmbox}
The contents of @var{defmbox} is processed and is replaced with the resulting
mailbox contents.  Useful for applying filters to user's mailbox.
@item guimb [@var{options}] --mailbox @var{defmbox} @var{mailbox} [@var{mailbox}...]
The contents of specified mailboxes is processed, and the resulting
mailbox contents is appended to @var{defmbox}.
@item guimb [@var{options}] --user @var{username} [@var{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 @command{guimb} as a mail delivery agent.
@end table

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

@node Passing Options to Scheme
@subheading 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 @option{--source} (@option{-s}) option, the rest of the
command line following the option's argument is passed as the
@var{args} argument to the @code{guimb-getopt} function, if such
function is defined.  This allows for making guimb scripts executable
by the shell.  If your system supports @samp{#!} magic at the start of
scripts, add the following two lines to the beginning of your script
to allow for its immediate execution: 

@example
#! /usr/local/bin/guimb -s
!#
@end example

@noindent
(replace @samp{/usr/local/bin/} with the actual path to the @command{guimb}).

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

@example
guimb --guile-arg -opt --guile-arg 24 --file @var{progfile}
@end example

In this example, the @code{guimb-getopt} function will get the
following argument

@example
( '-opt' 24 )
@end example

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

@example
guimb -@{ -opt 24 -@} --file @var{progfile}
@end example

@node Command Line Option Summary
@subheading Command Line Option Summary

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

@table @option
@item -d
@itemx --debug
Start with debugging evaluator and backtraces.
@item -e @var{expr}
@itemx --expression @var{expr}
Execute given Scheme expression.
@item -L @var{dir}
@item --load-path @var{dir}
Insert @var{dir} at the beginning of the @code{%load-path} list.  The
argument is either a single directory name, or a list of such names,
delimited by @samp{:} characters.
@item -m @var{path}
@itemx --mail-spool=@var{path}
Set path to the mailspool directory
@item -f @var{progfile}
@itemx --file @var{progfile}
Read Scheme program from @var{progfile}.
@item -g @var{arg}
@itemx --guile-command @var{arg}
Append @var{arg} to the command line passed to Scheme program.
@item -@{ ... -@}
Pass all command line options enclosed between @option{-@{} and @option{-@}}
to Scheme program.
@item -m
@itemx --mailbox @var{mbox}
Set default mailbox name.
@item -u
@itemx --user @var{name}
Act as local MDA for user @var{name}.
@item -h
@itemx --help
Display help message.
@item  -v
@itemx --version
Display program version.
@end table

Return to:

Send suggestions and report system problems to the System administrator.