Connection: refactor _store() and add setFlags() and setKeywords()

README.md

@@ -574,10 +574,14 @@ Connection Instance Methods
 
 * **delFlags**(< _mixed_ >source, < _mixed_ >flags, < _function_ >callback) - _(void)_ - Removes flag(s) from message(s). `source` can be a message UID, a message UID range (e.g. '2504:2507' or '\*' or '2504:\*'), or an _array_ of message UIDs and/or message UID ranges. `flags` is either a single flag or an _array_ of flags. `callback` has 1 parameter: < _Error_ >err.
 
+* **setFlags**(< _mixed_ >source, < _mixed_ >flags, < _function_ >callback) - _(void)_ - Sets the flag(s) for message(s). `source` can be a message UID, a message UID range (e.g. '2504:2507' or '\*' or '2504:\*'), or an _array_ of message UIDs and/or message UID ranges. `flags` is either a single flag or an _array_ of flags. `callback` has 1 parameter: < _Error_ >err.
+
 * **addKeywords**(< _mixed_ >source, < _mixed_ >keywords, < _function_ >callback) - _(void)_ - Adds keyword(s) to message(s). `source` can be a message UID, a message UID range (e.g. '2504:2507' or '\*' or '2504:\*'), or an _array_ of message UIDs and/or message UID ranges. `keywords` is either a single keyword or an _array_ of keywords. `callback` has 1 parameter: < _Error_ >err.
 
 * **delKeywords**(< _mixed_ >source, < _mixed_ >keywords, < _function_ >callback) - _(void)_ - Removes keyword(s) from message(s). `source` can be a message UID, a message UID range (e.g. '2504:2507' or '\*' or '2504:\*'), or an _array_ of message UIDs and/or message UID ranges. `keywords` is either a single keyword or an _array_ of keywords. `callback` has 1 parameter: < _Error_ >err.
 
+* **setKeywords**(< _mixed_ >source, < _mixed_ >keywords, < _function_ >callback) - _(void)_ - Sets keyword(s) for message(s). `source` can be a message UID, a message UID range (e.g. '2504:2507' or '\*' or '2504:\*'), or an _array_ of message UIDs and/or message UID ranges. `keywords` is either a single keyword or an _array_ of keywords. `callback` has 1 parameter: < _Error_ >err.
+
 * **serverSupports**(< _string_ >capability) - _boolean_ - Checks if the server supports the specified capability.
 
 

lib/Connection.js

@@ -432,30 +432,33 @@ Connection.prototype._search = function(which, criteria, cb) {
 };
 
 Connection.prototype.addFlags = function(uids, flags, cb) {
-  this._store('UID ', uids, flags, true, cb);
+  this._store('UID ', uids, { mode: '+', flags: flags }, cb);
 };
 
 Connection.prototype.delFlags = function(uids, flags, cb) {
-  this._store('UID ', uids, flags, false, cb);
+  this._store('UID ', uids, { mode: '-', flags: flags }, cb);
 };
 
-Connection.prototype.addKeywords = function(uids, flags, cb) {
+Connection.prototype.setFlags = function(uids, flags, cb) {
-  this._addKeywords('UID ', uids, flags, cb);
+  this._store('UID ', uids, { mode: '', flags: flags }, cb);
 };
 
-Connection.prototype._addKeywords = function(which, uids, flags, cb) {
+Connection.prototype.addKeywords = function(uids, keywords, cb) {
-  if (this._box && !this._box.newKeywords)
+  this._store('UID ', uids, { mode: '+', keywords: keywords }, cb);
-    throw new Error('This mailbox does not allow new keywords to be added');
-  this._store(which, uids, flags, true, cb);
 };
 
-Connection.prototype.delKeywords = function(uids, flags, cb) {
+Connection.prototype.delKeywords = function(uids, keywords, cb) {
-  this._store('UID ', uids, flags, false, cb);
+  this._store('UID ', uids, { mode: '-', keywords: keywords }, cb);
 };
 
-Connection.prototype._store = function(which, uids, flags, isAdding, cb) {
+Connection.prototype.setKeywords = function(uids, keywords, cb) {
-  var isKeywords = (arguments.callee.caller === this._addKeywords
+  this._store('UID ', uids, { mode: '', keywords: keywords }, cb);
-                    || arguments.callee.caller === this.delKeywords);
+};
+
+Connection.prototype._store = function(which, uids, cfg, cb) {
+  var mode = cfg.mode,
+      isFlags = (cfg.flags !== undefined),
+      items = (isFlags ? cfg.flags : cfg.keywords);
   if (this._box === undefined)
     throw new Error('No mailbox is currently selected');
   else if (uids === undefined)
@@ -465,32 +468,34 @@ Connection.prototype._store = function(which, uids, flags, isAdding, cb) {
     uids = [uids];
   validateUIDList(uids);
 
-  if ((!Array.isArray(flags) && typeof flags !== 'string')
+  if ((!Array.isArray(items) && typeof items !== 'string')
-      || (Array.isArray(flags) && flags.length === 0))
+      || (Array.isArray(items) && items.length === 0))
-    throw new Error((isKeywords ? 'Keywords' : 'Flags')
+    throw new Error((isFlags ? 'Flags' : 'Keywords')
                     + ' argument must be a string or a non-empty Array');
-  if (!Array.isArray(flags))
+  if (!Array.isArray(items))
-    flags = [flags];
+    items = [items];
-  for (var i = 0, len = flags.length; i < len; ++i) {
+  for (var i = 0, len = items.length; i < len; ++i) {
-    if (!isKeywords) {
+    if (isFlags) {
-      if (flags[i][0] !== '\\')
+      if (items[i][0] !== '\\')
-        flags[i] = '\\' + flags[i];
+        items[i] = '\\' + items[i];
     } else {
       // keyword contains any char except control characters (%x00-1F and %x7F)
       // and: '(', ')', '{', ' ', '%', '*', '\', '"', ']'
-      if (RE_INVALID_KW_CHARS.test(flags[i])) {
+      if (RE_INVALID_KW_CHARS.test(items[i])) {
-        throw new Error('The keyword "' + flags[i]
+        throw new Error('The keyword "' + items[i]
                         + '" contains invalid characters');
       }
     }
   }
 
-  flags = flags.join(' ');
+  items = items.join(' ');
   uids = uids.join(',');
 
+  var modifiers = '';
 
-  this._enqueue(which + 'STORE ' + uids + ' ' + (isAdding ? '+' : '-')
+  this._enqueue(which + 'STORE ' + uids + ' '
-                + 'FLAGS.SILENT (' + flags + ')', cb);
+                + modifiers
+                + mode + 'FLAGS.SILENT (' + items + ')', cb);
 };
 
 Connection.prototype.copy = function(uids, boxTo, cb) {
@@ -867,24 +872,39 @@ Connection.prototype._thread = function(which, algorithm, criteria, cb) {
 Connection.prototype.__defineGetter__('seq', function() {
   var self = this;
   return {
+    delKeywords: function(seqnos, keywords, cb) {
+      self._store('', seqnos, { mode: '-', keywords: keywords }, cb);
+    },
+    addKeywords: function(seqnos, keywords, cb) {
+      self._store('', seqnos, { mode: '+', keywords: keywords }, cb);
+    },
+    setKeywords: function(seqnos, keywords, cb) {
+      self._store('', seqnos, { mode: '', keywords: keywords }, cb);
+    },
+
+    delFlags: function(seqnos, flags, cb) {
+      self._store('', seqnos, { mode: '-', flags: flags }, cb);
+    },
+    addFlags: function(seqnos, flags, cb) {
+      self._store('', seqnos, { mode: '+', flags: flags }, cb);
+    },
+    setFlags: function(seqnos, flags, cb) {
+      self._store('', seqnos, { mode: '', flags: flags }, cb);
+    },
+
     move: function(seqnos, boxTo, cb) {
       self._move('', seqnos, boxTo, cb);
     },
     copy: function(seqnos, boxTo, cb) {
       self._copy('', seqnos, boxTo, cb);
     },
-    delKeywords: function(seqnos, flags, cb) {
+    fetch: function(seqnos, options, what, cb) {
-      self._store('', seqnos, flags, false, cb);
+      return self._fetch('', seqnos, options, what, cb);
-    },
-    addKeywords: function(seqnos, flags, cb) {
-      self._addKeywords('', seqnos, flags, cb);
-    },
-    delFlags: function(seqnos, flags, cb) {
-      self._store('', seqnos, flags, false, cb);
     },
-    addFlags: function(seqnos, flags, cb) {
+    search: function(options, cb) {
-      self._store('', seqnos, flags, true, cb);
+      self._search('', options, cb);
     },
+
     delLabels: function(seqnos, labels, cb) {
       self._storeLabels('', seqnos, labels, '-', cb);
     },