Overview of changes:

 *  Revamped packaging and handler API for Lua-correctness

    Most of imapdomo now behaves more like proper Lua code and part of
    this also rubs off to user, OTOH it only relates to one-time changes
    it's balanced by some extra configuration freedoms.

 *  Added support for hooks

    Handlers can now call dedicated external scripts prepared by user
    in advance, under `.imapdomo/config/hooks`.  The API is not fully
    fleshed, though.

 *  Enabled lock-related debugging

mkit.ini

 [project]
-    version     = 0.0.9
+    version     = 0.0.10
     name        = imapdomo
     pkgname     = imapdomo
     maintainer  = Alois Mahdal <netvor+imapdomo@vornet.cz>
 
 [files]
     bin     = src/imapdomo
+    share   = src/imapdomo.lua
     share   = src/main.lua
-    share   = src/common.lua
 
 #mkit version=0.0.34

packaging/debian/install

 /usr/bin/imapdomo
-/usr/share/imapdomo/common.lua
+/usr/share/imapdomo/imapdomo.lua
 /usr/share/imapdomo/main.lua

packaging/template.spec

 %files
 %dir %{_datadir}/%{name}
 %{_bindir}/%{name}
-%{_datadir}/%{name}/common.lua
+%{_datadir}/%{name}/imapdomo.lua
 %{_datadir}/%{name}/main.lua
 
 %changelog

src/common.lua → src/imapdomo.lua

-os = require "os"
-
+local pkg = {}
 
 ------------------------------------------------------------------------------
 -- config and handling                                                      --
 ------------------------------------------------------------------------------
 
-function file_exists(name)
+pkg.load_mailboxes = function()
+    --
+    -- Load mailboxes from $IMAPDOMO_CFGDIR/mailboxes.lua
+    --
+    local fname = os.getenv("IMAPDOMO_CFGDIR") .. '/mailboxes.lua'
+    assert(pkg.file_exists(fname))
+    return dofile(fname)
+end
+
+pkg.file_exists = function(name)
     --
     -- True if file *name* exists
     --
     end
 end
 
-function do_if_exists(filename)
+pkg.do_if_exists = function (filename)
     --
     -- Do file from home, if exists
     --
     local file = os.getenv("IMAPFILTER_HOME") .. "/" .. filename
-    if file_exists(file) then
+    if pkg.file_exists(file) then
         dofile(file)
         return
     end
 end
 
-function handle()
+pkg.handle = function()
     --
     -- Handle action if it's valid
     --
     local action = os.getenv("IMAPDOMO_ACTION")
     local file = os.getenv("IMAPFILTER_HOME") .. "/handlers/" .. action .. ".lua"
-    if file_exists(file) then
-        do_if_exists("init.lua")
+    if pkg.file_exists(file) then
+        pkg.do_if_exists("init.lua")
         dofile(file)
     else
         error("no handler for action: " .. action)
 -- mail getters                                                             --
 ------------------------------------------------------------------------------
 
-function get_queue(acct, mbox)
+pkg.get_queue = function(acct, mbox)
     --
     -- Get queue from *mbox* from *acct* or nil (no messages)
     --
     -- If mbox is not specified, "FILTER_QUEUE" is used
     --
     mbox = mbox or "FILTER_QUEUE"
-    local exist, unread, unseen, uidnext = acct[mbox]:check_status()
+    local exist = acct[mbox]:check_status()
     if exist > 0 then
         return acct[mbox]:select_all()
     end
     return nil
 end
 
-function _notifirc1(subj, from, body)
+pkg._notifirc1 = function(subj, from, body)
     --
     -- notify about message using (pre-configured) notifirc
     --
     fd:close()
 end
 
-function notifirc_all(seq)
+pkg.notifirc_all = function(seq)
     --
     -- Send notifications about all messages in *seq*
     --
     for _, mesg in ipairs(seq) do
+        local mbox, uid, subj, from, body
         mbox, uid = table.unpack(mesg)
         subj = mbox[uid]:fetch_field('Subject')
         from = mbox[uid]:fetch_field('From')
         body = mbox[uid]:fetch_body()
-        _notifirc1(subj, from, body)
+        pkg._notifirc1(subj, from, body)
     end
 end
 
-function _partinf_compare(a, b)
+pkg.hook_all = function(seq, hname, ...)
+    --
+    -- Call hook hname for all messages in seq
+    --
+    local hfile = os.getenv("IMAPFILTER_HOME") .. "/hooks/" .. hname
+    local hargs = {...}
+    local hcmd = hfile
+    local fmt = ' %q'
+    if pkg.file_exists(hfile) then
+        for _, harg in pairs(hargs) do
+            hcmd = hcmd .. fmt:format(harg)
+        end
+        for _, mesg in ipairs(seq) do
+            local mbox, uid, subj, body, from, to, date
+            mbox, uid = table.unpack(mesg)
+            subj = mbox[uid]:fetch_field('Subject')
+            from = mbox[uid]:fetch_field('From')
+            to = mbox[uid]:fetch_field('To')
+            date = mbox[uid]:fetch_field('Date')
+            body = mbox[uid]:fetch_body()
+            pkg._hook1(hcmd, subj, from, to, date, body)
+        end
+    else
+        error("no such hook: " .. hname)
+        return nil
+    end
+end
+
+pkg._hook1 = function(hcmd, subj, from, to, date, body)
+    --
+    -- push message through hook script
+    --
+    local fd = assert(io.popen(hcmd, "w"))
+    local fmt = "subj=%s\nfrom=%s\nto=%s\ndate=%s\n%s"
+    fd:write(fmt:format(subj, from, to, date, body))
+    fd:close()
+end
+
+pkg._partinf_compare = function(a, b)
     if not type(a) == type(b) then
         return false
     end
     end
 end
 
-function has_part_like(query, structure)
+pkg.has_part_like = function(query, structure)
     --
     -- True if structure has MIME part matching *query*
     --
         local part_answer = true
         -- check all query parts
         for qkey, qvalue in pairs(query) do
-            value = partinf[qkey]
-            if not _partinf_compare(value, qvalue) then
+            local value = partinf[qkey]
+            if not pkg._partinf_compare(value, qvalue) then
                 part_answer = false
                 break
             end
     return false
 end
 
-function save_header(mesg, name)
+pkg.save_header = function(mesg, name)
     --
     -- Append header from *mesg* to file named *name*
     --
     --
     local dest = os.getenv("IMAPDOMO_HEADERS") .. '/' .. name
     local cmd = ('cat >>"%q"'):format(dest)
-    mbox, uid = table.unpack(mesg)
-    header = mbox[uid]:fetch_header()
-    if pipe_to(cmd, header) == 0 then
+    local mbox, uid = table.unpack(mesg)
+    local header = mbox[uid]:fetch_header()
+    if pkg.pipe_to(cmd, header) == 0 then
         return true
     else
         return false
     end
 end
 
-function filter_header_saved(seq, name)
+pkg.filter_header_saved = function(seq, name)
     --
     -- Save headers from sequence
     --
     -- *name* and return new sequence with those messages where save was
     -- successful.
     --
-    result = Set {}
+    local result = {}
     for _, mesg in ipairs(seq) do
-        if save_header(mesg, name) then
+        if pkg.save_header(mesg, name) then
             table.insert(result, mesg)
         end
     end
     return result
 end
 
-function filter_part_like(query, seq)
+pkg.filter_part_like = function(query, seq)
     --
     -- Run MIME part query on *seq* sequence of messages
     --
-    result = Set {}
+    local result = {}
     for _, mesg in ipairs(seq) do
-        mbox, uid = table.unpack(mesg)
-        structure = mbox[uid]:fetch_structure()
-        if has_part_like(query, structure) then
+        local mbox, uid = table.unpack(mesg)
+        local structure = mbox[uid]:fetch_structure()
+        if pkg.has_part_like(query, structure) then
             table.insert(result, mesg)
         end
     end
     return result
 end
+
+return pkg

src/imapdomo.skel

        "configuration directory."                                             \
        ""                                                                     \
        "See imapfilter_config(5)) for guide and API reference.  Few functions"\
-       "are also available in .imapdomo/common.lua"                           \
+       "are also available in .imapdomo/imapdomo.lua"                         \
        ""                                                                     \
        "NOTE: Be aware that it's your responsibility to ensure that filters"  \
        "don't cause performance problems. (Trust me, it's not so hard to"     \
     # Compose imapfilter command
     #
     echo -n "IMAPDOMO_ACTION=$Action"
+    echo -n "  LUA_PATH=$IMAPDOMO_HOME/?.lua"
+    echo -n "  IMAPDOMO_CFGDIR=$CfgDir"
     echo -n "  IMAPDOMO_HEADERS=$HeaderDir"
     echo -n "  IMAPFILTER_HOME=$CfgDir"
     echo -n "  imapfilter"
     #
     # List recognized handlers
     #
-    find "$CfgDir/handlers" -name "*.lua" -printf "%f\n" \
+    find "$CfgDir/handlers" -name "*.lua" -printf '%f\n' \
       | sed 's/.lua$//'
 }
 
     #
     # Put the lockfile
     #
+    debug -v NoLock
     $NoLock && return 0
     date +"$$@%s" > "$IMAPDOMO_USER_CACHE/lock"
+    debug -f "$IMAPDOMO_USER_CACHE/lock"
 }
 
 is_locked() {
     # True if lockfile exists. False if lockfile does not exist or locking
     # is turned off.
     #
+    debug -v NoLock
     $NoLock && return 1
+    debug -f "$IMAPDOMO_USER_CACHE/lock"
     test -e "$IMAPDOMO_USER_CACHE/lock"
 }
 
     #
     # Remove the lockfile
     #
+    debug -v NoLock
     $NoLock && return 0
+    debug -f "$IMAPDOMO_USER_CACHE/lock"
     rm "$IMAPDOMO_USER_CACHE/lock"
 }
 
     esac done
     Action="$1"; shift
     test -n "$Action" || usage -w "no action specified"
+    test -f "$CfgDir/mailboxes.lua" || die "no mailboxes defined"
     debug -v Action CfgDir LogDir HeaderDir Debug CdTo NoLock
     is_locked && return 1
     lock
-    handle "$Action"; es=$?
+    handle; es=$?
     unlock
     return $es
 }

src/main.lua.skel

 #!/bin/lua
 
-dofile "__IMAPDOMO_SHARE__/common.lua"
+local imapdomo = require "imapdomo"
 
-handle()
+imapdomo.handle()