Hi, I have been trying to make Mutt extensible with a common extension language since I found it might be useful for people who want more control on Mutt's behavior or for people who would like to be able to automate various tasks. So far, I have modified Mutt 1.5.4i in order to make it extensible with any extension language, currently the Scheme language (using Guile) -- note that this is not an attempt to rewrite GNU Emacs, just an attempt to enhance a lightweight user-agent which I like. :) The result can be downloaded from: http://www.laas.fr/~lcourtes/software/mutt-guile-latest.tar.bz2 and a diff against Mutt 1.5.4i is available at: http://www.laas.fr/~lcourtes/software/mutt-1.5.4i-guile.diff.bz2 . Note that this is experimental-work-in-progress so there is a lot of room for improvements. However, I would be glad if people interested in it could comment on it, try it, or help me improve it. Below is a small documentation of how this all works (the `README.Extensible' file of the tarball). Thanks, Ludovic. Extensible version of Mutt =-=-=-=-=-=-=-=-=-=-=-=-=- This file describes an experimental integration of extension languages into Mutt, why one might need that, and what have been the basic design ideas behind that. Currently, the only supported extension language is Scheme (Guile). However, Mutt may still be compiled without extension language support, and even when compiled with extension language support it remains 100% compatible with the regular Mutt. This work is based on Mutt 1.5.4i. 1. Design approach ------------------ The idea was to allow Mutt to be extensible with _any_ extension language in a way that makes it possible to use and customize internal mechanisms, without being incompatible with the original Mutt. However, we don't want Mutt to become a heavy-weight program like GNU Emacs -- that's why we are not using Gnus. :) 1.1. Why adding an extension language? Mutt already has some nice features that may be used to customize its behavior, namely "hooks". However, there are mainly three limitations to this approach: * hooks are pre-defined and even though there are already several of them in well-chosen places, one might some day want to add an hook to another event than those predefined; * hooks are basic actions that can be executed either before or after a given operation and may not be used to change the behaviour of a given action; * hooks can only execute what Mutt calls `commands' (e.g. "set from=ludo@net", "exec tag-pattern", "exec delete-message"); however functions that can be used are, again, pre-defined, and most of them are interactive which makes it impossible to automate some particular operation (for instance, tag-pattern would present a prompt and wait till the user entered a pattern; delete-message would not only mark a message as deleted but also jump to the next non-deleted message). These limitations sometimes make the use of hooks quite frustrating. Without the use of an extension language, it is almost impossible for the user to: * customize a given feature (e.g. I don't like the default scoring method which rounds up negative scores to zero and I would like to have my own; I would like Mutt to warn me before displaying a message whose header contains 'X-Spam-Status: Yes'; etc.); * implement new features, new commands, which may be configured using new configuration variables (e.g. if `spam_learn' is "yes", then I would like Mutt to pipe messages through SpamAssassin once they have been displayed and recognized as spam/ham). Using a simple interpreted language such as Scheme makes it possible to quickly to this. 1.2. What should be extensible? How should it be extended? Ideally, any built-in feature, function or mechanism should be make extensible via the extension language. It should also be possible to implement and use new functions programmed with the extension language. Practically, this means that it should be possible to customize the way messages are scored or the way messages are displayed. This also means that it should be possible to implement a function that counts the number of messages coming from your best friend and call it through the standard Mutt interface. Muttrc files should still be available, but their use should become optional. This means that built-in configuration variables, commands and functions have to be made available to the extension language. Executing functions or commands written using the extension language requires that the command/function execution mechanism be customisable itself. 1.3. Implementation details Being able to change what a function does using the extension language requires that Mutt calls functions written in that language rather than built-in C functions. Usually, extension languages (i.e. interpreted languages) would allow to redefine a given function. This way, any feature can easily be modified. For instance, instead of calling mutt_display_message (), Mutt has to directly call the `display-message' Scheme function; in turn, this Scheme function may choose to just the `builtin-display-message' Scheme function which is just a wrapper for the original `mutt_display_message ()' C function. In the current implementation, the functions that can be extended in this way are defined in the file extension.h and we call them `commands' (which is different from what Mutt call `commands', functions that are called within a muttrc file). These commands declared in extension.h with the `MUTT_DECLARE_COMMAND' macro are extensible features. This macro declares three functions: one with a leading `cmd_' which is the function to be used throughout the code; one with a leading `smutt_cmd_' which is the Scheme version of this command; one with a leading `builtin_' which is the original C function for this feature. The C code should only call the `cmd_' functions, which in turn call the corresponding `smutt_cmd_' function if the extension language is Guile (see extension.c). The `builtin_' functions should be made available to the extension language. Here is what happens, by default, when `cmd_display_message ()' is called: cmd_display_message (C) -> smutt_cmd_display_message (C) -------------. | .--- builtin-display-message (Scheme) <- display-message (Scheme) <---' | `---> builtin_display_message (C) Sometimes, features can be customized at different levels of abstraction. Consider the execution of a command: + source_rc_file (".muttrc") | +--+ parse_rc_line ("set realname='ludo' ; exec delete-message") | +--+ execute_command ("set", "realname='ludo'") | | | +--+ set_option ("realname", "ludo") | +--+ execute_command ("exec", "delete-message") | +--+ execute_function ("delete-message") Each one of these features (commands) may be customized (well, almost). For example, allowing transparent query/modification of built-in and extension language variables may be done by customizing the `set_option' command and make it check whether the given variable name is the name of a built-in variable or not. Transparent execution of functions written in the execution language can be done by customizing the `execute_command' and/or the execute_function command. Making it possible required to split the `parse_set ()' C function into two distinct functions: `builtin_set_option ()' which is used to set the value of a built-in variable, and `builtin_query_option ()' which is used to display the value of a variable. The latter one gets called for instance when typing "set ?realname". The `mutt_parse_rc_line ()' function also had to be splitted in a similar way, leading to the creation of `builtin_execute_command ()'. As one might guess, integrating features one by one is not very scalable but seems to be the only solution. However, any built-in Mutt command may be customized since command execution is customizable. 1.4. Things left to do A lot of things are left to be done, mostly making more features extensible. The key binding mechanism might need some rewrite in order to be extensible (currenly, a key is bound to an `op' which is basically the ID of a function to be called when the key is pressed). It should be possible to create and handle menus (shouldn't be too hard). Also, currently only a few features may be customized (see `extension.h' for a complete list of what may be customized) and it would be nice to have some more. However, some features are not easy to integrate because the manipulate internal things which we do not want the extension language to know: for instance mx_sync_mailbox () sets its `index_hint' argument to something that may be used by the index; send_message () from send.c may not only return `true' of `false' but also a third value in case a message needs to be postponed. The current execute-command function is just passed a command name and an unparsed argument string. It would be much cleaner if argument parsing could be done *before* execute-command is called and then commands would just receive and argc/argv list of arguments. However, this would require rewriting of all Mutt commands and it may not work for all of them (for instance, would '=' be an argument for command 'set' when typing "set realname=myself"?). Try to add support for your favorite language (Python?). 2. Extending Mutt with Guile ---------------------------- 2.1. Features All the features described here are programmed in Scheme in the system-wide `mutt.scm' file which should get installed in /etc. Transparent call of Scheme functions through Mutt's command interface (i.e. either in a Muttrc file or by typing `:' in the index menu) or through the function interface (i.e. "exec <function>"). The following Scheme functions (define (my-command argstring) (ui-message argstring)) (define (my-function) (ui-message "This is my function")) can be called within a muttrc file (or using Mutt's `enter-command' function): my-command and its arguments exec my-function Transparent access to Scheme and built-in variables, which means that the following lines should work: (define my-own-variable 2) (set-option "spoolfile" "/var/mail/ludo") (set-option "my-own-variable" "Hello world!") This can also be done using the standard muttrc syntax: set my-own-variable="Hello world!" The default `save-alias' function has been rewritten so that aliases can be saved in a schemey way. For instance, while the standard way of saving aliases is: alias ludo Ludovic Courtès <ludo@xxxxxxxx> the schemey way to do that is: (create-alias "ludo" (create-address "Ludovic Courtès <ludo@xxxxxxxx>")) This is not very useful and may be overriden in the user's `$HOME/.mutt.scm' by simply adding the following line: (set! save-alias builtin-save-alias) Note that Scheme things may be debugged by setting the Scheme variable `debug' to "yes" (which can be done by typing `:set debug="yes"'); the `debug-time' variable may be set to the delay of debug messages. Finally, one can also execute Scheme code directly from within Mutt: :scheme (ui-message (format \#f "~a unread messages" (context-unread-messages))) (note that there are no quotes). Mutt will always ask before evaluating Scheme code to prevent from malicious use of this feature. Looking at the files `$SYSCONFIGDIR/mutt.scm' (probably `/etc/mutt.scm') and `dotmutt.scm' (my own `.mutt.scm' configuration file) is probably the best way to get started. 2.2. Data types The available data types available are: * `context', the equivalent of Mutt's CONTEXT, which may be used to get the number of messages (`context-messages context', etc.) and to traverse them (`context-select-headers proc context'); * `alias', alias objects that may be created using `create-alias name address'; * `address', address objects that may be created using `create-address realname email'; * `header' which represents messages and may be observed and modified using `header-delete!', `header-score', `header-envelope', etc.; * `envelope' which represents a header's envelope and may be observed and modified using `envelope-from', `envelope-subject', etc.; * `pattern' which represent Mutt limitation patterns and may be used using `compile-pattern string', `execute-pattern header pattern'; * `menu' which is not really useful yet. * `score', the equivalent of Mutt's SCORE which represents a message scoring rule (not very useful). All these data types come with a number of accessor functions allowing to access (and modify) their contents. For example, given HEADER, a header object, the following expression (address-mailbox (envelope-to (header-envelope header))) returns the email address of HEADER's recipient. Some accessors are procedures with setter, ie. procedures that may be used also when modifying an element with `set!': (set! (header-score header) (+ 3 (header-score header))) There are also type predicates: for instance, `header?' returns true when its argument is a header object. 2.3. Things left to do Better exception handling (currently only functions executed as Mutt commands or Mutt functions are safe because the `safe-exec' macro catches any exception when executing these Scheme functions). Sept. 2003. Please send comments to Ludovic Courtès <ludovic.courtes@xxxxxxx>. $Id$
Attachment:
pgpv744IPDapg.pgp
Description: PGP signature