Revamp packaging to achieve more correct Lua style

Several changes regarding packaging, namespacing and handler API:

 *  Utility function module is now called 'imapdomo', not 'common'.

 *  The module behaves as one, instead of being just a global-modifying
    include.

 *  Lots of cleanups as advised by luacheck (local declarations,
    removal of unused variables...)

 *  Handlers now have to access utility API via `require` and provide
    accout configuration in new file mailboxes.lua, which has to return
    table.  Accessing mailboxes is via utility function.  (This sounds
    complicated but actually is not.  Believe me! :))

mkit.ini

 
 [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

+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 hook_all(seq, hname, ...)
+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 harg
     local hcmd = hfile
     local fmt = ' %q'
-    if file_exists(hfile) then
+    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()
-            _hook1(hcmd, subj, from, to, date, body)
+            pkg._hook1(hcmd, subj, from, to, date, body)
         end
     else
         error("no such hook: " .. hname)
     end
 end
 
-function _hook1(hcmd, subj, from, to, date, body)
+pkg._hook1 = function(hcmd, subj, from, to, date, body)
     --
     -- push message through hook script
     --
     fd:close()
 end
 
-function _partinf_compare(a, b)
+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$//'
 }
 
     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

src/main.lua.skel

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