1/*  Part of SWI-Prolog
   2
   3    Author:        Jan Wielemaker
   4    E-mail:        J.Wielemaker@vu.nl
   5    WWW:           http://www.swi-prolog.org
   6    Copyright (c)  2006-2015, University of Amsterdam
   7    All rights reserved.
   8
   9    Redistribution and use in source and binary forms, with or without
  10    modification, are permitted provided that the following conditions
  11    are met:
  12
  13    1. Redistributions of source code must retain the above copyright
  14       notice, this list of conditions and the following disclaimer.
  15
  16    2. Redistributions in binary form must reproduce the above copyright
  17       notice, this list of conditions and the following disclaimer in
  18       the documentation and/or other materials provided with the
  19       distribution.
  20
  21    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  24    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  25    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  26    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  27    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  28    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  29    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  31    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  32    POSSIBILITY OF SUCH DAMAGE.
  33*/
  34
  35:- module(pldoc_search,
  36          [ search_form//1,             % +Options, //
  37            search_reply//2,            % +Search, +Options, //
  38            matching_object_table//2    % +Objects, +Options, //
  39          ]).
  40:- use_module(library(http/html_write)).
  41:- use_module(library(http/html_head)).
  42:- use_module(library(dcg/basics)).
  43:- use_module(library(occurs)).
  44:- use_module(library(option)).
  45:- use_module(library(pairs)).
  46:- use_module(doc_process).
  47:- use_module(doc_html).
  48:- use_module(doc_index).
  49:- use_module(doc_util).
  50:- include(hooks).
  51
  52/** <module> Search form and reply
  53
  54@tbd    Advanced search field
  55
  56                * Limit to a directory
  57                * Whole-word search
  58*/
  59
  60:- predicate_options(search_form//1, 1,
  61                     [ for(atom),
  62                       search_in(oneof([all,noapp,app,man])),
  63                       search_match(oneof([name,summary])),
  64                       search_options(boolean)
  65                     ]).
  66:- predicate_options(search_reply//2, 2,
  67                     [ resultFormat(oneof([summary,long])),
  68                       search_in(oneof([all,noapp,app,man])),
  69                       search_match(oneof([name,summary])),
  70                       header(boolean),
  71                       edit(boolean),
  72                       pass_to(pldoc_index:doc_links//2, 2)
  73                     ]).
  74
  75%!  search_form(+Options)//
  76%
  77%   Create  a  search  input  field.  The   input  field  points  to
  78%   =|/search?for=String|= on the current server.  Options:
  79%
  80%           * title(Title)
  81
  82search_form(Options) -->
  83    { (   option(for(Value), Options)
  84      ->  Extra = [value(Value)]
  85      ;   Extra = []
  86      ),
  87      option(search_in(In), Options, all),
  88      option(search_match(Match), Options, summary)
  89    },
  90    html(form([ id('search-form'),
  91                action(location_by_id(pldoc_search))
  92              ],
  93              [ div([ \search_field([ name(for),
  94                                      id(for)
  95                                    | Extra
  96                                    ])
  97                    ]),
  98                \search_options(In, Match, Options)
  99              ])).
 100
 101search_options(In, Match, Options) -->
 102    { option(search_options(false), Options) },
 103    !,
 104    hidden(in, In),
 105    hidden(match, Match).
 106search_options(In, Match, _Options) -->
 107    html(div(class('search-options'),
 108             [ span(class('search-in'),
 109                    [ \radio(in, all, 'All', In),
 110                      \radio(in, app, 'Application', In),
 111                      \radio(in, man, 'Manual', In)
 112                    ]),
 113               span(class('search-match'),
 114                    [ \radio(match, name, 'Name', Match),
 115                      \radio(match, summary, 'Summary', Match)
 116                    ]),
 117               span(class('search-help'),
 118                    [ a(href(location_by_id(pldoc_package)+'pldoc.html#sec:browser'),
 119                        'Help')
 120                    ])
 121             ])).
 122
 123
 124%!  search_field(+Options)// is det.
 125%
 126%   Hookable predicate to display the   search field. Hookability is
 127%   provided  to  experiment  with    auto-completion  outside  this
 128%   package.
 129
 130search_field(Options) -->
 131    prolog:doc_search_field(Options),
 132    !.
 133search_field(Options) -->
 134    html([ input(Options, []),
 135           input([ id('submit-for'),
 136                   type(submit),
 137                   value('Search')
 138                 ])
 139         ]).
 140
 141radio(Radio, Field, Label, In) -->
 142    {   Field == In
 143    ->  Extra = [checked]
 144    ;   Extra = []
 145    },
 146    html([ input([ type(radio),
 147                   name(Radio),
 148                   value(Field)
 149                 | Extra
 150                 ]),
 151           Label
 152         ]).
 153
 154hidden(Name, Value) -->
 155    html(input([type(hidden), name(Name), value(Value)])).
 156
 157%!  search_reply(+For, +Options)// is det.
 158%
 159%   Generate a reply searching for For.  Options include
 160%
 161%           * resultFormat(Format)
 162%           If =summary= (default), produce a summary-table.  If
 163%           =long=, produce full object descriptions.
 164%
 165%           * search_in(In)
 166%           Determine which databases to search.  One of
 167%           =all=, =app=, =man=
 168%
 169%           * search_match(Match)
 170%           What part of the object to match. One of =name=,
 171%           =summary=
 172%
 173%           * header(+Boolean)
 174%           If =false=, suppress the header.
 175
 176:- html_meta
 177    search_header(+, html, +, ?, ?).
 178
 179search_reply(For, Options) -->
 180    { var(For) ; For == '' },
 181    !,
 182    search_header('', 'Using PlDoc search', Options),
 183    html([ ul( class('search-help'),
 184               [ li([ 'If you pause typing, the search box will display ',
 185                      'an auto completion list.  Selecting an object jumps ',
 186                      'immediately to the corresponding documentation.'
 187                    ]),
 188                 li([ 'Searching for ', i('Name/Arity'), ', ',
 189                      i('Name//Arity'), ', ', i('Name'), ' or ',
 190                      i('C-function()'), ' ensures that ',
 191                      'matching definitions appear first in the search ',
 192                      'results'
 193                    ]),
 194                 li([ 'Other searches search through the name and summary ',
 195                      'descriptions in the manual.'
 196                    ])
 197               ])
 198         ]).
 199search_reply(For, Options) -->
 200    { search_doc(For, PerCategory, Options),
 201      PerCategory \== [],
 202      option(resultFormat(Format), Options, summary)
 203    },
 204    !,
 205    search_header(For, [ 'Search results for ',
 206                         span(class(for), ['"', For, '"'])
 207                       ],
 208                  Options),
 209    indexed_matches(Format, PerCategory, Options).
 210search_reply(For, Options) -->
 211    search_header(For, 'No matches', Options).
 212
 213
 214search_header(_For, _Title, Options) -->
 215    { option(header(false), Options) },
 216    !,
 217    html_requires(pldoc).
 218search_header(For, Title, Options) -->
 219    html_requires(pldoc),
 220    doc_links('', [for(For)|Options]),
 221    html(h1(class('search-results'), Title)).
 222
 223%!  matching_object_table(+Objects, +Options)// is det.
 224%
 225%   Show a list of matching objects,   similar  to a result-set from
 226%   search.
 227
 228matching_object_table(Objects, Options) -->
 229    { maplist(obj_cat_sec, Objects, Pairs),
 230      group_hits(Pairs, Organized),
 231      option(format(Format), Options, summary)
 232    },
 233    indexed_matches(Format, Organized, Options).
 234
 235obj_cat_sec(Object, Cat-(Section-Object)) :-
 236    prolog:doc_object_summary(Object, Cat, Section, _Summary).
 237
 238
 239indexed_matches(Format, PerCategory, Options) -->
 240    { count_matches(PerCategory, Matches)
 241    },
 242    html([ div(class('search-counts'),
 243               [ Matches, ' matches; ',
 244                 \count_by_category(PerCategory)
 245               ])
 246         | \matches(Format, PerCategory, Options)
 247         ]).
 248
 249count_by_category([]) -->
 250    [].
 251count_by_category([Cat-PerFile|T]) -->
 252    { count_category(PerFile, Count),
 253      atom_concat(#, Cat, HREF)
 254    },
 255    html([ a(href(HREF), \category_title(Cat)),
 256           ': ',
 257           Count
 258         ]),
 259    (   {T == []}
 260    ->  []
 261    ;   html(', '),
 262        count_by_category(T)
 263    ).
 264
 265count_matches([], 0).
 266count_matches([_-Cat|T], Count) :-
 267    count_matches(T, Count0),
 268    count_category(Cat, N),
 269    Count is Count0 + N.
 270
 271count_category([], 0).
 272count_category([_-Objs|T], Count) :-
 273    count_category(T, Count0),
 274    length(Objs, N),
 275    Count is Count0 + N.
 276
 277%!  matches(+Format, +PerCategory, +Options)// is det
 278%
 279%   Display search matches according to Format.
 280%
 281%   @param PerCategory List of File-Objects
 282
 283matches(long, PerCategory, Options) -->
 284    long_matches_by_type(PerCategory, Options).
 285matches(summary, PerCategory, Options) -->
 286    html(table(class(summary),
 287               \short_matches_by_type(PerCategory, 1, Options))).
 288
 289
 290long_matches_by_type([], _) -->
 291    [].
 292long_matches_by_type([Category-PerFile|T], Options) -->
 293    category_header(Category, Options),
 294    long_matches(PerFile, Options),
 295    long_matches_by_type(T, Options).
 296
 297
 298long_matches([], _) -->
 299    [].
 300long_matches([File-Objs|T], Options) -->
 301    file_header(File, Options),
 302    objects(Objs, Options),
 303    long_matches(T, Options).
 304
 305category_header(Category, _Options) -->
 306    html(h1(class(category), \category_title(Category))).
 307
 308short_matches_by_type([], _, _) -->
 309    [].
 310short_matches_by_type([Category-PerFile|T], Nth, Options) -->
 311    category_index_header(Category, Nth, Options),
 312    short_matches(PerFile, Options),
 313    { succ(Nth, Nth1) },
 314    short_matches_by_type(T, Nth1, Options).
 315
 316short_matches([], _) -->
 317    [].
 318short_matches([File-Objs|T], Options) -->
 319    file_index_header(File, Options),
 320    object_summaries(Objs, File, Options),
 321    short_matches(T, Options).
 322
 323
 324category_index_header(Category, Nth, _Options) -->
 325    (   { Nth > 1 }
 326    ->  category_sep('category-top-sep')
 327    ;   []
 328    ),
 329    html(tr(th([class(category), colspan(3)],
 330               a(name(Category), \category_title(Category))))),
 331    category_sep('category-bottom-sep').
 332
 333category_sep(Which) -->
 334    html(tr(th([class(Which), colspan(3)],
 335               &(nbsp)))).
 336
 337
 338category_title(Category) -->
 339    {   prolog:doc_category(Category, _Order, Title)
 340    ->  true
 341    ;   Title = Category
 342    },
 343    html(Title).
 344
 345%!  search_doc(+SearchString, -PerType:list, +Options) is det.
 346%
 347%   Return matches of SearchString  as   Type-PerFile  tuples, where
 348%   PerFile is a list File-ListOfObjects.
 349
 350search_doc(Search, PerType, Options) :-
 351    findall(Tuples, matching_object(Search, Tuples, Options), Tuples0),
 352    sort(Tuples0, Tuples),
 353    group_hits(Tuples, PerType).
 354
 355group_hits(Tuples, PerType) :-
 356    group_pairs_by_key(Tuples, PerCat0),
 357    key_sort_order(PerCat0, PerCat1),
 358    keysort(PerCat1, PerCat2),
 359    pairs_values(PerCat2, PerCat),
 360    group_by_file(PerCat, PerType).
 361
 362key_sort_order([], []).
 363key_sort_order([Cat-ByCat|T0], [Order-(Cat-ByCat)|T]) :-
 364    (   prolog:doc_category(Cat, Order, _Title)
 365    ->  true
 366    ;   Order = 99
 367    ),
 368    key_sort_order(T0, T).
 369
 370
 371group_by_file([], []).
 372group_by_file([Type-Tuples0|T0], [Type-ByFile|T]) :-
 373    keysort(Tuples0, Tuples),
 374    group_pairs_by_key(Tuples, ByFile),
 375    group_by_file(T0, T).
 376
 377
 378%!  matching_object(+SearchString, -Object, +Options) is nondet.
 379%
 380%   Object matches SearchString.  Options include
 381%
 382%           * search_in(In)
 383%           One of =all=, =app=, =man=.
 384%
 385%           * search_match(Match)
 386%           One of =name=, =summary=
 387%
 388%   @param Object   Term of the form File-Item
 389%   @tbd Deal with search syntax
 390
 391matching_object(Search, Type-(Section-Obj), Options) :-
 392    atom_concat(Function, '()', Search),
 393    Obj = c(Function),
 394    option(search_in(In), Options, all),
 395    prolog:doc_object_summary(Obj, Type, Section, _),
 396    matching_category(In, Type).
 397matching_object(Search, Type-(Section-Obj), Options) :-
 398    (   atom_pi(Search, Obj0),
 399        qualify(Obj0, Obj)
 400    ;   catch(atom_to_term(Search, Obj, _), _, fail)
 401    ),
 402    nonvar(Obj),
 403    option(search_in(In), Options, all),
 404    prolog:doc_object_summary(Obj, Type, Section, _),
 405    matching_category(In, Type).
 406matching_object(Search, Match, Options) :-
 407    atom_length(Search, Len), Len > 1,
 408    atom_codes(Search, Codes),
 409    phrase(search_spec(For0), Codes),
 410    (   For0 = not(_)
 411    ->  throw(error(bad_search(only_not), _))
 412    ;   optimise_search(For0, For),
 413        exec_search(For, Match, Options)
 414    ).
 415
 416qualify(Obj0, Obj) :-
 417    Obj0 = _:_,
 418    !,
 419    Obj = Obj0.
 420qualify(Obj, _:Obj).
 421
 422
 423%!  optimise_search(+Spec, -Optimised)
 424%
 425%   Optimise a search specification. Currently   only deals with the
 426%   simple case of  first  searching  for   a  negation  and  then a
 427%   positive term.
 428
 429optimise_search(and(not(A0), B0), and(B, not(A))) :-
 430    !,
 431    optimise_search(A0, A),
 432    optimise_search(B0, B).
 433optimise_search(A, A).
 434
 435
 436%!  exec_search(+Spec, -Match, +Options) is nondet.
 437%
 438%   Spec is one of
 439%
 440%           * and(Spec, Spec)
 441%           Intersection of the specification
 442%
 443%           * not(Spec)
 444%           Negation of the specification
 445
 446exec_search(and(A, B), Match, Options) :-
 447    !,
 448    exec_search(A, Match, Options),
 449    exec_search(B, Match, Options).
 450exec_search(Search, Type-(Section-Obj), Options) :-
 451    option(search_in(In), Options, all),
 452    option(search_match(Match), Options, summary),
 453    prolog:doc_object_summary(Obj, Type, Section, Summary),
 454    matching_category(In, Type),
 455    (   Search = not(For)
 456    ->  \+ (   Match == summary,
 457               apropos_match(For, Summary)
 458           ->  true
 459           ;   sub_term(S, Obj),
 460               atom(S),
 461               apropos_match(For, S)
 462           )
 463    ;   (   Match == summary,
 464            apropos_match(Search, Summary)
 465        ->  true
 466        ;   sub_term(S, Obj),
 467            atom(S),
 468            apropos_match(Search, S)
 469        )
 470    ).
 471
 472
 473matching_category(all, _).
 474matching_category(noapp, Category) :-
 475    !,
 476    Category \== application.
 477matching_category(app, application).
 478matching_category(man, manual).
 479
 480%!  search_spec(-Search)// is det.
 481%
 482%   Break a search string from the user into a logical expression.
 483
 484search_spec(Spec) -->
 485    blanks,
 486    prim_search_spec(A),
 487    blanks,
 488    (   eos
 489    ->  { Spec = A }
 490    ;   search_spec(B)
 491    ->  { Spec = and(A,B) }
 492    ).
 493
 494prim_search_spec(Quoted) -->
 495    "\"", string(Codes), "\"",
 496    !,
 497    { atom_codes(Quoted, Codes)
 498    }.
 499prim_search_spec(Spec) -->
 500    nonblanks(Codes),
 501    {   Codes = [0'-,C0|Rest],
 502        code_type(C0, csym)
 503    ->  atom_codes(Word, [C0|Rest]),
 504        Spec = not(Word)
 505    ;   Codes \== [],
 506        atom_codes(Spec, Codes)
 507    }.
 508
 509
 510%!  object_summary(?Object, ?Category, ?Section, ?Summary) is nondet.
 511%
 512%   True  if  Object  is  summarised   by  Summary.  This  multifile
 513%   predicate can be extended  with   other  search  mechanisms. The
 514%   returned objects must be  handled   by  object_summaries//2  and
 515%   objects//2.
 516%
 517%   @param Category Atom describing the source.
 518%   @param Section  Reference to the context of Object.
 519
 520prolog:doc_object_summary(Obj, Category, File, Summary) :-
 521    once(prolog_object(Obj)),
 522    current_prolog_flag(home, SWI),
 523    doc_comment(Obj0, File:_Line, Summary, _Comment),
 524    (   is_list(Obj0)
 525    ->  member(Obj, Obj0)
 526    ;   Obj = Obj0
 527    ),
 528    Obj \= _:module(_Title),                % HACK.  See ref_object//1
 529    (   sub_atom(File, 0, _, _, SWI)
 530    ->  Category = library
 531    ;   Category = application
 532    ).
 533
 534prolog_object(Var) :- var(Var), !.
 535prolog_object(_/_).
 536prolog_object(_//_).
 537prolog_object(_:_/_).
 538prolog_object(_:_//_).
 539prolog_object(module(_)).
 540
 541
 542%!  doc_category(Name, SortOrder, Description) is nondet.
 543%
 544%   Describe the various  categories  of   search  results.  Used to
 545%   create the category headers  as  well   as  the  advanced search
 546%   dialog.
 547%
 548%   @param SortOrder        Ranges 0..100.  Lower values come first
 549
 550prolog:doc_category(application, 20, 'Application').
 551prolog:doc_category(library,     80, 'System Libraries').
 552
 553
 554                 /*******************************
 555                 *             UTIL             *
 556                 *******************************/
 557
 558%!  apropos_match(+Needle, +Haystick) is semidet.
 559%
 560%   True if Needle can be found   as a case-insensitive substring in
 561%   Haystick.
 562
 563apropos_match(Needle, Haystack) :-
 564    sub_atom_icasechk(Haystack, _, Needle).