From: Richard Russon <rich@flatcap.org>
Date: Sun, 20 May 2018 00:42:26 +0000 (+0100)
Subject: comment blocks for aliases
X-Git-Tag: neomutt-20180622~47^2~2
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d97f16adeecdb8e323d9fd9eb1db9108f9d7f3bf;p=neomutt

comment blocks for aliases
---

diff --git a/alias.c b/alias.c
index ce284a774..20db4a9d4 100644
--- a/alias.c
+++ b/alias.c
@@ -38,18 +38,6 @@
 #include "options.h"
 #include "protos.h"
 
-struct Address *mutt_alias_lookup(const char *s)
-{
-  struct Alias *a = NULL;
-
-  TAILQ_FOREACH(a, &Aliases, entries)
-  {
-    if (mutt_str_strcasecmp(s, a->name) == 0)
-      return a->addr;
-  }
-  return NULL; /* no such alias */
-}
-
 /**
  * expand_aliases_r - Expand aliases, recursively
  * @param[in]  a    Address List
@@ -136,29 +124,10 @@ static struct Address *expand_aliases_r(struct Address *a, struct ListHead *expn
   return head;
 }
 
-struct Address *mutt_expand_aliases(struct Address *a)
-{
-  struct Address *t = NULL;
-  struct ListHead expn; /* previously expanded aliases to avoid loops */
-
-  STAILQ_INIT(&expn);
-  t = expand_aliases_r(a, &expn);
-  mutt_list_free(&expn);
-  return (mutt_remove_duplicates(t));
-}
-
-void mutt_expand_aliases_env(struct Envelope *env)
-{
-  env->from = mutt_expand_aliases(env->from);
-  env->to = mutt_expand_aliases(env->to);
-  env->cc = mutt_expand_aliases(env->cc);
-  env->bcc = mutt_expand_aliases(env->bcc);
-  env->reply_to = mutt_expand_aliases(env->reply_to);
-  env->mail_followup_to = mutt_expand_aliases(env->mail_followup_to);
-}
-
 /**
  * write_safe_address - Defang malicious email addresses
+ * @param fp File to write to
+ * @param s  Email address to defang
  *
  * if someone has an address like
  *      From: Michael `/bin/rm -f ~` Elkins <me@mutt.org>
@@ -183,55 +152,24 @@ static void write_safe_address(FILE *fp, char *s)
 {
   while (*s)
   {
-    if (*s == '\\' || *s == '`' || *s == '\'' || *s == '"' || *s == '$')
+    if ((*s == '\\') || (*s == '`') || (*s == '\'') || (*s == '"') || (*s == '$'))
       fputc('\\', fp);
     fputc(*s, fp);
     s++;
   }
 }
 
-struct Address *mutt_get_address(struct Envelope *env, char **pfxp)
-{
-  struct Address *addr = NULL;
-  char *pfx = NULL;
-
-  if (mutt_addr_is_user(env->from))
-  {
-    if (env->to && !mutt_is_mail_list(env->to))
-    {
-      pfx = "To";
-      addr = env->to;
-    }
-    else
-    {
-      pfx = "Cc";
-      addr = env->cc;
-    }
-  }
-  else if (env->reply_to && !mutt_is_mail_list(env->reply_to))
-  {
-    pfx = "Reply-To";
-    addr = env->reply_to;
-  }
-  else
-  {
-    addr = env->from;
-    pfx = "From";
-  }
-
-  if (pfxp)
-    *pfxp = pfx;
-
-  return addr;
-}
-
+/**
+ * recode_buf - XXX
+ * @param buf    Buffer to convert
+ * @param buflen Length of buffer
+ */
 static void recode_buf(char *buf, size_t buflen)
 {
-  char *s = NULL;
-
   if (!ConfigCharset || !*ConfigCharset || !Charset)
     return;
-  s = mutt_str_strdup(buf);
+
+  char *s = mutt_str_strdup(buf);
   if (!s)
     return;
   if (mutt_ch_convert_string(&s, Charset, ConfigCharset, 0) == 0)
@@ -241,11 +179,16 @@ static void recode_buf(char *buf, size_t buflen)
 
 /**
  * check_alias_name - Sanity-check an alias name
+ * @param s       Alias to check
+ * @param dest    Buffer for the result
+ * @param destlen Length of buffer
+ * @retval  0 Success
+ * @retval -1 Error
  *
  * Only characters which are non-special to both the RFC822 and the neomutt
  * configuration parser are permitted.
  */
-int check_alias_name(const char *s, char *dest, size_t destlen)
+static int check_alias_name(const char *s, char *dest, size_t destlen)
 {
   wchar_t wc;
   mbstate_t mb;
@@ -285,6 +228,122 @@ int check_alias_name(const char *s, char *dest, size_t destlen)
   return rc;
 }
 
+/**
+ * string_is_address - Does an email address match a user and domain?
+ * @param str Address string to test
+ * @param u   User name
+ * @param d   Domain name
+ * @retval true They match
+ */
+static bool string_is_address(const char *str, const char *u, const char *d)
+{
+  char buf[LONG_STRING];
+
+  snprintf(buf, sizeof(buf), "%s@%s", NONULL(u), NONULL(d));
+  if (mutt_str_strcasecmp(str, buf) == 0)
+    return true;
+
+  return false;
+}
+
+/**
+ * mutt_alias_lookup - Find an Alias
+ * @param s Alias string to find
+ * @retval ptr  Address for the Alias
+ * @retval NULL No such Alias
+ *
+ * @note The search is case-insensitive
+ */
+struct Address *mutt_alias_lookup(const char *s)
+{
+  struct Alias *a = NULL;
+
+  TAILQ_FOREACH(a, &Aliases, entries)
+  {
+    if (mutt_str_strcasecmp(s, a->name) == 0)
+      return a->addr;
+  }
+  return NULL;
+}
+
+/**
+ * mutt_expand_aliases - Expand aliases in a List of Addresses
+ * @param a First Address
+ * @retval ptr Top of the de-duped list
+ *
+ * Duplicate addresses are dropped
+ */
+struct Address *mutt_expand_aliases(struct Address *a)
+{
+  struct Address *t = NULL;
+  struct ListHead expn; /* previously expanded aliases to avoid loops */
+
+  STAILQ_INIT(&expn);
+  t = expand_aliases_r(a, &expn);
+  mutt_list_free(&expn);
+  return (mutt_remove_duplicates(t));
+}
+
+/**
+ * mutt_expand_aliases_env - XXX
+ * @param env Envelope to expand
+ */
+void mutt_expand_aliases_env(struct Envelope *env)
+{
+  env->from = mutt_expand_aliases(env->from);
+  env->to = mutt_expand_aliases(env->to);
+  env->cc = mutt_expand_aliases(env->cc);
+  env->bcc = mutt_expand_aliases(env->bcc);
+  env->reply_to = mutt_expand_aliases(env->reply_to);
+  env->mail_followup_to = mutt_expand_aliases(env->mail_followup_to);
+}
+
+/**
+ * mutt_get_address - Get an Address from an Envelope
+ * @param env  Envelope to examine
+ * @param pfxp Prefix for the Address, e.g. "To:"
+ * @retval ptr Address in the Envelope
+ */
+struct Address *mutt_get_address(struct Envelope *env, char **pfxp)
+{
+  struct Address *addr = NULL;
+  char *pfx = NULL;
+
+  if (mutt_addr_is_user(env->from))
+  {
+    if (env->to && !mutt_is_mail_list(env->to))
+    {
+      pfx = "To";
+      addr = env->to;
+    }
+    else
+    {
+      pfx = "Cc";
+      addr = env->cc;
+    }
+  }
+  else if (env->reply_to && !mutt_is_mail_list(env->reply_to))
+  {
+    pfx = "Reply-To";
+    addr = env->reply_to;
+  }
+  else
+  {
+    addr = env->from;
+    pfx = "From";
+  }
+
+  if (pfxp)
+    *pfxp = pfx;
+
+  return addr;
+}
+
+/**
+ * mutt_alias_create - Create a new Alias from an Envelope or an Address
+ * @param cur   Envelope to use
+ * @param iaddr Address to use
+ */
 void mutt_alias_create(struct Envelope *cur, struct Address *iaddr)
 {
   struct Alias *new = NULL;
@@ -449,9 +508,11 @@ fseek_err:
 }
 
 /**
- * alias_reverse_lookup - Does the user have an alias for the given address
+ * mutt_alias_reverse_lookup - Does the user have an alias for the given address
+ * @param a Address to lookup
+ * @retval ptr Matching Address
  */
-struct Address *alias_reverse_lookup(struct Address *a)
+struct Address *mutt_alias_reverse_lookup(struct Address *a)
 {
   if (!a || !a->mailbox)
     return NULL;
@@ -459,6 +520,10 @@ struct Address *alias_reverse_lookup(struct Address *a)
   return mutt_hash_find(ReverseAliases, a->mailbox);
 }
 
+/**
+ * mutt_alias_add_reverse - Add an email address lookup for an Alias
+ * @param t Alias to use
+ */
 void mutt_alias_add_reverse(struct Alias *t)
 {
   struct Address *ap = NULL;
@@ -467,7 +532,7 @@ void mutt_alias_add_reverse(struct Alias *t)
 
   /* Note that the address mailbox should be converted to intl form
    * before using as a key in the hash.  This is currently done
-   * by all callers, but added here mostly as documentation.. */
+   * by all callers, but added here mostly as documentation. */
   mutt_addrlist_to_intl(t->addr, NULL);
 
   for (ap = t->addr; ap; ap = ap->next)
@@ -477,6 +542,10 @@ void mutt_alias_add_reverse(struct Alias *t)
   }
 }
 
+/**
+ * mutt_alias_delete_reverse - Remove an email address lookup for an Alias
+ * @param t Alias to use
+ */
 void mutt_alias_delete_reverse(struct Alias *t)
 {
   struct Address *ap = NULL;
@@ -496,8 +565,12 @@ void mutt_alias_delete_reverse(struct Alias *t)
 
 /**
  * mutt_alias_complete - alias completion routine
+ * @param buf    Partial Alias to complete
+ * @param buflen Length of buffer
+ * @retval 1 Success
+ * @retval 0 Error
  *
- * given a partial alias, this routine attempts to fill in the alias
+ * Given a partial alias, this routine attempts to fill in the alias
  * from the alias list as much as possible. if given empty search string
  * or found nothing, present all aliases
  */
@@ -521,7 +594,7 @@ int mutt_alias_complete(char *buf, size_t buflen)
         else
         {
           int i;
-          for (i = 0; a->name[i] && a->name[i] == bestname[i]; i++)
+          for (i = 0; a->name[i] && (a->name[i] == bestname[i]); i++)
             ;
           bestname[i] = '\0';
         }
@@ -575,19 +648,9 @@ int mutt_alias_complete(char *buf, size_t buflen)
   return 0;
 }
 
-static bool string_is_address(const char *str, const char *u, const char *d)
-{
-  char buf[LONG_STRING];
-
-  snprintf(buf, sizeof(buf), "%s@%s", NONULL(u), NONULL(d));
-  if (mutt_str_strcasecmp(str, buf) == 0)
-    return true;
-
-  return false;
-}
-
 /**
  * mutt_addr_is_user - Does the address belong to the user
+ * @param addr Address to check
  * @retval true if the given address belongs to the user
  */
 bool mutt_addr_is_user(struct Address *addr)
@@ -648,20 +711,27 @@ bool mutt_addr_is_user(struct Address *addr)
   return false;
 }
 
+/**
+ * mutt_alias_free - Free an Alias
+ * @param p Alias to free
+ */
 void mutt_alias_free(struct Alias **p)
 {
-  struct Alias *a = NULL;
-  if (!p || !(*p))
+  if (!p || !*p)
     return;
 
-  a = *p;
-  mutt_alias_delete_reverse(a);
-  FREE(&a->name);
-  mutt_addr_free(&a->addr);
-  FREE(&a);
+  mutt_alias_delete_reverse(*p);
+  FREE(&(*p)->name);
+  mutt_addr_free(&(*p)->addr);
+  FREE(p);
 }
 
-void mutt_aliaslist_free(struct AliasList *a_list) {
+/**
+ * mutt_aliaslist_free - Free a List of Aliases
+ * @param a_list AliasList to free
+ */
+void mutt_aliaslist_free(struct AliasList *a_list)
+{
   struct Alias *a = NULL, *tmp = NULL;
   TAILQ_FOREACH_SAFE(a, a_list, entries, tmp)
   {
diff --git a/alias.h b/alias.h
index b00857e67..72199ec36 100644
--- a/alias.h
+++ b/alias.h
@@ -46,12 +46,10 @@ TAILQ_HEAD(AliasList, Alias);
 
 void            mutt_alias_create(struct Envelope *cur, struct Address *iaddr);
 void            mutt_alias_free(struct Alias **p);
-struct Address *mutt_alias_lookup(const char *s);
-
 void            mutt_aliaslist_free(struct AliasList *a_list);
-
+struct Address *mutt_alias_lookup(const char *s);
+void            mutt_expand_aliases_env(struct Envelope *env);
 struct Address *mutt_expand_aliases(struct Address *a);
-void mutt_expand_aliases_env(struct Envelope *env);
 struct Address *mutt_get_address(struct Envelope *env, char **pfxp);
 
 #endif /* _MUTT_ALIAS_H */
diff --git a/pattern.c b/pattern.c
index 5fea7540b..973ae5d85 100644
--- a/pattern.c
+++ b/pattern.c
@@ -1350,7 +1350,7 @@ static int match_addrlist(struct Pattern *pat, int match_personal, int n, ...)
   {
     for (struct Address *a = va_arg(ap, struct Address *); a; a = a->next)
     {
-      if (pat->alladdr ^ ((!pat->isalias || alias_reverse_lookup(a)) &&
+      if (pat->alladdr ^ ((!pat->isalias || mutt_alias_reverse_lookup(a)) &&
                           ((a->mailbox && !patmatch(pat, a->mailbox)) ||
                            (match_personal && a->personal && !patmatch(pat, a->personal)))))
       {
diff --git a/protos.h b/protos.h
index 73108309f..a85e33d56 100644
--- a/protos.h
+++ b/protos.h
@@ -346,7 +346,7 @@ uint32_t mutt_rand32(void);
 uint64_t mutt_rand64(void);
 int mutt_randbuf(void *out, size_t len);
 
-struct Address *alias_reverse_lookup(struct Address *a);
+struct Address *mutt_alias_reverse_lookup(struct Address *a);
 
 int getdnsdomainname(char *d, size_t len);
 
diff --git a/sort.c b/sort.c
index 48c8e8ade..b253afc48 100644
--- a/sort.c
+++ b/sort.c
@@ -115,7 +115,7 @@ const char *mutt_get_name(struct Address *a)
 
   if (a)
   {
-    if (ReverseAlias && (ali = alias_reverse_lookup(a)) && ali->personal)
+    if (ReverseAlias && (ali = mutt_alias_reverse_lookup(a)) && ali->personal)
       return ali->personal;
     else if (a->personal)
       return a->personal;