Did you know ... Search Documentation:
toplevel.pl
PublicShow source
Source version is det
Print the Prolog banner message and messages registered using version/1.
Source version(+Message) is det
Add message to version/0
Source load_init_file(+ScriptMode) is det[private]
Load the user customization file. This can be done using swipl -f file or simply using swipl. In the first case we search the file both directly and over the alias user_app_config. In the latter case we only use the alias.
Source loaded_init_file(?Base, ?AbsFile)[private]
Used by prolog_load_context/2 to confirm we are loading a script.
Source initialization :Goal
Runs Goal after loading the file in which this directive appears as well as after restoring a saved state.
See also
- initialization/2
Source initialize
Run goals registered with :- initialization(Goal, program).. Stop with an exception if a goal fails or raises an exception.
Source thread_initialization :Goal
Run Goal now and everytime a new thread is created.
Source $set_file_search_paths is det[private]
Process -p PathSpec options.
Source argv_prolog_files(-Files, -ScriptMode) is det[private]
Update the Prolog flag argv, extracting the leading script files. This is called after the C based parser removed Prolog options such as -q, -f none, etc. These options are availabkle through '$cmd_option_val'/2.

Our task is to update the Prolog flag argv and return a list of the files to be loaded. The rules are:

  • If we find -- all remaining options must go to argv
  • If we find *.pl files, these are added to Files and possibly remaining arguments are "script" arguments.
  • If we find an existing file, this is Files and possibly remaining arguments are "script" arguments.
  • File we find [search:]name, find search(name) as Prolog file, make this the content of Files and pass the remainder as options to argv.
Arguments:
ScriptMode- is one of
exe
Program is a saved state
prolog
One or more *.pl files on commandline
script
Single existing file on commandline
app
[path:]cli-name on commandline
none
Normal interactive session
Source win_associated_files(+Files)[private]
If SWI-Prolog is started as <exe> <file>.<ext>, where <ext> is the extension registered for associated files, set the Prolog flag associated_file, switch to the directory holding the file and -if possible- adjust the window title.
Source set_working_directory(+File)[private]
When opening as a GUI application, e.g., by opening a file from the Finder/Explorer/..., we typically want to change working directory to the location of the primary file. We currently detect that we are a GUI app by the Prolog flag console_menu, which is set by swipl-win[.exe].
Source start_pldoc[private]
If the option --pldoc[=port] is given, load the PlDoc system.
Source load_associated_files(+Files)[private]
Load Prolog files specified from the commandline.
Source $initialise is semidet
Called from PL_initialise() to do the Prolog part of the initialization. If an exception occurs, this is printed and '$initialise' fails.
Source run_init_goals(+Goals) is det[private]
Run registered initialization goals on order. If a goal fails, execution is halted.
Source run_program_init is det[private]
Run goals registered using
Source init_debug_flags is det[private]
Initialize the various Prolog flags that control the debugger and toplevel.
Source setup_backtrace[private]
Initialise printing a backtrace.
Source setup_colors is det[private]
Setup interactive usage by enabling colored output.
Source setup_history[private]
Enable per-directory persistent history.
Source setup_readline[private]
Setup line editing.
Source load_setup_file(+File) is semidet[private]
Load a file and fail silently if the file does not exist.
Source $toplevel
Called from PL_toplevel()
Source $runtoplevel[private]
Actually run the toplevel. The values default and prolog both start the interactive toplevel, where prolog implies the user gave -t prolog.
See also
- prolog/0 is the default interactive toplevel
Source $compile
Toplevel called when invoked with -c option.
Source $config
Toplevel when invoked with --dump-runtime-variables
Source prolog:repl_loop_hook(+BeginEnd, +BreakLevel) is nondet[multifile]
Multifile hook that allows acting on starting/stopping the interactive REPL loop. Called as
forall(prolog:repl_loop_hook(BeginEnd, BreakLevel), true)
Arguments:
BeginEnd- is one of begin or end
BreakLevel- is 0 for the normal toplevel, -1 when non-interactive and >0 for break environments.
Source prolog
Run the Prolog toplevel. This is now the same as break/0, which pretends to be in a break-level if there is a parent environment.
Source $query_loop
Run the normal Prolog query loop. Note that the query is not protected by catch/3. Dealing with unhandled exceptions is done by the C-function query_loop(). This ensures that unhandled exceptions are really unhandled (in Prolog).
Source read_query(+Prompt, -Goal, -Bindings) is det[private]
Read the next query. The first clause deals with the case where !-based history is enabled. The second is used if we have command line editing.
Source read_query_line(+Input, -Line) is det[private]
Source read_term_as_atom(+Input, -Line)[private]
Read the next term as an atom and skip to the newline or a non-space character.
Source skip_to_nl(+Input) is det[private]
Read input after the term. Skips white space and %... comment until the end of the line or a non-blank character.
Source set_default_history[private]
Enable !-based numbered command history. This is enabled by default if we are not running under GNU-emacs and we do not have our own line editing.
Source save_debug_after_read[private]
Called right after the toplevel read to save the debug status if it was modified from the GUI thread using e.g.
thread_signal(main, gdebug)
bug
- Ideally, the prompt would change if debug mode is enabled. That is hard to realise with all the different console interfaces supported by SWI-Prolog.
Source $execute_query(Goal, Bindings, -Truth) is det
Execute Goal using Bindings.
Source write_bindings(+Bindings, +ResidueVars, +Delays, +DetOrChp) is semidet[private]
Write bindings resulting from a query. The flag prompt_alternatives_on determines whether the user is prompted for alternatives. groundness gives the classical behaviour, determinism is considered more adequate and informative.

Succeeds if the user accepts the answer and fails otherwise.

Arguments:
ResidueVars- are the residual constraints and provided if the prolog flag toplevel_residue_vars is set to project.
Source name_vars(+Bindings, +Term) is det[private]
Give a name _[A-Z][0-9]* to all variables in Term, that do not have a name due to Bindings. Singleton variables in Term are named _. The behavior depends on these Prolog flags:
toplevel_name_variables
Only act when true, else name_vars/2 is a no-op.
toplevel_print_anon

Variables are named by unifying them to '$VAR'(Name)

Arguments:
Bindings- is a list Name=Value
Source residual_goals(:NonTerminal)
Directive that registers NonTerminal as a collector for residual goals.
Source prolog:residual_goals// is det
DCG that collects residual goals that are not associated with the answer through attributed variables.
Source prolog:translate_bindings(+Bindings0, -Bindings, +ResidueVars, +ResidualGoals, -Residuals) is det
Translate the raw variable bindings resulting from successfully completing a query into a binding list and list of residual goals suitable for human consumption.
Arguments:
Bindings- is a list of binding(Vars,Value,Substitutions), where Vars is a list of variable names. E.g. binding(['A','B'],42,[])` means that both the variable A and B have the value 42. Values may contain terms '$VAR'(Name) to indicate sharing with a given variable. Value is always an acyclic term. If cycles appear in the answer, Substitutions contains a list of substitutions that restore the original term.
Residuals- is a pair of two lists representing residual goals. The first element of the pair are residuals related to the query variables and the second are related that are disconnected from the query.
Source project_constraints(+Bindings, +ResidueVars) is det[private]
Call <module>:project_attributes/2 if the Prolog flag toplevel_residue_vars is set to project.
Source join_same_bindings(Bindings0, Bindings)[private]
Join variables that are bound to the same value. Note that we return the last value. This is because the factorization may be different and ultimately the names will be printed as V1 = V2, ... VN = Value. Using the last, Value has the factorization of VN.
Source omit_qualifiers(+QGoals, +TypeIn, -Goals) is det[private]
Omit unneeded module qualifiers from QGoals relative to the given module TypeIn.
Source bind_vars(+BindingsIn, -Bindings)[private]
Bind variables to '$VAR'(Name), so they are printed by the names used in the query. Note that by binding in the reverse order, variables bound to one another come out in the natural order.
Source bind_one_skel_vars(+Subst, +Bindings, +VarName, +N0, -N)[private]
Give names to the factorized variables that do not have a name yet. This introduces names _S<N>, avoiding duplicates. If a factorized variable shares with another binding, use the name of that variable.
To be done
- Consider the call below. We could remove either of the A = x(1). Which is best?
?- A = x(1), B = a(A,A).
A = x(1),
B = a(A, A), % where
    A = x(1).
Source factorize_bindings(+Bindings0, -Factorized)[private]
Factorize cycles and sharing in the bindings.
Source filter_bindings(+Bindings0, -Bindings)[private]
Remove bindings that must not be printed. There are two of them: Variables whose name start with '_' and variables that are only bound to themselves (or, unbound).
Source get_respons(-Action, +Chp)[private]
Read the continuation entered by the user.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

Source $thread_init