Debian Codegraph @

closure-library/closure/goog/format/emailaddress.js

raw
1 // Copyright 2010 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Provides functions to parse and manipulate email addresses.
17 *
18 */
19
20 goog.provide('goog.format.EmailAddress');
21
22 goog.require('goog.string');
23
24
25
26 /**
27 * Formats an email address string for display, and allows for extraction of
28 * the individual components of the address.
29 * @param {string=} opt_address The email address.
30 * @param {string=} opt_name The name associated with the email address.
31 * @constructor
32 */
33 goog.format.EmailAddress = function(opt_address, opt_name) {
34 /**
35 * The name or personal string associated with the address.
36 * @type {string}
37 * @private
38 */
39 this.name_ = opt_name || '';
40
41 /**
42 * The email address.
43 * @type {string}
44 * @protected
45 */
46 this.address = opt_address || '';
47 };
48
49
50 /**
51 * Match string for opening tokens.
52 * @type {string}
53 * @private
54 */
55 goog.format.EmailAddress.OPENERS_ = '"<([';
56
57
58 /**
59 * Match string for closing tokens.
60 * @type {string}
61 * @private
62 */
63 goog.format.EmailAddress.CLOSERS_ = '">)]';
64
65
66 /**
67 * Match string for characters that require display names to be quoted and are
68 * not address separators.
69 * @type {string}
70 * @const
71 * @package
72 */
73 goog.format.EmailAddress.SPECIAL_CHARS = '()<>@:\\\".[]';
74
75
76 /**
77 * Match string for address separators.
78 * @type {string}
79 * @const
80 * @private
81 */
82 goog.format.EmailAddress.ADDRESS_SEPARATORS_ = ',;';
83
84
85 /**
86 * Match string for characters that, when in a display name, require it to be
87 * quoted.
88 * @type {string}
89 * @const
90 * @private
91 */
92 goog.format.EmailAddress.CHARS_REQUIRE_QUOTES_ =
93 goog.format.EmailAddress.SPECIAL_CHARS +
94 goog.format.EmailAddress.ADDRESS_SEPARATORS_;
95
96
97 /**
98 * A RegExp to match all double quotes. Used in cleanAddress().
99 * @type {RegExp}
100 * @private
101 */
102 goog.format.EmailAddress.ALL_DOUBLE_QUOTES_ = /\"/g;
103
104
105 /**
106 * A RegExp to match escaped double quotes. Used in parse().
107 * @type {RegExp}
108 * @private
109 */
110 goog.format.EmailAddress.ESCAPED_DOUBLE_QUOTES_ = /\\\"/g;
111
112
113 /**
114 * A RegExp to match all backslashes. Used in cleanAddress().
115 * @type {RegExp}
116 * @private
117 */
118 goog.format.EmailAddress.ALL_BACKSLASHES_ = /\\/g;
119
120
121 /**
122 * A RegExp to match escaped backslashes. Used in parse().
123 * @type {RegExp}
124 * @private
125 */
126 goog.format.EmailAddress.ESCAPED_BACKSLASHES_ = /\\\\/g;
127
128
129 /**
130 * A string representing the RegExp for the local part of an email address.
131 * @private {string}
132 */
133 goog.format.EmailAddress.LOCAL_PART_REGEXP_STR_ =
134 '[+a-zA-Z0-9_.!#$%&\'*\\/=?^`{|}~-]+';
135
136
137 /**
138 * A string representing the RegExp for the domain part of an email address.
139 * @private {string}
140 */
141 goog.format.EmailAddress.DOMAIN_PART_REGEXP_STR_ =
142 '([a-zA-Z0-9-]+\\.)+[a-zA-Z0-9]{2,63}';
143
144
145 /**
146 * A RegExp to match the local part of an email address.
147 * @private {!RegExp}
148 */
149 goog.format.EmailAddress.LOCAL_PART_ =
150 new RegExp('^' + goog.format.EmailAddress.LOCAL_PART_REGEXP_STR_ + '$');
151
152
153 /**
154 * A RegExp to match the domain part of an email address.
155 * @private {!RegExp}
156 */
157 goog.format.EmailAddress.DOMAIN_PART_ =
158 new RegExp('^' + goog.format.EmailAddress.DOMAIN_PART_REGEXP_STR_ + '$');
159
160
161 /**
162 * A RegExp to match an email address.
163 * @private {!RegExp}
164 */
165 goog.format.EmailAddress.EMAIL_ADDRESS_ = new RegExp(
166 '^' + goog.format.EmailAddress.LOCAL_PART_REGEXP_STR_ + '@' +
167 goog.format.EmailAddress.DOMAIN_PART_REGEXP_STR_ + '$');
168
169
170 /**
171 * Get the name associated with the email address.
172 * @return {string} The name or personal portion of the address.
173 * @final
174 */
175 goog.format.EmailAddress.prototype.getName = function() {
176 return this.name_;
177 };
178
179
180 /**
181 * Get the email address.
182 * @return {string} The email address.
183 * @final
184 */
185 goog.format.EmailAddress.prototype.getAddress = function() {
186 return this.address;
187 };
188
189
190 /**
191 * Set the name associated with the email address.
192 * @param {string} name The name to associate.
193 * @final
194 */
195 goog.format.EmailAddress.prototype.setName = function(name) {
196 this.name_ = name;
197 };
198
199
200 /**
201 * Set the email address.
202 * @param {string} address The email address.
203 * @final
204 */
205 goog.format.EmailAddress.prototype.setAddress = function(address) {
206 this.address = address;
207 };
208
209
210 /**
211 * Return the address in a standard format:
212 * - remove extra spaces.
213 * - Surround name with quotes if it contains special characters.
214 * @return {string} The cleaned address.
215 * @override
216 */
217 goog.format.EmailAddress.prototype.toString = function() {
218 return this.toStringInternal(goog.format.EmailAddress.CHARS_REQUIRE_QUOTES_);
219 };
220
221
222 /**
223 * Check if a display name requires quoting.
224 * @param {string} name The display name
225 * @param {string} specialChars String that contains the characters that require
226 * the display name to be quoted. This may change based in whereas we are
227 * in EAI context or not.
228 * @return {boolean}
229 * @private
230 */
231 goog.format.EmailAddress.isQuoteNeeded_ = function(name, specialChars) {
232 for (var i = 0; i < specialChars.length; i++) {
233 var specialChar = specialChars[i];
234 if (goog.string.contains(name, specialChar)) {
235 return true;
236 }
237 }
238 return false;
239 };
240
241
242 /**
243 * Return the address in a standard format:
244 * - remove extra spaces.
245 * - Surround name with quotes if it contains special characters.
246 * @param {string} specialChars String that contains the characters that require
247 * the display name to be quoted.
248 * @return {string} The cleaned address.
249 * @protected
250 */
251 goog.format.EmailAddress.prototype.toStringInternal = function(specialChars) {
252 var name = this.getName();
253
254 // We intentionally remove double quotes in the name because escaping
255 // them to \" looks ugly.
256 name = name.replace(goog.format.EmailAddress.ALL_DOUBLE_QUOTES_, '');
257
258 // If the name has special characters, we need to quote it and escape \'s.
259 if (goog.format.EmailAddress.isQuoteNeeded_(name, specialChars)) {
260 name = '"' +
261 name.replace(goog.format.EmailAddress.ALL_BACKSLASHES_, '\\\\') + '"';
262 }
263
264 if (name == '') {
265 return this.address;
266 }
267 if (this.address == '') {
268 return name;
269 }
270 return name + ' <' + this.address + '>';
271 };
272
273
274 /**
275 * Determines if the current object is a valid email address.
276 * @return {boolean} Whether the email address is valid.
277 */
278 goog.format.EmailAddress.prototype.isValid = function() {
279 return goog.format.EmailAddress.isValidAddrSpec(this.address);
280 };
281
282
283 /**
284 * Checks if the provided string is a valid email address. Supports both
285 * simple email addresses (address specs) and addresses that contain display
286 * names.
287 * @param {string} str The email address to check.
288 * @return {boolean} Whether the provided string is a valid address.
289 */
290 goog.format.EmailAddress.isValidAddress = function(str) {
291 return goog.format.EmailAddress.parse(str).isValid();
292 };
293
294
295 /**
296 * Checks if the provided string is a valid address spec ([email protected]).
297 * @param {string} str The email address to check.
298 * @return {boolean} Whether the provided string is a valid address spec.
299 */
300 goog.format.EmailAddress.isValidAddrSpec = function(str) {
301 // This is a fairly naive implementation, but it covers 99% of use cases.
302 // For more details, see http://en.wikipedia.org/wiki/Email_address#Syntax
303 return goog.format.EmailAddress.EMAIL_ADDRESS_.test(str);
304 };
305
306
307 /**
308 * Checks if the provided string is a valid local part (part before the '@') of
309 * an email address.
310 * @param {string} str The local part to check.
311 * @return {boolean} Whether the provided string is a valid local part.
312 */
313 goog.format.EmailAddress.isValidLocalPartSpec = function(str) {
314 return goog.format.EmailAddress.LOCAL_PART_.test(str);
315 };
316
317
318 /**
319 * Checks if the provided string is a valid domain part (part after the '@') of
320 * an email address.
321 * @param {string} str The domain part to check.
322 * @return {boolean} Whether the provided string is a valid domain part.
323 */
324 goog.format.EmailAddress.isValidDomainPartSpec = function(str) {
325 return goog.format.EmailAddress.DOMAIN_PART_.test(str);
326 };
327
328
329 /**
330 * Parses an email address of the form "name" &lt;address&gt; ("name" is
331 * optional) into an email address.
332 * @param {string} addr The address string.
333 * @param {function(new: goog.format.EmailAddress, string=,string=)} ctor
334 * EmailAddress constructor to instantiate the output address.
335 * @return {!goog.format.EmailAddress} The parsed address.
336 * @protected
337 */
338 goog.format.EmailAddress.parseInternal = function(addr, ctor) {
339 // TODO(ecattell): Strip bidi markers.
340 var name = '';
341 var address = '';
342 for (var i = 0; i < addr.length;) {
343 var token = goog.format.EmailAddress.getToken_(addr, i);
344 if (token.charAt(0) == '<' && token.indexOf('>') != -1) {
345 var end = token.indexOf('>');
346 address = token.substring(1, end);
347 } else if (address == '') {
348 name += token;
349 }
350 i += token.length;
351 }
352
353 // Check if it's a simple email address of the form "[email protected]".
354 if (address == '' && name.indexOf('@') != -1) {
355 address = name;
356 name = '';
357 }
358
359 name = goog.string.collapseWhitespace(name);
360 name = goog.string.stripQuotes(name, '\'');
361 name = goog.string.stripQuotes(name, '"');
362 // Replace escaped quotes and slashes.
363 name = name.replace(goog.format.EmailAddress.ESCAPED_DOUBLE_QUOTES_, '"');
364 name = name.replace(goog.format.EmailAddress.ESCAPED_BACKSLASHES_, '\\');
365 address = goog.string.collapseWhitespace(address);
366 return new ctor(address, name);
367 };
368
369
370 /**
371 * Parses an email address of the form "name" &lt;address&gt; into
372 * an email address.
373 * @param {string} addr The address string.
374 * @return {!goog.format.EmailAddress} The parsed address.
375 */
376 goog.format.EmailAddress.parse = function(addr) {
377 return goog.format.EmailAddress.parseInternal(addr, goog.format.EmailAddress);
378 };
379
380
381 /**
382 * Parse a string containing email addresses of the form
383 * "name" &lt;address&gt; into an array of email addresses.
384 * @param {string} str The address list.
385 * @param {function(string)} parser The parser to employ.
386 * @param {function(string):boolean} separatorChecker Accepts a character and
387 * returns whether it should be considered an address separator.
388 * @return {!Array<!goog.format.EmailAddress>} The parsed emails.
389 * @protected
390 */
391 goog.format.EmailAddress.parseListInternal = function(
392 str, parser, separatorChecker) {
393 var result = [];
394 var email = '';
395 var token;
396
397 // Remove non-UNIX-style newlines that would otherwise cause getToken_ to
398 // choke. Remove multiple consecutive whitespace characters for the same
399 // reason.
400 str = goog.string.collapseWhitespace(str);
401
402 for (var i = 0; i < str.length;) {
403 token = goog.format.EmailAddress.getToken_(str, i);
404 if (separatorChecker(token) || (token == ' ' && parser(email).isValid())) {
405 if (!goog.string.isEmptyOrWhitespace(email)) {
406 result.push(parser(email));
407 }
408 email = '';
409 i++;
410 continue;
411 }
412 email += token;
413 i += token.length;
414 }
415
416 // Add the final token.
417 if (!goog.string.isEmptyOrWhitespace(email)) {
418 result.push(parser(email));
419 }
420 return result;
421 };
422
423
424 /**
425 * Parses a string containing email addresses of the form
426 * "name" &lt;address&gt; into an array of email addresses.
427 * @param {string} str The address list.
428 * @return {!Array<!goog.format.EmailAddress>} The parsed emails.
429 */
430 goog.format.EmailAddress.parseList = function(str) {
431 return goog.format.EmailAddress.parseListInternal(
432 str, goog.format.EmailAddress.parse,
433 goog.format.EmailAddress.isAddressSeparator);
434 };
435
436
437 /**
438 * Get the next token from a position in an address string.
439 * @param {string} str the string.
440 * @param {number} pos the position.
441 * @return {string} the token.
442 * @private
443 */
444 goog.format.EmailAddress.getToken_ = function(str, pos) {
445 var ch = str.charAt(pos);
446 var p = goog.format.EmailAddress.OPENERS_.indexOf(ch);
447 if (p == -1) {
448 return ch;
449 }
450 if (goog.format.EmailAddress.isEscapedDlQuote_(str, pos)) {
451 // If an opener is an escaped quote we do not treat it as a real opener
452 // and keep accumulating the token.
453 return ch;
454 }
455 var closerChar = goog.format.EmailAddress.CLOSERS_.charAt(p);
456 var endPos = str.indexOf(closerChar, pos + 1);
457
458 // If the closer is a quote we go forward skipping escaped quotes until we
459 // hit the real closing one.
460 while (endPos >= 0 &&
461 goog.format.EmailAddress.isEscapedDlQuote_(str, endPos)) {
462 endPos = str.indexOf(closerChar, endPos + 1);
463 }
464 var token = (endPos >= 0) ? str.substring(pos, endPos + 1) : ch;
465 return token;
466 };
467
468
469 /**
470 * Checks if the character in the current position is an escaped double quote
471 * ( \" ).
472 * @param {string} str the string.
473 * @param {number} pos the position.
474 * @return {boolean} true if the char is escaped double quote.
475 * @private
476 */
477 goog.format.EmailAddress.isEscapedDlQuote_ = function(str, pos) {
478 if (str.charAt(pos) != '"') {
479 return false;
480 }
481 var slashCount = 0;
482 for (var idx = pos - 1; idx >= 0 && str.charAt(idx) == '\\'; idx--) {
483 slashCount++;
484 }
485 return ((slashCount % 2) != 0);
486 };
487
488
489 /**
490 * @param {string} ch The character to test.
491 * @return {boolean} Whether the provided character is an address separator.
492 */
493 goog.format.EmailAddress.isAddressSeparator = function(ch) {
494 return goog.string.contains(goog.format.EmailAddress.ADDRESS_SEPARATORS_, ch);
495 };