Add support for appending messages to mailboxes

Add a new function append_message(), update man page and add new example
in the sample configurations.

doc/imapfilter_config.5

@@ -1,4 +1,4 @@
-.Dd April 6, 2011
+.Dd August 5, 2011
 .Dt IMAPFILTER_CONFIG 5
 .Os
 .Sh NAME
@@ -537,8 +537,8 @@ either at the same or different accounts, for example when the same actions
 will be executed on messages residing in different mailboxes or accounts.
 .Bd -literal -offset 4n
 results = myaccount.mymailbox:is_unseen() +
-	  myaccount.othermailbox:is_larger(100000) +
-	  otheraccount.othermailbox:contain_subject('test')
+	  myaccount.myothermailbox:is_larger(100000) +
+	  myotheraccount.myothermailbox:contain_subject('test')
 .Ed
 .Pp
 The following method can be used to get all messages in a mailbox:
@@ -987,39 +987,45 @@ while if the server supports it, new user keywords may be defined:
 .It Fn add_flags flags
 Adds the
 .Fa flags
-.Po Vt table
+.Po
+.Vt table
 that contains
-.Vt strings Pc
+.Vt strings
+.Pc
 to the messages.
 .Pp
 .It Fn remove_flags flags
 Removes the
 .Fa flags
-.Po Vt table
+.Po
+.Vt table
 that contains
-.Vt strings Pc
+.Vt strings
+.Pc
 from the messages.
 .Pp
 .It Fn replace_flags flags
 Replaces the
 .Fa flags
-.Po Vt table
+.Po
+.Vt table
 that contains
-.Vt strings Pc
+.Vt strings
+.Pc
 of the messages.
 .El
 .Pp
 Examples:
 .Bd -literal -offset 4n
 results:delete_messages()
-results:copy_messages(myaccount.othermailbox)
-results:move_messages(otheraccount.mymailbox)
+results:copy_messages(myaccount.myothermailbox)
+results:move_messages(myotheraccount.mymailbox)
 results:mark_seen()
 results:unmark_flagged()
 results:add_flags({ 'MyFlag', '\e\eSeen' })
 results:remove_flags({ '\e\eSeen' })
 
-results:move_messages(otheraccount['myfolder/mymailbox'])
+results:move_messages(myotheraccount['myfolder/mymailbox'])
 .Ed
 .Sh MESSAGES
 The messages that are residing in any mailbox can be also accessed, as a whole
@@ -1064,9 +1070,7 @@ of the message.
 .It Fn fetch_part part
 Fetches the specified
 .Fa part
-.Po
-.Vt string
-.Pc
+.Pq Vt string
 of the message.
 .El
 .Pp
@@ -1076,7 +1080,7 @@ message:
 .Bl -tag -width Ds -compact
 .It Fn fetch_flags
 Fetches the flags of the message.  Returns a
-.Vt table ,
+.Vt table
 of
 .Vt strings .
 .Pp
@@ -1095,14 +1099,42 @@ that has as keys the parts of the message, and as values a
 .Vt table
 that has one mandatory element, the type
 .Pq Vt string
-of the part, and two
-optional elements,
-the size
+of the part, and two optional elements, the size
 .Pq Vt number
 and name
 .Pq Vt string
 of the part.
 .El
+.Ss APPENDING
+.Pp
+The following methods can be used to append a message to a mailbox:
+.Pp
+.Bl -tag -width Ds -compact
+.It Fn append_message message
+Appends the
+.Fa message
+.Pq Vt string
+to the mailbox.
+.Pp
+.It Fn append_message message message flags date
+Appends the
+.Fa message
+.Pq Vt string
+to the mailbox, setting the specified
+.Fa flags
+.Po
+.Vt table
+of
+.Vt strings
+.Pc ,
+as returned by
+.Fn fetch_flags ,
+and
+.Fa date
+.Pq Vt string ,
+as returned by
+.Fn fetch_date .
+.El
 .Pp
 Examples:
 .Bd -literal -offset 4n
@@ -1112,6 +1144,8 @@ myaccount.mymailbox[5]:fetch_part('1.1')
 
 myaccount['mymailbox'][7]:fetch_message()
 myaccount['myfolder/mymailbox'][11]:fetch_message()
+
+myaccount.mymailbox:append_message(message)
 .Ed
 .Sh FUNCTIONS
 The following auxiliary functions are also available for convenience:

samples/extend.lua

@@ -14,7 +14,7 @@
 
 function forever()
     results = myaccount.mymailbox:is_old()
-    results:move_messages(myaccount.archive)
+    results:move_messages(myaccount.myothermailbox)
 end
 
 become_daemon(600, forever)
@@ -68,6 +68,24 @@ end
 results:delete_messages()
 
 
+-- Messages can be appended to a mailbox.  One can fetch a message from a
+-- mailbox, optionally process it, and then upload it to the same or different
+-- mailbox, at the same or different mail servers.  In the following example a
+-- header field is added to all messages, and the processed messages are then
+-- appended to a different mailbox.
+
+all = myaccount.mymailbox:select_all()
+
+for _, mesg in ipairs(all) do
+    mbox, uid = unpack(all)
+    header = mbox[uid]:fetch_header()
+    body = mbox[uid]:fetch_body()
+    message = header:gsub('[\r\n]+$', '\r\n') ..
+              'My-Header: My-Content\r\n' .. '\r\n' .. body
+    myaccount.myothermaibox:append_message(message)
+end
+
+
 -- Passwords could be extracted during execution time from an encrypted
 -- file.
 --

src/core.c

@@ -924,22 +924,16 @@ ifcore_append(lua_State *lua)
 	const char *s, *u, *p;
 	int r;
 
-	switch (lua_gettop(lua)) {
-	case 5:
-		luaL_checktype(lua, 5, LUA_TSTRING);
-		/* FALLTHROUGH */
-	case 4:
-		luaL_checktype(lua, 4, LUA_TSTRING);
-		/* FALLTHROUGH */
-	case 3:
-		luaL_checktype(lua, 3, LUA_TSTRING);
-		luaL_checktype(lua, 2, LUA_TSTRING);
-		luaL_checktype(lua, 1, LUA_TTABLE);
-		break;
-	default:
+	if (lua_gettop(lua) != 5)
 		luaL_error(lua, "wrong number of arguments");
-		break;
-	}
+
+	luaL_checktype(lua, 1, LUA_TTABLE);
+	luaL_checktype(lua, 2, LUA_TSTRING);
+	luaL_checktype(lua, 3, LUA_TSTRING);
+	if (lua_type(lua, 4) != LUA_TNIL)
+		luaL_checktype(lua, 4, LUA_TSTRING);
+	if (lua_type(lua, 5) != LUA_TNIL)
+		luaL_checktype(lua, 5, LUA_TSTRING);
 
 	lua_pushvalue(lua, 1);
 	if (!(s = get_table_string("server")))
@@ -950,7 +944,9 @@ ifcore_append(lua_State *lua)
 	lua_pop(lua, 1);
 
 	r = request_append(s, p, u, lua_tostring(lua, 2), lua_tostring(lua, 3),
-	    lua_strlen(lua, 3), lua_tostring(lua, 4), lua_tostring(lua, 5));
+	    lua_strlen(lua, 3), lua_type(lua, 4) == LUA_TSTRING ?
+	    lua_tostring(lua, 4) : NULL, lua_type(lua, 5) == LUA_TSTRING ?
+	    lua_tostring(lua, 5) : NULL);
 
 	lua_pop(lua, lua_gettop(lua));
 

src/mailbox.lua

@@ -915,6 +915,20 @@ function Mailbox.fetch_parts(self, parts, message)
 end
 
 
+function Mailbox.append_message(self, message, flags, date)
+    _check_required(message, 'string')
+    _check_optional(flags, { 'string', 'table' })
+    _check_optional(date, 'string')
+
+    if (type(flags) == 'table') then
+        flags = table.concat(flags, ' ')
+    end
+
+    return ifcore.append(self._account._imap, self._mailbox, message, flags,
+    date)
+end
+
+
 function Mailbox.is_answered(self)
     return self.send_query(self, 'ANSWERED')
 end