1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker
    4    E-mail:        J.Wielemaker@vu.nl
    5    WWW:           http://www.swi-prolog.org/projects/xpce/
    6    Copyright (c)  2011-2025, University of Amsterdam
    7                              VU University Amsterdam
    8                              CWI, Amsterdam
    9                              SWI-Prolog Solutions b.v.
   10    All rights reserved.
   11
   12    Redistribution and use in source and binary forms, with or without
   13    modification, are permitted provided that the following conditions
   14    are met:
   15
   16    1. Redistributions of source code must retain the above copyright
   17       notice, this list of conditions and the following disclaimer.
   18
   19    2. Redistributions in binary form must reproduce the above copyright
   20       notice, this list of conditions and the following disclaimer in
   21       the documentation and/or other materials provided with the
   22       distribution.
   23
   24    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   25    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   26    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   27    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   28    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   29    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   30    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   31    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   32    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   33    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   34    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   35    POSSIBILITY OF SUCH DAMAGE.
   36*/
   37
   38:- module(prolog_colour,
   39          [ prolog_colourise_stream/3,  % +Stream, +SourceID, :ColourItem
   40            prolog_colourise_stream/4,  % +Stream, +SourceID, :ColourItem, +Opts
   41            prolog_colourise_term/4,    % +Stream, +SourceID, :ColourItem, +Opts
   42            prolog_colourise_query/3,   % +String, +SourceID, :ColourItem
   43            syntax_colour/2,            % +Class, -Attributes
   44            syntax_message//1           % +Class
   45          ]).   46:- use_module(library(record),[(record)/1, op(_,_,record)]).   47:- use_module(library(debug),[debug/3]).   48:- autoload(library(apply),[maplist/3]).   49:- autoload(library(error),[is_of_type/2]).   50:- autoload(library(lists),[member/2,append/3]).   51:- autoload(library(operators),
   52	    [push_operators/1,pop_operators/0,push_op/3]).   53:- autoload(library(option),[option/3]).   54:- autoload(library(predicate_options),
   55	    [current_option_arg/2,current_predicate_options/3]).   56:- autoload(library(prolog_clause),[predicate_name/2]).   57:- autoload(library(prolog_source),
   58	    [ load_quasi_quotation_syntax/2,
   59	      read_source_term_at_location/3,
   60	      prolog_canonical_source/2
   61	    ]).   62:- autoload(library(prolog_xref),
   63	    [ xref_option/2,
   64	      xref_public_list/3,
   65	      xref_op/2,
   66	      xref_prolog_flag/4,
   67	      xref_module/2,
   68	      xref_meta/3,
   69	      xref_source_file/4,
   70	      xref_defined/3,
   71	      xref_called/3,
   72	      xref_defined_class/3,
   73	      xref_exported/2,
   74	      xref_hook/1
   75	    ]).   76
   77:- meta_predicate
   78    prolog_colourise_stream(+, +, 3),
   79    prolog_colourise_stream(+, +, 3, +),
   80    prolog_colourise_query(+, +, 3),
   81    prolog_colourise_term(+, +, 3, +).   82
   83:- predicate_options(prolog_colourise_term/4, 4,
   84                     [ subterm_positions(-any)
   85                     ]).   86:- predicate_options(prolog_colourise_stream/4, 4,
   87                     [ operators(list(any))
   88                     ]).

   98:- multifile
   99    style/2,                        % +ColourClass, -Attributes
  100    message//1,                     % +ColourClass
  101    term_colours/2,                 % +SourceTerm, -ColourSpec
  102    goal_colours/2,                 % +Goal, -ColourSpec
  103    goal_colours/3,                 % +Goal, +Class, -ColourSpec
  104    directive_colours/2,            % +Goal, -ColourSpec
  105    goal_classification/2,          % +Goal, -Class
  106    vararg_goal_classification/3.   % +Name, +Arity, -Class
  107
  108
  109:- record
  110    colour_state(source_id_list,
  111                 module,
  112                 stream,
  113                 closure,
  114                 singletons,
  115                 current_variable).  116
  117colour_state_source_id(State, SourceID) :-
  118    colour_state_source_id_list(State, SourceIDList),
  119    member(SourceID, SourceIDList).

 prolog_colourise_stream(+Stream, +SourceID, :ColourItem) is det

 prolog_colourise_stream(+Stream, +SourceID, :ColourItem, +Opts) is det

Determine colour fragments for the data on Stream. SourceID is the canonical identifier of the input as known to the cross-referencer, i.e., as created using xref_source(SourceID).

ColourItem is a closure that is called for each identified fragment with three additional arguments:

• The syntactical category
• Start position (character offset) of the fragment
• Length of the fragment (in characters).

Options

operators(+Ops)

Provide an initial list of additional operators.

  140prolog_colourise_stream(Fd, SourceId, ColourItem) :-
  141    prolog_colourise_stream(Fd, SourceId, ColourItem, []).
  142prolog_colourise_stream(Fd, SourceId, ColourItem, Options) :-
  143    to_list(SourceId, SourceIdList),
  144    make_colour_state([ source_id_list(SourceIdList),
  145                        stream(Fd),
  146                        closure(ColourItem)
  147                      ],
  148                      TB),
  149    option(operators(Ops), Options, []),
  150    setup_call_cleanup(
  151        save_settings(TB, Ops, State),
  152        colourise_stream(Fd, TB),
  153        restore_settings(State)).
  154
  155to_list(List, List) :-
  156    is_list(List),
  157    !.
  158to_list(One, [One]).
  159
  160
  161colourise_stream(Fd, TB) :-
  162    (   peek_char(Fd, #)            % skip #! script line
  163    ->  skip(Fd, 10)
  164    ;   true
  165    ),
  166    repeat,
  167        colour_state_module(TB, SM),
  168        character_count(Fd, Start),
  169        catch(read_term(Fd, Term,
  170                        [ subterm_positions(TermPos),
  171                          singletons(Singletons0),
  172                          module(SM),
  173                          comments(Comments)
  174                        ]),
  175              E,
  176              read_error(E, TB, Start, Fd)),
  177        fix_operators(Term, SM, TB),
  178        warnable_singletons(Singletons0, Singletons),
  179        colour_state_singletons(TB, Singletons),
  180        (   colourise_term(Term, TB, TermPos, Comments)
  181        ->  true
  182        ;   arg(1, TermPos, From),
  183            print_message(warning,
  184                          format('Failed to colourise ~p at index ~d~n',
  185                                 [Term, From]))
  186        ),
  187        Term == end_of_file,
  188    !.
  189
  190save_settings(TB, Ops, state(Style, Flags, OSM, Xref)) :-
  191    (   source_module(TB, SM)
  192    ->  true
  193    ;   SM = prolog_colour_ops
  194    ),
  195    set_xref(Xref, true),
  196    '$set_source_module'(OSM, SM),
  197    colour_state_module(TB, SM),
  198    maplist(qualify_op(SM), Ops, QOps),
  199    push_operators(QOps),
  200    syntax_flags(Flags),
  201    '$style_check'(Style, Style).
  202
  203qualify_op(M, op(P,T,[]), Q)            => Q = op(P,T,M:[]).
  204qualify_op(M, op(P,T,N), Q), atom(N)    => Q = op(P,T,M:N).
  205qualify_op(M, op(P,T,L), Q), is_list(Q) =>
  206    Q = op(P, T, QL),
  207    maplist(qualify_op_name(M), L, QL).
  208qualify_op(_, Op, Q)			=> Q = Op.
  209
  210qualify_op_name(M, N,  Q), atom(N) => Q = M:N.
  211qualify_op_name(M, [], Q)          => Q = M:[].
  212qualify_op_name(_, V,  Q)          => Q = V.
  213
  214restore_settings(state(Style, Flags, OSM, Xref)) :-
  215    restore_syntax_flags(Flags),
  216    '$style_check'(_, Style),
  217    pop_operators,
  218    '$set_source_module'(OSM),
  219    set_xref(_, Xref).
  220
  221set_xref(Old, New) :-
  222    current_prolog_flag(xref, Old),
  223    !,
  224    set_prolog_flag(xref, New).
  225set_xref(false, New) :-
  226    set_prolog_flag(xref, New).
  227
  228
  229syntax_flags(Pairs) :-
  230    findall(set_prolog_flag(Flag, Value),
  231            syntax_flag(Flag, Value),
  232            Pairs).
  233
  234syntax_flag(Flag, Value) :-
  235    syntax_flag(Flag),
  236    current_prolog_flag(Flag, Value).
  237
  238restore_syntax_flags([]).
  239restore_syntax_flags([set_prolog_flag(Flag, Value)|T]) :-
  240    set_prolog_flag(Flag, Value),
  241    restore_syntax_flags(T).

 source_module(+State, -Module) is semidet

True when Module is the module context into which the file is loaded. This is the module of the file if File is a module file, or the load context of File if File is not included or the module context of the file into which the file was included.

  250source_module(TB, Module) :-
  251    colour_state_source_id_list(TB, []),
  252    !,
  253    colour_state_module(TB, Module).
  254source_module(TB, Module) :-
  255    colour_state_source_id(TB, SourceId),
  256    xref_option(SourceId, module(Module)),
  257    !.
  258source_module(TB, Module) :-
  259    (   colour_state_source_id(TB, File),
  260        atom(File)
  261    ;   colour_state_stream(TB, Fd),
  262        is_stream(Fd),
  263        stream_property(Fd, file_name(File))
  264    ),
  265    module_context(File, [], Module).
  266
  267module_context(File, _, Module) :-
  268    source_file_property(File, module(Module)),
  269    !.
  270module_context(File, Seen, Module) :-
  271    source_file_property(File, included_in(File2, _Line)),
  272    \+ memberchk(File, Seen),
  273    !,
  274    module_context(File2, [File|Seen], Module).
  275module_context(File, _, Module) :-
  276    source_file_property(File, load_context(Module, _, _)).

 read_error(+Error, +TB, +Start, +Stream) is failure

If this is a syntax error, create a syntax-error fragment.

  283read_error(Error, TB, Start, EndSpec) :-
  284    (   syntax_error(Error, Id, CharNo)
  285    ->  message_to_string(error(syntax_error(Id), _), Msg),
  286        (   integer(EndSpec)
  287        ->  End = EndSpec
  288        ;   character_count(EndSpec, End)
  289        ),
  290        show_syntax_error(TB, CharNo:Msg, Start-End),
  291        fail
  292    ;   throw(Error)
  293    ).
  294
  295syntax_error(error(syntax_error(Id), stream(_S, _Line, _LinePos, CharNo)),
  296             Id, CharNo).
  297syntax_error(error(syntax_error(Id), file(_S, _Line, _LinePos, CharNo)),
  298             Id, CharNo).
  299syntax_error(error(syntax_error(Id), string(_Text, CharNo)),
  300             Id, CharNo).

 warnable_singletons(+Singletons, -Warn) is det

Warn is the subset of the singletons that we warn about.

  306warnable_singletons([], []).
  307warnable_singletons([H|T0], List) :-
  308    H = (Name=_Var),
  309    (   '$is_named_var'(Name)
  310    ->  List = [H|T]
  311    ;   List = T
  312    ),
  313    warnable_singletons(T0, T).

 colour_item(+Class, +TB, +Pos) is det

  317colour_item(Class, TB, Pos) :-
  318    arg(1, Pos, Start),
  319    arg(2, Pos, End),
  320    Len is End - Start,
  321    colour_state_closure(TB, Closure),
  322    call(Closure, Class, Start, Len).

 safe_push_op(+Prec, +Type, :Name, +State)

Define operators into the default source module and register them to be undone by pop_operators/0.

  330safe_push_op(P, T, N0, State) :-
  331    colour_state_module(State, CM),
  332    strip_module(CM:N0, M, N),
  333    (   is_list(N),
  334        N \== []                                % define list as operator
  335    ->  acyclic_term(N),
  336        forall(member(Name, N),
  337               safe_push_op(P, T, M:Name, State))
  338    ;   push_op(P, T, M:N)
  339    ),
  340    debug(colour, ':- ~w.', [op(P,T,M:N)]).

 fix_operators(+Term, +Module, +State) is det

Fix flags that affect the syntax, such as operators and some style checking options. Src is the canonical source as required by the cross-referencer.

  348fix_operators((:- Directive), M, Src) :-
  349    callable(Directive),
  350    acyclic_term(Directive),
  351    catch(process_directive(Directive, M, Src), error(_,_), true),
  352    !.
  353fix_operators(_, _, _).
  354
  355:- multifile
  356    prolog:xref_update_syntax/2.  357
  358process_directive(Directive, M, _Src),
  359    ground(Directive),
  360    prolog:xref_update_syntax((:- Directive), M) =>
  361    true.
  362process_directive(style_check(X), _, _), ground(X) =>
  363    style_check(X).
  364process_directive(set_prolog_flag(Flag, Value), M, _),
  365    ground(Flag+Value),
  366    syntax_flag(Flag) =>
  367    set_prolog_flag(M:Flag, Value).
  368process_directive(M:op(P,T,N), _, Src), ground(M) =>
  369    process_directive(op(P,T,N), M, Src).
  370process_directive(op(P,T,N), M, Src), ground(op(P,T,N)) =>
  371    safe_push_op(P, T, M:N, Src).
  372process_directive(module(_Name, Export), M, Src), ground(Export) =>
  373    forall(member(op(P,A,N), Export),
  374           safe_push_op(P,A,M:N, Src)).
  375process_directive(use_module(Spec), _, Src), ground(Spec) =>
  376    catch(process_use_module1(Spec, Src), _, true).
  377process_directive(use_module(Spec, Imports), _, Src), ground(Spec), is_list(Imports) =>
  378    catch(process_use_module2(Spec, Imports, Src), _, true).
  379process_directive(Directive, _, Src), ground(Directive) =>
  380    prolog_source:expand((:-Directive), Src, _).
  381
  382syntax_flag(character_escapes).
  383syntax_flag(var_prefix).
  384syntax_flag(allow_variable_name_as_functor).
  385syntax_flag(allow_dot_in_atom).

 process_use_module1(+Imports, +Src)

Get the exported operators from the referenced files.

  391process_use_module1([], _) :- !.
  392process_use_module1([H|T], Src) :-
  393    !,
  394    process_use_module1(H, Src),
  395    process_use_module1(T, Src).
  396process_use_module1(File, Src) :-
  397    (   xref_public_list(File, Src,
  398                         [ exports(Exports),
  399                           silent(true),
  400                           path(Path)
  401                         ])
  402    ->  forall(member(op(P,T,N), Exports),
  403               safe_push_op(P,T,N,Src)),
  404        colour_state_module(Src, SM),
  405        (   member(Syntax/4, Exports),
  406            load_quasi_quotation_syntax(SM:Path, Syntax),
  407            fail
  408        ;   true
  409        )
  410    ;   true
  411    ).
  412
  413process_use_module2(File, Imports, Src) :-
  414    (   xref_public_list(File, Src,
  415                         [ exports(Exports),
  416                           silent(true),
  417                           path(Path)
  418                         ])
  419    ->  forall(( member(op(P,T,N), Exports),
  420                 member(op(P,T,N), Imports)),
  421               safe_push_op(P,T,N,Src)),
  422        colour_state_module(Src, SM),
  423        (   member(Syntax/4, Exports),
  424            member(Syntax/4, Imports),
  425            load_quasi_quotation_syntax(SM:Path, Syntax),
  426            fail
  427        ;   true
  428        )
  429    ;   true
  430    ).

 prolog_colourise_query(+Query:string, +SourceId, :ColourItem)

Colourise a query, to be executed in the context of SourceId.

Arguments:

SourceId

- Execute Query in the context of the cross-referenced environment SourceID.

  439prolog_colourise_query(QueryString, SourceID, ColourItem) :-
  440    query_colour_state(SourceID, ColourItem, TB),
  441    setup_call_cleanup(
  442        save_settings(TB, [], State),
  443        colourise_query(QueryString, TB),
  444        restore_settings(State)).
  445
  446query_colour_state(module(Module), ColourItem, TB) :-
  447    !,
  448    make_colour_state([ source_id_list([]),
  449                        module(Module),
  450                        closure(ColourItem)
  451                      ],
  452                      TB).
  453query_colour_state(SourceID, ColourItem, TB) :-
  454    to_list(SourceID, SourceIDList),
  455    make_colour_state([ source_id_list(SourceIDList),
  456                        closure(ColourItem)
  457                      ],
  458                      TB).
  459
  460
  461colourise_query(QueryString, TB) :-
  462    colour_state_module(TB, SM),
  463    string_length(QueryString, End),
  464    (   catch(term_string(Query, QueryString,
  465                          [ subterm_positions(TermPos),
  466                            singletons(Singletons0),
  467                            module(SM),
  468                            comments(Comments)
  469                          ]),
  470              E,
  471              read_error(E, TB, 0, End))
  472    ->  warnable_singletons(Singletons0, Singletons),
  473        colour_state_singletons(TB, Singletons),
  474        colourise_comments(Comments, TB),
  475        (   Query == end_of_file
  476        ->  true
  477        ;   colourise_body(Query, TB, TermPos)
  478        )
  479    ;   true                        % only a syntax error
  480    ).

 prolog_colourise_term(+Stream, +SourceID, :ColourItem, +Options)

Colourise the next term on Stream. Unlike prolog_colourise_stream/3, this predicate assumes it is reading a single term rather than the entire stream. This implies that it cannot adjust syntax according to directives that precede it.

Options:

subterm_positions(-TermPos)

Return complete term-layout. If an error is read, this is a term error_position(StartClause, EndClause, ErrorPos)

current_variable(+VarName)

Variable to highlight

  497prolog_colourise_term(Stream, SourceId, ColourItem, Options) :-
  498    to_list(SourceId, SourceIdList),
  499    make_colour_state([ source_id_list(SourceIdList),
  500                        stream(Stream),
  501                        closure(ColourItem)
  502                      ],
  503                      TB),
  504    option(subterm_positions(TermPos), Options, _),
  505    findall(Op, xref_op(SourceId, Op), Ops),
  506    debug(colour, 'Ops from ~p: ~p', [SourceId, Ops]),
  507    findall(Opt, xref_flag_option(SourceId, Opt), Opts),
  508    character_count(Stream, Start),
  509    (   source_module(TB, Module)
  510    ->  true
  511    ;   Module = prolog_colour_ops
  512    ),
  513    read_source_term_at_location(
  514        Stream, Term,
  515        [ module(Module),
  516          operators(Ops),
  517          error(Error),
  518          subterm_positions(TermPos),
  519          variable_names(VarNames),
  520          singletons(Singletons0),
  521          comments(Comments)
  522        | Opts
  523        ]),
  524    (   var(Error)
  525    ->  warnable_singletons(Singletons0, Singletons),
  526        colour_state_singletons(TB, Singletons),
  527        set_current_variable(TB, VarNames, Options),
  528        colour_item(range, TB, TermPos),            % Call to allow clearing
  529        colourise_term(Term, TB, TermPos, Comments)
  530    ;   character_count(Stream, End),
  531        TermPos = error_position(Start, End, Pos),
  532        colour_item(range, TB, TermPos),
  533        show_syntax_error(TB, Error, Start-End),
  534        Error = Pos:_Message
  535    ).
  536
  537xref_flag_option(TB, var_prefix(Bool)) :-
  538    xref_prolog_flag(TB, var_prefix, Bool, _Line).
  539
  540show_syntax_error(TB, Pos:Message, Range) :-
  541    integer(Pos),
  542    !,
  543    End is Pos + 1,
  544    colour_item(syntax_error(Message, Range), TB, Pos-End).
  545show_syntax_error(TB, _:Message, Range) :-
  546    colour_item(syntax_error(Message, Range), TB, Range).

 singleton(@Var, +TB) is semidet

True when Var is a singleton.

  552singleton(Var, TB) :-
  553    colour_state_singletons(TB, Singletons),
  554    member_var(Var, Singletons).
  555
  556member_var(V, [_=V2|_]) :-
  557    V == V2,
  558    !.
  559member_var(V, [_|T]) :-
  560    member_var(V, T).
  561
  562set_current_variable(TB, VarNames, Options) :-
  563    option(current_variable(Name), Options),
  564    memberchk(Name=CV, VarNames),
  565    !,
  566    colour_state_current_variable(TB, CV).
  567set_current_variable(_, _, _).
  568
  569current_variable(Var, TB) :-
  570    colour_state_current_variable(TB, Current),
  571    Var == Current.

 colourise_term(+Term, +TB, +Termpos, +Comments)

Colourise the next Term.

bug

- The colour spec is closed with fullstop, but the position information does not include the full stop location, so all we can do is assume it is behind the term.

  583colourise_term(Term, TB, TermPos, Comments) :-
  584    colourise_comments(Comments, TB),
  585    (   Term == end_of_file
  586    ->  true
  587    ;   colourise_term(Term, TB, TermPos),
  588        colourise_fullstop(TB, TermPos)
  589    ).
  590
  591colourise_fullstop(TB, TermPos) :-
  592    arg(2, TermPos, EndTerm),
  593    Start is EndTerm,
  594    End is Start+1,
  595    colour_item(fullstop, TB, Start-End).
  596
  597colourise_comments(-, _).
  598colourise_comments([], _).
  599colourise_comments([H|T], TB) :-
  600    colourise_comment(H, TB),
  601    colourise_comments(T, TB).
  602
  603colourise_comment((-)-_, _) :- !.
  604colourise_comment(Pos-Comment, TB) :-
  605    comment_style(Comment, Style),
  606    stream_position_data(char_count, Pos, Start),
  607    string_length(Comment, Len),
  608    End is Start + Len + 1,
  609    colour_item(comment(Style), TB, Start-End).
  610
  611comment_style(Comment, structured) :-           % Starts %%, %! or /**
  612    structured_comment_start(Start),
  613    sub_string(Comment, 0, Len, _, Start),
  614    Next is Len+1,
  615    string_code(Next, Comment, NextCode),
  616    code_type(NextCode, space),
  617    !.
  618comment_style(Comment, line) :-                 % Starts %
  619    sub_string(Comment, 0, _, _, '%'),
  620    !.
  621comment_style(_, block).                        % Starts /*

 structured_comment_start(-Start)

Copied from library(pldoc/doc_process). Unfortunate, but we do not want to force loading pldoc.

  628structured_comment_start('%%').
  629structured_comment_start('%!').
  630structured_comment_start('/**').

 colourise_term(+Term, +TB, +Pos)

Colorise a file toplevel term.

  636colourise_term(Var, TB, Start-End) :-
  637    var(Var),
  638    !,
  639    colour_item(instantiation_error, TB, Start-End).
  640colourise_term(_, _, Pos) :-
  641    var(Pos),
  642    !.
  643colourise_term(Term, TB, parentheses_term_position(PO,PC,Pos)) :-
  644    !,
  645    colour_item(parentheses, TB, PO-PC),
  646    colourise_term(Term, TB, Pos).
  647colourise_term(Term, TB, Pos) :-
  648    term_colours(Term, FuncSpec-ArgSpecs),
  649    !,
  650    Pos = term_position(F,T,FF,FT,ArgPos),
  651    colour_item(term, TB, F-T),     % TBD: Allow specifying by term_colours/2?
  652    specified_item(FuncSpec, Term, TB, FF-FT),
  653    specified_items(ArgSpecs, Term, TB, ArgPos).
  654colourise_term((Pre=>Body), TB,
  655               term_position(F,T,FF,FT,[PP,BP])) :-
  656    nonvar(Pre),
  657    Pre = (Head,Cond),
  658    PP = term_position(_HF,_HT,_HFF,_HFT,[HP,CP]),
  659    !,
  660    colour_item(clause,         TB, F-T),
  661    colour_item(neck(=>),       TB, FF-FT),
  662    colourise_clause_head(Head, TB, HP),
  663    colour_item(rule_condition, TB, CP),
  664    colourise_body(Cond, Head,  TB, CP),
  665    colourise_body(Body, Head,  TB, BP).
  666colourise_term(Term, TB,
  667               term_position(F,T,FF,FT,[HP,BP])) :-
  668    neck(Term, Head, Body, Neck),
  669    !,
  670    colour_item(clause,         TB, F-T),
  671    colour_item(neck(Neck),     TB, FF-FT),
  672    colourise_clause_head(Head, TB, HP),
  673    colourise_body(Body, Head,  TB, BP).
  674colourise_term(((Head,RHC) --> Body), TB,
  675               term_position(F,T,FF,FT,
  676                             [ term_position(_,_,_,_,[HP,RHCP]),
  677                               BP
  678                             ])) :-
  679    !,
  680    colour_item(grammar_rule,       TB, F-T),
  681    colour_item(dcg_right_hand_ctx, TB, RHCP),
  682    colourise_term_arg(RHC, TB, RHCP),
  683    colour_item(neck(-->),          TB, FF-FT),
  684    colourise_extended_head(Head, 2, TB, HP),
  685    colourise_dcg(Body, Head,       TB, BP).
  686colourise_term((Head --> Body), TB,                     % TBD: expansion!
  687               term_position(F,T,FF,FT,[HP,BP])) :-
  688    !,
  689    colour_item(grammar_rule,       TB, F-T),
  690    colour_item(neck(-->),          TB, FF-FT),
  691    colourise_extended_head(Head, 2, TB, HP),
  692    colourise_dcg(Body, Head,       TB, BP).
  693colourise_term(((Head,RHC) ==> Body), TB,
  694               term_position(F,T,FF,FT,
  695                             [ term_position(_,_,_,_,[HP,RHCP]),
  696                               BP
  697                             ])) :-
  698    !,
  699    extend(Head, 2, HeadEx),
  700    colour_item(grammar_rule,        TB, F-T),
  701    colour_item(rule_condition,      TB, RHCP),
  702    colourise_body(RHC, HeadEx,      TB, RHCP),
  703    colour_item(neck(==>),           TB, FF-FT),
  704    colourise_extended_head(Head, 2, TB, HP),
  705    colourise_dcg(Body, Head,        TB, BP).
  706colourise_term((Head ==> Body), TB,                     % TBD: expansion!
  707               term_position(F,T,FF,FT,[HP,BP])) :-
  708    !,
  709    colour_item(grammar_rule,       TB, F-T),
  710    colour_item(neck(==>),          TB, FF-FT),
  711    colourise_extended_head(Head, 2, TB, HP),
  712    colourise_dcg(Body, Head,       TB, BP).
  713colourise_term(:->(Head, Body), TB,
  714               term_position(F,T,FF,FT,[HP,BP])) :-
  715    !,
  716    colour_item(method,             TB, F-T),
  717    colour_item(neck(:->), TB, FF-FT),
  718    colour_method_head(send(Head),  TB, HP),
  719    colourise_method_body(Body,     TB, BP).
  720colourise_term(:<-(Head, Body), TB,
  721               term_position(F,T,FF,FT,[HP,BP])) :-
  722    !,
  723    colour_item(method,            TB, F-T),
  724    colour_item(neck(:<-), TB, FF-FT),
  725    colour_method_head(get(Head),  TB, HP),
  726    colourise_method_body(Body,    TB, BP).
  727colourise_term((:- Directive), TB, Pos) :-
  728    !,
  729    colour_item(directive, TB, Pos),
  730    Pos = term_position(_F,_T,FF,FT,[ArgPos]),
  731    colour_item(neck(directive), TB, FF-FT),
  732    colourise_directive(Directive, TB, ArgPos).
  733colourise_term((?- Directive), TB, Pos) :-
  734    !,
  735    colourise_term((:- Directive), TB, Pos).
  736colourise_term(end_of_file, _, _) :- !.
  737colourise_term(Fact, TB, Pos) :-
  738    !,
  739    colour_item(clause, TB, Pos),
  740    colourise_clause_head(Fact, TB, Pos).
  741
  742neck((Head  :- Body), Head, Body, :-).
  743neck((Head  => Body), Head, Body, =>).
  744neck(?=>(Head, Body), Head, Body, ?=>).

 colourise_extended_head(+Head, +ExtraArgs, +TB, +Pos) is det

Colourise a clause-head that is extended by term_expansion, getting ExtraArgs more arguments (e.g., DCGs add two more arguments.

  752colourise_extended_head(Head, N, TB, Pos) :-
  753    extend(Head, N, TheHead),
  754    colourise_clause_head(TheHead, TB, Pos).
  755
  756extend(M:Head, N, M:ExtHead) :-
  757    nonvar(Head),
  758    !,
  759    extend(Head, N, ExtHead).
  760extend(Head, N, ExtHead) :-
  761    compound(Head),
  762    !,
  763    compound_name_arguments(Head, Name, Args),
  764    length(Extra, N),
  765    append(Args, Extra, NArgs),
  766    compound_name_arguments(ExtHead, Name, NArgs).
  767extend(Head, N, ExtHead) :-
  768    atom(Head),
  769    !,
  770    length(Extra, N),
  771    compound_name_arguments(ExtHead, Head, Extra).
  772extend(Head, _, Head).
  773
  774
  775colourise_clause_head(_, _, Pos) :-
  776    var(Pos),
  777    !.
  778colourise_clause_head(Head, TB, parentheses_term_position(PO,PC,Pos)) :-
  779    colour_item(parentheses, TB, PO-PC),
  780    colourise_clause_head(Head, TB, Pos).
  781colourise_clause_head(M:Head, TB, QHeadPos) :-
  782    QHeadPos = term_position(_,_,QF,QT,[MPos,HeadPos]),
  783    head_colours(M:Head, meta-[_, ClassSpec-ArgSpecs]),
  784    !,
  785    colourise_module(M, TB, MPos),
  786    colour_item(functor, TB, QF-QT),
  787    functor_position(HeadPos, FPos, ArgPos),
  788    (   ClassSpec == classify
  789    ->  classify_head(TB, Head, Class)
  790    ;   Class = ClassSpec
  791    ),
  792    colour_item(head_term(Class, Head), TB, QHeadPos),
  793    colour_item(head(Class, Head), TB, FPos),
  794    specified_items(ArgSpecs, Head, TB, ArgPos).
  795colourise_clause_head(#(Macro), TB, term_position(_,_,HF,HT,[MPos])) :-
  796    expand_macro(TB, Macro, Head),
  797    !,
  798    macro_term_string(Head, String),
  799    functor_position(MPos, FPos, _),
  800    classify_head(TB, Head, Class),
  801    colour_item(macro(String), TB, HF-HT),
  802    colour_item(head_term(Class, Head), TB, MPos),
  803    colour_item(head(Class, Head), TB, FPos),
  804    colourise_term_args(Macro, TB, MPos).
  805colourise_clause_head(Head, TB, Pos) :-
  806    head_colours(Head, ClassSpec-ArgSpecs),
  807    !,
  808    functor_position(Pos, FPos, ArgPos),
  809    (   ClassSpec == classify
  810    ->  classify_head(TB, Head, Class)
  811    ;   Class = ClassSpec
  812    ),
  813    colour_item(head_term(Class, Head), TB, Pos),
  814    colour_item(head(Class, Head), TB, FPos),
  815    specified_items(ArgSpecs, Head, TB, ArgPos).
  816colourise_clause_head(:=(Eval, Ret), TB,
  817                      term_position(_,_,AF,AT,
  818                                    [ term_position(_,_,SF,ST,
  819                                                    [ SelfPos,
  820                                                      FuncPos
  821                                                    ]),
  822                                      RetPos
  823                                    ])) :-
  824    Eval =.. [.,M,Func],
  825    FuncPos = term_position(_,_,FF,FT,_),
  826    !,
  827    colourise_term_arg(M, TB, SelfPos),
  828    colour_item(func_dot, TB, SF-ST),               % .
  829    colour_item(dict_function(Func), TB, FF-FT),
  830    colourise_term_args(Func, TB, FuncPos),
  831    colour_item(dict_return_op, TB, AF-AT),         % :=
  832    colourise_term_arg(Ret, TB, RetPos).
  833colourise_clause_head(Head, TB, Pos) :-
  834    functor_position(Pos, FPos, _),
  835    classify_head(TB, Head, Class),
  836    colour_item(head_term(Class, Head), TB, Pos),
  837    colour_item(head(Class, Head), TB, FPos),
  838    colourise_term_args(Head, TB, Pos).

 colourise_extern_head(+Head, +Module, +TB, +Pos)

Colourise the head specified as Module:Head. Normally used for adding clauses to multifile predicates in other modules.

  845colourise_extern_head(Head, M, TB, Pos) :-
  846    functor_position(Pos, FPos, _),
  847    colour_item(head(extern(M), Head), TB, FPos),
  848    colourise_term_args(Head, TB, Pos).
  849
  850colour_method_head(SGHead, TB, Pos) :-
  851    arg(1, SGHead, Head),
  852    functor_name(SGHead, SG),
  853    functor_position(Pos, FPos, _),
  854    colour_item(method(SG), TB, FPos),
  855    colourise_term_args(Head, TB, Pos).

 functor_position(+Term, -FunctorPos, -ArgPosList)

Get the position of a functor and its argument. Unfortunately this goes wrong for lists, who have two `functor-positions'.

  862functor_position(term_position(_,_,FF,FT,ArgPos), FF-FT, ArgPos) :- !.
  863functor_position(list_position(F,_T,Elms,none), F-FT, Elms) :-
  864    !,
  865    FT is F + 1.
  866functor_position(dict_position(_,_,FF,FT,KVPos), FF-FT, KVPos) :- !.
  867functor_position(brace_term_position(F,T,Arg), F-T, [Arg]) :- !.
  868functor_position(Pos, Pos, []).
  869
  870colourise_module(Term, TB, Pos) :-
  871    (   var(Term)
  872    ;   atom(Term)
  873    ),
  874    !,
  875    colour_item(module(Term), TB, Pos).
  876colourise_module(_, TB, Pos) :-
  877    colour_item(type_error(module), TB, Pos).

 colourise_directive(+Body, +TB, +Pos)

Colourise the body of a directive.

  883colourise_directive(_,_,Pos) :-
  884    var(Pos),
  885    !.
  886colourise_directive(Dir, TB, parentheses_term_position(PO,PC,Pos)) :-
  887    !,
  888    colour_item(parentheses, TB, PO-PC),
  889    colourise_directive(Dir, TB, Pos).
  890colourise_directive((A,B), TB, term_position(_,_,_,_,[PA,PB])) :-
  891    !,
  892    colourise_directive(A, TB, PA),
  893    colourise_directive(B, TB, PB).
  894colourise_directive(Body, TB, Pos) :-
  895    nonvar(Body),
  896    directive_colours(Body, ClassSpec-ArgSpecs),   % specified
  897    !,
  898    functor_position(Pos, FPos, ArgPos),
  899    (   ClassSpec == classify
  900    ->  goal_classification(TB, Body, [], Class)
  901    ;   Class = ClassSpec
  902    ),
  903    colour_item(goal(Class, Body), TB, FPos),
  904    specified_items(ArgSpecs, Body, TB, ArgPos).
  905colourise_directive(Body, TB, Pos) :-
  906    colourise_body(Body, TB, Pos).
  907
  908
  909%       colourise_body(+Body, +TB, +Pos)
  910%
  911%       Breaks down to colourise_goal/3.
  912
  913colourise_body(Body, TB, Pos) :-
  914    colourise_body(Body, [], TB, Pos).
  915
  916colourise_body(Body, Origin, TB, Pos) :-
  917    colour_item(body, TB, Pos),
  918    colourise_goals(Body, Origin, TB, Pos).

 colourise_method_body(+MethodBody, +TB, +Pos)

Colourise the optional "comment":: as pce(comment) and proceed with the body.

To be done

- Get this handled by a hook.

  927colourise_method_body(_, _, Pos) :-
  928    var(Pos),
  929    !.
  930colourise_method_body(Body, TB, parentheses_term_position(PO,PC,Pos)) :-
  931    !,
  932    colour_item(parentheses, TB, PO-PC),
  933    colourise_method_body(Body, TB, Pos).
  934colourise_method_body(::(_Comment,Body), TB,
  935                      term_position(_F,_T,_FF,_FT,[CP,BP])) :-
  936    !,
  937    colour_item(comment(string), TB, CP),
  938    colourise_body(Body, TB, BP).
  939colourise_method_body(Body, TB, Pos) :-         % deal with pri(::) < 1000
  940    Body =.. [F,A,B],
  941    control_op(F),
  942    !,
  943    Pos = term_position(_F,_T,FF,FT,
  944                        [ AP,
  945                          BP
  946                        ]),
  947    colour_item(control, TB, FF-FT),
  948    colourise_method_body(A, TB, AP),
  949    colourise_body(B, TB, BP).
  950colourise_method_body(Body, TB, Pos) :-
  951    colourise_body(Body, TB, Pos).
  952
  953control_op(',').
  954control_op((;)).
  955control_op((->)).
  956control_op((*->)).

 colourise_goals(+Body, +Origin, +TB, +Pos)

Colourise the goals in a body.

  962colourise_goals(_, _, _, Pos) :-
  963    var(Pos),
  964    !.
  965colourise_goals(Body, Origin, TB, parentheses_term_position(PO,PC,Pos)) :-
  966    !,
  967    colour_item(parentheses, TB, PO-PC),
  968    colourise_goals(Body, Origin, TB, Pos).
  969colourise_goals(Body, Origin, TB, term_position(_,_,FF,FT,ArgPos)) :-
  970    body_compiled(Body),
  971    !,
  972    colour_item(control, TB, FF-FT),
  973    colourise_subgoals(ArgPos, 1, Body, Origin, TB).
  974colourise_goals(Goal, Origin, TB, Pos) :-
  975    colourise_goal(Goal, Origin, TB, Pos).
  976
  977colourise_subgoals([], _, _, _, _).
  978colourise_subgoals([Pos|T], N, Body, Origin, TB) :-
  979    arg(N, Body, Arg),
  980    colourise_goals(Arg, Origin, TB, Pos),
  981    NN is N + 1,
  982    colourise_subgoals(T, NN, Body, Origin, TB).

 colourise_dcg(+Body, +Head, +TB, +Pos)

Breaks down to colourise_dcg_goal/3.

  988colourise_dcg(Body, Head, TB, Pos) :-
  989    colour_item(dcg, TB, Pos),
  990    (   dcg_extend(Head, Origin)
  991    ->  true
  992    ;   Origin = Head
  993    ),
  994    colourise_dcg_goals(Body, Origin, TB, Pos).
  995
  996colourise_dcg_goals(Var, _, TB, Pos) :-
  997    var(Var),
  998    !,
  999    colour_item(goal(meta,Var), TB, Pos).
 1000colourise_dcg_goals(_, _, _, Pos) :-
 1001    var(Pos),
 1002    !.
 1003colourise_dcg_goals(Body, Origin, TB, parentheses_term_position(PO,PC,Pos)) :-
 1004    !,
 1005    colour_item(parentheses, TB, PO-PC),
 1006    colourise_dcg_goals(Body, Origin, TB, Pos).
 1007colourise_dcg_goals({Body}, Origin, TB, brace_term_position(F,T,Arg)) :-
 1008    !,
 1009    colour_item(dcg(plain), TB, F-T),
 1010    colourise_goals(Body, Origin, TB, Arg).
 1011colourise_dcg_goals([], _, TB, Pos) :-
 1012    !,
 1013    colour_item(dcg(terminal), TB, Pos).
 1014colourise_dcg_goals(List, _, TB, list_position(F,T,Elms,Tail)) :-
 1015    List = [_|_],
 1016    !,
 1017    colour_item(dcg(terminal), TB, F-T),
 1018    colourise_list_args(Elms, Tail, List, TB, classify).
 1019colourise_dcg_goals(_, _, TB, string_position(F,T)) :-
 1020    integer(F),
 1021    !,
 1022    colour_item(dcg(string), TB, F-T).
 1023colourise_dcg_goals(Body, Origin, TB, term_position(_,_,FF,FT,ArgPos)) :-
 1024    dcg_body_compiled(Body),       % control structures
 1025    !,
 1026    colour_item(control, TB, FF-FT),
 1027    colourise_dcg_subgoals(ArgPos, 1, Body, Origin, TB).
 1028colourise_dcg_goals(Goal, Origin, TB, Pos) :-
 1029    colourise_dcg_goal(Goal, Origin, TB, Pos).
 1030
 1031colourise_dcg_subgoals([], _, _, _, _).
 1032colourise_dcg_subgoals([Pos|T], N, Body, Origin, TB) :-
 1033    arg(N, Body, Arg),
 1034    colourise_dcg_goals(Arg, Origin, TB, Pos),
 1035    NN is N + 1,
 1036    colourise_dcg_subgoals(T, NN, Body, Origin, TB).
 1037
 1038dcg_extend(Term, _) :-
 1039    var(Term), !, fail.
 1040dcg_extend(M:Term, M:Goal) :-
 1041    dcg_extend(Term, Goal).
 1042dcg_extend(Term, Goal) :-
 1043    compound(Term),
 1044    !,
 1045    compound_name_arguments(Term, Name, Args),
 1046    append(Args, [_,_], NArgs),
 1047    compound_name_arguments(Goal, Name, NArgs).
 1048dcg_extend(Term, Goal) :-
 1049    atom(Term),
 1050    !,
 1051    compound_name_arguments(Goal, Term, [_,_]).
 1052
 1053dcg_body_compiled(G) :-
 1054    body_compiled(G),
 1055    !.
 1056dcg_body_compiled((_|_)).
 1057
 1058%       colourise_dcg_goal(+Goal, +Origin, +TB, +Pos).
 1059
 1060colourise_dcg_goal(!, Origin, TB, TermPos) :-
 1061    !,
 1062    colourise_goal(!, Origin, TB, TermPos).
 1063colourise_dcg_goal(Goal, Origin, TB, TermPos) :-
 1064    dcg_extend(Goal, TheGoal),
 1065    !,
 1066    colourise_goal(TheGoal, Origin, TB, TermPos).
 1067colourise_dcg_goal(Goal, _, TB, Pos) :-
 1068    colourise_term_args(Goal, TB, Pos).

 colourise_goal(+Goal, +Origin, +TB, +Pos)

Colourise access to a single goal.

To be done

- Quasi Quotations are coloured as a general term argument. Possibly we should do something with the goal information it refers to, in particular if this goal is not defined.

 1079                                        % Deal with list as goal (consult)
 1080colourise_goal(_,_,_,Pos) :-
 1081    var(Pos),
 1082    !.
 1083colourise_goal(Goal, Origin, TB, parentheses_term_position(PO,PC,Pos)) :-
 1084    !,
 1085    colour_item(parentheses, TB, PO-PC),
 1086    colourise_goal(Goal, Origin, TB, Pos).
 1087colourise_goal(Goal, _, TB, Pos) :-
 1088    Pos = list_position(F,T,Elms,TailPos),
 1089    Goal = [_|_],
 1090    !,
 1091    FT is F + 1,
 1092    AT is T - 1,
 1093    colour_item(goal_term(built_in, Goal), TB, Pos),
 1094    colour_item(goal(built_in, Goal), TB, F-FT),
 1095    colour_item(goal(built_in, Goal), TB, AT-T),
 1096    colourise_file_list(Goal, TB, Elms, TailPos, any).
 1097colourise_goal(Goal, Origin, TB, Pos) :-
 1098    Pos = list_position(F,T,Elms,Tail),
 1099    callable(Goal),
 1100    Goal =.. [_,GH,GT|_],
 1101    !,
 1102    goal_classification(TB, Goal, Origin, Class),
 1103    FT is F + 1,
 1104    AT is T - 1,
 1105    colour_item(goal_term(Class, Goal), TB, Pos),
 1106    colour_item(goal(Class, Goal), TB, F-FT),
 1107    colour_item(goal(Class, Goal), TB, AT-T),
 1108    colourise_list_args(Elms, Tail, [GH|GT], TB, classify).
 1109colourise_goal(Goal, _Origin, TB, Pos) :-
 1110    Pos = quasi_quotation_position(_F,_T,_QQType,_QQTypePos,_CPos),
 1111    !,
 1112    colourise_term_arg(Goal, TB, Pos).
 1113colourise_goal(#(Macro), Origin, TB, term_position(_,_,HF,HT,[MPos])) :-
 1114    expand_macro(TB, Macro, Goal),
 1115    !,
 1116    macro_term_string(Goal, String),
 1117    goal_classification(TB, Goal, Origin, Class),
 1118    (   MPos = term_position(_,_,FF,FT,_ArgPos)
 1119    ->  FPos = FF-FT
 1120    ;   FPos = MPos
 1121    ),
 1122    colour_item(macro(String), TB, HF-HT),
 1123    colour_item(goal_term(Class, Goal), TB, MPos),
 1124    colour_item(goal(Class, Goal), TB, FPos),
 1125    colourise_goal_args(Goal, TB, MPos).
 1126colourise_goal(Goal, Origin, TB, Pos) :-
 1127    strip_module(Goal, _, PGoal),
 1128    nonvar(PGoal),
 1129    (   goal_classification(TB, Goal, Origin, ClassInferred),
 1130        call_goal_colours(Goal, ClassInferred, ClassSpec-ArgSpecs)
 1131    ->  true
 1132    ;   call_goal_colours(Goal, ClassSpec-ArgSpecs)
 1133    ),
 1134    !,                                          % specified
 1135    functor_position(Pos, FPos, ArgPos),
 1136    (   ClassSpec == classify
 1137    ->  goal_classification(TB, Goal, Origin, Class)
 1138    ;   Class = ClassSpec
 1139    ),
 1140    colour_item(goal_term(Class, Goal), TB, Pos),
 1141    colour_item(goal(Class, Goal), TB, FPos),
 1142    colour_dict_braces(TB, Pos),
 1143    specified_items(ArgSpecs, Goal, TB, ArgPos).
 1144colourise_goal(Module:Goal, _Origin, TB, QGoalPos) :-
 1145    QGoalPos = term_position(_,_,QF,QT,[PM,PG]),
 1146    !,
 1147    colourise_module(Module, TB, PM),
 1148    colour_item(functor, TB, QF-QT),
 1149    (   PG = term_position(_,_,FF,FT,_)
 1150    ->  FP = FF-FT
 1151    ;   FP = PG
 1152    ),
 1153    (   callable(Goal)
 1154    ->  qualified_goal_classification(Module:Goal, TB, Class),
 1155        colour_item(goal_term(Class, Goal), TB, QGoalPos),
 1156        colour_item(goal(Class, Goal), TB, FP),
 1157        colourise_goal_args(Goal, Module, TB, PG)
 1158    ;   var(Goal)
 1159    ->  colourise_term_arg(Goal, TB, PG)
 1160    ;   colour_item(type_error(callable), TB, PG)
 1161    ).
 1162colourise_goal(Op, _Origin, TB, Pos) :-
 1163    nonvar(Op),
 1164    Op = op(_,_,_),
 1165    !,
 1166    colourise_op_declaration(Op, TB, Pos).
 1167colourise_goal(Goal, Origin, TB, Pos) :-
 1168    goal_classification(TB, Goal, Origin, Class),
 1169    (   Pos = term_position(_,_,FF,FT,_ArgPos)
 1170    ->  FPos = FF-FT
 1171    ;   FPos = Pos
 1172    ),
 1173    colour_item(goal_term(Class, Goal), TB, Pos),
 1174    colour_item(goal(Class, Goal), TB, FPos),
 1175    colourise_goal_args(Goal, TB, Pos).
 1176
 1177% make sure to emit a fragment for the braces of tag{k:v, ...} or
 1178% {...} that is mapped to something else.
 1179
 1180colour_dict_braces(TB, dict_position(_F,T,_TF,TT,_KVPos)) :-
 1181    !,
 1182    BStart is TT+1,
 1183    colour_item(dict_content, TB, BStart-T).
 1184colour_dict_braces(_, _).

 colourise_goal_args(+Goal, +TB, +Pos)

Colourise the arguments to a goal. This predicate deals with meta- and database-access predicates.

 1191colourise_goal_args(Goal, TB, Pos) :-
 1192    colourization_module(TB, Module),
 1193    colourise_goal_args(Goal, Module, TB, Pos).
 1194
 1195colourization_module(TB, Module) :-
 1196    (   colour_state_source_id(TB, SourceId),
 1197        xref_module(SourceId, Module)
 1198    ->  true
 1199    ;   Module = user
 1200    ).
 1201
 1202colourise_goal_args(Goal, M, TB, term_position(_,_,_,_,ArgPos)) :-
 1203    !,
 1204    (   meta_args(Goal, TB, MetaArgs)
 1205    ->  colourise_meta_args(1, Goal, M, MetaArgs, TB, ArgPos)
 1206    ;   colourise_goal_args(1, Goal, M, TB, ArgPos)
 1207    ).
 1208colourise_goal_args(Goal, M, TB, brace_term_position(_,_,ArgPos)) :-
 1209    !,
 1210    (   meta_args(Goal, TB, MetaArgs)
 1211    ->  colourise_meta_args(1, Goal, M, MetaArgs, TB, [ArgPos])
 1212    ;   colourise_goal_args(1, Goal, M, TB, [ArgPos])
 1213    ).
 1214colourise_goal_args(_, _, _, _).                % no arguments
 1215
 1216colourise_goal_args(_, _, _, _, []) :- !.
 1217colourise_goal_args(N, Goal, Module, TB, [P0|PT]) :-
 1218    colourise_option_arg(Goal, Module, N, TB, P0),
 1219    !,
 1220    NN is N + 1,
 1221    colourise_goal_args(NN, Goal, Module, TB, PT).
 1222colourise_goal_args(N, Goal, Module, TB, [P0|PT]) :-
 1223    arg(N, Goal, Arg),
 1224    colourise_term_arg(Arg, TB, P0),
 1225    NN is N + 1,
 1226    colourise_goal_args(NN, Goal, Module, TB, PT).
 1227
 1228
 1229colourise_meta_args(_, _, _, _, _, []) :- !.
 1230colourise_meta_args(N, Goal, Module, MetaArgs, TB, [P0|PT]) :-
 1231    colourise_option_arg(Goal, Module, N, TB, P0),
 1232    !,
 1233    NN is N + 1,
 1234    colourise_meta_args(NN, Goal, Module, MetaArgs, TB, PT).
 1235colourise_meta_args(N, Goal, Module, MetaArgs, TB, [P0|PT]) :-
 1236    arg(N, Goal, Arg),
 1237    arg(N, MetaArgs, MetaSpec),
 1238    colourise_meta_arg(MetaSpec, Arg, TB, P0),
 1239    NN is N + 1,
 1240    colourise_meta_args(NN, Goal, Module, MetaArgs, TB, PT).
 1241
 1242colourise_meta_arg(MetaSpec, Arg, TB, Pos) :-
 1243    nonvar(Arg),
 1244    expand_meta(MetaSpec, Arg, Expanded),
 1245    !,
 1246    colourise_goal(Expanded, [], TB, Pos). % TBD: recursion
 1247colourise_meta_arg(MetaSpec, Arg, TB, Pos) :-
 1248    nonvar(Arg),
 1249    MetaSpec == //,
 1250    !,
 1251    colourise_dcg_goals(Arg, //, TB, Pos).
 1252colourise_meta_arg(_, Arg, TB, Pos) :-
 1253    colourise_term_arg(Arg, TB, Pos).

 meta_args(+Goal, +TB, -ArgSpec) is semidet

Return a copy of Goal, where each meta-argument is an integer representing the number of extra arguments or the atom // for indicating a DCG body. The non-meta arguments are unbound variables.

E.g. meta_args(maplist(foo,x,y), X) --> X = maplist(2,_,_)

NOTE: this could be cached if performance becomes an issue.

 1266meta_args(Goal, TB, VarGoal) :-
 1267    colour_state_source_id(TB, SourceId),
 1268    xref_meta(SourceId, Goal, _),
 1269    !,
 1270    compound_name_arity(Goal, Name, Arity),
 1271    compound_name_arity(VarGoal, Name, Arity),
 1272    xref_meta(SourceId, VarGoal, MetaArgs),
 1273    instantiate_meta(MetaArgs).
 1274
 1275instantiate_meta([]).
 1276instantiate_meta([H|T]) :-
 1277    (   var(H)
 1278    ->  H = 0
 1279    ;   H = V+N
 1280    ->  V = N
 1281    ;   H = //(V)
 1282    ->  V = (//)
 1283    ),
 1284    instantiate_meta(T).

 expand_meta(+MetaSpec, +Goal, -Expanded) is semidet

Add extra arguments to the goal if the meta-specifier is an integer (see above).

 1291expand_meta(MetaSpec, Goal, Goal) :-
 1292    MetaSpec == 0.
 1293expand_meta(MetaSpec, M:Goal, M:Expanded) :-
 1294    atom(M),
 1295    !,
 1296    expand_meta(MetaSpec, Goal, Expanded).
 1297expand_meta(MetaSpec, Goal, Expanded) :-
 1298    integer(MetaSpec),
 1299    MetaSpec > 0,
 1300    (   atom(Goal)
 1301    ->  functor(Expanded, Goal, MetaSpec)
 1302    ;   compound(Goal)
 1303    ->  compound_name_arguments(Goal, Name, Args0),
 1304        length(Extra, MetaSpec),
 1305        append(Args0, Extra, Args),
 1306        compound_name_arguments(Expanded, Name, Args)
 1307    ).

 colourise_setof(+Term, +TB, +Pos)

Colourise the 2nd argument of setof/bagof

 1313colourise_setof(Var^G, TB, term_position(_,_,FF,FT,[VP,GP])) :-
 1314    !,
 1315    colourise_term_arg(Var, TB, VP),
 1316    colour_item(ext_quant, TB, FF-FT),
 1317    colourise_setof(G, TB, GP).
 1318colourise_setof(Term, TB, Pos) :-
 1319    colourise_goal(Term, [], TB, Pos).
 1320
 1321%       colourise_db(+Arg, +TB, +Pos)
 1322%
 1323%       Colourise database modification calls (assert/1, retract/1 and
 1324%       friends.
 1325
 1326colourise_db((Head:-Body), TB, term_position(_,_,_,_,[HP,BP])) :-
 1327    !,
 1328    colourise_db(Head, TB, HP),
 1329    colourise_body(Body, Head, TB, BP).
 1330colourise_db(Module:Head, TB, term_position(_,_,QF,QT,[MP,HP])) :-
 1331    !,
 1332    colourise_module(Module, TB, MP),
 1333    colour_item(functor, TB, QF-QT),
 1334    (   atom(Module),
 1335        colour_state_source_id(TB, SourceId),
 1336        xref_module(SourceId, Module)
 1337    ->  colourise_db(Head, TB, HP)
 1338    ;   colourise_db(Head, TB, HP)
 1339    ).
 1340colourise_db(Head, TB, Pos) :-
 1341    colourise_goal(Head, '<db-change>', TB, Pos).

 colourise_option_args(+Goal, +Module, +Arg:integer, +TB, +ArgPos) is semidet

Colourise predicate options for the Arg-th argument of Module:Goal

 1350colourise_option_arg(Goal, Module, Arg, TB, ArgPos) :-
 1351    goal_name_arity(Goal, Name, Arity),
 1352    current_option_arg(Module:Name/Arity, Arg),
 1353    current_predicate_options(Module:Name/Arity, Arg, OptionDecl),
 1354    debug(emacs, 'Colouring option-arg ~w of ~p',
 1355          [Arg, Module:Name/Arity]),
 1356    arg(Arg, Goal, Options),
 1357    colourise_option(Options, Module, Goal, Arg, OptionDecl, TB, ArgPos).
 1358
 1359colourise_option(Options0, Module, Goal, Arg, OptionDecl, TB, Pos0) :-
 1360    strip_option_module_qualifier(Goal, Module, Arg, TB,
 1361                                  Options0, Pos0, Options, Pos),
 1362    (   Pos = list_position(F, T, ElmPos, TailPos)
 1363    ->  colour_item(list, TB, F-T),
 1364        colourise_option_list(Options, OptionDecl, TB, ElmPos, TailPos)
 1365    ;   (   var(Options)
 1366        ;   Options == []
 1367        )
 1368    ->  colourise_term_arg(Options, TB, Pos)
 1369    ;   colour_item(type_error(list), TB, Pos)
 1370    ).
 1371
 1372strip_option_module_qualifier(Goal, Module, Arg, TB,
 1373                              M:Options, term_position(_,_,_,_,[MP,Pos]),
 1374                              Options, Pos) :-
 1375    predicate_property(Module:Goal, meta_predicate(Head)),
 1376    arg(Arg, Head, :),
 1377    !,
 1378    colourise_module(M, TB, MP).
 1379strip_option_module_qualifier(_, _, _, _,
 1380                              Options, Pos, Options, Pos).
 1381
 1382
 1383colourise_option_list(_, _, _, [], none) :- !.
 1384colourise_option_list(Tail, _, TB, [], TailPos) :-
 1385    !,
 1386    colourise_term_arg(Tail, TB, TailPos).
 1387colourise_option_list([H|T], OptionDecl, TB, [HPos|TPos], TailPos) :-
 1388    colourise_option(H, OptionDecl, TB, HPos),
 1389    colourise_option_list(T, OptionDecl, TB, TPos, TailPos).
 1390
 1391colourise_option(Opt, _, TB, Pos) :-
 1392    var(Opt),
 1393    !,
 1394    colourise_term_arg(Opt, TB, Pos).
 1395colourise_option(Opt, OptionDecl, TB, term_position(_,_,FF,FT,ValPosList)) :-
 1396    !,
 1397    generalise_term(Opt, GenOpt),
 1398    (   memberchk(GenOpt, OptionDecl)
 1399    ->  colour_item(option_name, TB, FF-FT),
 1400        Opt =.. [Name|Values],
 1401        GenOpt =.. [Name|Types],
 1402        colour_option_values(Values, Types, TB, ValPosList)
 1403    ;   colour_item(no_option_name, TB, FF-FT),
 1404        colourise_term_args(ValPosList, 1, Opt, TB)
 1405    ).
 1406colourise_option(_, _, TB, Pos) :-
 1407    colour_item(type_error(option), TB, Pos).
 1408
 1409colour_option_values([], [], _, _).
 1410colour_option_values([V0|TV], [T0|TT], TB, [P0|TP]) :-
 1411    (   (   var(V0)
 1412        ;   is_of_type(T0, V0)
 1413        ;   T0 = list(_),
 1414            member(E, V0),
 1415            var(E)
 1416        ;   dict_field_extraction(V0)
 1417        )
 1418    ->  colourise_term_arg(V0, TB, P0)
 1419    ;   callable(V0),
 1420        (   T0 = callable
 1421        ->  N = 0
 1422        ;   T0 = (callable+N)
 1423        )
 1424    ->  colourise_meta_arg(N, V0, TB, P0)
 1425    ;   colour_item(type_error(T0), TB, P0)
 1426    ),
 1427    colour_option_values(TV, TT, TB, TP).