[geary/mjog/746-gmail-flag-quote-bug: 1/5] Geary.Imap.DataFormat: Clean up source code

[Michael Gratton <mjog src gnome org>]

commit ce1abb8ebdf084efbaa98aa80d0b64846413c9fd
Author: Michael Gratton <mike vee net>
Date:   Fri May 1 12:08:22 2020 +1000

    Geary.Imap.DataFormat: Clean up source code
    
    Restyle to confirm to style convention, add some doc comments. Fix up
    use inline function modifiers.

 src/engine/imap/message/imap-data-format.vala | 148 +++++++++++++++-----------
 1 file changed, 84 insertions(+), 64 deletions(-)
---
diff --git a/src/engine/imap/message/imap-data-format.vala b/src/engine/imap/message/imap-data-format.vala
index 35e490fe..48b9e40e 100644
--- a/src/engine/imap/message/imap-data-format.vala
+++ b/src/engine/imap/message/imap-data-format.vala
@@ -1,77 +1,86 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright © 2016 Software Freedom Conservancy Inc.
+ * Copyright © 2020 Micahel Gratton <mike vee net>
  *
  * This software is licensed under the GNU Lesser General Public License
- * (version 2.1 or later).  See the COPYING file in this distribution.
+ * (version 2.1 or later). See the COPYING file in this distribution.
  */
 
+/**
+ * IMAP protocol utility functions.
+ */
 namespace Geary.Imap.DataFormat {
 
-private const char[] ATOM_SPECIALS = {
-    '(', ')', '{', ' ', // CTL chars are handled by is_special_char
-    '%', '*',           // list-wildcards
-    '"', '\\',          // quoted-specials
-    ']'                 // resp-specials
-};
-
-private const char[] TAG_SPECIALS = {
-    '(', ')', '{', '%', '\"', '\\', '+'
-};
-
-public enum Quoting {
-    REQUIRED,
-    OPTIONAL,
-    UNALLOWED
-}
-
-private bool is_special_char(char ch, char[] ar, string? exceptions) {
-    // Check for CTL chars
-    if (ch <= 0x1F || ch >= 0x7F) {
-        return true;
+    // RFC 3501 §9:
+    //
+    // atom-specials   = "(" / ")" / "{" / SP / CTL / list-wildcards /
+    //                   quoted-specials / resp-specials
+    private const char[] ATOM_SPECIALS = {
+        '(', ')', '{', ' ', // CTL chars are handled by is_special_char
+        '%', '*',           // list-wildcards
+        '"', '\\',          // quoted-specials
+        ']'                 // resp-specials
+    };
+
+    // RFC 3501 §9:
+    //
+    // tag             = 1*<any ASTRING-CHAR except "+">
+    // ASTRING-CHAR    = ATOM-CHAR / resp-specials
+    // ATOM-CHAR       = <any CHAR except atom-specials>
+    private const char[] TAG_SPECIALS = {
+        '(', ')', '{', ' ', // CTL chars are handled by is_special_char
+        '%', '*',           // list-wildcards
+        '"', '\\',          // quoted-specials
+        '+'                 // tag special
+    };
+
+    public enum Quoting {
+        REQUIRED,
+        OPTIONAL,
+        UNALLOWED
     }
 
-    if (ch in ar) {
-        return (exceptions != null) ? Ascii.index_of(exceptions, ch) < 0 : true;
+    /**
+     * Returns true if the character is considered an atom-special.
+     *
+     * Note that while documentation indicates that the backslash
+     * cannot be used in an atom, they *are* used for message flags
+     * and thus must be special cased by the caller.
+     */
+    public bool is_atom_special(char ch, string? exceptions = null) {
+        return is_special_char(ch, ATOM_SPECIALS, exceptions);
     }
 
-    return false;
-}
-
-/**
- * Returns true if the character is considered an atom special.  Note that while documentation
- * indicates that the backslash cannot be used in an atom, they *are* used for message flags and
- * thus must be special cased by the caller.
- */
-public inline bool is_atom_special(char ch, string? exceptions = null) {
-    return is_special_char(ch, ATOM_SPECIALS, exceptions);
-}
-
-/**
- * Tag specials are like atom specials but include the continuation character ('+').  Also, the
- * star character is allowed, although technically only correct in the context of a status response;
- * it's the responsibility of the caller to catch this.
- */
-public bool is_tag_special(char ch, string? exceptions = null) {
-    return is_special_char(ch, TAG_SPECIALS, exceptions);
-}
+    /**
+     * Returns true if the character is considered a tag-special.
+     *
+     * Tag specials are like atom specials but include the
+     * continuation character ('+'). Also, the star character is
+     * allowed, although technically only correct in the context of a
+     * status response; it's the responsibility of the caller to catch
+     * this.
+     */
+    public bool is_tag_special(char ch, string? exceptions = null) {
+        return is_special_char(ch, TAG_SPECIALS, exceptions);
+    }
 
-/**
- * Returns Quoting to indicate if the string must be quoted before sent on the wire, of if it
- * must be sent as a literal.
- */
-public Quoting is_quoting_required(string str) {
-    if (String.is_empty(str))
-        return Quoting.REQUIRED;
+    /**
+     * Determines quoting policy for a string to be sent over the wire.
+     */
+    public Quoting is_quoting_required(string str) {
+        if (String.is_empty(str))
+            return Quoting.REQUIRED;
 
-    int index = 0;
-    for (;;) {
-        char ch = str[index++];
-        if (ch == String.EOS)
-            break;
+        int index = 0;
+        for (;;) {
+            char ch = str[index++];
+            if (ch == String.EOS)
+                break;
 
-        if (ch > 0x7F)
-            return Quoting.UNALLOWED;
+            if (ch > 0x7F)
+                return Quoting.UNALLOWED;
 
-        switch (ch) {
+            switch (ch) {
             case '\n':
             case '\r':
                 return Quoting.UNALLOWED;
@@ -79,13 +88,24 @@ public Quoting is_quoting_required(string str) {
             default:
                 if (is_atom_special(ch))
                     return Quoting.REQUIRED;
-            break;
+                break;
+            }
         }
+
+        return Quoting.OPTIONAL;
     }
 
-    return Quoting.OPTIONAL;
-}
+    private inline bool is_special_char(char ch, char[] ar, string? exceptions) {
+        // Check for CTL chars
+        if (ch <= 0x1F || ch >= 0x7F) {
+            return true;
+        }
+
+        if (ch in ar) {
+            return (exceptions != null) ? Ascii.index_of(exceptions, ch) < 0 : true;
+        }
 
+        return false;
+    }
 
 }
-