Real-time collaboration for Jupyter Notebooks, Linux Terminals, LaTeX, VS Code, R IDE, and more,
all in one place. Commercial Alternative to JupyterHub.

Sage Reference Manual

1
/*
2
 * searchtools.js_t
3
 * ~~~~~~~~~~~~~~~~
4
 *
5
 * Sphinx JavaScript utilties for the full-text search.
6
 *
7
 * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
8
 * :license: BSD, see LICENSE for details.
9
 *
10
 */
11

12

13
/**
14
 * Porter Stemmer
15
 */
16
var Stemmer = function() {
17

18
  var step2list = {
19
    ational: 'ate',
20
    tional: 'tion',
21
    enci: 'ence',
22
    anci: 'ance',
23
    izer: 'ize',
24
    bli: 'ble',
25
    alli: 'al',
26
    entli: 'ent',
27
    eli: 'e',
28
    ousli: 'ous',
29
    ization: 'ize',
30
    ation: 'ate',
31
    ator: 'ate',
32
    alism: 'al',
33
    iveness: 'ive',
34
    fulness: 'ful',
35
    ousness: 'ous',
36
    aliti: 'al',
37
    iviti: 'ive',
38
    biliti: 'ble',
39
    logi: 'log'
40
  };
41

42
  var step3list = {
43
    icate: 'ic',
44
    ative: '',
45
    alize: 'al',
46
    iciti: 'ic',
47
    ical: 'ic',
48
    ful: '',
49
    ness: ''
50
  };
51

52
  var c = "[^aeiou]";          // consonant
53
  var v = "[aeiouy]";          // vowel
54
  var C = c + "[^aeiouy]*";    // consonant sequence
55
  var V = v + "[aeiou]*";      // vowel sequence
56

57
  var mgr0 = "^(" + C + ")?" + V + C;                      // [C]VC... is m>0
58
  var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$";    // [C]VC[V] is m=1
59
  var mgr1 = "^(" + C + ")?" + V + C + V + C;              // [C]VCVC... is m>1
60
  var s_v   = "^(" + C + ")?" + v;                         // vowel in stem
61

62
  this.stemWord = function (w) {
63
    var stem;
64
    var suffix;
65
    var firstch;
66
    var origword = w;
67

68
    if (w.length < 3)
69
      return w;
70

71
    var re;
72
    var re2;
73
    var re3;
74
    var re4;
75

76
    firstch = w.substr(0,1);
77
    if (firstch == "y")
78
      w = firstch.toUpperCase() + w.substr(1);
79

80
    // Step 1a
81
    re = /^(.+?)(ss|i)es$/;
82
    re2 = /^(.+?)([^s])s$/;
83

84
    if (re.test(w))
85
      w = w.replace(re,"$1$2");
86
    else if (re2.test(w))
87
      w = w.replace(re2,"$1$2");
88

89
    // Step 1b
90
    re = /^(.+?)eed$/;
91
    re2 = /^(.+?)(ed|ing)$/;
92
    if (re.test(w)) {
93
      var fp = re.exec(w);
94
      re = new RegExp(mgr0);
95
      if (re.test(fp[1])) {
96
        re = /.$/;
97
        w = w.replace(re,"");
98
      }
99
    }
100
    else if (re2.test(w)) {
101
      var fp = re2.exec(w);
102
      stem = fp[1];
103
      re2 = new RegExp(s_v);
104
      if (re2.test(stem)) {
105
        w = stem;
106
        re2 = /(at|bl|iz)$/;
107
        re3 = new RegExp("([^aeiouylsz])\\1$");
108
        re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
109
        if (re2.test(w))
110
          w = w + "e";
111
        else if (re3.test(w)) {
112
          re = /.$/;
113
          w = w.replace(re,"");
114
        }
115
        else if (re4.test(w))
116
          w = w + "e";
117
      }
118
    }
119

120
    // Step 1c
121
    re = /^(.+?)y$/;
122
    if (re.test(w)) {
123
      var fp = re.exec(w);
124
      stem = fp[1];
125
      re = new RegExp(s_v);
126
      if (re.test(stem))
127
        w = stem + "i";
128
    }
129

130
    // Step 2
131
    re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
132
    if (re.test(w)) {
133
      var fp = re.exec(w);
134
      stem = fp[1];
135
      suffix = fp[2];
136
      re = new RegExp(mgr0);
137
      if (re.test(stem))
138
        w = stem + step2list[suffix];
139
    }
140

141
    // Step 3
142
    re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
143
    if (re.test(w)) {
144
      var fp = re.exec(w);
145
      stem = fp[1];
146
      suffix = fp[2];
147
      re = new RegExp(mgr0);
148
      if (re.test(stem))
149
        w = stem + step3list[suffix];
150
    }
151

152
    // Step 4
153
    re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
154
    re2 = /^(.+?)(s|t)(ion)$/;
155
    if (re.test(w)) {
156
      var fp = re.exec(w);
157
      stem = fp[1];
158
      re = new RegExp(mgr1);
159
      if (re.test(stem))
160
        w = stem;
161
    }
162
    else if (re2.test(w)) {
163
      var fp = re2.exec(w);
164
      stem = fp[1] + fp[2];
165
      re2 = new RegExp(mgr1);
166
      if (re2.test(stem))
167
        w = stem;
168
    }
169

170
    // Step 5
171
    re = /^(.+?)e$/;
172
    if (re.test(w)) {
173
      var fp = re.exec(w);
174
      stem = fp[1];
175
      re = new RegExp(mgr1);
176
      re2 = new RegExp(meq1);
177
      re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
178
      if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
179
        w = stem;
180
    }
181
    re = /ll$/;
182
    re2 = new RegExp(mgr1);
183
    if (re.test(w) && re2.test(w)) {
184
      re = /.$/;
185
      w = w.replace(re,"");
186
    }
187

188
    // and turn initial Y back to y
189
    if (firstch == "y")
190
      w = firstch.toLowerCase() + w.substr(1);
191
    return w;
192
  }
193
}
194

195

196

197
/**
198
 * Simple result scoring code.
199
 */
200
var Scorer = {
201
  // Implement the following function to further tweak the score for each result
202
  // The function takes a result array [filename, title, anchor, descr, score]
203
  // and returns the new score.
204
  /*
205
  score: function(result) {
206
    return result[4];
207
  },
208
  */
209

210
  // query matches the full name of an object
211
  objNameMatch: 11,
212
  // or matches in the last dotted part of the object name
213
  objPartialMatch: 6,
214
  // Additive scores depending on the priority of the object
215
  objPrio: {0:  15,   // used to be importantResults
216
            1:  5,   // used to be objectResults
217
            2: -5},  // used to be unimportantResults
218
  //  Used when the priority is not in the mapping.
219
  objPrioDefault: 0,
220

221
  // query found in title
222
  title: 15,
223
  // query found in terms
224
  term: 5
225
};
226

227

228
/**
229
 * Search Module
230
 */
231
var Search = {
232

233
  _index : null,
234
  _queued_query : null,
235
  _pulse_status : -1,
236

237
  init : function() {
238
      var params = $.getQueryParameters();
239
      if (params.q) {
240
          var query = params.q[0];
241
          $('input[name="q"]')[0].value = query;
242
          this.performSearch(query);
243
      }
244
  },
245

246
  loadIndex : function(url) {
247
    $.ajax({type: "GET", url: url, data: null,
248
            dataType: "script", cache: true,
249
            complete: function(jqxhr, textstatus) {
250
              if (textstatus != "success") {
251
                document.getElementById("searchindexloader").src = url;
252
              }
253
            }});
254
  },
255

256
  setIndex : function(index) {
257
    var q;
258
    this._index = index;
259
    if ((q = this._queued_query) !== null) {
260
      this._queued_query = null;
261
      Search.query(q);
262
    }
263
  },
264

265
  hasIndex : function() {
266
      return this._index !== null;
267
  },
268

269
  deferQuery : function(query) {
270
      this._queued_query = query;
271
  },
272

273
  stopPulse : function() {
274
      this._pulse_status = 0;
275
  },
276

277
  startPulse : function() {
278
    if (this._pulse_status >= 0)
279
        return;
280
    function pulse() {
281
      var i;
282
      Search._pulse_status = (Search._pulse_status + 1) % 4;
283
      var dotString = '';
284
      for (i = 0; i < Search._pulse_status; i++)
285
        dotString += '.';
286
      Search.dots.text(dotString);
287
      if (Search._pulse_status > -1)
288
        window.setTimeout(pulse, 500);
289
    }
290
    pulse();
291
  },
292

293
  /**
294
   * perform a search for something (or wait until index is loaded)
295
   */
296
  performSearch : function(query) {
297
    // create the required interface elements
298
    this.out = $('#search-results');
299
    this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
300
    this.dots = $('<span></span>').appendTo(this.title);
301
    this.status = $('<p style="display: none"></p>').appendTo(this.out);
302
    this.output = $('<ul class="search"/>').appendTo(this.out);
303

304
    $('#search-progress').text(_('Preparing search...'));
305
    this.startPulse();
306

307
    // index already loaded, the browser was quick!
308
    if (this.hasIndex())
309
      this.query(query);
310
    else
311
      this.deferQuery(query);
312
  },
313

314
  /**
315
   * execute search (requires search index to be loaded)
316
   */
317
  query : function(query) {
318
    var i;
319
    var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"];
320

321
    // stem the searchterms and add them to the correct list
322
    var stemmer = new Stemmer();
323
    var searchterms = [];
324
    var excluded = [];
325
    var hlterms = [];
326
    var tmp = query.split(/\s+/);
327
    var objectterms = [];
328
    for (i = 0; i < tmp.length; i++) {
329
      if (tmp[i] !== "") {
330
          objectterms.push(tmp[i].toLowerCase());
331
      }
332

333
      if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i].match(/^\d+$/) ||
334
          tmp[i] === "") {
335
        // skip this "word"
336
        continue;
337
      }
338
      // stem the word
339
      var word = stemmer.stemWord(tmp[i].toLowerCase());
340
      var toAppend;
341
      // select the correct list
342
      if (word[0] == '-') {
343
        toAppend = excluded;
344
        word = word.substr(1);
345
      }
346
      else {
347
        toAppend = searchterms;
348
        hlterms.push(tmp[i].toLowerCase());
349
      }
350
      // only add if not already in the list
351
      if (!$u.contains(toAppend, word))
352
        toAppend.push(word);
353
    }
354
    var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
355

356
    // console.debug('SEARCH: searching for:');
357
    // console.info('required: ', searchterms);
358
    // console.info('excluded: ', excluded);
359

360
    // prepare search
361
    var terms = this._index.terms;
362
    var titleterms = this._index.titleterms;
363

364
    // array of [filename, title, anchor, descr, score]
365
    var results = [];
366
    $('#search-progress').empty();
367

368
    // lookup as object
369
    for (i = 0; i < objectterms.length; i++) {
370
      var others = [].concat(objectterms.slice(0, i),
371
                             objectterms.slice(i+1, objectterms.length));
372
      results = results.concat(this.performObjectSearch(objectterms[i], others));
373
    }
374

375
    // lookup as search terms in fulltext
376
    results = results.concat(this.performTermsSearch(searchterms, excluded, terms, Scorer.term))
377
                     .concat(this.performTermsSearch(searchterms, excluded, titleterms, Scorer.title));
378

379
    // let the scorer override scores with a custom scoring function
380
    if (Scorer.score) {
381
      for (i = 0; i < results.length; i++)
382
        results[i][4] = Scorer.score(results[i]);
383
    }
384

385
    // now sort the results by score (in opposite order of appearance, since the
386
    // display function below uses pop() to retrieve items) and then
387
    // alphabetically
388
    results.sort(function(a, b) {
389
      var left = a[4];
390
      var right = b[4];
391
      if (left > right) {
392
        return 1;
393
      } else if (left < right) {
394
        return -1;
395
      } else {
396
        // same score: sort alphabetically
397
        left = a[1].toLowerCase();
398
        right = b[1].toLowerCase();
399
        return (left > right) ? -1 : ((left < right) ? 1 : 0);
400
      }
401
    });
402

403
    // for debugging
404
    //Search.lastresults = results.slice();  // a copy
405
    //console.info('search results:', Search.lastresults);
406

407
    // print the results
408
    var resultCount = results.length;
409
    function displayNextItem() {
410
      // results left, load the summary and display it
411
      if (results.length) {
412
        var item = results.pop();
413
        var listItem = $('<li style="display:none"></li>');
414
        if (DOCUMENTATION_OPTIONS.FILE_SUFFIX === '') {
415
          // dirhtml builder
416
          var dirname = item[0] + '/';
417
          if (dirname.match(/\/index\/$/)) {
418
            dirname = dirname.substring(0, dirname.length-6);
419
          } else if (dirname == 'index/') {
420
            dirname = '';
421
          }
422
          listItem.append($('<a/>').attr('href',
423
            DOCUMENTATION_OPTIONS.URL_ROOT + dirname +
424
            highlightstring + item[2]).html(item[1]));
425
        } else {
426
          // normal html builders
427
          listItem.append($('<a/>').attr('href',
428
            item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
429
            highlightstring + item[2]).html(item[1]));
430
        }
431
        if (item[3]) {
432
          listItem.append($('<span> (' + item[3] + ')</span>'));
433
          Search.output.append(listItem);
434
          listItem.slideDown(5, function() {
435
            displayNextItem();
436
          });
437
        } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
438
          $.ajax({url: DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' + item[0] + '.txt',
439
                  dataType: "text",
440
                  complete: function(jqxhr, textstatus) {
441
                    var data = jqxhr.responseText;
442
                    if (data !== '') {
443
                      listItem.append(Search.makeSearchSummary(data, searchterms, hlterms));
444
                    }
445
                    Search.output.append(listItem);
446
                    listItem.slideDown(5, function() {
447
                      displayNextItem();
448
                    });
449
                  }});
450
        } else {
451
          // no source available, just display title
452
          Search.output.append(listItem);
453
          listItem.slideDown(5, function() {
454
            displayNextItem();
455
          });
456
        }
457
      }
458
      // search finished, update title and status message
459
      else {
460
        Search.stopPulse();
461
        Search.title.text(_('Search Results'));
462
        if (!resultCount)
463
          Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
464
        else
465
            Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
466
        Search.status.fadeIn(500);
467
      }
468
    }
469
    displayNextItem();
470
  },
471

472
  /**
473
   * search for object names
474
   */
475
  performObjectSearch : function(object, otherterms) {
476
    var filenames = this._index.filenames;
477
    var objects = this._index.objects;
478
    var objnames = this._index.objnames;
479
    var titles = this._index.titles;
480

481
    var i;
482
    var results = [];
483

484
    for (var prefix in objects) {
485
      for (var name in objects[prefix]) {
486
        var fullname = (prefix ? prefix + '.' : '') + name;
487
        if (fullname.toLowerCase().indexOf(object) > -1) {
488
          var score = 0;
489
          var parts = fullname.split('.');
490
          // check for different match types: exact matches of full name or
491
          // "last name" (i.e. last dotted part)
492
          if (fullname == object || parts[parts.length - 1] == object) {
493
            score += Scorer.objNameMatch;
494
          // matches in last name
495
          } else if (parts[parts.length - 1].indexOf(object) > -1) {
496
            score += Scorer.objPartialMatch;
497
          }
498
          var match = objects[prefix][name];
499
          var objname = objnames[match[1]][2];
500
          var title = titles[match[0]];
501
          // If more than one term searched for, we require other words to be
502
          // found in the name/title/description
503
          if (otherterms.length > 0) {
504
            var haystack = (prefix + ' ' + name + ' ' +
505
                            objname + ' ' + title).toLowerCase();
506
            var allfound = true;
507
            for (i = 0; i < otherterms.length; i++) {
508
              if (haystack.indexOf(otherterms[i]) == -1) {
509
                allfound = false;
510
                break;
511
              }
512
            }
513
            if (!allfound) {
514
              continue;
515
            }
516
          }
517
          var descr = objname + _(', in ') + title;
518

519
          var anchor = match[3];
520
          if (anchor === '')
521
            anchor = fullname;
522
          else if (anchor == '-')
523
            anchor = objnames[match[1]][1] + '-' + fullname;
524
          // add custom score for some objects according to scorer
525
          if (Scorer.objPrio.hasOwnProperty(match[2])) {
526
            score += Scorer.objPrio[match[2]];
527
          } else {
528
            score += Scorer.objPrioDefault;
529
          }
530
          results.push([filenames[match[0]], fullname, '#'+anchor, descr, score]);
531
        }
532
      }
533
    }
534

535
    return results;
536
  },
537

538
  /**
539
   * search for full-text terms in the index
540
   */
541
  performTermsSearch : function(searchterms, excluded, terms, score) {
542
    var filenames = this._index.filenames;
543
    var titles = this._index.titles;
544

545
    var i, j, file, files;
546
    var fileMap = {};
547
    var results = [];
548

549
    // perform the search on the required terms
550
    for (i = 0; i < searchterms.length; i++) {
551
      var word = searchterms[i];
552
      // no match but word was a required one
553
      if ((files = terms[word]) === undefined)
554
        break;
555
      if (files.length === undefined) {
556
        files = [files];
557
      }
558
      // create the mapping
559
      for (j = 0; j < files.length; j++) {
560
        file = files[j];
561
        if (file in fileMap)
562
          fileMap[file].push(word);
563
        else
564
          fileMap[file] = [word];
565
      }
566
    }
567

568
    // now check if the files don't contain excluded terms
569
    for (file in fileMap) {
570
      var valid = true;
571

572
      // check if all requirements are matched
573
      if (fileMap[file].length != searchterms.length)
574
          continue;
575

576
      // ensure that none of the excluded terms is in the search result
577
      for (i = 0; i < excluded.length; i++) {
578
        if (terms[excluded[i]] == file ||
579
          $u.contains(terms[excluded[i]] || [], file)) {
580
          valid = false;
581
          break;
582
        }
583
      }
584

585
      // if we have still a valid result we can add it to the result list
586
      if (valid) {
587
        results.push([filenames[file], titles[file], '', null, score]);
588
      }
589
    }
590
    return results;
591
  },
592

593
  /**
594
   * helper function to return a node containing the
595
   * search summary for a given text. keywords is a list
596
   * of stemmed words, hlwords is the list of normal, unstemmed
597
   * words. the first one is used to find the occurance, the
598
   * latter for highlighting it.
599
   */
600
  makeSearchSummary : function(text, keywords, hlwords) {
601
    var textLower = text.toLowerCase();
602
    var start = 0;
603
    $.each(keywords, function() {
604
      var i = textLower.indexOf(this.toLowerCase());
605
      if (i > -1)
606
        start = i;
607
    });
608
    start = Math.max(start - 120, 0);
609
    var excerpt = ((start > 0) ? '...' : '') +
610
      $.trim(text.substr(start, 240)) +
611
      ((start + 240 - text.length) ? '...' : '');
612
    var rv = $('<div class="context"></div>').text(excerpt);
613
    $.each(hlwords, function() {
614
      rv = rv.highlightText(this, 'highlighted');
615
    });
616
    return rv;
617
  }
618
};
619

620
$(document).ready(function() {
621
  Search.init();
622
});
623