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-2019, University of Amsterdam
    7                              VU University Amsterdam
    8                              CWI, Amsterdam
    9    All rights reserved.
   10
   11    Redistribution and use in source and binary forms, with or without
   12    modification, are permitted provided that the following conditions
   13    are met:
   14
   15    1. Redistributions of source code must retain the above copyright
   16       notice, this list of conditions and the following disclaimer.
   17
   18    2. Redistributions in binary form must reproduce the above copyright
   19       notice, this list of conditions and the following disclaimer in
   20       the documentation and/or other materials provided with the
   21       distribution.
   22
   23    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   24    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   25    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   26    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   27    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   28    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   29    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   30    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   31    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   32    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   33    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   34    POSSIBILITY OF SUCH DAMAGE.
   35*/
   36
   37:- module(pldoc_wiki,
   38          [ wiki_codes_to_dom/3,        % +Codes, +Args, -DOM
   39            wiki_lines_to_dom/3,        % +Lines, +Map, -DOM
   40            section_comment_header/3,   % +Lines, -Header, -RestLines
   41            summary_from_lines/2,       % +Lines, -Codes
   42            indented_lines/3,           % +Text, +PrefixChars, -Lines
   43            strip_leading_par/2,        % +DOM0, -DOM
   44            autolink_extension/2,       % ?Extension, ?Type
   45            autolink_file/2             % +FileName, -Type
   46          ]).   47:- use_module(library(lists)).   48:- use_module(library(debug)).   49:- use_module(library(error)).   50:- use_module(library(pairs)).   51:- use_module(library(option)).   52:- use_module(library(debug)).   53:- use_module(library(apply)).   54:- use_module(library(dcg/basics)).   55
   56:- use_module(doc_util).

   70:- multifile
   71    prolog:doc_wiki_face//2,        % -Out, +VarNames
   72    prolog:doc_url_expansion/3,     % +Alias(Rest), -HREF, -Label
   73    prolog:url_expansion_hook/3,    % +Term, -Ref, -Label
   74    prolog:doc_autolink_extension/2.% +Extension, -Type
   75
   76
   77                 /*******************************
   78                 *          WIKI PARSING        *
   79                 *******************************/

 wiki_lines_to_dom(+Lines:lines, +Args:list(atom), -Term) is det

Translate a Wiki text into an HTML term suitable for html//1 from the html_write library.

   86wiki_lines_to_dom(Lines, Args, HTML) :-
   87    tokenize_lines(Lines, Tokens0),
   88    normalise_indentation(Tokens0, Tokens),
   89    wiki_structure(Tokens, -1, Pars),
   90    wiki_faces(Pars, Args, HTML).

 wiki_codes_to_dom(+String, +Args, -DOM) is det

Translate a plain text into a DOM term.

Arguments:

String

- Plain text. Either a string or a list of codes.

   99wiki_codes_to_dom(Codes, Args, DOM) :-
  100    indented_lines(Codes, [], Lines),
  101    wiki_lines_to_dom(Lines, Args, DOM).

 wiki_structure(+Lines:lines, +BaseIndent, -Blocks:list(block)) is det

Get the structure in terms of block-level elements: paragraphs, lists and tables. This processing uses a mixture of layout and punctuation.

  111wiki_structure([], _, []) :- !.
  112wiki_structure([_-[]|T], BI, Pars) :-          % empty lines
  113    !,
  114    wiki_structure(T, BI, Pars).
  115wiki_structure(Lines, _, [\tags(Tags)]) :-
  116    tags(Lines, Tags),
  117    !.
  118wiki_structure(Lines, BI, [P1|PL]) :-
  119    take_block(Lines, BI, P1, RestLines),
  120    wiki_structure(RestLines, BI, PL).

 take_block(+Lines, +BaseIndent, ?Block, -RestLines) is semidet

Take a block-structure from the input. Defined block elements are lists, table, hrule, section header and paragraph.

  127take_block([_-[]|Lines], BaseIndent, Block, Rest) :-
  128    !,
  129    take_block(Lines, BaseIndent, Block, Rest).
  130take_block([N-_|_], BaseIndent, _, _) :-
  131    N < BaseIndent,
  132    !,
  133    fail.                           % less indented
  134take_block(Lines, BaseIndent, List, Rest) :-
  135    list_item(Lines, Type, Indent, LI, LIT, Rest0),
  136    !,
  137    Indent > BaseIndent,
  138    rest_list(Rest0, Type, Indent, LIT, [], Rest),
  139    List0 =.. [Type, LI],
  140    (   ul_to_dl(List0, List)
  141    ->  true
  142    ;   List0 = dl(Items)
  143    ->  List = dl(class=wiki, Items)
  144    ;   List = List0
  145    ).
  146take_block([N-['|'|RL1]|LT], _, Table, Rest) :-
  147    phrase(row(R0), RL1),
  148    take_table(LT, N, R0, Table, Rest),
  149    !.
  150take_block([0-[-,-|More]|LT], _, Block, LT) :-  % separation line
  151    maplist(=(-), More),
  152    !,
  153    Block = hr([]).
  154take_block([_-Line|LT], _, Block, LT) :-        % separation line
  155    ruler(Line),
  156    !,
  157    Block = hr([]).
  158take_block([_-[@|_]], _, _, _) :-              % starts @tags section
  159    !,
  160    fail.
  161take_block(Lines, _BaseIndent, Section, RestLines) :-
  162    section_header(Lines, Section, RestLines),
  163    !.
  164take_block([_-Verb|Lines], _, Verb, Lines) :-
  165    verbatim_term(Verb),
  166    !.
  167take_block([I-L1|LT], BaseIndent, Elem, Rest) :-
  168    !,
  169    append(L1, PT, Par),
  170    rest_par(LT, PT, I, BaseIndent, MaxI, Rest),
  171    (   MaxI >= BaseIndent+16
  172    ->  Elem = center(Par)
  173    ;   phrase(blockquote(BQ), Par)
  174    ->  Elem = blockquote(BQ)
  175    ;   Elem = p(Par)
  176    ).
  177take_block([Verb|Lines], _, Verb, Lines).
  178
  179blockquote(Clean) -->
  180    [>, ' '],
  181    bq_lines(Clean).
  182
  183bq_lines([' '|Par]) -->
  184    ['\n'], !, [>,' '],
  185    bq_lines(Par).
  186bq_lines([H|T]) -->
  187    [H],
  188    bq_lines(T).
  189bq_lines([]) -->
  190    [].

 ruler(+Line) is semidet

True if Line contains 3 ruler chars and otherwise spaces.

  197ruler([C0|Line]) :-
  198    rule_char(C0),
  199    phrase(ruler(C0, 1), Line).
  200
  201ruler(C, N) --> [C], !, { N2 is N+1 }, ruler(C, N2).
  202ruler(C, N) --> [' '], !, ruler(C, N).
  203ruler(_, N) --> { N >= 3 }.
  204
  205rule_char('-').
  206rule_char('_').
  207rule_char('*').

 list_item(+Lines, ?Type, ?Indent, -LI0, -LIT, -RestLines) is det

Create a list-item. Naturally this should produce a single item, but DL lists produce two items, so we create the list of items as a difference list.

To be done

- Pass base-indent

  217list_item([Indent-Line|LT], Type, Indent, Items, ItemT, Rest) :-
  218    !,
  219    list_item_prefix(Type, Line, L1),
  220    (   Type == dl
  221    ->  split_dt(L1, DT0, DD1),
  222        append(DD1, LIT, DD),
  223        strip_ws_tokens(DT0, DT),
  224        Items = [dt(DT),dd(DD)|ItemT]
  225    ;   append(L1, LIT, LI0),
  226        Items = [li(LI0)|ItemT]
  227    ),
  228    rest_list_item(LT, Type, Indent, LIT, Rest).

 rest_list_item(+Lines, +Type, +Indent, -RestItem, -RestLines) is det

Extract the remainder (after the first line) of a list item.

  234rest_list_item(Lines, _Type, Indent, RestItem, RestLines) :-
  235    take_blocks_at_indent(Lines, Indent, Blocks, RestLines),
  236    (   Blocks = [p(Par)|MoreBlocks]
  237    ->  append(['\n'|Par], MoreBlocks, RestItem)
  238    ;   RestItem = Blocks
  239    ).

 take_blocks_at_indent(+Lines, +Indent, -Pars, -RestLines) is det

Process paragraphs and verbatim blocks (==..==) in bullet-lists.

  245take_blocks_at_indent(Lines, _, [], Lines) :-
  246    skip_empty_lines(Lines, Lines1),
  247    section_header(Lines1, _, _),
  248    !.
  249take_blocks_at_indent(Lines, N, [Block|RestBlocks], RestLines) :-
  250    take_block(Lines, N, Block, Rest0),
  251    !,
  252    take_blocks_at_indent(Rest0, N, RestBlocks, RestLines).
  253take_blocks_at_indent(Lines, _, [], Lines).

 rest_list(+Lines, +Type, +Indent, -Items, -ItemTail, -RestLines) is det

  259rest_list(Lines, Type, N, Items, IT, Rest) :-
  260    skip_empty_lines(Lines, Lines1),
  261    list_item(Lines1, Type, N, Items, IT0, Rest0),
  262    !,
  263    rest_list(Rest0, Type, N, IT0, IT, Rest).
  264rest_list(Rest, _, _, IT, IT, Rest).

 list_item_prefix(?Type, +Line, -Rest) is det

  268list_item_prefix(ul, [*, ' '|T], T) :- !.
  269list_item_prefix(ul, [-, ' '|T], T) :- !.
  270list_item_prefix(dl, [$, ' '|T], T) :-
  271    split_dt(T, _, _),
  272    !.
  273list_item_prefix(ol, [w(N), '.', ' '|T], T) :-
  274    atom_codes(N, [D]),
  275    between(0'0, 0'9, D).

 split_dt(+LineAfterDollar, -DT, -Rest)

First see whether the entire line is the item. This allows creating items holding : by using $ <tokens> :\n

  282split_dt(In, DT, []) :-
  283    append(DT, [':'], In),
  284    !.
  285split_dt(In, DT, Rest) :-
  286    append(DT, [':'|Rest0], In),
  287    (   Rest0 == []
  288    ->  Rest = []
  289    ;   Rest0 = [' '|Rest]
  290    ),
  291    !.

 ul_to_dl(+UL, -DL) is semidet

Translate an UL list into a DL list if all entries are of the form "* <term> nl, <description>" and at least one <description> is non-empty, or all items are of the form [[PredicateIndicator]].

  301ul_to_dl(ul(Items), Description) :-
  302    term_items(Items, DLItems, []),
  303    (   terms_to_predicate_includes(DLItems, Preds)
  304    ->  Description = dl(class(predicates), Preds)
  305    ;   member(dd(DD), DLItems), DD \== []
  306    ->  Description = dl(class(termlist), DLItems)
  307    ).
  308
  309term_items([], T, T).
  310term_items([LI|LIs], DLItems, Tail) :-
  311    term_item(LI, DLItems, Tail1),
  312    term_items(LIs, Tail1, Tail).

 term_item(+LI, -DLItem, ?Tail) is semidet

If LI is of the form <Term> followed by a newline, return it as dt-dd tuple. The <dt> item contains a term

\term(Text, Term, Bindings).

  321term_item(li(Tokens),
  322          [ dt(class=term, \term(Text, Term, Bindings)),
  323            dd(Descr)
  324          | Tail
  325          ], Tail) :-
  326    (   (   append(TermTokens, ['\n'|Descr], Tokens)
  327        ->  true
  328        ;   TermTokens = Tokens,
  329            Descr = []
  330        )
  331    ->  with_output_to(string(Tmp),
  332                       ( forall(member(T, TermTokens),
  333                                write_token(T)),
  334                         write(' .\n'))),
  335        E = error(_,_),
  336        catch(setup_call_cleanup(
  337                  open_string(Tmp, In),
  338                  ( read_dt_term(In, Term, Bindings),
  339                    read_dt_term(In, end_of_file, []),
  340                    atom_string(Text, Tmp)
  341                  ),
  342                  close(In)),
  343              E, fail)
  344    ).
  345
  346write_token(w(X)) :-
  347    !,
  348    write(X).
  349write_token(X) :-
  350    write(X).
  351
  352read_dt_term(In, Term, Bindings) :-
  353    read_term(In, Term,
  354              [ variable_names(Bindings),
  355                module(pldoc_modes)
  356              ]).
  357
  358terms_to_predicate_includes([], []).
  359terms_to_predicate_includes([dt(class=term, \term(_, [[PI]], [])), dd([])|T0],
  360                            [\include(PI, predicate, [])|T]) :-
  361    is_pi(PI),
  362    terms_to_predicate_includes(T0, T).
  363
  364is_pi(Name/Arity) :-
  365    atom(Name),
  366    integer(Arity),
  367    between(0, 20, Arity).
  368is_pi(Name//Arity) :-
  369    atom(Name),
  370    integer(Arity),
  371    between(0, 20, Arity).

 row(-Cells)// is det

  376row([C0|CL]) -->
  377    cell(C0),
  378    !,
  379    row(CL).
  380row([]) -->
  381    [].
  382
  383cell(td(C)) -->
  384    face_tokens(C0),
  385    ['|'],
  386    !,
  387    { strip_ws_tokens(C0, C)
  388    }.
  389
  390face_tokens([]) -->
  391    [].
  392face_tokens(Tokens) -->
  393    face_token(H),                          % Deal with embedded *|...|*, etc.
  394    token('|'),
  395    face_tokens(Face),
  396    token('|'),
  397    face_token(H),
  398    !,
  399    { append([[H,'|'], Face, ['|', H], Rest], Tokens) },
  400    face_tokens(Rest).
  401face_tokens([H|T]) -->
  402    token(H),
  403    face_tokens(T).
  404
  405face_token(=) --> [=].
  406face_token(*) --> [*].
  407face_token('_') --> ['_'].
  408
  409take_table(Lines, Indent, Row0, Table, Rest) :-
  410    rest_table(Lines, Indent, Rows, Rest),
  411    (   Rows = [align(Align)|Rows1]
  412    ->  maplist(align_row(Align), Rows1, Rows2),
  413        (   maplist(=(td([])), Row0)        % empty header
  414        ->  Table = table(class=wiki, Rows2)
  415        ;   maplist(td_to_th, Row0, Header),
  416            Table = table(class=wiki, [tr(Header)|Rows2])
  417        )
  418    ;   Table = table(class=wiki, [tr(Row0)|Rows])
  419    ).
  420
  421td_to_th(td(X), th(X)) :- !.
  422td_to_th(X, X).
  423
  424align_row(Align, tr(Row0), tr(Row)) :-
  425    align_cells(Align, Row0, Row).
  426
  427align_cells([Align|AT], [Cell0|T0], [Cell|T]) :-
  428    align_cell(Align, Cell0, Cell),
  429    align_cells(AT, T0, T).
  430align_cells(_, Cells, Cells).
  431
  432align_cell(Align, td(Content), td(class=Align, Content)).

 rest_table(+Lines, +Indent, -Rows, -RestLines)

  436rest_table([N-Line|LT], N, [align(Align)|RL], Rest) :-
  437    phrase(column_alignment(Align), Line),
  438    !,
  439    rest_table2(LT, N, RL, Rest).
  440rest_table(Lines, N, RL, Rest) :-
  441    rest_table2(Lines, N, RL, Rest).
  442
  443rest_table2([N-['|'|RL1]|LT], N, [tr(R0)|RL], Rest) :-
  444    !,
  445    phrase(row(R0), RL1),
  446    rest_table2(LT, N, RL, Rest).
  447rest_table2(Rest, _, [], Rest).

 column_alignment(-Alignment) is semidet

Process an alignment line.

  453column_alignment([H|T]) -->
  454    ['|'],
  455    (   colspec(H)
  456    ->  column_alignment(T)
  457    ;   {T=[]}
  458    ).
  459
  460colspec(Align) -->
  461    ws_tokens, [':'], dashes3,
  462    (   [':']
  463    ->  {Align = center}
  464    ;   {Align = left}
  465    ),
  466    ws_tokens.
  467colspec(Align) -->
  468    ws_tokens, dashes3,
  469    (   [':']
  470    ->  {Align = right}
  471    ;   {Align = left}
  472    ),
  473    ws_tokens.
  474
  475dashes3 -->
  476    [-,-,-],
  477    dashes.
  478
  479dashes --> [-], !, dashes.
  480dashes --> [].
  481
  482ws_tokens --> [' '], !, ws_tokens.
  483ws_tokens --> [].

 rest_par(+Lines, -Par, +BaseIndent, +MaxI0, -MaxI, -RestLines) is det

Take the rest of a paragraph. Paragraphs are ended by a blank line or the start of a list-item. The latter is a bit dubious. Why not a general block-level object? The current definition allows for writing lists without a blank line between the items.

  493rest_par([], [], BI, MaxI0, MaxI, []) :-
  494    !,
  495    MaxI is max(BI, MaxI0).
  496rest_par([_-[]|Rest], [], _, MaxI, MaxI, Rest) :- !.
  497rest_par(Lines, [], _, MaxI, MaxI, Lines) :-
  498    Lines = [_-Verb|_],
  499    verbatim_term(Verb),
  500    !.
  501rest_par([I-L|Rest], [], _, MaxI, MaxI, [I-L|Rest]) :-
  502    list_item_prefix(_, L, _),
  503    !.
  504rest_par([I-L1|LT], ['\n'|Par], BI, MaxI0, MaxI, Rest) :-
  505    append(L1, PT, Par),
  506    MaxI1 is max(I, MaxI0),
  507    rest_par(LT, PT, BI, MaxI1, MaxI, Rest).

 section_header(+Lines, -Section, -RestLines) is semidet

Get a section line from the input.

  514section_header([_-L1|LT], Section, LT) :-
  515    twiki_section_line(L1, Section),
  516    !.
  517section_header([0-L1|LT], Section, LT) :-
  518    md_section_line(L1, Section),
  519    !.
  520section_header([_-L1,0-L2|LT], Section, LT) :-
  521    md_section_line(L1, L2, Section),
  522    !.

 twiki_section_line(+Tokens, -Section) is semidet

Extract a section using the Twiki conventions. The section may be preceeded by [Word], in which case we generate an anchor name Word for the section.

  530twiki_section_line([-,-,-|Rest], Section) :-
  531    plusses(Rest, Section).
  532
  533plusses([+, ' '|Rest], h1(Attrs, Content)) :-
  534    hdr_attributes(Rest, Attrs, Content).
  535plusses([+, +, ' '|Rest], h2(Attrs, Content)) :-
  536    hdr_attributes(Rest, Attrs, Content).
  537plusses([+, +, +, ' '|Rest], h3(Attrs, Content)) :-
  538    hdr_attributes(Rest, Attrs, Content).
  539plusses([+, +, +, +, ' '|Rest], h4(Attrs, Content)) :-
  540    hdr_attributes(Rest, Attrs, Content).
  541
  542hdr_attributes(List, Attrs, Content) :-
  543    strip_leading_ws(List, List2),
  544    (   List2 = ['[',w(Name),']'|List3]
  545    ->  strip_ws_tokens(List3, Content),
  546        Attrs = [class(wiki), id(Name)]
  547    ;   Attrs = class(wiki),
  548        strip_ws_tokens(List, Content)
  549    ).

 md_section_line(+Tokens, -Section) is semidet

Handle markdown section lines staring with #

  555md_section_line([#, ' '|Rest], h1(Attrs, Content)) :-
  556    md_section_attributes(Rest, Attrs, Content).
  557md_section_line([#, #, ' '|Rest], h2(Attrs, Content)) :-
  558    md_section_attributes(Rest, Attrs, Content).
  559md_section_line([#, #, #, ' '|Rest], h3(Attrs, Content)) :-
  560    md_section_attributes(Rest, Attrs, Content).
  561md_section_line([#, #, #, #, ' '|Rest], h4(Attrs, Content)) :-
  562    md_section_attributes(Rest, Attrs, Content).
  563
  564md_section_attributes(List, Attrs, Content) :-
  565    phrase((tokens(Content), [' '], section_label(Label)), List),
  566    !,
  567    Attrs = [class(wiki), id(Label)].
  568md_section_attributes(Content, Attrs, Content) :-
  569    Attrs = [class(wiki)].
  570
  571section_label(Label) -->
  572    [ '{', '#', w(Name) ],
  573    label_conts(Cont), ['}'],
  574    !,
  575    { atomic_list_concat([Name|Cont], Label) }.
  576
  577label_conts([H|T]) --> label_cont(H), !, label_conts(T).
  578label_conts([]) --> [].
  579
  580label_cont(-) --> [-].
  581label_cont(Name) --> [w(Name)].
  582
  583
  584md_section_line(Line1, Line2, Header) :-
  585    Line1 \== [],
  586    section_underline(Line2, Type),
  587    is_list(Line1),
  588    phrase(wiki_words(_), Line1),  % Should not have structure elements
  589    !,
  590    (   phrase(labeled_section_line(Title, Attrs), Line1)
  591    ->  true
  592    ;   Title = Line1,
  593        Attrs = []
  594    ),
  595    Header =.. [Type, [class(wiki)|Attrs], Title].
  596
  597section_underline([=,=,=|T], h1) :-
  598    maplist(=(=), T),
  599    !.
  600section_underline([-,-,-|T], h2) :-
  601    maplist(=(-), T),
  602    !.
  603
  604labeled_section_line(Title, Attrs) -->
  605    tokens(Title), [' '], section_label(Label),
  606    !,
  607    { Attrs = [id(Label)] }.

 strip_ws_tokens(+Tokens, -Stripped)

Strip leading and trailing whitespace from a token list. Note the the whitespace is already normalised.

  615strip_ws_tokens([' '|T0], T) :-
  616    !,
  617    strip_ws_tokens(T0, T).
  618strip_ws_tokens(L0, L) :-
  619    append(L, [' '], L0),
  620    !.
  621strip_ws_tokens(L, L).

 strip_leading_ws(+Tokens, -Stripped) is det

Strip leading whitespace from a token list.

  628strip_leading_ws([' '|T], T) :- !.
  629strip_leading_ws(T, T).
  630
  631
  632                 /*******************************
  633                 *             TAGS             *
  634                 *******************************/

 tags(+Lines:lines, -Tags) is semidet

If the first line is a @tag, read the remainder of the lines to a list of \tag(Name, Value) terms.

  641tags(Lines, Tags) :-
  642    collect_tags(Lines, Tags0),
  643    keysort(Tags0, Tags1),
  644    pairs_values(Tags1, Tags2),
  645    combine_tags(Tags2, Tags).

 collect_tags(+IndentedLines, -Tags) is semidet

Create a list Order-tag(Tag,Tokens) for each @tag encountered. Order is the desired position as defined by tag_order/2.

To be done

- Tag content is often poorly aligned. We now find the alignment of subsequent lines and assume the first line is alligned with the remaining lines.

  656collect_tags([], []).
  657collect_tags([Indent-[@,String|L0]|Lines], [Order-tag(Tag,Value)|Tags]) :-
  658    tag_name(String, Tag, Order),
  659    !,
  660    strip_leading_ws(L0, L),
  661    rest_tag(Lines, Indent, VT, RestLines),
  662    normalise_indentation(VT, VT1),
  663    wiki_structure([0-L|VT1], -1, Value0),
  664    strip_leading_par(Value0, Value),
  665    collect_tags(RestLines, Tags).

 tag_name(+String, -Tag:atom, -Order:int) is semidet

If String denotes a know tag-name,

  672tag_name(w(Name), Tag, Order) :-
  673    (   renamed_tag(Name, Tag, Level),
  674        tag_order(Tag, Order)
  675    ->  print_message(Level, pldoc(deprecated_tag(Name, Tag)))
  676    ;   tag_order(Name, Order)
  677    ->  Tag = Name
  678    ;   print_message(warning, pldoc(unknown_tag(Name))),
  679        fail
  680    ).
  681
  682
  683rest_tag([], _, [], []) :- !.
  684rest_tag(Lines, Indent, [], Lines) :-
  685    Lines = [Indent-[@,Word|_]|_],
  686    tag_name(Word, _, _),
  687    !.
  688rest_tag([L|Lines0], Indent, [L|VT], Lines) :-
  689    rest_tag(Lines0, Indent, VT, Lines).

 renamed_tag(+DeprecatedTag:atom, -Tag:atom, -Warn) is semidet

Declaration for deprecated tags.

  696renamed_tag(exception, throws, warning).
  697renamed_tag(param,     arg,    silent).

 tag_order(+Tag:atom, -Order:int) is semidet

Both declares the know tags and their expected order. Currently the tags are forced into this order without warning. Future versions may issue a warning if the order is inconsistent.

  706:- multifile
  707    pldoc:tag_order/2.  708
  709tag_order(Tag, Order) :-
  710    pldoc:tag_order(Tag, Order),
  711    !.
  712tag_order(arg,         100).
  713tag_order(error,       200).            % same as throw
  714tag_order(throws,      300).
  715tag_order(author,      400).
  716tag_order(version,     500).
  717tag_order(see,         600).
  718tag_order(deprecated,  700).
  719tag_order(compat,      800).            % PlDoc extension
  720tag_order(copyright,   900).
  721tag_order(license,    1000).
  722tag_order(bug,        1100).
  723tag_order(tbd,        1200).

 combine_tags(+Tags:list(tag(Key,Value)), -Tags:list) is det

Creates the final tag-list. Tags is a list of

• \params(list(param(Name, Descr)))
• \tag(Name, list(Descr))

Descr is a list of tokens.

  734combine_tags([], []).
  735combine_tags([tag(arg, V1)|T0], [\args([P1|PL])|Tags]) :-
  736    !,
  737    arg_tag(V1, P1),
  738    arg_tags(T0, PL, T1),
  739    combine_tags(T1, Tags).
  740combine_tags([tag(Tag,V0)|T0], [\tag(Tag, [V0|Vs])|T]) :-
  741    same_tag(Tag, T0, T1, Vs),
  742    combine_tags(T1, T).
  743
  744arg_tag([PT|Descr0], arg(PN, Descr)) :-
  745    word_of(PT, PN),
  746    strip_leading_ws(Descr0, Descr).
  747
  748word_of(w(W), W) :- !.                  % TBD: check non-word arg
  749word_of(W, W).
  750
  751arg_tags([tag(arg, V1)|T0], [P1|PL], T) :-
  752    !,
  753    arg_tag(V1, P1),
  754    arg_tags(T0, PL, T).
  755arg_tags(T, [], T).
  756
  757same_tag(Tag, [tag(Tag, V)|T0], T, [V|Vs]) :-
  758    !,
  759    same_tag(Tag, T0, T, Vs).
  760same_tag(_, L, L, []).
  761
  762
  763                 /*******************************
  764                 *             FACES            *
  765                 *******************************/

 wiki_faces(+Structure, +ArgNames, -HTML) is det

Given the wiki structure, analyse the content of the paragraphs, list items and table cells and apply font faces and links.

  772wiki_faces([dt(Class, \term(Text, Term, Bindings)), dd(Descr0)|T0],
  773           ArgNames,
  774           [dt(Class, \term(Text, Term, Bindings)), dd(Descr)|T]) :-
  775    !,
  776    varnames(Bindings, VarNames, ArgNames),
  777    wiki_faces(Descr0, VarNames, Descr),
  778    wiki_faces(T0, ArgNames, T).
  779wiki_faces(DOM0, ArgNames, DOM) :-
  780    structure_term(DOM0, Functor, Content0),
  781    !,
  782    wiki_faces_list(Content0, ArgNames, Content),
  783    structure_term(DOM, Functor, Content).
  784wiki_faces(Verb, _, Verb) :-
  785    verbatim_term(Verb),
  786    !.
  787wiki_faces(Content0, ArgNames, Content) :-
  788    assertion(is_list(Content0)),
  789    phrase(wiki_faces(Content, ArgNames), Content0),
  790    !.
  791
  792varnames([], List, List).
  793varnames([Name=_|T0], [Name|T], List) :-
  794    varnames(T0, T, List).
  795
  796wiki_faces_list([], _, []).
  797wiki_faces_list([H0|T0], Args, [H|T]) :-
  798    wiki_faces(H0, Args, H),
  799    wiki_faces_list(T0, Args, T).

 structure_term(+Term, -Functor, -Content) is semidet

structure_term(-Term, +Functor, +Content) is det

(Un)pack a term describing structure, so we can process Content and re-pack the structure.

  807structure_term(\tags(Tags), tags, [Tags]) :- !.
  808structure_term(\args(Params), args, [Params]) :- !.
  809structure_term(arg(Name,Descr), arg(Name), [Descr]) :- !.
  810structure_term(\tag(Name,Value), tag(Name), [Value]) :- !.
  811structure_term(\include(What,Type,Opts), include(What,Type,Opts), []) :- !.
  812structure_term(dl(Att, Args), dl(Att), [Args]) :- !.
  813structure_term(dt(Att, Args), dt(Att), [Args]) :- !.
  814structure_term(table(Att, Args), table(Att), [Args]) :- !.
  815structure_term(td(Att, Args), td(Att), [Args]) :- !.
  816structure_term(h1(Att, Args), h1(Att), [Args]) :- !.
  817structure_term(h2(Att, Args), h2(Att), [Args]) :- !.
  818structure_term(h3(Att, Args), h3(Att), [Args]) :- !.
  819structure_term(h4(Att, Args), h4(Att), [Args]) :- !.
  820structure_term(hr(Att), hr(Att), []) :- !.
  821structure_term(p(Args), p, [Args]) :- !.
  822structure_term(Term, Functor, Args) :-
  823    structure_term_any(Term, Functor, Args).
  824
  825structure_term(Term) :-
  826    structure_term_any(Term, _Functor, _Args).
  827
  828structure_term_any(Term, Functor, Args) :-
  829    functor(Term, Functor, 1),
  830    structure_tag(Functor),
  831    !,
  832    Term =.. [Functor|Args].
  833
  834structure_tag(ul).
  835structure_tag(ol).
  836structure_tag(dl).
  837structure_tag(li).
  838structure_tag(dt).
  839structure_tag(dd).
  840structure_tag(table).
  841structure_tag(tr).
  842structure_tag(td).
  843structure_tag(th).
  844structure_tag(blockquote).
  845structure_tag(center).

 verbatim_term(?Term) is det

True if Term must be passes verbatim.

  852verbatim_term(pre(_,_)).
  853verbatim_term(\term(_,_,_)).

 matches(:Goal, -Input, -Last)//

True when Goal runs successfully on the DCG input and Input is the list of matched tokens.

  860:- meta_predicate matches(2, -, -, ?, ?).  861
  862matches(Goal, Input, Last, List, Rest) :-
  863    call(Goal, List, Rest),
  864    input(List, Rest, Input, Last).
  865
  866input([H|T0], Rest, Input, Last) :-
  867    (   T0 == Rest
  868    ->  Input = [H],
  869        Last = H
  870    ;   Input = [H|T],
  871        input(T0, Rest, T, Last)
  872    ).

 wiki_faces(-WithFaces, +ArgNames)// is nondet

 wiki_faces(-WithFaces, +ArgNames, +Options)// is nondet

Apply font-changes and automatic links to running text. The faces are applied after discovering the structure (paragraphs, lists, tables, keywords).

Arguments:

Options

- is a dict, minimally containing depth

  884wiki_faces(WithFaces, ArgNames, List, Rest) :-
  885    default_faces_options(Options),
  886    catch(wiki_faces(WithFaces, ArgNames, Options, List, Rest),
  887          pldoc(depth_limit),
  888          failed_faces(WithFaces, List, Rest)).
  889
  890default_faces_options(_{depth:5}).
  891
  892failed_faces(WithFaces) -->
  893    { debug(markdown(overflow), 'Depth limit exceeded', []) },
  894    wiki_words(WithFaces).
  895
  896wiki_faces([EmphTerm|T], ArgNames, Options) -->
  897    emphasis_seq(EmphTerm, ArgNames, Options),
  898    !,
  899    wiki_faces_int(T, ArgNames).
  900wiki_faces(Faces, ArgNames, Options) -->
  901    wiki_faces_int(Faces, ArgNames, Options).
  902
  903wiki_faces_int(WithFaces, ArgNames) -->
  904    { default_faces_options(Options)
  905    },
  906    wiki_faces_int(WithFaces, ArgNames, Options).
  907
  908wiki_faces_int([], _, _) -->
  909    [].
  910wiki_faces_int(List, ArgNames, Options) -->
  911    wiki_face(H, ArgNames, Options),
  912    !,
  913    {   is_list(H)
  914    ->  append(H, T, List)
  915    ;   List = [H|T]
  916    },
  917    wiki_faces(T, ArgNames, Options).
  918wiki_faces_int([Before,EmphTerm|T], ArgNames, Options) -->
  919    emphasis_before(Before),
  920    emphasis_seq(EmphTerm, ArgNames, Options),
  921    !,
  922    wiki_faces_int(T, ArgNames, Options).
  923wiki_faces_int([H|T], ArgNames, Options) -->
  924    wiki_face_simple(H, ArgNames, Options),
  925    !,
  926    wiki_faces_int(T, ArgNames, Options).
  927
  928next_level(Options0, Options) -->
  929    {   succ(NewDepth, Options0.depth)
  930    ->  Options = Options0.put(depth, NewDepth)
  931    ;   throw(pldoc(depth_limit))
  932    }.

 prolog:doc_wiki_face(-Out, +VarNames)// is semidet

prolog:doc_wiki_face(-Out, +VarNames, +Options0)// is semidet

Hook that can be used to provide additional processing for additional inline wiki constructs. The DCG list is a list of tokens. Defined tokens are:

w(Atom)

Recognised word (alphanumerical)

Atom

Single character atom representing punctuation marks or the atom ' ' (space), representing white-space.

The Out variable is input for the backends defined in doc_latex.pl and doc_html.pl. Roughly, these are terms similar to what html//1 from library(http/html_write) accepts.

  951wiki_face(Out, Args, _) -->
  952    prolog:doc_wiki_face(Out, Args),
  953    !.
  954wiki_face(var(Arg), ArgNames, _) -->
  955    [w(Arg)],
  956    { memberchk(Arg, ArgNames)
  957    },
  958    !.
  959wiki_face(b(Bold), ArgNames, Options) -->
  960    [*,'|'], string(Tokens), ['|',*],
  961    !,
  962    { phrase(wiki_faces(Bold, ArgNames, Options), Tokens) }.
  963wiki_face(i(Italic), ArgNames, Options) -->
  964    ['_','|'], string(Tokens), ['|','_'],
  965    !,
  966    { phrase(wiki_faces(Italic, ArgNames, Options), Tokens) }.
  967wiki_face(code(Code), _, _) -->
  968    [=], eq_code_words(Words), [=],
  969    !,
  970    { atomic_list_concat(Words, Code) }.
  971wiki_face(code(Code), _, _) -->
  972    [=,'|'], wiki_words(Code), ['|',=],
  973    !.
  974wiki_face(PredRef, _, _) -->
  975    ['`'], take_predref(PredRef), ['`'],
  976    !.
  977wiki_face(\nopredref(Pred), _, _) -->
  978    ['`', '`'], take_predref(\predref(Pred)), ['`', '`'],
  979    !.
  980wiki_face([flag, ' ', \flagref(Flag)], _, _) -->
  981    [ w('flag'), ' ', '`', w(Flag), '`' ],
  982    { current_prolog_flag(Flag, _) },
  983    !.
  984wiki_face(code(Code), _, _) -->
  985    ['`','`'], wiki_words(Code), ['`','`'],
  986    !.
  987wiki_face(Code, _, _) -->
  988    (   ['`'], code_words(Words), ['`']
  989    ->  { atomic_list_concat(Words, Text),
  990          E = error(_,_),
  991          catch(atom_to_term(Text, Term, Vars), E, fail),
  992          !,
  993          code_face(Text, Term, Vars, Code)
  994        }
  995    ).
  996wiki_face(Face, _, Options) -->
  997    [ w(Name) ], arg_list(List),
  998    { atomic_list_concat([Name|List], Text),
  999      E = error(_,_),
 1000      catch(atom_to_term(Text, Term, Vars), E, fail),
 1001      term_face(Text, Term, Vars, Face, Options)
 1002    },
 1003    !.
 1004wiki_face(br([]), _, _) -->
 1005    [<,w(br),>,'\n'], !.
 1006wiki_face(br([]), _, _) -->
 1007    [<,w(br),/,>,'\n'], !.
 1008        % Below this, we only do links.
 1009wiki_face(_, _, Options) -->
 1010    { Options.get(link) == false,
 1011      !,
 1012      fail
 1013    }.
 1014wiki_face(PredRef, _, _) -->
 1015    take_predref(PredRef),
 1016    !.
 1017wiki_face(\cite(Citations), _, _) -->
 1018    ['['], citations(Citations), [']'].
 1019wiki_face(\include(Name, Type, Options), _, _) -->
 1020    ['[','['], file_name(Base, Ext), [']',']'],
 1021    { autolink_extension(Ext, Type),
 1022      !,
 1023      file_name_extension(Base, Ext, Name),
 1024      resolve_file(Name, Options, [])
 1025    },
 1026    !.
 1027wiki_face(\include(Name, Type, [caption(Caption)|Options]), _, _) -->
 1028    (   ['!','['], tokens(100, Caption), [']','(']
 1029    ->  file_name(Base, Ext), [')'],
 1030        { autolink_extension(Ext, Type),
 1031          !,
 1032          file_name_extension(Base, Ext, Name),
 1033          resolve_file(Name, Options, [])
 1034        }
 1035    ),
 1036    !.
 1037wiki_face(Link, ArgNames, Options) -->          % TWiki: [[Label][Link]]
 1038    (   ['[','['], wiki_label(Label, ArgNames, Options), [']','[']
 1039    ->  wiki_link(Link, [label(Label), relative(true), end(']')]),
 1040        [']',']'], !
 1041    ).
 1042wiki_face(Link, ArgNames, Options) -->          % Markdown: [Label](Link)
 1043    (   ['['], wiki_label(Label, ArgNames, Options), [']','(']
 1044    ->  wiki_link(Link, [label(Label), relative(true), end(')')]),
 1045        [')'], !
 1046    ).
 1047wiki_face(Link, _ArgNames, _) -->
 1048    wiki_link(Link, []),
 1049    !.
 1050
 1051wiki_label(Label, _ArgNames, _Options) -->
 1052    image_label(Label).
 1053wiki_label(Label, ArgNames, Options) -->
 1054    next_level(Options, NOptions),
 1055    limit(40, wiki_faces(Label, ArgNames, NOptions.put(link,false))).

 wiki_face_simple(-Out, +ArgNames, +Options)

Skip simple (non-markup) wiki.

 1061wiki_face_simple(Word, _, _) -->
 1062    [ w(Word) ],
 1063    !.
 1064wiki_face_simple(SpaceOrPunct, _, _) -->
 1065    [ SpaceOrPunct ],
 1066    { atomic(SpaceOrPunct) },
 1067    !.
 1068wiki_face_simple(FT, ArgNames, _) -->
 1069    [Structure],
 1070    { wiki_faces(Structure, ArgNames, FT)
 1071    }.
 1072
 1073wiki_words([]) --> [].
 1074wiki_words([Word|T]) --> [w(Word)], !, wiki_words(T).
 1075wiki_words([Punct|T]) --> [Punct], {atomic(Punct)}, wiki_words(T).

 code_words(-Words)//

True when Words is the content as it appears in `code`, where `` is mapped to `.

 1082code_words([]) --> [].
 1083code_words([Word|T]) --> [w(Word)], code_words(T).
 1084code_words(CodeL) --> ['`','`'], {CodeL = ['`'|T]}, code_words(T).
 1085code_words([Punct|T]) --> [Punct], {atomic(Punct)}, code_words(T).

 eq_code_words(-Words)//

Stuff that can be between single =. This is limited to

• Start and end must be a word
• In between may be the following punctuation chars: .-:/, notably dealing with file names and identifiers in various external languages.

 1096eq_code_words([Word]) -->
 1097    [ w(Word) ].
 1098eq_code_words([Word|T]) -->
 1099    [ w(Word) ], eq_code_internals(T, [End]), [w(End)].
 1100
 1101eq_code_internals(T, T) --> [].
 1102eq_code_internals([H|T], Tail) -->
 1103    eq_code_internal(H),
 1104    eq_code_internals(T, Tail).
 1105
 1106eq_code_internal(Word) -->
 1107    [w(Word)].
 1108eq_code_internal(Punct) -->
 1109    [Punct],
 1110    { eq_code_internal_punct(Punct) }.
 1111
 1112eq_code_internal_punct('.').
 1113eq_code_internal_punct('-').
 1114eq_code_internal_punct(':').
 1115eq_code_internal_punct('/').

 code_face(+Text, +Term, +Vars, -Code) is det

Deal with `... code ...` sequences. Text is the matched text, Term is the parsed Prolog term and Code is the resulting intermediate code.

 1124code_face(Text, Var, _, Code) :-
 1125    var(Var),
 1126    !,
 1127    Code = var(Text).
 1128code_face(Text, _, _, code(Text)).

 emphasis_seq(-Out, +ArgNames, +Options) is semidet

Recognise emphasis sequences

 1135emphasis_seq(EmphTerm, ArgNames, Options) -->
 1136    emphasis_start(C),
 1137    next_level(Options, NOptions),
 1138    matches(limit(100, wiki_faces(Emph, ArgNames, NOptions)), Input, Last),
 1139    emphasis_end(C),
 1140    { emph_markdown(Last, Input),
 1141      emphasis_term(C, Emph, EmphTerm)
 1142    },
 1143    !.

 emphasis_term(+Emphasis, +Tokens, -Term) is det

 emphasis_before(-Before)// is semidet

 emphasis_start(-Emphasis)// is semidet

 emphasis_end(+Emphasis)// is semidet

Primitives for Doxygen emphasis handling.

 1153emphasis_term('_',   Term, i(Term)).
 1154emphasis_term('*',   Term, b(Term)).
 1155emphasis_term('__',  Term, strong(Term)).
 1156emphasis_term('**',  Term, strong(Term)).
 1157
 1158emph_markdown(_, [w(_)]) :- !.
 1159emph_markdown(Last, Tokens) :-
 1160    \+ emphasis_after_sep(Last),
 1161    E = error(_,_),
 1162    catch(b_getval(pldoc_object, Obj), E, Obj = '??'),
 1163    debug(markdown(emphasis), '~q: additionally emphasis: ~p',
 1164          [Obj, Tokens]).
 1165
 1166emphasis_before(Before) -->
 1167    [Before],
 1168    { emphasis_start_sep(Before) }.
 1169
 1170emphasis_start_sep('\n').
 1171emphasis_start_sep(' ').
 1172emphasis_start_sep('<').
 1173emphasis_start_sep('{').
 1174emphasis_start_sep('(').
 1175emphasis_start_sep('[').
 1176emphasis_start_sep(',').
 1177emphasis_start_sep(':').
 1178emphasis_start_sep(';').
 1179
 1180emphasis_start(Which), [w(Word)] -->
 1181    emphasis(Which),
 1182    [w(Word)].
 1183
 1184emphasis(**)   --> [*, *].
 1185emphasis(*)    --> [*].
 1186emphasis('__') --> ['_', '_'].
 1187emphasis('_')  --> ['_'].
 1188
 1189emphasis_end(Which), [After] -->
 1190    emphasis(Which),
 1191    [ After ],
 1192    !,
 1193    { emphasis_close_sep(After) -> true }.
 1194emphasis_end(Which) -->
 1195    emphasis(Which).
 1196
 1197% these characters should not be before a closing * or _.
 1198
 1199emphasis_after_sep('\n').
 1200emphasis_after_sep(' ').
 1201emphasis_after_sep('(').
 1202emphasis_after_sep('[').
 1203emphasis_after_sep('<').
 1204emphasis_after_sep('=').
 1205emphasis_after_sep('+').
 1206emphasis_after_sep('\\').
 1207emphasis_after_sep('@').
 1208
 1209emphasis_close_sep('\n').                       % white
 1210emphasis_close_sep(' ').                        % white
 1211emphasis_close_sep(',').                        % sentence punctuation
 1212emphasis_close_sep('.').
 1213emphasis_close_sep('!').
 1214emphasis_close_sep('?').
 1215emphasis_close_sep(':').
 1216emphasis_close_sep(';').
 1217emphasis_close_sep(']').                        % [**label**](link)
 1218emphasis_close_sep(')').                        % ... _italic_)
 1219emphasis_close_sep('}').                        % ... _italic_}
 1220emphasis_close_sep(Token) :-
 1221    structure_term(Token).

 arg_list(-Atoms) is nondet

Atoms is a token-list for a Prolog argument list. An argument-list is a sequence of tokens '(' ... ')'.

bug

- the current implementation does not deal correctly with brackets that are embedded in quoted strings.

 1232arg_list(['('|T]) -->
 1233    ['('], arg_list_close(T, 1).
 1234
 1235arg_list_close(Tokens, Depth) -->
 1236    [')'],
 1237    !,
 1238    (   { Depth == 1 }
 1239    ->  { Tokens = [')'] }
 1240    ;   { Depth > 1 }
 1241    ->  { Tokens = [')'|More],
 1242          NewDepth is Depth - 1
 1243        },
 1244        arg_list_close(More, NewDepth)
 1245    ).
 1246arg_list_close(['('|T], Depth) -->
 1247    ['('], { NewDepth is Depth+1 },
 1248    arg_list_close(T, NewDepth).
 1249arg_list_close([H|T], Depth) -->
 1250    [w(H)],
 1251    !,
 1252    arg_list_close(T, Depth).
 1253arg_list_close([H|T], Depth) -->
 1254    [H],
 1255    arg_list_close(T, Depth).

 term_face(+Text, +Term, +Vars, -Face, +Options) is semidet

Process embedded Prolog-terms. Currently processes Alias(Arg) terms that refer to files. Future versions will also provide pretty-printing of Prolog terms.

 1264term_face(_Text, Term, _Vars, \file(Name, FileOptions), Options) :-
 1265    ground(Term),
 1266    compound(Term),
 1267    compound_name_arity(Term, Alias, 1),
 1268    user:file_search_path(Alias, _),
 1269    existing_file(Term, FileOptions, [], Options),
 1270    !,
 1271    format(atom(Name), '~q', [Term]).
 1272term_face(Text, Term, Vars, Face, _Options) :-
 1273    code_face(Text, Term, Vars, Face).
 1274
 1275untag([], []).
 1276untag([w(W)|T0], [W|T]) :-
 1277    !,
 1278    untag(T0, T).
 1279untag([H|T0], [H|T]) :-
 1280    untag(T0, T).

 image_label(-Label)//

Match File[;param=value[,param=value]*]

 1286image_label(\include(Name, image, Options)) -->
 1287    file_name(Base, Ext),
 1288    { autolink_extension(Ext, image),
 1289      file_name_extension(Base, Ext, Name),
 1290      resolve_file(Name, Options, RestOptions)
 1291    },
 1292    file_options(RestOptions).
 1293
 1294
 1295take_predref(\predref(Name/Arity)) -->
 1296    [ w(Name), '/' ], arity(Arity),
 1297    { functor_name(Name)
 1298    }.
 1299take_predref(\predref(Module:(Name/Arity))) -->
 1300    [ w(Module), ':', w(Name), '/' ], arity(Arity),
 1301    { functor_name(Name)
 1302    }.
 1303take_predref(\predref(Name/Arity)) -->
 1304    prolog_symbol_char(S0),
 1305    symbol_string(SRest), [ '/' ], arity(Arity),
 1306    !,
 1307    { atom_chars(Name, [S0|SRest])
 1308    }.
 1309take_predref(\predref(Name//Arity)) -->
 1310    [ w(Name), '/', '/' ], arity(Arity),
 1311    { functor_name(Name)
 1312    }.
 1313take_predref(\predref(Module:(Name//Arity))) -->
 1314    [ w(Module), ':', w(Name), '/', '/' ], arity(Arity),
 1315    { functor_name(Name)
 1316    }.

 file_options(-Options) is det

Extracts additional processing options for files. The format is ;name="value",name2=value2,... Spaces are not allowed.

 1323file_options(Options) -->
 1324    [;], nv_pairs(Options),
 1325    !.
 1326file_options([]) -->
 1327    [].
 1328
 1329nv_pairs([H|T]) -->
 1330    nv_pair(H),
 1331    (   [',']
 1332    ->  nv_pairs(T)
 1333    ;   {T=[]}
 1334    ).
 1335
 1336nv_pair(Option) -->
 1337    [ w(Name), =,'"'], tokens(Tokens), ['"'],
 1338    !,
 1339    { untag(Tokens, Atoms),
 1340      atomic_list_concat(Atoms, Value0),
 1341      (   atom_number(Value0, Value)
 1342      ->  true
 1343      ;   Value = Value0
 1344      ),
 1345      Option =.. [Name,Value]
 1346    }.

 wiki_link(-Link, +Options)// is semidet

True if we can find a link to a file or URL. Links are described as one of:

filename

A filename defined using autolink_file/2 or autolink_extension/2

<url-protocol>://<rest-url>

A fully qualified URL

'<' URL '>'

Be more relaxed on the URL specification.

 1362:- multifile
 1363    user:url_path/2. 1364
 1365wiki_link(\file(Name, FileOptions), Options) -->
 1366    file_name(Base, Ext),
 1367    { file_name_extension(Base, Ext, Name),
 1368      (   autolink_file(Name, _)
 1369      ;   autolink_extension(Ext, _)
 1370      ),
 1371      !,
 1372      resolve_file(Name, FileOptions, Options)
 1373    }.
 1374wiki_link(\file(Name, FileOptions), Options) -->
 1375    [w(Name)],
 1376    { autolink_file(Name, _),
 1377      !,
 1378      resolve_file(Name, FileOptions, Options)
 1379    },
 1380    !.
 1381wiki_link(a(href(Ref), Label), Options) -->
 1382    [ w(Prot),:,/,/], { url_protocol(Prot) },
 1383    { option(end(End), Options, space)
 1384    },
 1385    tokens_no_whitespace(Rest), peek_end_url(End),
 1386    !,
 1387    { atomic_list_concat([Prot, :,/,/ | Rest], Ref),
 1388      option(label(Label), Options, Ref)
 1389    }.
 1390wiki_link(a(href(Ref), Label), _Options) -->
 1391    [<, w(Alias), :],
 1392    tokens_no_whitespace(Rest), [>],
 1393    { Term = (Alias:Rest),
 1394      prolog:url_expansion_hook(Term, Ref, Label), !
 1395    }.
 1396wiki_link(a(href(Ref), Label), Options) -->
 1397    [<, w(Alias), :],
 1398    { user:url_path(Alias, _)
 1399    },
 1400    tokens_no_whitespace(Rest), [>],
 1401    { atomic_list_concat(Rest, Local),
 1402      (   Local == ''
 1403      ->  Term =.. [Alias,'.']
 1404      ;   Term =.. [Alias,Local]
 1405      ),
 1406      E = error(_,_),
 1407      catch(expand_url_path(Term, Ref), E, fail),
 1408      option(label(Label), Options, Ref)
 1409    }.
 1410wiki_link(a(href(Ref), Label), Options) -->
 1411    [#, w(First)],
 1412    { option(end(End), Options) },
 1413    tokens_no_whitespace(Rest),
 1414    peek_end_url(End),
 1415    !,
 1416    { atomic_list_concat([#,First|Rest], Ref),
 1417      option(label(Label), Options, Ref)
 1418    }.
 1419wiki_link(a(href(Ref), Label), Options) -->
 1420    [<],
 1421    (   { option(relative(true), Options),
 1422          Parts = Rest
 1423        }
 1424    ->  tokens_no_whitespace(Rest)
 1425    ;   { Parts = [Prot, : | Rest]
 1426        },
 1427        [w(Prot), :], tokens_no_whitespace(Rest)
 1428    ),
 1429    [>],
 1430    !,
 1431    { atomic_list_concat(Parts, Ref),
 1432      option(label(Label), Options, Ref)
 1433    }.

 prolog:url_expansion_hook(+Term, -HREF, -Label) is semidet

This hook is called after recognising <Alias:Rest>, where Term is of the form Alias(Rest). If it succeeds, it must bind HREF to an atom or string representing the link target and Label to an html//1 expression for the label.

 file_name(-Name:atom, -Ext:atom)// is semidet

Matches a filename. A filename is defined as a sequence <segment>{/<segment}.<ext>.

 1447file_name(FileBase, Extension) -->
 1448    segment(S1),
 1449    segments(List),
 1450    ['.'], file_extension(Extension),
 1451    !,
 1452    { atomic_list_concat([S1|List], '/', FileBase) }.
 1453file_name(FileBase, Extension) -->
 1454    [w(Alias), '('],
 1455    { once(user:file_search_path(Alias, _)) },
 1456    segment(S1),
 1457    segments(List),
 1458    [')'],
 1459    !,
 1460    { atomic_list_concat([S1|List], '/', Base),
 1461      Spec =.. [Alias,Base],
 1462      absolute_file_name(Spec, Path,
 1463                         [ access(read),
 1464                           extensions([pl]),
 1465                           file_type(prolog),
 1466                           file_errors(fail)
 1467                         ]),
 1468      file_name_extension(FileBase, Extension, Path)
 1469    }.
 1470
 1471
 1472segment(..) -->
 1473    ['.','.'],
 1474    !.
 1475segment(Word) -->
 1476    [w(Word)].
 1477segment(Dir) -->
 1478    [w(Word),'.',w(d)],
 1479    { atom_concat(Word, '.d', Dir) }.
 1480
 1481segments([H|T]) -->
 1482    ['/'],
 1483    !,
 1484    segment(H),
 1485    segments(T).
 1486segments([]) -->
 1487    [].
 1488
 1489file_extension(Ext) -->
 1490    [w(Ext)],
 1491    { autolink_extension(Ext, _)
 1492    }.