View source with formatted comments or as raw
    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)  1985-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('$autoload',
   39          [ '$find_library'/5,
   40            '$in_library'/3,
   41            '$define_predicate'/1,
   42            '$update_library_index'/1,          % +Options
   43            '$autoload'/1,
   44
   45            make_library_index/1,
   46            make_library_index/2,
   47            reload_library_index/0,
   48            autoload_path/1,
   49
   50            autoload/1,                         % +File
   51            autoload/2,                         % +File, +Imports
   52
   53            autoload_call/1,                    % :Goal
   54
   55            require/1                           % +Predicates
   56          ]).   57
   58:- meta_predicate
   59    '$autoload'(:),
   60    autoload(:),
   61    autoload(:, +),
   62    autoload_call(0),
   63    require(:).   64
   65:- dynamic
   66    library_index/3,                % Head x Module x Path
   67    autoload_directories/1,         % List
   68    index_checked_at/1.             % Time
   69:- volatile
   70    library_index/3,
   71    autoload_directories/1,
   72    index_checked_at/1.   73
   74user:file_search_path(autoload, swi(library)).
   75user:file_search_path(autoload, pce(prolog/lib)).
   76user:file_search_path(autoload, app_config(lib)).
   77user:file_search_path(autoload, Dir) :-
   78    '$ext_library_directory'(Dir).
   79
   80:- create_prolog_flag(warn_autoload, false, []).   81
   82%!  '$find_library'(+Module, +Name, +Arity, -LoadModule, -Library) is semidet.
   83%
   84%   Locate a predicate in the library. Name   and arity are the name
   85%   and arity of  the  predicate  searched   for.  `Module'  is  the
   86%   preferred target module. The return  values   are  the full path
   87%   name (excluding extension) of the library and module declared in
   88%   that file.
   89
   90'$find_library'(_Module, :, 2, _LoadModule, _Library) :-
   91    !, fail.
   92'$find_library'(Module, Name, Arity, LoadModule, Library) :-
   93    load_library_index(Name, Arity),
   94    functor(Head, Name, Arity),
   95    (   library_index(Head, Module, Library),
   96        LoadModule = Module
   97    ;   library_index(Head, LoadModule, Library)
   98    ),
   99    !.
  100
  101%!  '$in_library'(+Name, +Arity, -Path) is semidet.
  102%!  '$in_library'(-Name, -Arity, -Path) is nondet.
  103%
  104%   Is true if Name/Arity is in the autoload libraries.
  105
  106'$in_library'(Name, Arity, Path) :-
  107    atom(Name), integer(Arity),
  108    !,
  109    Name/Arity \= (:)/2,
  110    load_library_index(Name, Arity),
  111    functor(Head, Name, Arity),
  112    library_index(Head, _, Path).
  113'$in_library'(Name, Arity, Path) :-
  114    load_library_index(Name, Arity),
  115    library_index(Head, _, Path),
  116    Head \= _:_,
  117    functor(Head, Name, Arity).
  118
  119%!  '$define_predicate'(:Head)
  120%
  121%   Make sure PredInd can be called. First  test if the predicate is
  122%   defined. If not, invoke the autoloader.
  123
  124:- meta_predicate
  125    '$define_predicate'(:).  126
  127'$define_predicate'(Head) :-
  128    '$defined_predicate'(Head),
  129    !.
  130'$define_predicate'(Term) :-
  131    Term = Module:Head,
  132    (   compound(Head)
  133    ->  compound_name_arity(Head, Name, Arity)
  134    ;   Name = Head, Arity = 0
  135    ),
  136    '$undefined_procedure'(Module, Name, Arity, retry).
  137
  138
  139                /********************************
  140                *          UPDATE INDEX         *
  141                ********************************/
  142
  143:- thread_local
  144    silent/0.  145
  146%!  '$update_library_index'(+Options)
  147%
  148%   Called from make/0 to update the index   of the library for each
  149%   library directory that has a writable   index.  Note that in the
  150%   Windows  version  access_file/2  is  mostly   bogus.  We  assert
  151%   silent/0 to suppress error messages.  Options:
  152%
  153%       - system(+Boolean)
  154%         Do (not) include system libraries.   Default `false`.
  155%       - user(+Boolean)
  156%         Do (not) include user libraries.  Default `true`.
  157
  158'$update_library_index'(Options) :-
  159    setof(Dir, writable_indexed_directory(Dir, Options), Dirs),
  160    !,
  161    setup_call_cleanup(
  162        asserta(silent, Ref),
  163        guarded_make_library_index(Dirs),
  164        erase(Ref)),
  165    (   flag('$modified_index', true, false)
  166    ->  reload_library_index
  167    ;   true
  168    ).
  169'$update_library_index'(_).
  170
  171guarded_make_library_index([]).
  172guarded_make_library_index([Dir|Dirs]) :-
  173    (   catch(make_library_index(Dir), E,
  174              print_message(error, E))
  175    ->  true
  176    ;   print_message(warning, goal_failed(make_library_index(Dir)))
  177    ),
  178    guarded_make_library_index(Dirs).
  179
  180%!  writable_indexed_directory(-Dir, +Options) is nondet.
  181%
  182%   True when Dir is an indexed   library  directory with a writable
  183%   index, i.e., an index that can be updated.
  184
  185writable_indexed_directory(Dir, Options) :-
  186    current_prolog_flag(home, Home),
  187    writable_indexed_directory(Dir),
  188    (   sub_atom(Dir, 0, _, _, Home)
  189    ->  '$option'(system(true), Options, false)
  190    ;   '$option'(user(true), Options, true)
  191    ).
  192
  193writable_indexed_directory(Dir) :-
  194    index_file_name(IndexFile, autoload('INDEX'), [access([read,write])]),
  195    file_directory_name(IndexFile, Dir).
  196writable_indexed_directory(Dir) :-
  197    absolute_file_name(library('MKINDEX'),
  198                       [ file_type(prolog),
  199                         access(read),
  200                         solutions(all),
  201                         file_errors(fail)
  202                       ], MkIndexFile),
  203    file_directory_name(MkIndexFile, Dir),
  204    plfile_in_dir(Dir, 'INDEX', _, IndexFile),
  205    access_file(IndexFile, write).
  206
  207
  208                /********************************
  209                *           LOAD INDEX          *
  210                ********************************/
  211
  212%!  reload_library_index
  213%
  214%   Reload the index on the next call
  215
  216reload_library_index :-
  217    context_module(M),
  218    reload_library_index(M).
  219
  220reload_library_index(M) :-
  221    with_mutex('$autoload', clear_library_index(M)).
  222
  223clear_library_index(M) :-
  224    retractall(M:library_index(_, _, _)),
  225    retractall(M:autoload_directories(_)),
  226    retractall(M:index_checked_at(_)).
  227
  228
  229%!  load_library_index(?Name, ?Arity) is det.
  230%!  load_library_index(?Name, ?Arity, :IndexSpec) is det.
  231%
  232%   Try to find Name/Arity  in  the   library.  If  the predicate is
  233%   there, we are happy. If not, we  check whether the set of loaded
  234%   libraries has changed and if so we reload the index.
  235
  236:- meta_predicate load_library_index(?, ?, :).  237:- public load_library_index/3.  238
  239load_library_index(Name, Arity) :-
  240    load_library_index(Name, Arity, autoload('INDEX')).
  241
  242load_library_index(Name, Arity, M:_Spec) :-
  243    atom(Name), integer(Arity),
  244    functor(Head, Name, Arity),
  245    M:library_index(Head, _, _),
  246    !.
  247load_library_index(_, _, Spec) :-
  248    notrace(with_mutex('$autoload', load_library_index_p(Spec))).
  249
  250load_library_index_p(M:_) :-
  251    M:index_checked_at(Time),
  252    get_time(Now),
  253    Now-Time < 60,
  254    !.
  255load_library_index_p(M:Spec) :-
  256    findall(Index, index_file_name(Index, Spec, [access(read)]), List0),
  257    '$list_to_set'(List0, List),
  258    retractall(M:index_checked_at(_)),
  259    get_time(Now),
  260    assert(M:index_checked_at(Now)),
  261    (   M:autoload_directories(List)
  262    ->  true
  263    ;   retractall(M:library_index(_, _, _)),
  264        retractall(M:autoload_directories(_)),
  265        read_index(List, M),
  266        assert(M:autoload_directories(List))
  267    ).
  268
  269%!  index_file_name(-IndexFile, +Spec, +Options) is nondet.
  270%
  271%   True if IndexFile is an autoload   index file. Options is passed
  272%   to  absolute_file_name/3.  This  predicate   searches  the  path
  273%   =autoload=.
  274%
  275%   @see file_search_path/2.
  276
  277index_file_name(IndexFile, FileSpec, Options) :-
  278    absolute_file_name(FileSpec,
  279                       IndexFile,
  280                       [ file_type(prolog),
  281                         solutions(all),
  282                         file_errors(fail)
  283                       | Options
  284                       ]).
  285
  286read_index([], _) :- !.
  287read_index([H|T], M) :-
  288    !,
  289    read_index(H, M),
  290    read_index(T, M).
  291read_index(Index, M) :-
  292    print_message(silent, autoload(read_index(Dir))),
  293    file_directory_name(Index, Dir),
  294    setup_call_cleanup(
  295        '$push_input_context'(autoload_index),
  296        setup_call_cleanup(
  297            win_open_index(Index, In),
  298            read_index_from_stream(Dir, In, M),
  299            close(In)),
  300        '$pop_input_context').
  301
  302%!  win_open_index(+Index, -Stream) is det.
  303%
  304%   Open an INDEX.pl file. When concurrently   building the index we may
  305%   run into sharing violations on Windows.
  306
  307:- if(current_prolog_flag(windows, true)).  308win_open_index(Index, In) :-
  309    between(1, 10, _),
  310    catch(open(Index, read, In, [encoding(utf8)]),
  311          error(permission_error(open, source_sink, _),_), (sleep(0.1),fail)),
  312    !.
  313:- endif.  314win_open_index(Index, In) :-
  315    open(Index, read, In, [encoding(utf8)]).
  316
  317read_index_from_stream(Dir, In, M) :-
  318    repeat,
  319        read(In, Term),
  320        assert_index(Term, Dir, M),
  321    !.
  322
  323assert_index(end_of_file, _, _) :- !.
  324assert_index(index(Term, Module, File), Dir, M) :-
  325    !,
  326    atomic_list_concat([Dir, '/', File], Path),
  327    assertz(M:library_index(Term, Module, Path)),
  328    fail.
  329assert_index(index(Name, Arity, Module, File), Dir, M) :-
  330    !,                                          % Read old index format
  331    functor(Head, Name, Arity),
  332    head_meta_any(Head),
  333    assert_index(index(Head, Module, File), Dir, M).
  334assert_index(Term, Dir, _) :-
  335    print_message(error, illegal_autoload_index(Dir, Term)),
  336    fail.
  337
  338
  339                /********************************
  340                *       CREATE INDEX.pl         *
  341                ********************************/
  342
  343%!  make_library_index(+Dir) is det.
  344%
  345%   Create an index for autoloading  from   the  directory  Dir. The
  346%   index  file  is  called  INDEX.pl.  In    Dir  contains  a  file
  347%   MKINDEX.pl, this file is loaded and we  assume that the index is
  348%   created by directives that appearin   this  file. Otherwise, all
  349%   source  files  are  scanned  for  their  module-header  and  all
  350%   exported predicates are added to the autoload index.
  351%
  352%   @see make_library_index/2
  353
  354make_library_index(Dir0) :-
  355    forall(absolute_file_name(Dir0, Dir,
  356                              [ expand(true),
  357                                file_type(directory),
  358                                file_errors(fail),
  359                                solutions(all)
  360                              ]),
  361           make_library_index2(Dir)).
  362
  363make_library_index2(Dir) :-
  364    plfile_in_dir(Dir, 'MKINDEX', _MkIndex, AbsMkIndex),
  365    access_file(AbsMkIndex, read),
  366    !,
  367    load_files(user:AbsMkIndex, [silent(true)]).
  368make_library_index2(Dir) :-
  369    findall(Pattern, source_file_pattern(Pattern), PatternList),
  370    make_library_index2(Dir, PatternList).
  371
  372%!  make_library_index(+Dir, +Patterns:list(atom)) is det.
  373%
  374%   Create an autoload index INDEX.pl for  Dir by scanning all files
  375%   that match any of the file-patterns in Patterns. Typically, this
  376%   appears as a directive in MKINDEX.pl.  For example:
  377%
  378%   ```
  379%   :- prolog_load_context(directory, Dir),
  380%      make_library_index(Dir, ['*.pl']).
  381%   ```
  382%
  383%   @see make_library_index/1.
  384
  385make_library_index(Dir0, Patterns) :-
  386    forall(absolute_file_name(Dir0, Dir,
  387                              [ expand(true),
  388                                file_type(directory),
  389                                file_errors(fail),
  390                                solutions(all)
  391                              ]),
  392           make_library_index2(Dir, Patterns)).
  393
  394make_library_index2(Dir, Patterns) :-
  395    plfile_in_dir(Dir, 'INDEX', _Index, AbsIndex),
  396    ensure_slash(Dir, DirS),
  397    pattern_files(Patterns, DirS, Files),
  398    (   library_index_out_of_date(Dir, AbsIndex, Files)
  399    ->  do_make_library_index(AbsIndex, DirS, Files),
  400        set_flag('$modified_index', true)
  401    ;   true
  402    ).
  403
  404ensure_slash(Dir, DirS) :-
  405    (   sub_atom(Dir, _, _, 0, /)
  406    ->  DirS = Dir
  407    ;   atom_concat(Dir, /, DirS)
  408    ).
  409
  410source_file_pattern(Pattern) :-
  411    user:prolog_file_type(PlExt, prolog),
  412    PlExt \== qlf,
  413    atom_concat('*.', PlExt, Pattern).
  414
  415plfile_in_dir(Dir, Base, PlBase, File) :-
  416    file_name_extension(Base, pl, PlBase),
  417    atomic_list_concat([Dir, '/', PlBase], File).
  418
  419pattern_files([], _, []).
  420pattern_files([H|T], DirS, Files) :-
  421    atom_concat(DirS, H, P0),
  422    expand_file_name(P0, Files0),
  423    '$append'(Files0, Rest, Files),
  424    pattern_files(T, DirS, Rest).
  425
  426library_index_out_of_date(_Dir, Index, _Files) :-
  427    \+ exists_file(Index),
  428    !.
  429library_index_out_of_date(Dir, Index, Files) :-
  430    time_file(Index, IndexTime),
  431    (   time_file(Dir, DotTime),
  432        DotTime - IndexTime > 0.001             % compensate for jitter
  433    ;   '$member'(File, Files),                 % and rounding
  434        time_file(File, FileTime),
  435        FileTime - IndexTime > 0.001
  436    ),
  437    !.
  438
  439
  440do_make_library_index(Index, Dir, Files) :-
  441    ensure_slash(Dir, DirS),
  442    '$stage_file'(Index, StagedIndex),
  443    setup_call_catcher_cleanup(
  444        open(StagedIndex, write, Out),
  445        ( print_message(informational, make(library_index(Dir))),
  446          index_header(Out),
  447          index_files(Files, DirS, Out)
  448        ),
  449        Catcher,
  450        install_index(Out, Catcher, StagedIndex, Index)).
  451
  452install_index(Out, Catcher, StagedIndex, Index) :-
  453    catch(close(Out), Error, true),
  454    (   silent
  455    ->  OnError = silent
  456    ;   OnError = error
  457    ),
  458    (   var(Error)
  459    ->  TheCatcher = Catcher
  460    ;   TheCatcher = exception(Error)
  461    ),
  462    '$install_staged_file'(TheCatcher, StagedIndex, Index, OnError).
  463
  464%!  index_files(+Files, +Directory, +Out:stream) is det.
  465%
  466%   Write index for Files in Directory to the stream Out.
  467
  468index_files([], _, _).
  469index_files([File|Files], DirS, Fd) :-
  470    (   catch(exports(File, Module, Exports, Meta, Public), E,
  471              print_message(warning, E)),
  472        nonvar(Module)
  473    ->  atom_concat(DirS, Local, File),
  474        file_name_extension(Base, _, Local),
  475        forall(index_term(Exports, Meta, Public, Term),
  476               format(Fd, 'index(~k, ~k, ~k).~n',
  477                      [Term, Module, Base]))
  478    ;   true
  479    ),
  480    index_files(Files, DirS, Fd).
  481
  482index_term(Exports, Meta, _Public, Term) :-
  483    '$member'(Export, Exports),
  484    ground(Export),
  485    export_term(Export, Meta, Term).
  486index_term(_Exports, _Meta, Publics, (public):Head) :-
  487    '$member'(Public, Publics),
  488    '$pi_head'(Public, Head).
  489
  490export_term(Op, _Meta, Term) :-
  491    Op = op(_Pri,_Type,_Name),
  492    !,
  493    Term = op:Op.
  494export_term(PI, Meta, Head) :-
  495    '$pi_head'(PI, Head),
  496    (   '$member'(Head, Meta)
  497    ->  true
  498    ;   head_meta_any(Head)
  499    ).
  500
  501head_meta_any(Head) :-
  502    (   atom(Head)
  503    ->  true
  504    ;   compound_name_arguments(Head, _, Args),
  505        meta_any(Args)
  506    ).
  507
  508meta_any([]).
  509meta_any([?|T]) :-
  510    meta_any(T).
  511
  512index_header(Fd):-
  513    format(Fd, '/*  Creator: make/0~n~n', []),
  514    format(Fd, '    Purpose: Provide index for autoload~n', []),
  515    format(Fd, '*/~n~n', []).
  516
  517%!  exports(+File, -Module, -Exports) is det.
  518%!  exports(+File, -Module, -Exports, -Meta) is det.
  519%
  520%   Get the exports from a library as  a   list  of PIs. Exports are all
  521%   exports of the module header (including  op/3 terms) and encountered
  522%   export/1  directives.  Meta  are  all    heads  in  meta_predicate/1
  523%   declarations.
  524
  525:- public exports/3.                            % using by library(prolog_deps).
  526exports(File, Module, Exports) :-
  527    exports(File, Module, Exports, _Meta, _Public).
  528
  529exports(File, Module, Exports, Meta, Public) :-
  530    setup_call_cleanup(
  531        push_prolog_flag(xref, true),
  532        snapshot(exports_(File, Module, Exports, Meta, Public)),
  533        pop_prolog_flag(xref)).
  534
  535exports_(File, Module, Exports, Meta, Public) :-
  536    State = state(true, _, [], [], []),
  537    (   '$source_term'(File,
  538                       _Read,_RLayout,
  539                       Term,_TermLayout,
  540                       _Stream,
  541                       [ syntax_errors(quiet)
  542                       ]),
  543        (   Term = (:- module(M,ModuleExports)),
  544            is_list(ModuleExports),
  545            arg(1, State, true)
  546        ->  nb_setarg(1, State, false),
  547            nb_setarg(2, State, M),
  548            nb_setarg(3, State, ModuleExports),
  549            fail
  550        ;   nb_setarg(1, State, false),
  551            fail
  552        ;   Term = (:- export(Export))
  553        ->  phrase(export_pi(Export), PIs),
  554            arg(3, State, E0),
  555            '$append'(E0, PIs, E1),
  556            nb_setarg(3, State, E1),
  557            fail
  558        ;   Term = (:- public(Public))
  559        ->  phrase(export_pi(Public), PIs),
  560            arg(5, State, E0),
  561            '$append'(E0, PIs, E1),
  562            nb_setarg(5, State, E1),
  563            fail
  564        ;   Term = (:- meta_predicate(Heads)),
  565            phrase(meta(Heads), M1),
  566            arg(4, State, M0),
  567            '$append'(M0, M1, M2),
  568            nb_setarg(4, State, M2)
  569        ;   Term = (:- use_foreign_library(Lib)),
  570            nonvar(Lib),
  571            arg(2, State, M),
  572            atom(M)
  573        ->  catch('$syspreds':use_foreign_library_noi(M:Lib), error(_,_), true),
  574            fail
  575        ;   Term = (:- Directive),
  576            nonvar(Directive)
  577        ->  fail
  578        ;   Term == []                          % Expansion for conditionals
  579        ->  fail
  580        ;   !
  581        )
  582    ;   true
  583    ),
  584    arg(2, State, Module),
  585    arg(3, State, Exports),
  586    arg(4, State, Meta),
  587    arg(5, State, Public).
  588
  589export_pi(Var) -->
  590    { var(Var) },
  591    !.
  592export_pi((A,B)) -->
  593    !,
  594    export_pi(A),
  595    export_pi(B).
  596export_pi(PI) -->
  597    { ground(PI) },
  598    [PI].
  599
  600meta(Var) -->
  601    { var(Var) },
  602    !.
  603meta((A,B)) -->
  604    !,
  605    meta(A),
  606    meta(B).
  607meta(Head) -->
  608    { callable(Head) },
  609    [Head].
  610
  611
  612                 /*******************************
  613                 *            EXTENDING         *
  614                 *******************************/
  615
  616%!  autoload_path(+Path) is det.
  617%
  618%   Add Path to the libraries that are  used by the autoloader. This
  619%   extends the search  path  =autoload=   and  reloads  the library
  620%   index.  For example:
  621%
  622%     ==
  623%     :- autoload_path(library(http)).
  624%     ==
  625%
  626%   If this call appears as a directive,  it is term-expanded into a
  627%   clause  for  user:file_search_path/2  and  a  directive  calling
  628%   reload_library_index/0. This keeps source information and allows
  629%   for removing this directive.
  630
  631autoload_path(Alias) :-
  632    (   user:file_search_path(autoload, Alias)
  633    ->  true
  634    ;   assertz(user:file_search_path(autoload, Alias)),
  635        reload_library_index
  636    ).
  637
  638system:term_expansion((:- autoload_path(Alias)),
  639                      [ user:file_search_path(autoload, Alias),
  640                        (:- reload_library_index)
  641                      ]).
  642
  643
  644		 /*******************************
  645		 *      RUNTIME AUTOLOADER	*
  646		 *******************************/
  647
  648%!  $autoload'(:PI) is semidet.
  649%
  650%   Provide PI by autoloading.  This checks:
  651%
  652%     - Explicit autoload/2 declarations
  653%     - Explicit autoload/1 declarations
  654%     - The library if current_prolog_flag(autoload, true) holds.
  655
  656'$autoload'(PI) :-
  657    source_location(File, _Line),
  658    !,
  659    setup_call_cleanup(
  660        '$start_aux'(File, Context),
  661        '$autoload2'(PI),
  662        '$end_aux'(File, Context)).
  663'$autoload'(PI) :-
  664    '$autoload2'(PI).
  665
  666'$autoload2'(PI) :-
  667    setup_call_cleanup(
  668        leave_sandbox(Old),
  669        '$autoload3'(PI),
  670        restore_sandbox(Old)).
  671
  672leave_sandbox(Sandboxed) :-
  673    current_prolog_flag(sandboxed_load, Sandboxed),
  674    set_prolog_flag(sandboxed_load, false).
  675restore_sandbox(Sandboxed) :-
  676    set_prolog_flag(sandboxed_load, Sandboxed).
  677
  678'$autoload3'(PI) :-
  679    autoload_from(PI, LoadModule, FullFile),
  680    do_autoload(FullFile, PI, LoadModule).
  681
  682%!  autoload_from(+PI, -LoadModule, -PlFile) is semidet.
  683%
  684%   True when PI can be defined  by   loading  File which is defined the
  685%   module LoadModule.
  686
  687autoload_from(Module:PI, LoadModule, FullFile) :-
  688    autoload_in(Module, explicit),
  689    current_autoload(Module:File, Ctx, import(Imports)),
  690    memberchk(PI, Imports),
  691    in_module_dialect(Module,
  692                      library_info(File, Ctx, FullFile, LoadModule, Exports)),
  693    (   pi_in_exports(PI, Exports)
  694    ->  !
  695    ;   autoload_error(Ctx, not_exported(PI, File, FullFile, Exports)),
  696        fail
  697    ).
  698autoload_from(Module:Name/Arity, LoadModule, FullFile) :-
  699    autoload_in(Module, explicit),
  700    PI = Name/Arity,
  701    current_autoload(Module:File, Ctx, all),
  702    in_module_dialect(Module,
  703                      library_info(File, Ctx, FullFile, LoadModule, Exports)),
  704    pi_in_exports(PI, Exports).
  705autoload_from(Module:Name/Arity, LoadModule, Library) :-
  706    autoload_in(Module, general),
  707    '$find_library'(Module, Name, Arity, LoadModule, Library).
  708
  709%!  in_module_dialect(+Module, :Goal) is semidet.
  710%
  711%   Run Goal in the dialect of Module.  System and library modules are
  712%   written for SWI-Prolog, so their autoload/1,2 declarations must be
  713%   resolved in the `swi` dialect, also if the application has called
  714%   expects_dialect/1.  Otherwise, e.g., library(lists) resolves to
  715%   library(dialect/sicstus/lists) if the SICStus dialect is active.
  716
  717in_module_dialect(Module, Goal) :-
  718    current_prolog_flag(emulated_dialect, Dialect),
  719    Dialect \== swi,
  720    '$module_property'(Module, class(Class)),
  721    swi_module_class(Class),
  722    !,
  723    setup_call_cleanup(
  724        set_prolog_flag(emulated_dialect, swi),
  725        once(Goal),
  726        set_prolog_flag(emulated_dialect, Dialect)).
  727in_module_dialect(_, Goal) :-
  728    once(Goal).
  729
  730swi_module_class(system).
  731swi_module_class(library).
  732
  733:- public autoload_in/2.                        % used in syspred
  734
  735autoload_in(Module, How) :-
  736    current_prolog_flag(autoload, AutoLoad),
  737    autoload_in(AutoLoad, How, Module),
  738    !.
  739
  740%!  autoload_in(+AutoloadFlag, +AutoloadMode, +TargetModule) is semidet.
  741
  742autoload_in(true,             _,        _).
  743autoload_in(explicit,         explicit, _).
  744autoload_in(user,             _,        user).
  745autoload_in(user_or_explicit, explicit, _).
  746autoload_in(user_or_explicit, _,        user).
  747
  748
  749%!  do_autoload(Library, :PI, +LoadModule) is det.
  750%
  751%   Load File, importing PI into the qualified  module. File is known to
  752%   define LoadModule. There are three cases:
  753%
  754%     - The target is the autoload module itself.  Uncommon.
  755%     - We already loaded this module. Note that
  756%       '$get_predicate_attribute'/3 alone is not enough as it will
  757%       consider auto-import from `user`. '$c_current_predicate'/2
  758%       verifies the predicate really exists, but doesn't validate
  759%       that it is defined.
  760%     - We must load the module and import the target predicate.
  761%
  762%   @arg Library is an absolute file   name, either without extension or
  763%   with the source (.pl) extension.
  764
  765do_autoload(Library, Module:Name/Arity, LoadModule) :-
  766    functor(Head, Name, Arity),
  767    '$update_autoload_level'([autoload(true)], Old),
  768    verbose_autoload(Module:Name/Arity, Library),
  769    loadable_file(Library, File),
  770    '$compilation_mode'(OldComp, database),
  771    (   Module == LoadModule
  772    ->  ensure_loaded(Module:File)
  773    ;   (   '$c_current_predicate'(_, LoadModule:Head),
  774            '$get_predicate_attribute'(LoadModule:Head, defined, 1),
  775            \+ '$loading'(Library)
  776        ->  Module:import(LoadModule:Name/Arity)
  777        ;   use_module(Module:File, [Name/Arity])
  778        ),
  779        warn_autoload(Module, LoadModule:Name/Arity)
  780    ),
  781    '$set_compilation_mode'(OldComp),
  782    '$set_autoload_level'(Old),
  783    '$c_current_predicate'(_, Module:Head).
  784
  785loadable_file(PlFile, File) :-
  786    exists_file(PlFile), !,
  787    File = PlFile.
  788loadable_file(PlFile, Base) :-
  789    file_name_extension(Base, pl, PlFile),
  790    !.
  791loadable_file(File, File).
  792
  793verbose_autoload(PI, Library) :-
  794    current_prolog_flag(verbose_autoload, true),
  795    !,
  796    set_prolog_flag(verbose_autoload, false),
  797    print_message(informational, autoload(PI, Library)),
  798    set_prolog_flag(verbose_autoload, true).
  799verbose_autoload(PI, Library) :-
  800    print_message(silent, autoload(PI, Library)).
  801
  802%!  autoload_call(:Goal)
  803%
  804%   Call Goal, optionally autoloading it first.
  805
  806autoload_call(Goal) :-
  807    '$pi_head'(PI, Goal),
  808    (   current_predicate(PI)
  809    ->  true
  810    ;   '$autoload'(PI)
  811    ),
  812    call(Goal).
  813
  814%!  autoloadable(:Head, -File) is nondet.
  815%
  816%   True when Head can be  autoloaded   from  File.  This implements the
  817%   predicate_property/2 property autoload(File).  The   module  must be
  818%   instantiated.
  819
  820:- public                               % used from predicate_property/2
  821    autoloadable/2.  822
  823autoloadable(M:Head, FullFile) :-
  824    atom(M),
  825    current_module(M),
  826    autoload_in(M, explicit),
  827    (   callable(Head)
  828    ->  goal_name_arity(Head, Name, Arity),
  829        autoload_from(M:Name/Arity, _, FullFile)
  830    ;   findall((M:H)-F, autoloadable_2(M:H, F), Pairs),
  831        (   '$member'(M:Head-FullFile, Pairs)
  832        ;   current_autoload(M:File, Ctx, all),
  833            library_info(File, Ctx, FullFile, _, Exports),
  834            '$member'(PI, Exports),
  835            '$pi_head'(PI, Head),
  836            \+ memberchk(M:Head-_, Pairs)
  837        )
  838    ).
  839autoloadable(M:Head, FullFile) :-
  840    (   var(M)
  841    ->  autoload_in(any, general)
  842    ;   autoload_in(M, general)
  843    ),
  844    (   callable(Head)
  845    ->  goal_name_arity(Head, Name, Arity),
  846        (   '$find_library'(_, Name, Arity, _, FullFile)
  847        ->  true
  848        )
  849    ;   '$in_library'(Name, Arity, autoload),
  850        functor(Head, Name, Arity)
  851    ).
  852
  853
  854autoloadable_2(M:Head, FullFile) :-
  855    current_autoload(M:File, Ctx, import(Imports)),
  856    library_info(File, Ctx, FullFile, _LoadModule, _Exports),
  857    '$member'(PI, Imports),
  858    '$pi_head'(PI, Head).
  859
  860goal_name_arity(Head, Name, Arity) :-
  861    compound(Head),
  862    !,
  863    compound_name_arity(Head, Name, Arity).
  864goal_name_arity(Head, Head, 0).
  865
  866%!  library_info(+Spec, +AutoloadContext, -FullFile, -Module, -Exports)
  867%
  868%   Find information about a library. Spec  is the file specification as
  869%   it appears in the  autoload/1,2  call.   AutoloadContext  is  a term
  870%   File:Line, providing the location of the directive.
  871%
  872%   @arg FullFile is the source (.pl) file in canonical (absolute)
  873%   notation.
  874%   @arg Module is the module defined in FullFile
  875%   @arg Exports is a list of predicate indicators.
  876
  877library_info(Spec, _, FullFile, Module, Exports) :-
  878    '$resolved_source_path'(Spec, FullFile, []),
  879    !,
  880    (   \+ '$loading_file'(FullFile, _Queue, _LoadThread)
  881    ->  '$current_module'(Module, FullFile),
  882        '$module_property'(Module, exports(Exports))
  883    ;   library_info_from_file(FullFile, _, Module, Exports)
  884    ).
  885library_info(Spec, Context, FullFile, Module, Exports) :-
  886    (   Context = (Path:_Line)
  887    ->  Extra = [relative_to(Path)]
  888    ;   Extra = []
  889    ),
  890    (   absolute_file_name(Spec, AbsFile,
  891                           [ file_type(prolog),
  892                             access(read),
  893                             file_errors(fail)
  894                           | Extra
  895                           ])
  896    ->  library_info_from_file(AbsFile, FullFile, Module, Exports),
  897        '$register_resolved_source_path'(Spec, FullFile)
  898    ;   absolute_file_name(Spec, FullFile,
  899                           [ file_type(prolog),
  900                             solutions(all),
  901                             file_errors(fail)
  902                           | Extra
  903                           ]),
  904        source_file(FullFile),
  905        '$current_module'(Module, FullFile)
  906    ->  '$module_property'(Module, exports(Exports))
  907    ;   autoload_error(Context, no_file(Spec)),
  908        fail
  909    ).
  910
  911library_info_from_file(QlfFile, PlFile, Module, Exports) :-
  912    file_name_extension(_, qlf, QlfFile),
  913    !,
  914    '$qlf_module'(QlfFile, Info),
  915    _{module:Module, exports:Exports, file:PlFile} :< Info.
  916library_info_from_file(PlFile, PlFile, Module, Exports) :-
  917    setup_call_cleanup(
  918        '$set_source_module'(OldModule, system),
  919        setup_call_cleanup(
  920            '$open_source'(PlFile, In, State, [], []),
  921            '$term_in_file'(In, _Read, _RLayout, Term, _TLayout, _Stream,
  922                            [PlFile], []),
  923            '$close_source'(State, true)),
  924        '$set_source_module'(OldModule)),
  925    (   Term = (:- module(Module, Exports))
  926    ->  !
  927    ;   nonvar(Term),
  928        skip_header(Term)
  929    ->  fail
  930    ;   '$domain_error'(module_header, Term)
  931    ).
  932
  933skip_header(begin_of_file).
  934
  935
  936:- dynamic printed/3.  937:- volatile printed/3.  938
  939autoload_error(Context, Error) :-
  940    suppress(Context, Error),
  941    !.
  942autoload_error(Context, Error) :-
  943    get_time(Now),
  944    assertz(printed(Context, Error, Now)),
  945    print_message(warning, error(autoload(Error), autoload(Context))).
  946
  947suppress(Context, Error) :-
  948    printed(Context, Error, Printed),
  949    get_time(Now),
  950    (   Now - Printed < 1
  951    ->  true
  952    ;   retractall(printed(Context, Error, _)),
  953        fail
  954    ).
  955
  956
  957		 /*******************************
  958		 *            CALLBACK		*
  959		 *******************************/
  960
  961:- public
  962    set_autoload/1.  963
  964%!  set_autoload(+Value) is det.
  965%
  966%   Hook called from set_prolog_flag/2 when  autoloading is switched. If
  967%   the desired value is `false` we   should  materialize all registered
  968%   requests for autoloading. We must do so before disabling autoloading
  969%   as loading the files may require autoloading.
  970
  971set_autoload(FlagValue) :-
  972    current_prolog_flag(autoload, FlagValue),
  973    !.
  974set_autoload(FlagValue) :-
  975    \+ autoload_in(FlagValue, explicit, any),
  976    !,
  977    setup_call_cleanup(
  978        nb_setval('$autoload_disabling', true),
  979        materialize_autoload(Count),
  980        nb_delete('$autoload_disabling')),
  981    print_message(informational, autoload(disabled(Count))).
  982set_autoload(_).
  983
  984materialize_autoload(Count) :-
  985    State = state(0),
  986    forall(current_predicate(M:'$autoload'/3),
  987           materialize_autoload(M, State)),
  988    arg(1, State, Count).
  989
  990materialize_autoload(M, State) :-
  991    (   current_autoload(M:File, Context, Import),
  992        library_info(File, Context, PlFile, _LoadModule, _Exports),
  993        arg(1, State, N0),
  994        N is N0+1,
  995        nb_setarg(1, State, N),
  996        loadable_file(PlFile, LoadFile),
  997        (   Import == all
  998        ->  verbose_autoload(M:all, PlFile),
  999            use_module(M:LoadFile)
 1000        ;   Import = import(Preds)
 1001        ->  verbose_autoload(M:Preds, PlFile),
 1002            use_module(M:LoadFile, Preds)
 1003        ),
 1004        fail
 1005    ;   true
 1006    ),
 1007    abolish(M:'$autoload'/3).
 1008
 1009
 1010		 /*******************************
 1011		 *          AUTOLOAD/2		*
 1012		 *******************************/
 1013
 1014autoload(M:File) :-
 1015    (   \+ autoload_in(M, explicit)
 1016    ;   nb_current('$autoload_disabling', true)
 1017    ),
 1018    !,
 1019    use_module(M:File).
 1020autoload(M:File) :-
 1021    '$must_be'(filespec, File),
 1022    source_context(Context),
 1023    assert_autoload(M, File, Context, all).
 1024
 1025autoload(M:File, Imports) :-
 1026    (   \+ autoload_in(M, explicit)
 1027    ;   nb_current('$autoload_disabling', true)
 1028    ),
 1029    !,
 1030    use_module(M:File, Imports).
 1031autoload(M:File, Imports0) :-
 1032    '$must_be'(filespec, File),
 1033    valid_imports(Imports0, Imports),
 1034    source_context(Context),
 1035    register_autoloads(Imports, M, File, Context),
 1036    assert_autoload(M, File, Context, import(Imports)).
 1037
 1038source_context(Path:Line) :-
 1039    source_location(Path, Line),
 1040    !.
 1041source_context(-).
 1042
 1043%!  assert_autoload(+Module, +File, +Context, +Imports) is det.
 1044%
 1045%   Assert that Module can autoload  predicates   defines  in Imports by
 1046%   loading File. Context provides the file owner of the declaration.
 1047%
 1048%   @arg Imports is either `all`  or   imports(List).  That latter comes
 1049%   from an autoload/2 directive.
 1050
 1051assert_autoload(Module, File, _, Imports) :-
 1052    current_autoload(Module:File, _, Imports),
 1053    !.
 1054assert_autoload(Module, File, Context, Imports) :-
 1055    set_admin_properties(Module),
 1056    Clause = Module:'$autoload'(File, Context, Imports),
 1057    '$initialization_context'(Source, Ctx),
 1058    '$store_admin_clause2'(Clause, _Layout, Source, Ctx).
 1059
 1060set_admin_properties(Module) :-
 1061    predicate_property(Module:'$autoload'(_,_,_), discontiguous),
 1062    !.
 1063set_admin_properties(Module) :-
 1064    discontiguous(Module:'$autoload'/3).
 1065
 1066valid_imports(Imports0, Imports) :-
 1067    '$must_be'(list, Imports0),
 1068    valid_import_list(Imports0, Imports).
 1069
 1070valid_import_list([], []).
 1071valid_import_list([H0|T0], [H|T]) :-
 1072    '$pi_head'(H0, Head),
 1073    '$pi_head'(H, Head),
 1074    valid_import_list(T0, T).
 1075
 1076%!  register_autoloads(+ListOfPI, +Module, +File, +Context)
 1077%
 1078%   Put an `autoload` flag on all   predicates declared using autoload/2
 1079%   to prevent duplicates or the user defining the same predicate.
 1080%
 1081%   @arg File is the first argument of autoload/1,2
 1082
 1083register_autoloads([], _, _, _).
 1084register_autoloads([PI|T], Module, File, Context) :-
 1085    PI = Name/Arity,
 1086    functor(Head, Name, Arity),
 1087    (   '$get_predicate_attribute'(Module:Head, autoload, 1)
 1088    ->  (   current_autoload(Module:_File0, _Ctx0, import(Imports)),
 1089            memberchk(PI, Imports)
 1090        ->  '$permission_error'(redefine, imported_procedure, PI),
 1091            fail
 1092        ;   Done = true
 1093        )
 1094    ;   '$c_current_predicate'(_, Module:Head), % no auto-import
 1095        '$get_predicate_attribute'(Module:Head, imported, From)
 1096    ->  (   (   '$resolved_source_path'(File, FullFile)
 1097            ->  true
 1098            ;   '$resolve_source_path'(File, FullFile, [])
 1099            ),
 1100            module_property(From, file(FullFile))
 1101        ->  Done = true
 1102        ;   print_message(warning,
 1103                          autoload(already_defined(Module:PI, From))),
 1104            Done = true
 1105        )
 1106    ;   true
 1107    ),
 1108    (   Done == true
 1109    ->  true
 1110    ;   '$set_predicate_attribute'(Module:Head, autoload, 1)
 1111    ),
 1112    register_autoloads(T, Module, File, Context).
 1113
 1114pi_in_exports(PI, Exports) :-
 1115    '$member'(E, Exports),
 1116    canonical_pi(E, PI),
 1117    !.
 1118
 1119canonical_pi(Var, _) :-
 1120    var(Var), !, fail.
 1121canonical_pi(Name/Arity, Name/Arity).
 1122canonical_pi(Name//A0,   Name/Arity) :-
 1123    Arity is A0 + 2.
 1124
 1125current_autoload(M:File, Context, Term) :-
 1126    '$get_predicate_attribute'(M:'$autoload'(_,_,_), defined, 1),
 1127    M:'$autoload'(File, Context, Term).
 1128
 1129		 /*******************************
 1130		 *            CHECK		*
 1131		 *******************************/
 1132
 1133%!  warn_autoload(+TargetModule, :PI) is det.
 1134%
 1135%   @arg PI is of the shape LoadModule:Name/Arity.
 1136
 1137warn_autoload(TargetModule, PI) :-
 1138    current_prolog_flag(warn_autoload, true),
 1139    \+ current_prolog_flag(xref, true),
 1140    \+ nb_current('$autoload_warning', true),
 1141    \+ nowarn_autoload(TargetModule, PI),
 1142    '$pi_head'(PI, Head),
 1143    source_file(Head, File),
 1144    '$source_defines_expansion'(File),
 1145    setup_call_cleanup(
 1146        b_setval('$autoload_warning', true),
 1147        print_message(warning,
 1148                      deprecated(autoload(TargetModule, File, PI, expansion))),
 1149        nb_delete('$autoload_warning')).
 1150warn_autoload(_, _).
 1151
 1152%!  nowarn_autoload(+TargetModule, +LoadModulePI) is semidet.
 1153%
 1154%   True when LoadModule:'$nowarn_autoload'(PI,TargetModule)  is defined
 1155%   and true.
 1156%
 1157%   @tbd As is, these  facts  must  be   defined  by  the  library being
 1158%   autoloaded. Possibly we want a specific autoload declaration. As all
 1159%   this only affects the Prolog libraries,   we can always change this.
 1160%   One option might be this, where `How`   is one of `true`, `false` or
 1161%   `warning`.
 1162%
 1163%      :- autoloadable(PI, How)
 1164
 1165nowarn_autoload(TargetModule, LoadModule:PI) :-
 1166    NoWarn = LoadModule:'$nowarn_autoload'(PI,TargetModule),
 1167    '$c_current_predicate'(_, NoWarn),
 1168    \+ '$get_predicate_attribute'(NoWarn, imported, _From),
 1169    call(NoWarn).
 1170
 1171
 1172                 /*******************************
 1173                 *             REQUIRE          *
 1174                 *******************************/
 1175
 1176%!  require(:ListOfPredIndicators) is det.
 1177%
 1178%   Register the predicates  in   ListOfPredIndicators  for  autoloading
 1179%   using autoload/2 if they are not system predicates.
 1180
 1181require(M:Spec) :-
 1182    (   is_list(Spec)
 1183    ->  List = Spec
 1184    ;   phrase(comma_list(Spec), List)
 1185    ), !,
 1186    require(List, M, FromLib),
 1187    keysort(FromLib, Sorted),
 1188    by_file(Sorted, Autoload),
 1189    forall('$member'(File-Import, Autoload),
 1190           autoload(M:File, Import)).
 1191require(_:Spec) :-
 1192    '$type_error'(list, Spec).
 1193
 1194require([],_, []).
 1195require([H|T], M, Needed) :-
 1196   '$pi_head'(H, Head),
 1197   (   '$get_predicate_attribute'(system:Head, defined, 1)
 1198   ->  require(T, M, Needed)
 1199   ;   '$pi_head'(Module:Name/Arity, M:Head),
 1200       (   '$find_library'(Module, Name, Arity, LoadModule, Library)
 1201       ->  (   current_predicate(LoadModule:Name/Arity)
 1202           ->  Module:import(LoadModule:Name/Arity),
 1203               require(T, M, Needed)
 1204           ;   Needed = [Library-H|More],
 1205               require(T, M, More)
 1206           )
 1207       ;   print_message(error, error(existence_error(procedure, Name/Arity), _)),
 1208           require(T, M, Needed)
 1209       )
 1210   ).
 1211
 1212by_file([], []).
 1213by_file([File-PI|T0], [Spec-[PI|PIs]|T]) :-
 1214    on_path(File, Spec),
 1215    same_file(T0, File, PIs, T1),
 1216    by_file(T1, T).
 1217
 1218on_path(Library, library(Base)) :-
 1219    file_base_name(Library, Base),
 1220    findall(Path, plain_source(library(Base), Path), [Library]),
 1221    !.
 1222on_path(Library, Library).
 1223
 1224plain_source(Spec, Path) :-
 1225    absolute_file_name(Spec, PathExt,
 1226                       [ file_type(prolog),
 1227                         access(read),
 1228                         file_errors(fail),
 1229                         solutions(all)
 1230                       ]),
 1231    file_name_extension(Path, _, PathExt).
 1232
 1233same_file([File-PI|T0], File, [PI|PIs], T) :-
 1234    !,
 1235    same_file(T0, File, PIs, T).
 1236same_file(List, _, [], List).
 1237
 1238comma_list(Var) -->
 1239    { var(Var),
 1240      !,
 1241      '$instantiation_error'(Var)
 1242    }.
 1243comma_list((A,B)) -->
 1244    !,
 1245    comma_list(A),
 1246    comma_list(B).
 1247comma_list(A) -->
 1248    [A]