sphinx/_static/searchtools.js

   1 /*
   2  * searchtools.js
   3  * ~~~~~~~~~~~~~~~~
   4  *
   5  * Sphinx JavaScript utilities for the full-text search.
   6  *
   7  * :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
   8  * :license: BSD, see LICENSE for details.
   9  *
  10  */
  11
  12 if (!Scorer) {
  13   /**
  14    * Simple result scoring code.
  15    */
  16   var Scorer = {
  17     // Implement the following function to further tweak the score for each result
  18     // The function takes a result array [filename, title, anchor, descr, score]
  19     // and returns the new score.
  20     /*
  21     score: function(result) {
  22       return result[4];
  23     },
  24     */
  25
  26     // query matches the full name of an object
  27     objNameMatch: 11,
  28     // or matches in the last dotted part of the object name
  29     objPartialMatch: 6,
  30     // Additive scores depending on the priority of the object
  31     objPrio: {0:  15,   // used to be importantResults
  32               1:  5,   // used to be objectResults
  33               2: -5},  // used to be unimportantResults
  34     //  Used when the priority is not in the mapping.
  35     objPrioDefault: 0,
  36
  37     // query found in title
  38     title: 15,
  39     partialTitle: 7,
  40     // query found in terms
  41     term: 5,
  42     partialTerm: 2
  43   };
  44 }
  45
  46 if (!splitQuery) {
  47   function splitQuery(query) {
  48     return query.split(/\s+/);
  49   }
  50 }
  51
  52 /**
  53  * Search Module
  54  */
  55 var Search = {
  56
  57   _index : null,
  58   _queued_query : null,
  59   _pulse_status : -1,
  60
  61   htmlToText : function(htmlString) {
  62       var htmlElement = document.createElement('span');
  63       htmlElement.innerHTML = htmlString;
  64       $(htmlElement).find('.headerlink').remove();
  65       docContent = $(htmlElement).find('[role=main]')[0];
  66       return docContent.textContent || docContent.innerText;
  67   },
  68
  69   init : function() {
  70       var params = $.getQueryParameters();
  71       if (params.q) {
  72           var query = params.q[0];
  73           $('input[name="q"]')[0].value = query;
  74           this.performSearch(query);
  75       }
  76   },
  77
  78   loadIndex : function(url) {
  79     $.ajax({type: "GET", url: url, data: null,
  80             dataType: "script", cache: true,
  81             complete: function(jqxhr, textstatus) {
  82               if (textstatus != "success") {
  83                 document.getElementById("searchindexloader").src = url;
  84               }
  85             }});
  86   },
  87
  88   setIndex : function(index) {
  89     var q;
  90     this._index = index;
  91     if ((q = this._queued_query) !== null) {
  92       this._queued_query = null;
  93       Search.query(q);
  94     }
  95   },
  96
  97   hasIndex : function() {
  98       return this._index !== null;
  99   },
 100
 101   deferQuery : function(query) {
 102       this._queued_query = query;
 103   },
 104
 105   stopPulse : function() {
 106       this._pulse_status = 0;
 107   },
 108
 109   startPulse : function() {
 110     if (this._pulse_status >= 0)
 111         return;
 112     function pulse() {
 113       var i;
 114       Search._pulse_status = (Search._pulse_status + 1) % 4;
 115       var dotString = '';
 116       for (i = 0; i < Search._pulse_status; i++)
 117         dotString += '.';
 118       Search.dots.text(dotString);
 119       if (Search._pulse_status > -1)
 120         window.setTimeout(pulse, 500);
 121     }
 122     pulse();
 123   },
 124
 125   /**
 126    * perform a search for something (or wait until index is loaded)
 127    */
 128   performSearch : function(query) {
 129     // create the required interface elements
 130     this.out = $('#search-results');
 131     this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
 132     this.dots = $('<span></span>').appendTo(this.title);
 133     this.status = $('<p class="search-summary">&nbsp;</p>').appendTo(this.out);
 134     this.output = $('<ul class="search"/>').appendTo(this.out);
 135
 136     $('#search-progress').text(_('Preparing search...'));
 137     this.startPulse();
 138
 139     // index already loaded, the browser was quick!
 140     if (this.hasIndex())
 141       this.query(query);
 142     else
 143       this.deferQuery(query);
 144   },
 145
 146   /**
 147    * execute search (requires search index to be loaded)
 148    */
 149   query : function(query) {
 150     var i;
 151
 152     // stem the searchterms and add them to the correct list
 153     var stemmer = new Stemmer();
 154     var searchterms = [];
 155     var excluded = [];
 156     var hlterms = [];
 157     var tmp = splitQuery(query);
 158     var objectterms = [];
 159     for (i = 0; i < tmp.length; i++) {
 160       if (tmp[i] !== "") {
 161           objectterms.push(tmp[i].toLowerCase());
 162       }
 163
 164       if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i].match(/^\d+$/) ||
 165           tmp[i] === "") {
 166         // skip this "word"
 167         continue;
 168       }
 169       // stem the word
 170       var word = stemmer.stemWord(tmp[i].toLowerCase());
 171       // prevent stemmer from cutting word smaller than two chars
 172       if(word.length < 3 && tmp[i].length >= 3) {
 173         word = tmp[i];
 174       }
 175       var toAppend;
 176       // select the correct list
 177       if (word[0] == '-') {
 178         toAppend = excluded;
 179         word = word.substr(1);
 180       }
 181       else {
 182         toAppend = searchterms;
 183         hlterms.push(tmp[i].toLowerCase());
 184       }
 185       // only add if not already in the list
 186       if (!$u.contains(toAppend, word))
 187         toAppend.push(word);
 188     }
 189     var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
 190
 191     // console.debug('SEARCH: searching for:');
 192     // console.info('required: ', searchterms);
 193     // console.info('excluded: ', excluded);
 194
 195     // prepare search
 196     var terms = this._index.terms;
 197     var titleterms = this._index.titleterms;
 198
 199     // array of [filename, title, anchor, descr, score]
 200     var results = [];
 201     $('#search-progress').empty();
 202
 203     // lookup as object
 204     for (i = 0; i < objectterms.length; i++) {
 205       var others = [].concat(objectterms.slice(0, i),
 206                              objectterms.slice(i+1, objectterms.length));
 207       results = results.concat(this.performObjectSearch(objectterms[i], others));
 208     }
 209
 210     // lookup as search terms in fulltext
 211     results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms));
 212
 213     // let the scorer override scores with a custom scoring function
 214     if (Scorer.score) {
 215       for (i = 0; i < results.length; i++)
 216         results[i][4] = Scorer.score(results[i]);
 217     }
 218
 219     // now sort the results by score (in opposite order of appearance, since the
 220     // display function below uses pop() to retrieve items) and then
 221     // alphabetically
 222     results.sort(function(a, b) {
 223       var left = a[4];
 224       var right = b[4];
 225       if (left > right) {
 226         return 1;
 227       } else if (left < right) {
 228         return -1;
 229       } else {
 230         // same score: sort alphabetically
 231         left = a[1].toLowerCase();
 232         right = b[1].toLowerCase();
 233         return (left > right) ? -1 : ((left < right) ? 1 : 0);
 234       }
 235     });
 236
 237     // for debugging
 238     //Search.lastresults = results.slice();  // a copy
 239     //console.info('search results:', Search.lastresults);
 240
 241     // print the results
 242     var resultCount = results.length;
 243     function displayNextItem() {
 244       // results left, load the summary and display it
 245       if (results.length) {
 246         var item = results.pop();
 247         var listItem = $('<li style="display:none"></li>');
 248         if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') {
 249           // dirhtml builder
 250           var dirname = item[0] + '/';
 251           if (dirname.match(/\/index\/$/)) {
 252             dirname = dirname.substring(0, dirname.length-6);
 253           } else if (dirname == 'index/') {
 254             dirname = '';
 255           }
 256           listItem.append($('<a/>').attr('href',
 257             DOCUMENTATION_OPTIONS.URL_ROOT + dirname +
 258             highlightstring + item[2]).html(item[1]));
 259         } else {
 260           // normal html builders
 261           listItem.append($('<a/>').attr('href',
 262             item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
 263             highlightstring + item[2]).html(item[1]));
 264         }
 265         if (item[3]) {
 266           listItem.append($('<span> (' + item[3] + ')</span>'));
 267           Search.output.append(listItem);
 268           listItem.slideDown(5, function() {
 269             displayNextItem();
 270           });
 271         } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
 272           $.ajax({url: DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX,
 273                   dataType: "text",
 274                   complete: function(jqxhr, textstatus) {
 275                     var data = jqxhr.responseText;
 276                     if (data !== '' && data !== undefined) {
 277                       listItem.append(Search.makeSearchSummary(data, searchterms, hlterms));
 278                     }
 279                     Search.output.append(listItem);
 280                     listItem.slideDown(5, function() {
 281                       displayNextItem();
 282                     });
 283                   }});
 284         } else {
 285           // no source available, just display title
 286           Search.output.append(listItem);
 287           listItem.slideDown(5, function() {
 288             displayNextItem();
 289           });
 290         }
 291       }
 292       // search finished, update title and status message
 293       else {
 294         Search.stopPulse();
 295         Search.title.text(_('Search Results'));
 296         if (!resultCount)
 297           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.'));
 298         else
 299             Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
 300         Search.status.fadeIn(500);
 301       }
 302     }
 303     displayNextItem();
 304   },
 305
 306   /**
 307    * search for object names
 308    */
 309   performObjectSearch : function(object, otherterms) {
 310     var filenames = this._index.filenames;
 311     var docnames = this._index.docnames;
 312     var objects = this._index.objects;
 313     var objnames = this._index.objnames;
 314     var titles = this._index.titles;
 315
 316     var i;
 317     var results = [];
 318
 319     for (var prefix in objects) {
 320       for (var name in objects[prefix]) {
 321         var fullname = (prefix ? prefix + '.' : '') + name;
 322         var fullnameLower = fullname.toLowerCase()
 323         if (fullnameLower.indexOf(object) > -1) {
 324           var score = 0;
 325           var parts = fullnameLower.split('.');
 326           // check for different match types: exact matches of full name or
 327           // "last name" (i.e. last dotted part)
 328           if (fullnameLower == object || parts[parts.length - 1] == object) {
 329             score += Scorer.objNameMatch;
 330           // matches in last name
 331           } else if (parts[parts.length - 1].indexOf(object) > -1) {
 332             score += Scorer.objPartialMatch;
 333           }
 334           var match = objects[prefix][name];
 335           var objname = objnames[match[1]][2];
 336           var title = titles[match[0]];
 337           // If more than one term searched for, we require other words to be
 338           // found in the name/title/description
 339           if (otherterms.length > 0) {
 340             var haystack = (prefix + ' ' + name + ' ' +
 341                             objname + ' ' + title).toLowerCase();
 342             var allfound = true;
 343             for (i = 0; i < otherterms.length; i++) {
 344               if (haystack.indexOf(otherterms[i]) == -1) {
 345                 allfound = false;
 346                 break;
 347               }
 348             }
 349             if (!allfound) {
 350               continue;
 351             }
 352           }
 353           var descr = objname + _(', in ') + title;
 354
 355           var anchor = match[3];
 356           if (anchor === '')
 357             anchor = fullname;
 358           else if (anchor == '-')
 359             anchor = objnames[match[1]][1] + '-' + fullname;
 360           // add custom score for some objects according to scorer
 361           if (Scorer.objPrio.hasOwnProperty(match[2])) {
 362             score += Scorer.objPrio[match[2]];
 363           } else {
 364             score += Scorer.objPrioDefault;
 365           }
 366           results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]);
 367         }
 368       }
 369     }
 370
 371     return results;
 372   },
 373
 374   /**
 375    * search for full-text terms in the index
 376    */
 377   performTermsSearch : function(searchterms, excluded, terms, titleterms) {
 378     var docnames = this._index.docnames;
 379     var filenames = this._index.filenames;
 380     var titles = this._index.titles;
 381
 382     var i, j, file;
 383     var fileMap = {};
 384     var scoreMap = {};
 385     var results = [];
 386
 387     // perform the search on the required terms
 388     for (i = 0; i < searchterms.length; i++) {
 389       var word = searchterms[i];
 390       var files = [];
 391       var _o = [
 392         {files: terms[word], score: Scorer.term},
 393         {files: titleterms[word], score: Scorer.title}
 394       ];
 395       // add support for partial matches
 396       if (word.length > 2) {
 397         for (var w in terms) {
 398           if (w.match(word) && !terms[word]) {
 399             _o.push({files: terms[w], score: Scorer.partialTerm})
 400           }
 401         }
 402         for (var w in titleterms) {
 403           if (w.match(word) && !titleterms[word]) {
 404               _o.push({files: titleterms[w], score: Scorer.partialTitle})
 405           }
 406         }
 407       }
 408
 409       // no match but word was a required one
 410       if ($u.every(_o, function(o){return o.files === undefined;})) {
 411         break;
 412       }
 413       // found search word in contents
 414       $u.each(_o, function(o) {
 415         var _files = o.files;
 416         if (_files === undefined)
 417           return
 418
 419         if (_files.length === undefined)
 420           _files = [_files];
 421         files = files.concat(_files);
 422
 423         // set score for the word in each file to Scorer.term
 424         for (j = 0; j < _files.length; j++) {
 425           file = _files[j];
 426           if (!(file in scoreMap))
 427             scoreMap[file] = {};
 428           scoreMap[file][word] = o.score;
 429         }
 430       });
 431
 432       // create the mapping
 433       for (j = 0; j < files.length; j++) {
 434         file = files[j];
 435         if (file in fileMap && fileMap[file].indexOf(word) === -1)
 436           fileMap[file].push(word);
 437         else
 438           fileMap[file] = [word];
 439       }
 440     }
 441
 442     // now check if the files don't contain excluded terms
 443     for (file in fileMap) {
 444       var valid = true;
 445
 446       // check if all requirements are matched
 447       var filteredTermCount = // as search terms with length < 3 are discarded: ignore
 448         searchterms.filter(function(term){return term.length > 2}).length
 449       if (
 450         fileMap[file].length != searchterms.length &&
 451         fileMap[file].length != filteredTermCount
 452       ) continue;
 453
 454       // ensure that none of the excluded terms is in the search result
 455       for (i = 0; i < excluded.length; i++) {
 456         if (terms[excluded[i]] == file ||
 457             titleterms[excluded[i]] == file ||
 458             $u.contains(terms[excluded[i]] || [], file) ||
 459             $u.contains(titleterms[excluded[i]] || [], file)) {
 460           valid = false;
 461           break;
 462         }
 463       }
 464
 465       // if we have still a valid result we can add it to the result list
 466       if (valid) {
 467         // select one (max) score for the file.
 468         // for better ranking, we should calculate ranking by using words statistics like basic tf-idf...
 469         var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]}));
 470         results.push([docnames[file], titles[file], '', null, score, filenames[file]]);
 471       }
 472     }
 473     return results;
 474   },
 475
 476   /**
 477    * helper function to return a node containing the
 478    * search summary for a given text. keywords is a list
 479    * of stemmed words, hlwords is the list of normal, unstemmed
 480    * words. the first one is used to find the occurrence, the
 481    * latter for highlighting it.
 482    */
 483   makeSearchSummary : function(htmlText, keywords, hlwords) {
 484     var text = Search.htmlToText(htmlText);
 485     var textLower = text.toLowerCase();
 486     var start = 0;
 487     $.each(keywords, function() {
 488       var i = textLower.indexOf(this.toLowerCase());
 489       if (i > -1)
 490         start = i;
 491     });
 492     start = Math.max(start - 120, 0);
 493     var excerpt = ((start > 0) ? '...' : '') +
 494       $.trim(text.substr(start, 240)) +
 495       ((start + 240 - text.length) ? '...' : '');
 496     var rv = $('<div class="context"></div>').text(excerpt);
 497     $.each(hlwords, function() {
 498       rv = rv.highlightText(this, 'highlighted');
 499     });
 500     return rv;
 501   }
 502 };
 503
 504 $(document).ready(function() {
 505   Search.init();
 506 });