1
// Copyright 2007 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 Support class for spell checker components.
17
 *
18
 * @author [email protected] (Emil A Eklund)
19
 */
20

21
goog.provide('goog.spell.SpellCheck');
22
goog.provide('goog.spell.SpellCheck.WordChangedEvent');
23

24
goog.require('goog.Timer');
25
goog.require('goog.events.Event');
26
goog.require('goog.events.EventTarget');
27
goog.require('goog.structs.Set');
28

29

30

31
/**
32
 * Support class for spell checker components. Provides basic functionality
33
 * such as word lookup and caching.
34
 *
35
 * @param {Function=} opt_lookupFunction Function to use for word lookup. Must
36
 *     accept an array of words, an object reference and a callback function as
37
 *     parameters. It must also call the callback function (as a method on the
38
 *     object), once ready, with an array containing the original words, their
39
 *     spelling status and optionally an array of suggestions.
40
 * @param {string=} opt_language Content language.
41
 * @constructor
42
 * @extends {goog.events.EventTarget}
43
 * @final
44
 */
45
goog.spell.SpellCheck = function(opt_lookupFunction, opt_language) {
46
  goog.events.EventTarget.call(this);
47

48
  /**
49
   * Function used to lookup spelling of words.
50
   * @type {Function}
51
   * @private
52
   */
53
  this.lookupFunction_ = opt_lookupFunction || null;
54

55
  /**
56
   * Cache for words not yet checked with lookup function.
57
   * @type {goog.structs.Set}
58
   * @private
59
   */
60
  this.unknownWords_ = new goog.structs.Set();
61

62
  this.setLanguage(opt_language);
63
};
64
goog.inherits(goog.spell.SpellCheck, goog.events.EventTarget);
65

66

67
/**
68
 * Delay, in ms, to wait for additional words to be entered before a lookup
69
 * operation is triggered.
70
 *
71
 * @type {number}
72
 * @private
73
 */
74
goog.spell.SpellCheck.LOOKUP_DELAY_ = 100;
75

76

77
/**
78
 * Constants for event names
79
 *
80
 * @enum {string}
81
 */
82
goog.spell.SpellCheck.EventType = {
83
  /**
84
   * Fired when all pending words have been processed.
85
   */
86
  READY: 'ready',
87

88
  /**
89
   * Fired when all lookup function failed.
90
   */
91
  ERROR: 'error',
92

93
  /**
94
   * Fired when a word's status is changed.
95
   */
96
  WORD_CHANGED: 'wordchanged'
97
};
98

99

100
/**
101
 * Cache. Shared across all spell checker instances. Map with langauge as the
102
 * key and a cache for that language as the value.
103
 *
104
 * @type {Object}
105
 * @private
106
 */
107
goog.spell.SpellCheck.cache_ = {};
108

109

110
/**
111
 * Content Language.
112
 * @type {string}
113
 * @private
114
 */
115
goog.spell.SpellCheck.prototype.language_ = '';
116

117

118
/**
119
 * Cache for set language. Reference to the element corresponding to the set
120
 * language in the static goog.spell.SpellCheck.cache_.
121
 *
122
 * @type {Object|undefined}
123
 * @private
124
 */
125
goog.spell.SpellCheck.prototype.cache_;
126

127

128
/**
129
 * Id for timer processing the pending queue.
130
 *
131
 * @type {number}
132
 * @private
133
 */
134
goog.spell.SpellCheck.prototype.queueTimer_ = 0;
135

136

137
/**
138
 * Whether a lookup operation is in progress.
139
 *
140
 * @type {boolean}
141
 * @private
142
 */
143
goog.spell.SpellCheck.prototype.lookupInProgress_ = false;
144

145

146
/**
147
 * Codes representing the status of an individual word.
148
 *
149
 * @enum {number}
150
 */
151
goog.spell.SpellCheck.WordStatus = {
152
  UNKNOWN: 0,
153
  VALID: 1,
154
  INVALID: 2,
155
  IGNORED: 3,
156
  CORRECTED: 4  // Temporary status, not stored in cache
157
};
158

159

160
/**
161
 * Fields for word array in cache.
162
 *
163
 * @enum {number}
164
 */
165
goog.spell.SpellCheck.CacheIndex = {
166
  STATUS: 0,
167
  SUGGESTIONS: 1
168
};
169

170

171
/**
172
 * Regular expression for identifying word boundaries.
173
 *
174
 * @type {string}
175
 */
176
goog.spell.SpellCheck.WORD_BOUNDARY_CHARS =
177
    '\t\r\n\u00A0 !\"#$%&()*+,\-.\/:;<=>?@\[\\\]^_`{|}~';
178

179

180
/**
181
 * Regular expression for identifying word boundaries.
182
 *
183
 * @type {RegExp}
184
 */
185
goog.spell.SpellCheck.WORD_BOUNDARY_REGEX =
186
    new RegExp('[' + goog.spell.SpellCheck.WORD_BOUNDARY_CHARS + ']');
187

188

189
/**
190
 * Regular expression for splitting a string into individual words and blocks of
191
 * separators. Matches zero or one word followed by zero or more separators.
192
 *
193
 * @type {RegExp}
194
 */
195
goog.spell.SpellCheck.SPLIT_REGEX = new RegExp(
196
    '([^' + goog.spell.SpellCheck.WORD_BOUNDARY_CHARS + ']*)' +
197
    '([' + goog.spell.SpellCheck.WORD_BOUNDARY_CHARS + ']*)');
198

199

200
/**
201
 * Sets the lookup function.
202
 *
203
 * @param {Function} f Function to use for word lookup. Must accept an array of
204
 *     words, an object reference and a callback function as parameters.
205
 *     It must also call the callback function (as a method on the object),
206
 *     once ready, with an array containing the original words, their
207
 *     spelling status and optionally an array of suggestions.
208
 */
209
goog.spell.SpellCheck.prototype.setLookupFunction = function(f) {
210
  this.lookupFunction_ = f;
211
};
212

213

214
/**
215
 * Sets language.
216
 *
217
 * @param {string=} opt_language Content language.
218
 */
219
goog.spell.SpellCheck.prototype.setLanguage = function(opt_language) {
220
  this.language_ = opt_language || '';
221

222
  if (!goog.spell.SpellCheck.cache_[this.language_]) {
223
    goog.spell.SpellCheck.cache_[this.language_] = {};
224
  }
225
  this.cache_ = goog.spell.SpellCheck.cache_[this.language_];
226
};
227

228

229
/**
230
 * Returns language.
231
 *
232
 * @return {string} Content language.
233
 */
234
goog.spell.SpellCheck.prototype.getLanguage = function() {
235
  return this.language_;
236
};
237

238

239
/**
240
 * Checks spelling for a block of text.
241
 *
242
 * @param {string} text Block of text to spell check.
243
 */
244
goog.spell.SpellCheck.prototype.checkBlock = function(text) {
245
  var words = text.split(goog.spell.SpellCheck.WORD_BOUNDARY_REGEX);
246

247
  var len = words.length;
248
  for (var word, i = 0; i < len; i++) {
249
    word = words[i];
250
    this.checkWord_(word);
251
  }
252

253
  if (!this.queueTimer_ && !this.lookupInProgress_ &&
254
      this.unknownWords_.getCount()) {
255
    this.processPending_();
256
  } else if (this.unknownWords_.getCount() == 0) {
257
    this.dispatchEvent(goog.spell.SpellCheck.EventType.READY);
258
  }
259
};
260

261

262
/**
263
 * Checks spelling for a single word. Returns the status of the supplied word,
264
 * or UNKNOWN if it's not cached. If it's not cached the word is added to a
265
 * queue and checked with the verification implementation with a short delay.
266
 *
267
 * @param {string} word Word to check spelling of.
268
 * @return {goog.spell.SpellCheck.WordStatus} The status of the supplied word,
269
 *     or UNKNOWN if it's not cached.
270
 */
271
goog.spell.SpellCheck.prototype.checkWord = function(word) {
272
  var status = this.checkWord_(word);
273

274
  if (status == goog.spell.SpellCheck.WordStatus.UNKNOWN && !this.queueTimer_ &&
275
      !this.lookupInProgress_) {
276
    this.queueTimer_ = goog.Timer.callOnce(
277
        this.processPending_, goog.spell.SpellCheck.LOOKUP_DELAY_, this);
278
  }
279

280
  return status;
281
};
282

283

284
/**
285
 * Checks spelling for a single word. Returns the status of the supplied word,
286
 * or UNKNOWN if it's not cached.
287
 *
288
 * @param {string} word Word to check spelling of.
289
 * @return {goog.spell.SpellCheck.WordStatus} The status of the supplied word,
290
 *     or UNKNOWN if it's not cached.
291
 * @private
292
 */
293
goog.spell.SpellCheck.prototype.checkWord_ = function(word) {
294
  if (!word) {
295
    return goog.spell.SpellCheck.WordStatus.INVALID;
296
  }
297

298
  var cacheEntry = this.cache_[word];
299
  if (!cacheEntry) {
300
    this.unknownWords_.add(word);
301
    return goog.spell.SpellCheck.WordStatus.UNKNOWN;
302
  }
303

304
  return cacheEntry[goog.spell.SpellCheck.CacheIndex.STATUS];
305
};
306

307

308
/**
309
 * Processes pending words unless a lookup operation has already been queued or
310
 * is in progress.
311
 *
312
 * @throws {Error}
313
 */
314
goog.spell.SpellCheck.prototype.processPending = function() {
315
  if (this.unknownWords_.getCount()) {
316
    if (!this.queueTimer_ && !this.lookupInProgress_) {
317
      this.processPending_();
318
    }
319
  } else {
320
    this.dispatchEvent(goog.spell.SpellCheck.EventType.READY);
321
  }
322
};
323

324

325
/**
326
 * Processes pending words using the verification callback.
327
 *
328
 * @throws {Error}
329
 * @private
330
 */
331
goog.spell.SpellCheck.prototype.processPending_ = function() {
332
  if (!this.lookupFunction_) {
333
    throw Error('No lookup function provided for spell checker.');
334
  }
335

336
  if (this.unknownWords_.getCount()) {
337
    this.lookupInProgress_ = true;
338
    var func = this.lookupFunction_;
339
    func(this.unknownWords_.getValues(), this, this.lookupCallback_);
340
  } else {
341
    this.dispatchEvent(goog.spell.SpellCheck.EventType.READY);
342
  }
343

344
  this.queueTimer_ = 0;
345
};
346

347

348
/**
349
 * Callback for lookup function.
350
 *
351
 * @param {Array<Array<?>>} data Data array. Each word is represented by an
352
 *     array containing the word, the status and optionally an array of
353
 *     suggestions. Passing null indicates that the operation failed.
354
 * @private
355
 *
356
 * Example:
357
 * obj.lookupCallback_([
358
 *   ['word', VALID],
359
 *   ['wrod', INVALID, ['word', 'wood', 'rod']]
360
 * ]);
361
 */
362
goog.spell.SpellCheck.prototype.lookupCallback_ = function(data) {
363

364
  // Lookup function failed; abort then dispatch error event.
365
  if (data == null) {
366
    if (this.queueTimer_) {
367
      goog.Timer.clear(this.queueTimer_);
368
      this.queueTimer_ = 0;
369
    }
370
    this.lookupInProgress_ = false;
371

372
    this.dispatchEvent(goog.spell.SpellCheck.EventType.ERROR);
373
    return;
374
  }
375

376
  for (var a, i = 0; a = data[i]; i++) {
377
    this.setWordStatus_(a[0], a[1], a[2]);
378
  }
379
  this.lookupInProgress_ = false;
380

381
  // Fire ready event if all pending words have been processed.
382
  if (this.unknownWords_.getCount() == 0) {
383
    this.dispatchEvent(goog.spell.SpellCheck.EventType.READY);
384

385
    // Process pending
386
  } else if (!this.queueTimer_) {
387
    this.queueTimer_ = goog.Timer.callOnce(
388
        this.processPending_, goog.spell.SpellCheck.LOOKUP_DELAY_, this);
389
  }
390
};
391

392

393
/**
394
 * Sets a words spelling status.
395
 *
396
 * @param {string} word Word to set status for.
397
 * @param {goog.spell.SpellCheck.WordStatus} status Status of word.
398
 * @param {Array<string>=} opt_suggestions Suggestions.
399
 *
400
 * Example:
401
 * obj.setWordStatus('word', VALID);
402
 * obj.setWordStatus('wrod', INVALID, ['word', 'wood', 'rod']);.
403
 */
404
goog.spell.SpellCheck.prototype.setWordStatus = function(
405
    word, status, opt_suggestions) {
406
  this.setWordStatus_(word, status, opt_suggestions);
407
};
408

409

410
/**
411
 * Sets a words spelling status.
412
 *
413
 * @param {string} word Word to set status for.
414
 * @param {goog.spell.SpellCheck.WordStatus} status Status of word.
415
 * @param {Array<string>=} opt_suggestions Suggestions.
416
 * @private
417
 */
418
goog.spell.SpellCheck.prototype.setWordStatus_ = function(
419
    word, status, opt_suggestions) {
420
  var suggestions = opt_suggestions || [];
421
  this.cache_[word] = [status, suggestions];
422
  this.unknownWords_.remove(word);
423

424
  this.dispatchEvent(
425
      new goog.spell.SpellCheck.WordChangedEvent(this, word, status));
426
};
427

428

429
/**
430
 * Returns suggestions for the given word.
431
 *
432
 * @param {string} word Word to get suggestions for.
433
 * @return {Array<string>} An array of suggestions for the given word.
434
 */
435
goog.spell.SpellCheck.prototype.getSuggestions = function(word) {
436
  var cacheEntry = this.cache_[word];
437

438
  if (!cacheEntry) {
439
    this.checkWord(word);
440
    return [];
441
  }
442

443
  return cacheEntry[goog.spell.SpellCheck.CacheIndex.STATUS] ==
444
          goog.spell.SpellCheck.WordStatus.INVALID ?
445
      cacheEntry[goog.spell.SpellCheck.CacheIndex.SUGGESTIONS] :
446
      [];
447
};
448

449

450

451
/**
452
 * Object representing a word changed event. Fired when the status of a word
453
 * changes.
454
 *
455
 * @param {goog.spell.SpellCheck} target Spellcheck object initiating event.
456
 * @param {string} word Word to set status for.
457
 * @param {goog.spell.SpellCheck.WordStatus} status Status of word.
458
 * @extends {goog.events.Event}
459
 * @constructor
460
 * @final
461
 */
462
goog.spell.SpellCheck.WordChangedEvent = function(target, word, status) {
463
  goog.events.Event.call(
464
      this, goog.spell.SpellCheck.EventType.WORD_CHANGED, target);
465

466
  /**
467
   * Word the status has changed for.
468
   * @type {string}
469
   */
470
  this.word = word;
471

472
  /**
473
   * New status
474
   * @type {goog.spell.SpellCheck.WordStatus}
475
   */
476
  this.status = status;
477
};
478
goog.inherits(goog.spell.SpellCheck.WordChangedEvent, goog.events.Event);
479

480