From 37f74d859adee09ebdf245c5eb819bb98160b083 Mon Sep 17 00:00:00 2001
From: Adam Spiers <offlineimap@adamspiers.org>
Date: Tue, 24 Jun 2014 18:06:34 +0100
Subject: [PATCH] addmessageheader: fix case #2 and flesh out docstring

The example illustrations were slightly cryptic;
modify them to be more obvious.

Fix case #2 (message starts with two line breaks)
where additional line break was shown and coded.

Signed-off-by: Eygene Ryabinkin <rea@codelabs.ru>
---
 offlineimap/folder/Base.py | 86 ++++++++++++++++++++++----------------
 1 file changed, 49 insertions(+), 37 deletions(-)

diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py
index 63dbada..ff36d5a 100644
--- a/offlineimap/folder/Base.py
+++ b/offlineimap/folder/Base.py
@@ -386,40 +386,6 @@ class BaseFolder(object):
         for uid in uidlist:
             self.deletemessagelabels(uid, labels)
 
-
-    """
-    Illustration of all cases for addmessageheader().
-    '+' means the added contents.
-
-Case 1: No '\n\n', leading '\n'
-+X-Flying-Pig-Header: i am here\n
-\n
-This is the body\n
-next line\n
-
-Case 2: '\n\n' at position 0
-+X-Flying-Pig-Header: i am here\n
-\n
-\n
-This is the body\n
-next line\n
-
-Case 3: No '\n\n', no leading '\n'
-+X-Flying-Pig-Header: i am here\n
-+\n
-This is the body\n
-next line\n
-
-Case 4: '\n\n' at non-zero position
-Subject: Something wrong with OI\n
-From: some@person.at+\n
-X-Flying-Pig-Header: i am here\n <-- orig '\n'
-\n
-This is the body\n
-next line\n
-
-    """
-
     def addmessageheader(self, content, linebreak, headername, headervalue):
         """
         Adds new header to the provided message.
@@ -430,19 +396,65 @@ next line\n
         - headername: name of the header to add
         - headervalue: value of the header to add
 
+        This has to deal with strange corner cases where the header is
+        missing or empty.  Here are illustrations for all the cases,
+        showing where the header gets inserted and what the end result
+        is.  In each illustration, '+' means the added contents.  Note
+        that these examples assume LF for linebreak, not CRLF, so '\n'
+        denotes a linebreak and '\n\n' corresponds to the transition
+        between header and body.  However if the linebreak parameter
+        is set to '\r\n' then you would have to substitute '\r\n' for
+        '\n' in the below examples.
+
+          * Case 1: No '\n\n', leading '\n'
+
+            +X-Flying-Pig-Header: i am here\n
+            \n
+            This is the body\n
+            next line\n
+
+          * Case 2: '\n\n' at position 0
+
+            +X-Flying-Pig-Header: i am here
+            \n
+            \n
+            This is the body\n
+            next line\n
+
+          * Case 3: No '\n\n', no leading '\n'
+
+            +X-Flying-Pig-Header: i am here\n
+            +\n
+            This is the body\n
+            next line\n
+
+          * Case 4: '\n\n' at non-zero position
+
+            Subject: Something wrong with OI\n
+            From: some@person.at
+            +\nX-Flying-Pig-Header: i am here
+            \n
+            \n
+            This is the body\n
+            next line\n
         """
         self.ui.debug('',
                  'addmessageheader: called to add %s: %s' % (headername,
                                                              headervalue))
+        # Hoping for case #4
         prefix = linebreak
         suffix = ''
         insertionpoint = content.find(linebreak * 2)
-        if insertionpoint == 0 or insertionpoint == -1:
+        # Case #2
+        if insertionpoint == 0:
+            prefix = ''
+            suffix = ''
+        # Either case #1 or #3
+        elif insertionpoint == -1:
             prefix = ''
             suffix = linebreak
-        if insertionpoint == -1:
             insertionpoint = 0
-            # When body starts immediately, without preceding '\n'
+            # Case #3: when body starts immediately, without preceding '\n'
             # (this shouldn't happen with proper mail messages, but
             # we seen many broken ones), we should add '\n' to make
             # new (and the only header, in this case) to be properly