#+title:                 Sweep: SWI-Prolog Embedded in Emacs
#+author:                Eshel Yaron
#+email:                 me@eshelyaron.com
#+language:              en
#+options:               ':t toc:nil author:t email:t num:nil ^:{}
#+startup:               content indent
#+export_file_name:      sweep.texi
#+texinfo_filename:      sweep.info
#+texinfo_dir_category:  Emacs
#+texinfo_dir_title:     Sweep: (sweep)
#+texinfo_dir_desc:      SWI-Prolog Embedded in Emacs
#+texinfo_header:        @set MAINTAINERSITE @uref{https://eshelyaron.com,maintainer webpage}
#+texinfo_header:        @set MAINTAINER Eshel Yaron
#+texinfo_header:        @set MAINTAINEREMAIL @email{me@eshelyaron.com}
#+texinfo_header:        @set MAINTAINERCONTACT @uref{mailto:me@eshelyaron.com,contact the maintainer}

This manual describes the Emacs package Sweep (or =sweeprolog.el=),
which provides an embedded SWI-Prolog runtime inside of Emacs.

#+toc: headlines 8 insert TOC here, with eight headline levels

* Overview
:PROPERTIES:
:CUSTOM_ID: overview
:DESCRIPTION: Major mode for reading and writing Prolog
:ALT_TITLE: Overview
:END:

Sweep is an embedding of SWI-Prolog in Emacs.  It provides an
interface for executing Prolog queries and consuming their results
from Emacs Lisp (see [[Querying Prolog]]).  Sweep further builds on top of
this interface and on top of the standard Emacs facilities to provide
advanced features for developing SWI-Prolog programs in Emacs.

** High-level Architecture
:PROPERTIES:
:CUSTOM_ID: high-level-architecture
:DESCRIPTION: Overall structure of this project
:ALT_TITLE: Architecture
:END:

Sweep uses the C interfaces of both SWI-Prolog and Emacs Lisp to
create a dynamically loaded Emacs module that contains the SWI-Prolog
runtime.  As such, Sweep has parts written in C, in Prolog and in
Emacs Lisp.

The different parts of Sweep are structured as follows:

#+CINDEX: sweep-module
- =sweep.c= defines a dynamic Emacs module which is referred to from
  Elisp as =sweep-module=. This module is linked against the SWI-Prolog
  runtime library (=libswipl=) and exposes a subset of the SWI-Prolog C
  interface to Emacs in the form of Elisp functions (see [[Querying
  Prolog]]). Notably, =sweep-module= is responsible for translating Elisp
  objects to Prolog terms and vice versa.

#+CINDEX: sweeprolog.el
- =sweeprolog.el= defines an Elisp library (named simply =sweeprolog=),
  which builds on top of =sweep-module= to provide user-facing commands
  and functionality. It is also responsible for loading =sweep-module=.

#+CINDEX: sweep.pl
- =sweep.pl= defines a Prolog module (named, unsurprisingly, Sweep)
  which is by default arranged by =sweeprolog.el= to be loaded when the
  embedded Prolog runtime is initialized. It contains predicates that
  =sweeprolog.el= invoke through =sweep-module= to facilitate its different
  commands (see [[Finding Prolog code]]).

* Installation
:PROPERTIES:
:CUSTOM_ID: installation
:DESCRIPTION: Intructions for installing sweep
:ALT_TITLE: Installation
:END:

#+CINDEX: install
The dynamic Emacs module =sweep-module= is included with SWI-Prolog
versions 8.5.18 and later.  For instructions on how to build and
install SWI-Prolog, see [[https://www.swi-prolog.org/build/]].

The =sweeprolog= Elisp package is available on NonGNU ELPA, to install
=sweeprolog= simply type =M-x package-install RET sweeprolog RET=.

An alternative to installing from ELPA is to get the Elisp library
from the Sweep Git repository:

1. Clone the Sweep repository:
   #+begin_src sh
     git clone https://git.sr.ht/~eshel/sweep
   #+end_src

   Or:

   #+begin_src sh
     git clone https://github.com/SWI-Prolog/packages-sweep sweep
   #+end_src

2. Add Sweep to Emacs's =load-path=:
   #+begin_src emacs-lisp
     (add-to-list 'load-path "/path/to/sweep")
   #+end_src

* Getting Started
:PROPERTIES:
:CUSTOM_ID: getting-started
:DESCRIPTION: First steps with sweep
:ALT_TITLE: Getting Started
:END:

#+CINDEX: configuration
After installing the =sweeprolog= Elisp library, load it into Emacs:

#+begin_src emacs-lisp
  (require 'sweeprolog)
#+end_src

#+VINDEX: sweeprolog-swipl-path
Sweep tries to find SWI-Prolog by looking for the =swipl= executable in
the directories listed in the Emacs variable ~exec-path~.  When Emacs is
started from a shell, ~exec-path~ is initialized from the shell's ~PATH~
environment variable which normally includes the location of =swipl= in
common SWI-Prolog installations.  If the =swipl= executable cannot be
found via ~exec-path~, you can tell Sweep where to find it by setting
the variable ~sweeprolog-swipl-path~ to point to it:

#+begin_src emacs-lisp
  (setq sweeprolog-swipl-path "/path/to/swipl")
#+end_src

All set!  =sweeprolog= automatically loads =sweep-module= and initializes
the embedded SWI-Prolog runtime.  For a description of the different
features of Sweep, see the following sections of this manual.

_Important note for Linux users_: prior to version 29, Emacs would load
dynamic modules in a way that is not fully compatible with the way the
SWI-Prolog native library, =libswipl=, loads its own native extensions.
This may lead to Sweep failing after loading =sweep-module=.  To work
around this issue, users running Emacs 28 or earlier on Linux can
start Emacs with =libswipl= loaded upfront via =LD_PRELOAD=, for example:

#+begin_src sh
  LD_PRELOAD=/usr/local/lib/libswipl.so emacs
#+end_src

* Prolog Initialization and Cleanup
:PROPERTIES:
:CUSTOM_ID: prolog-init
:DESCRIPTION: Functions for starting and stopping the embedded Prolog runtime
:ALT_TITLE: Initialization
:END:

The embedded SWI-Prolog runtime must be initialized before it can
start executing queries.  Initializing Prolog is usually taken care of
by Sweep when you first use a command that requires running some
Prolog code.  This section elaborates about Prolog initialization and
its customization options in Sweep:

- Function: sweeprolog-initialize prog &rest args :: Initialize the
  embedded Prolog runtime.  PROG should be the path to the =swipl=
  executable, and ARGS should be a list of strings denoting command
  line arguments for =swipl=.  They are used to initialize Prolog as if
  it was started from the command line as ~PROG ARGS~.
- Function: sweeprolog-handle-command-line-args :: Enable support for
  the Sweep specific ~--swipl-args~ Emacs command line flag.  This flag
  can be used to specify additional Prolog initialization arguments
  for Sweep to use when initializing Prolog on-demand, directly from
  Emacs's command line invocation.
- User Option: sweeprolog-init-args :: List of strings used as
  initialization arguments for Prolog.  Sweep uses these as the ARGS
  argument of ~sweeprolog-initialize~ when it initializes Prolog
  on-demand.
- Command: sweeprolog-restart :: Restart the embedded Prolog runtime.

In Sweep, Prolog initialization is done via
the C-implemented =sweeprolog-initialize= Elisp function defined in
=sweep-module=.  =sweeprolog-initialize= takes one or more arguments, which
must all be strings, and initializes the embedded Prolog as if it were
invoked externally in a command line with the given strings as command
line arguments, where the first argument to =sweeprolog-initialize=
corresponds to =argv[0]=.

Sweep loads and initializes Prolog on-demand at the first invocation
of a command that requires the embedded Prolog.  The arguments used to
initialize Prolog are then determined by the value of the user-option
~sweeprolog-init-args~ which the user is free to extend with e.g.:

#+begin_src emacs-lisp
  (add-to-list 'sweeprolog-init-args "--stack-limit=512m")
#+end_src

#+CINDEX: sweep Prolog flag
The default value of ~sweeprolog-init-args~ is set to load the Prolog
helper library =sweep.pl= and to create a boolean Prolog flag Sweep, set
to ~true~, which indicates to SWI-Prolog that it is running under Sweep.

#+CINDEX: command line arguments
It is also possible to specify initialization arguments to SWI-Prolog
by passing them as command line arguments to Emacs, which can be
convenient when using Emacs and Sweep as an alternative for the common
shell-based interaction with SWI-Prolog.  This is achieved by adding
the flag ~--swipl-args~ followed by any number of arguments intended for
SWI-Prolog, with a single semicolon (";") argument marking the end of
the SWI-Prolog arguments, after which further arguments are processed
by Emacs as usual (see [[info:emacs#Emacs Invocation][Emacs Invocation]] for more information about
Emacs's command line options), for example:

#+begin_src sh
  emacs --some-emacs-option --swipl-args -l foobar.pl \; --more-emacs-options
#+end_src

In order for Sweep to be able to handle Emacs's command line
arguments, the function ~sweeprolog-handle-command-line-args~ must be
called before Emacs processes the ~--swipl-args~ argument.  This can be
ensured by calling it from the command line as well:

#+begin_src sh
  emacs -f sweeprolog-handle-command-line-args --swipl-args -l foobar.pl \;
#+end_src

The embedded Prolog runtime can be reset using the command
~sweeprolog-restart~.  This command cleans up the the Prolog state and
resources, and starts it anew.  When called with a prefix argument
(~C-u M-x sweeprolog-restart~), this command prompts the user for
additional initialization arguments to pass to the embedded Prolog
runtime on startup.

* Querying Prolog
:PROPERTIES:
:CUSTOM_ID: querying-prolog
:DESCRIPTION: Functions for invoking Prolog predicates and consuming their results
:ALT_TITLE: Querying Prolog
:END:

This section describes a set of Elisp functions that let you invoke
Prolog queries and interact with the embedded Prolog runtime:

- Function: sweeprolog-open-query context module functor input reverse  :: Query
  the Prolog predicate MODULE:FUNCTOR/2 in the context of the module
  CONTEXT.  Converts INPUT to a Prolog term and uses it as the first
  argument, unless REVERSE is non-nil, in which can it uses INPUT as
  the second argument.  The other argument is called the output
  argument of the query, it is expected to be unified with some output
  that the query wants to return to Elisp.  The output argument can be
  retrieved with ~sweeprolog-next-solution~.  Always returns ~t~ if called
  with valid arguments, otherwise returns ~nil~.
- Function: sweeprolog-next-solution :: Return the next solution of
  the last Prolog query.  Returns a cons cell ~(DET . OUTPUT)~ if the
  query succeed, where ~DET~ is the symbol ~!~ if no choice points remain
  and ~t~ otherwise, and ~OUTPUT~ is the output argument of the query
  converted to an Elisp sexp.  If there are no more solutions, return
  ~nil~ instead.  If a Prolog exception was thrown, return a cons cell
  ~(exception . EXP)~ where ~EXP~ is the exception term converted to
  Elisp.
- Function: sweeprolog-cut-query :: Cut the last Prolog query.  This
  releases any resources reserved for it and makes further calls to
  ~sweeprolog-next-solution~ invalid until you open a new query.
- Function: sweeprolog-cut-query :: Close the last Prolog query.
  Similar to ~sweeprolog-cut-query~ expect that any unifications created
  by the last query are dropped.

Sweep provides the Elisp function =sweeprolog-open-query= for invoking Prolog
predicates.  The invoked predicate must be of arity two and will be
called in mode =p(+In, -Out)= i.e. the predicate should treat the first
argument as input and expect a variable for the second argument which
should be unified with some output.  This restriction is placed in
order to facilitate a natural calling convention between Elisp, a
functional language, and Prolog, a logical one.

The ~sweeprolog-open-query~ function takes five arguments, the first three
are strings which denote:
- The name of the Prolog context module from which to execute the
  query,
- The name of the module in which the invoked predicate is defined,
  and
- The name of the predicate to call.

The fourth argument to ~sweeprolog-open-query~ is converted into a Prolog
term and used as the first argument of the predicate (see [[Conversion
of Elisp objects to Prolog terms]]).  The fifth argument is an
optional "reverse" flag, when this flag is set to non-nil, the order
of the arguments is reversed such that the predicate is called in mode
~p(-Out, +In)~ rather than ~p(+In, -Out)~.

The function ~sweeprolog-next-solution~ can be used to examine the results of
a query.  If the query succeeded, ~sweeprolog-next-solution~ returns a cons
cell whose ~car~ is either the symbol ~!~ when the success was
deterministic or ~t~ otherwise, and the ~cdr~ is the current value of the
second (output) Prolog argument converted to an Elisp object (see
[[Conversion of Prolog terms to Elisp objects]]).  If the query failed,
~sweeprolog-next-solution~ returns nil.

Sweep only executes one Prolog query at a given time, thus queries
opened with ~sweeprolog-open-query~ need to be closed before other
queries can be opened.  When no more solutions are available for the
current query (i.e. after ~sweeprolog-next-solution~ returned ~nil~), or
when otherwise further solutions are not of interest, the query must
be closed with either ~sweeprolog-cut-query~ or
~sweeprolog-close-query~. Both of these functions close the current
query, but ~sweeprolog-close-query~ also destroys any Prolog bindings
created by the query.

** Conversion of Elisp objects to Prolog terms
:PROPERTIES:
:CUSTOM_ID: elisp-to-prolog
:DESCRIPTION: How sweep translates Emacs Lisp to Prolog
:ALT_TITLE: Elisp to Prolog
:END:

Sweep converts Elisp objects into Prolog terms to allow the Elisp
programmers to specify arguments for Prolog predicates invocations (see
~sweeprolog-open-query~).  Seeing as some Elisp objects, like Elisp compiled
functions, wouldn't be as useful for a passing to Prolog as others,
Sweep only converts Elisp objects of certain types to Prolog, namely
we convert /trees of strings and numbers/:

- Elisp strings are converted to equivalent Prolog strings.
- Elisp integers are converted to equivalent Prolog integers.
- Elisp floats are converted to equivalent Prolog floats.
- The Elisp nil object is converted to the Prolog empty list =[]=.
- Elisp cons cells are converted to Prolog lists whose head and tail
  are the Prolog representations of the =car= and the =cdr= of the cons.

** Conversion of Prolog terms to Elisp objects
:PROPERTIES:
:CUSTOM_ID: prolog-to-elisp
:DESCRIPTION: How sweep translates Prolog to Emacs Lisp
:ALT_TITLE: Prolog to Elisp
:END:

Sweep converts Prolog terms into Elisp object to allow efficient
processing of Prolog query results in Elisp (see ~sweeprolog-next-solution~).

- Prolog strings are converted to equivalent Elisp strings.
- Prolog integers are converted to equivalent Elisp integers.
- Prolog floats are converted to equivalent Elisp floats.
- A Prolog atom ~foo~ is converted to a cons cell ~(atom . "foo")~.
- The Prolog empty list ~[]~ is converted to the Elisp ~nil~ object.
- Prolog lists are converted to Elisp cons cells whose ~car~ and ~cdr~ are
  the representations of the head and the tail of the list.
- Prolog compounds are converted to list whose first element is the
  symbol ~compound~. The second element is a string denoting the functor
  name of the compound, and the rest of the elements are the arguments
  of the compound in their Elisp representation.
- All other Prolog terms (variables, blobs and dicts) are currently
  represented in Elisp only by their type:
  + Prolog variables are converted to the symbol ~variable~,
  + Prolog blobs are converted to the symbol ~blob~, and
  + Prolog dicts are converted to the symbol ~dict~.

** Example - counting solutions for a Prolog predicate in Elisp
:PROPERTIES:
:CUSTOM_ID: count-permutations
:DESCRIPTION:
:ALT_TITLE: Example Query
:END:

As an example of using the Sweep interface for executing Prolog
queries, we show an invocation of the non-deterministic predicate
~lists:permutation/2~ from Elisp where we count the number of different
permutations of the list ~(1 2 3 4 5)~:

#+name: count-list-permutations
#+begin_src emacs-lisp
  (sweeprolog-open-query "user" "lists" "permutation" '(1 2 3 4 5))
  (let ((num 0)
        (sol (sweeprolog-next-solution)))
    (while sol
      (setq num (1+ num))
      (setq sol (sweeprolog-next-solution)))
    (sweeprolog-close-query)
    num)
#+end_src

** Calling Elisp function inside Prolog queries
:PROPERTIES:
:CUSTOM_ID: funcall-from-prolog
:DESCRIPTION: Special predicates for calling back to Emacs from Prolog
:ALT_TITLE: Call Back to Elisp
:END:

The ~sweep-module~ defines the foreign Prolog predicates ~sweep_funcall/2~
and ~sweep_funcall/3~, which allow for calling Elisp functions from
Prolog code.  These predicates may only be called in the context of a
Prolog query initiated by ~sweeprolog-open-query~, i.e. only in the Prolog
thread controlled by Emacs.  The first argument to these predicates is
a Prolog string holding the name of the Elisp function to call.  The
last argument to these predicates is unified with the return value of
the Elisp function, represented as a Prolog term (see [[Conversion of
Elisp objects to Prolog terms]]).  The second argument of
~sweep_funcall/3~ is converted to an Elisp object (see [[Conversion of
Prolog terms to Elisp objects]]) and passed as a sole argument to the
invoked Elisp function.  The ~sweep_funcall/2~ variant invokes the Elisp
function without any arguments.

* Editing Prolog code
:PROPERTIES:
:CUSTOM_ID: editing-prolog-code
:DESCRIPTION: Major mode for reading and writing Prolog
:ALT_TITLE: Editing Prolog Code
:END:

#+CINDEX: sweeprolog-mode
Sweep includes a dedicated major mode for reading and editing Prolog
code, called ~sweeprolog-mode~:

- Command: sweeprolog-mode :: Enable Sweep major mode for reading and
  editing SWI-Prolog code in the current buffer.
- Variable: sweeprolog-mode-hook :: Hook run after entering
  ~sweeprolog-mode~.  For more information about major mode hooks in
  Emacs see [[info:emacs#Hooks][Hooks]] in the Emacs manual.

To activate this mode in a buffer, type ~M-x sweeprolog-mode~.  To
instruct Emacs to always open Prolog files in ~sweeprolog-mode~, modify
the Emacs variable ~auto-mode-alist~ accordingly:

#+begin_src emacs-lisp
  (add-to-list 'auto-mode-alist '("\\.pl\\'"   . sweeprolog-mode))
  (add-to-list 'auto-mode-alist '("\\.plt\\'"  . sweeprolog-mode))
#+end_src

For more information about how Emacs chooses a major mode to use when
you visit a file, see [[info:emacs#Choosing Modes][Choosing Modes]] in the Emacs manual.

** Indentation
:PROPERTIES:
:CUSTOM_ID: indentation
:DESCRIPTION: How sweep indents Prolog code
:ALT_TITLE: Indentation
:END:

#+CINDEX: indentation
In ~sweeprolog-mode~ buffers, the appropriate indentation for each line is
determined by a bespoke /indentation engine/.  The indentation engine
analyses the syntactic context of a given line and determines the
appropriate indentation to apply based on a set of rules.

#+KINDEX: C-i
- Key: TAB (indent-for-tab-command) :: Indent the current line.  If
  the region is active, indent all the lines within it.  Calls the
  mode-dependent function specified by the variable
  ~indent-line-function~ to do the work.
- Function: sweeprolog-indent-line :: Indent the current line
  according to SWI-Prolog conventions.  This function is used as an
  ~indent-line-function~ in ~sweeprolog-mode~ buffers.
- Command: sweeprolog-infer-indent-style :: Infer indentation style
  for the current buffer from its contents.

The entry point of the indentation engine is the function
~sweeprolog-indent-line~ which takes no arguments and indents that line
at point.  ~sweeprolog-mode~ supports the standard Emacs interface for
indentation by arranging for ~sweeprolog-indent-line~ to be called
whenever a line should be indented, notably after pressing ~TAB~.  For a
full description of the available commands and options that pertain to
indentation, see [[info:emacs#Indentation][Indentation]] in the Emacs manual.

#+CINDEX: indentation style
#+VINDEX: indent-tabs-mode
#+VINDEX: sweeprolog-indent-offset
The user option ~sweeprolog-indent-offset~ specifies how many columns
lines are indented with.  The standard Emacs variable ~indent-tabs-mode~
determines if indentation can use tabs or only spaces.  You may
sometimes want to adjust these options to match the indentation style
used in an existing Prolog codebase, the command
~sweeprolog-infer-indent-style~ can do that for you by analyzing the
contents of the current buffer and updating the buffer-local values of
~sweeprolog-indent-offset~ and ~indent-tabs-mode~ accordingly.  Consider
adding ~sweeprolog-infer-indent-style~ to ~sweeprolog-mode-hook~ to have
it set up the indentation style automatically in all ~sweeprolog-mode~
buffers:

#+begin_src emacs-lisp
  (add-hook 'sweeprolog-mode-hook #'sweeprolog-infer-indent-style)
#+end_src

*** Indentation rules
:PROPERTIES:
:CUSTOM_ID: indentation-rules
:DESCRIPTION: The intented indentation scenaria
:ALT_TITLE: Indentation Rules
:END:

Lines in ~sweeprolog-mode~ buffers are indented according to the following
rules:

1. If the current line starts inside a string or a multi-line comment,
   do not indent.
2. If the current line starts with a top term, do not indent.
3. If the current line starts with a closing parenthesis and the
   matching opening parenthesis is part of a functor, indent to the
   column of the opening parenthesis if any arguments appear on the
   same line as the functor, otherwise indent to the start of the
   functor.

   This rule yields the following layouts:

   #+begin_src prolog
     some_functor(
         some_arg
     ).

     some_functor( some_arg
                 ).
   #+end_src

4. If the current line is the first non-comment line of a clause body,
   indent to the starting column of the head term plus the value of
   the user option ~sweeprolog-indent-offset~ (by default, four extra
   columns).

   As an example, this rule yields the following layouts when
   ~sweeprolog-indent-offset~ is set to the default value of four columns:

   #+begin_src prolog
     some_functor(arg1, arg2) :-
         body_term.

     asserta( some_functor(arg1, arg2) :-
                  body_term
            ).
   #+end_src

5. If the current line starts with the right hand side operand of an
   infix operator, indent to the starting column of the first operand
   in the chain of infix operators of the same precedence.

   This rule yields the following layouts:

   #+begin_src prolog
     head :- body1, body2, body3,
             body4, body5.

     A is 1 * 2 ^ 3 * 4 *
          5.

     A is 1 * 2 + 3 * 4 *
                  5.
   #+end_src

6. If the last non-comment line ends with a functor and its opening
   parenthesis, indent to the starting column of the functor plus
   ~sweeprolog-indent-offset~.

   This rule yields the following layout:

   #+begin_src prolog
     some_functor(
         arg1, ...
   #+end_src

7. If the last non-comment line ends with a prefix operator, indent to
   starting column of the operator plus ~sweeprolog-indent-offset~.

   This rule yields the following layout:

   #+begin_src prolog
     :- multifile
            predicate/3.
   #+end_src

** Semantic Highlighting
:PROPERTIES:
:CUSTOM_ID: semantic-highlighting
:DESCRIPTION: Rich fontification for Prolog code
:ALT_TITLE: Highlighting
:END:

#+CINDEX: fontification
~sweeprolog-mode~ integrates with the standard Emacs ~font-lock~ system which
is used for highlighting text in buffers (see [[info:emacs#Font Lock][Font Lock in the Emacs
manual]]).  ~sweeprolog-mode~ highlights different tokens in Prolog code
according to their semantics, determined through static analysis which
is performed on demand.  When a buffer is first opened in ~sweeprolog-mode~,
its entire contents are analyzed to collect and cache cross reference
data, and the buffer is highlighted accordingly.  In contrast, when
editing and moving around the buffer, a faster, local analysis is
invoked to updated the semantic highlighting in response to changes in
the buffer.

- Key: C-c C-c (sweeprolog-analyze-buffer) :: Analyze the current
  buffer and update cross-references.
- User Option: sweeprolog-analyze-buffer-on-idle :: If non-nil,
  analyze ~sweeprolog-mode~ buffers on idle.  Defaults to ~t~.
- User Option: sweeprolog-analyze-buffer-max-size :: Maximum number
  characters in a ~sweeprolog-mode~ buffer to analyze on idle.  Larger
  buffers are not analyzed on idle.  Defaults to 100,000 characters.
- User Option: sweeprolog-analyze-buffer-min-interval :: Minimum
  number of idle seconds to wait before analyzing a ~sweeprolog-mode~
  buffer.  Defaults to 1.5.

At any point in a ~sweeprolog-mode~ buffer, the command ~C-c C-c~ (or ~M-x
sweeprolog-analyze-buffer~) can be used to update the cross reference
cache and highlight the buffer accordingly.  When Flymake integration
is enabled, this command also updates the diagnostics for the current
buffer (see [[#diagnostics][Examining Diagnostics]]).  This may be useful e.g. after
defining a new predicate.

If the user option ~sweeprolog-analyze-buffer-on-idle~ is set to non-nil
(as it is by default), ~sweeprolog-mode~ also updates semantic highlighting
in the buffer whenever Emacs is idle for a reasonable amount of time,
unless the buffer is larger than the value of the
~sweeprolog-analyze-buffer-max-size~ user option ( 100,000 by default).
The minimum idle time to wait before automatically updating semantic
highlighting can be set via the user option
~sweeprolog-analyze-buffer-min-interval~.

#+CINDEX: sweeprolog-faces
Sweep defines three highlighting /styles/, each containing more than 60
different faces (named sets of properties that determine the
appearance of a specific text in Emacs buffers, see also [[info:emacs#Faces][Faces in the
Emacs manual]]) to signify the specific semantics of each token in a
Prolog code buffer.

To view and customize all of the faces defined and used in Sweep, type
~M-x customize-group RET sweeprolog-faces RET~.

*** Available Styles
:PROPERTIES:
:CUSTOM_ID: highlighting-styles
:DESCRIPTION: Available highlighting styles
:ALT_TITLE: Available Styles
:END:

Sweep comes with three highlighting styles:

1. The default style includes faces that mostly inherit from standard
   Emacs faces commonly used in programming modes.
2. The ~light~ style mimics the colors used in the SWI-Prolog built-in
   editor.
3. The ~dark~ style mimics the colors used in the SWI-Prolog built-in
   editor in dark mode.

- User Option: sweeprolog-faces-style :: Style of faces to use for
  semantic highlighting in ~sweeprolog-mode~ buffers.  Defaults to ~nil~.

To choose a style, customize the user option ~sweeprolog-faces-style~ with
~M-x customize-option RET sweeprolog-faces-style RET~.  The new style will
apply to all new ~sweeprolog-mode~ buffers.  To apply the new style to an
existing buffer, use ~C-x x f~ (~font-lock-update~) in that buffer.

*** Highlighting occurrences of a variable
:PROPERTIES:
:CUSTOM_ID: variable-highlighting
:DESCRIPTION: Commands for emphasizing all occurrences of a Prolog variable
:ALT_TITLE: Highlight Variables
:END:

#+CINDEX: variable highlighting
~sweeprolog-mode~ can highlight all occurrences of a given Prolog
variable in the clause in which it appears.  By default, occurrences
of the variable at point are highlighted automatically whenever the
cursor is moved into a variable.  To achieve this, Sweep uses the
Emacs minor mode ~cursor-sensor-mode~ which allows for running hooks
when the cursor enters or leaves certain text regions (see also [[info:elisp#Special
Properties][Special Properties in the Elisp manual]]).

- Command: sweeprolog-highlight-variable :: Highlight occurrences of a
  Prolog variable in the clause at point.  With a prefix argument,
  clear variable highlighting in the clause at point instead.

- User Option: sweeprolog-enable-cursor-sensor :: If non-nil, use
  ~cursor-sensor-mode~ to highlight Prolog variables sharing with the
  variable at point in ~sweeprolog-mode~ buffers.  Defaults to ~t~.

To disable automatic variable highlighting based on the variable at
point, customize the variable ~sweeprolog-enable-cursor-sensor~ to nil.

To manually highlight occurrences of a variable in the clause
surrounding point, ~sweeprolog-mode~ provides the command ~M-x
sweeprolog-highlight-variable~.  This command prompts for variable to
highlight, defaulting to the variable at point, if any.  If called
with a prefix argument (~C-u M-x sweeprolog-highlight-variable~), it
clears all variable highlighting in the current clause instead.

*** Quasi-quotation highlighting
:PROPERTIES:
:CUSTOM_ID: qq-highlighting
:DESCRIPTION: Delegating fontification of quasi-quoted contents to other Emacs major modes
:ALT_TITLE: Quasi-Quotation
:END:

Quasi-quotations in ~sweeprolog-mode~ buffer are highlighted according
to the Emacs mode corresponding to the quoted language by default.

- User Option: sweeprolog-qq-mode-alist :: Alist of (TYPE . MODE)
  pairs, where TYPE is a Prolog quasi-quotation type, and MODE is a
  symbol specifying a major mode to use for highlighting the
  quasi-quoted text.

The association between SWI-Prolog quasi-quotation types and Emacs
major modes is determined by the user option ~sweeprolog-qq-mode-alist~.
To modify the default associations provided by ~sweeprolog-mode~, type
~M-x customize-option RET sweeprolog-qq-mode-alist RET~.

If a quasi-quotation type does not have a matching mode in
~sweeprolog-qq-mode-alist~, the function ~sweeprolog-qq-content-face~ is
used to determine a default face for quoted content.

For more information about quasi-quotations in SWI-Prolog, see
[[https://www.swi-prolog.org/pldoc/man?section=quasiquotations][library(quasi_quotations) in the SWI-Prolog manual]].

** Hover for Help
:PROPERTIES:
:CUSTOM_ID: help-echo
:DESCRIPTION: Display description of Prolog tokens by hovering with the mouse
:ALT_TITLE: Hover for Help
:END:

In the [[#semantic-highlighting][Semantic Highlighting]] section we talked about how Sweep
performs semantic analysis to determine the meaning of different terms
in different contexts and highlight them accordingly.  Beyond
highlighting, Sweep can also tell you explicitly what different tokens
in Prolog code mean by annotating them with a textual description
that's displayed when you hover over them with the mouse.

- User Option: sweeprolog-enable-help-echo :: If non-nil, annotate
  Prolog tokens with help text via the ~help-echo~ text
  property. Defaults to ~t~.
- Key: C-h . (display-local-help) :: Display the ~help-echo~ text of the
  token at point in the echo area.

If the user option ~sweeprolog-enable-help-echo~ is non-nil, as it is by
default, ~sweeprolog-mode~ annotates tokens with a short description of
their meaning in that specific context.  This is done by adding the
~help-echo~ text property to different parts of the buffer based on
semantic analysis.  The ~help-echo~ text is automatically displayed at
the mouse tooltip when you hover over different tokens in the buffer.

Alternatively, you can display the ~help-echo~ text for the token at
point in the echo area by typing ~C-h .~ (~C-h~ followed by dot).

The ~help-echo~ description of file specification in import directives
is especially useful as it tells you which predicates that the current
buffer uses actually come from the imported file.  For example, if we
have a Prolog file with the following contents:

#+begin_src prolog
  :- use_module(library(lists)).

  foo(Foo, Bar) :- flatten(Bar, Baz), member(Foo, Baz).
#+end_src

Then hovering over ~library(lists)~ shows:

#+begin_quote
Dependency on /usr/local/lib/swipl/library/lists.pl, resolves calls to flatten/2, member/2
#+end_quote

** Maintaining Code Layout
:PROPERTIES:
:CUSTOM_ID: whitespace
:DESCRIPTION: Commands for aligning Prolog code without having to count spaces
:ALT_TITLE: Code Layout
:END:

#+CINDEX: whitespace
#+CINDEX: alignment
#+CINDEX: layout
Some Prolog constructs, such as if-then-else constructs, have a
conventional /layout/, where each goal starts at the fourth column after
the /start/ of the opening parenthesis or operator, as follows:

  #+begin_src prolog
    (   if
    ->  then
    ;   else
    ,*-> elif
    ;   true
    )
  #+end_src

To simplify maintaining the desired layout without manually counting
spaces, Sweep provides a command ~sweeprolog-align-spaces~ that updates
the whitespace around point such that the next token is aligned to a
(multiple of) four columns from the start of the previous token, as
well as a dedicated minor mode ~sweeprolog-electric-layout-mode~ that
adjusts whitespace around point automatically as you type ([[*Electric Layout mode][Electric
Layout mode]]).

*** Inserting the Right Number of Spaces
:PROPERTIES:
:CUSTOM_ID: cycle-spacing
:DESCRIPTION: Commands for adjusting whitespace according to Prolog conventions
:ALT_TITLE: Aligning Spaces
:END:

- Command: sweeprolog-align-spaces :: Insert or remove spaces around
  point to such that the next Prolog token starts at a column
  distanced from the beginning of the previous token by a multiple of
  four columns.
- User Option: sweeprolog-enable-cycle-spacing :: If non-nil, add
  ~sweeprolog-align-spaces~ as the first element of
  ~cycle-spacing-actions~ in ~sweeprolog-mode~ buffers.  Defaults to ~t~.

To insert or update whitespace around point, use the command ~M-x
sweeprolog-align-spaces~.  For example, consider a ~sweeprolog-mode~
buffer with the following contents, where =^= designates the location of
the cursor:

#+begin_src prolog
  foo :-
      (   if
      ;
       ^
#+end_src

Calling ~M-x sweeprolog-align-spaces~ will insert three spaces, to yield
the expected layout:

#+begin_src prolog
  foo :-
      (   if
      ;
          ^
#+end_src

#+FINDEX: cycle-spacing
In Emacs 29, the command ~M-x cycle-spacing~ is extensible via a list of
callback functions stored in the variable ~cycle-spacing-actions~.
Sweep leverages this facility and adds ~sweeprolog-align-spaces~ as the
first action of ~cycle-spacing~.  To inhibit ~sweeprolog-mode~ from doing
so, set the user option ~sweeprolog-enable-cycle-spacing~ to nil.

#+KINDEX: M-SPC
Moreover, in Emacs 29 ~cycle-spacing~ is bound by default to ~M-SPC~, thus
aligning if-then-else and similar constructs only requires typing
~M-SPC~ after the first token.

In Emacs prior to version 29, users are advised to bind
~sweeprolog-align-spaces~ to ~M-SPC~ directly by adding the following
lines to Emacs's initialization file (see [[info:emacs#Init File][The Emacs Initialization File]]).

#+begin_src emacs-lisp
  (eval-after-load 'sweeprolog
    '(define-key sweeprolog-mode-map (kbd "M-SPC") #'sweeprolog-align-spaces))
#+end_src

*** Electric Layout mode
:PROPERTIES:
:CUSTOM_ID: electric-layout-mode
:DESCRIPTION: Minor mode for automatically adjusting whitespace
:ALT_TITLE: Electric Layout mode
:END:

#+CINDEX: electric layout
The minor mode ~sweeprolog-electric-layout-mode~ adjusts whitespace
around point automatically as you type:

- Command: sweeprolog-electric-layout-mode :: Toggle automatic
  whitespace adjustment according to SWI-Prolog conventions.

It works by examining the context of point whenever a character is
inserted in the current buffer, and applying the following layout
rules:

- =PlDoc= Comments :: Insert two consecutive spaces after the ~%!~ or ~%%~
  starting a =PlDoc= predicate documentation structured comment.
- If-Then-Else :: Insert spaces after a part of an if-then-else
  constructs such that point is positioned four columns after its
  beginning.  The specific tokens that trigger this rule are the
  opening parenthesis ~(~ and the operators ~;~, ~->~ and ~*->~, and only if
  they are inserted in a callable context, where an if-then-else
  construct would normally appear.

To enable this mode in a ~sweeprolog-mode~ buffer, type ~M-x
sweeprolog-electric-layout-mode~.  This step can be automated by adding
~sweeprolog-electric-layout-mode~ to ~sweeprolog-mode-hook~:

#+begin_src emacs-lisp
  (add-hook 'sweeprolog-mode-hook #'sweeprolog-electric-layout-mode)
#+end_src

** Term-based editing and motion commands
:PROPERTIES:
:CUSTOM_ID: term-based-commands
:DESCRIPTION: Commands that recognize and operate on Prolog terms
:ALT_TITLE: Term-based Editing
:END:

#+CINDEX: sexps
Emacs includes many useful features for operating on syntactic units
in source code buffer, such as marking, transposing and moving over
expressions.  By default, these features are geared towards working
with Lisp expressions, or "sexps".  =sweeprolog-mode= extends the Emacs's
notion of syntactic expressions to accommodate for Prolog terms, which
allows the standard sexp-based commands to operate on them seamlessly.

The [[info:emacs#Expressions][Expressions]] section in the Emacs manual covers the most important
commands that operate on sexps, and by extension on Prolog terms.
Another useful command for Prolog programmers is =M-x
kill-backward-up-list=, bound by default to =C-M-^= in =sweeprolog-mode=
buffers.

- Key: C-M-^ (kill-backward-up-list) :: Kill the Prolog term
  containing the current term, leaving the current term itself.

This command replaces the parent term containing the term at
point with the term itself.  To illustrate the utility of this
command, consider the following clause:

#+begin_src prolog
  head :-
      goal1,
      setup_call_cleanup(setup,
                         goal2,
                         cleanup).
#+end_src

Now with point anywhere inside =goal2=, calling =kill-backward-up-list=
removes the =setup_call_cleanup/3= term leaving =goal2= to be called
directly:

#+begin_src prolog
  head :-
      goal1,
      goal2.
#+end_src

** Holes
:PROPERTIES:
:CUSTOM_ID: holes
:DESCRIPTION: Commands for finding and filling holes for interactive term insertion
:ALT_TITLE: Holes
:END:

#+CINDEX: holes
/Holes/ are Prolog variables that some Sweep commands use as placeholder
for other terms.

When writing Prolog code in the usual way of typing in one character
at a time, the buffer text is often found in a syntactically incorrect
state while you edit it.  This happens for example right after you
insert an infix operator, before typing its expected right-hand side
argument.  Sweep provides an alternative method for inserting Prolog
terms in a way that maintains the syntactic correctness of the buffer
text while allowing the user to incrementally refine it by using
placeholder terms, called simply "holes".  Holes indicate the location
of missing terms that the user can later fill in, essentially they
represent source-level unknown terms and their presence satisfies the
Prolog parser.  Holes are written in the buffer as regular Prolog
variables, but they are annotated with a special text property that
allows Sweep to recognize them as holes needed to be filled.

See [[#insert-holes-with-holes][Inserting Terms with Holes]] for a command that uses holes to let
you write syntactically correct Prolog terms incrementally.  Several
other Sweep commands insert holes in place of unknown terms, including
~C-M-i~ (see [[#code-completion][Code Completion]]), ~C-M-m~ (see [[#insert-term-at-point][Context-Based Term Insertion]])
and ~M-x sweeprolog-plunit-testset-skeleton~ (see [[#writing-tests][Writing Tests]]).

*** Inserting Terms with Holes
:PROPERTIES:
:CUSTOM_ID: insert-holes-with-holes
:DESCRIPTION: Write Prolog one term at a time, not one character at a time
:ALT_TITLE: Terms with Holes
:END:

Use the command ~C-c RET~ to add a term to the buffer at point while
keeping it syntactically correct.  You don't need to give the entire
term at once, only its functor and arity.  Sweep automatically inserts
holes for the arguments (if any), which you can incrementally fill one
after the other.

#+KINDEX: C-c C-m
- Key: C-c RET (sweeprolog-insert-term-with-holes) :: Insert a Prolog
  term with a given functor and arity at point, using holes for
  arguments.

The main command for inserting terms with holes is ~M-x
sweeprolog-insert-term-with-holes~.  This command, bound by default to
~C-c C-m~ (or ~C-c RET~) in ~sweeprolog-mode~ buffers, prompts for a functor
and an arity and inserts a corresponding term with holes in place of
the term's arguments.  It leaves point right after the first hole,
sets the mark to its start and activates the region such that the hole
is marked.  Call ~sweeprolog-insert-term-with-holes~ again to replace
the active region, which now covers the first hole, with another term,
that may again contain further holes.  That way you can incrementally
write a Prolog term, including whole clauses, by working down the
syntactic structure of the term and maintaining its correctness all
the while.  Without a prefix argument,
~sweeprolog-insert-term-with-holes~ prompts for the functor and the
arity to use.  A non-negative prefix argument, such as ~C-2 C-c C-m~ or
~C-u C-c C-m~, is taken to be the inserted term's arity and in this case
~sweeprolog-insert-term-with-holes~ only prompts for the functor to
insert.  A negative prefix argument, ~C-- C-c C-m~, inserts only a
single hole without prompting for a functor.  To further help with
keeping the buffer syntactically correct, this command adds a comma
(~,~) before or after the inserted term when needed according to the
surrounding tokens.  If you call it at the end of a term that doesn't
have a closing fullstop, it adds the fullstop after the inserted term.

*** Jumping to Holes
:PROPERTIES:
:CUSTOM_ID: jump-to-hole
:DESCRIPTION: Commands for going to the next hole in the buffer
:ALT_TITLE: Jumping to Holes
:END:

Use these commands to move between holes in the current Prolog buffer:

#+KINDEX: C-c C-i
- Key: C-c TAB (sweeprolog-forward-hole) :: Move point to the next
  hole in the buffer.
#+KINDEX: C-c C-S-i
- Key: C-c S-TAB (sweeprolog-backward-hole) :: Move point to the
  previous hole in the buffer.
- Command: sweeprolog-forward-hole-on-tab-mode :: Toggle moving to the
  next hole in the buffer with ~TAB~ if the current line is already
  properly indented.

To jump to the next hole in a ~sweeprolog-mode~ buffer, use the command
~M-x sweeprolog-forward-hole~, bound by default to ~C-c TAB~ (or ~C-c C-i~).
This command sets up the region to cover the next hole after point
leaving the cursor at right after the hole.  To jump to the previous
hole instead, use ~sweeprolog-backward-hole~ or call
~sweeprolog-forward-hole~ with a negative prefix argument (~C-- C-c TAB~).

When the minor mode ~sweeprolog-forward-hole-on-tab-mode~ is enabled,
the ~TAB~ key is bound to a command moves to the next hole when called
in a properly indented line (otherwise it indents the line).  This
makes moving between holes in the buffer easier since ~TAB~ can be used
instead of ~C-c TAB~ in most cases.  To enable this mode in a Prolog
buffer, type ~M-x sweeprolog-forward-hole-on-tab-mode-map~.  This step
can be automated by adding ~sweeprolog-forward-hole-on-tab-mode~ to
~sweeprolog-mode-hook~:

#+begin_src emacs-lisp
  (add-hook 'sweeprolog-mode-hook #'sweeprolog-forward-hole-on-tab-mode)
#+end_src

*** Filling Holes
:PROPERTIES:
:CUSTOM_ID: filling-holes
:DESCRIPTION: Filling holes in Prolog terms
:ALT_TITLE: Filling Holes
:END:

Filling a hole means replacing it in the buffer with a Prolog term.
The simplest way to fill a hole is how you would replace any other
piece of text in Emacs--select it as the region, kill it (for example,
with ~C-w~) and insert another Prolog term in its place.  For more
information about the region, see [[info:emacs#Mark][Mark]] in the Emacs manual.

Yanking a hole with ~C-y~ (~yank~) after you kill it removes the special
hole property and inserts it as a plain variable.  This is can be
useful if you want to keep the variable name that Sweep chose for the
hole--simply press ~C-w C-y~ with the hole marked.

As an alternative to manually killing the region with ~C-w~, if you
enable Delete Selection mode (~M-x delete-selection-mode~), the hole is
automatically removed as soon as you start typing while its marked.
For more information about Delete Selection mode, see [[info:emacs#Using Region][Using Region]] in
the Emacs manual.

Most Sweep commands that insert holes also move to the first hole they
insert and select it as the region for you to fill it.  Similarly,
jumping to the next hole in the buffer with ~C-c TAB~ also selects it.
The command ~C-c RET~, described in [[*Inserting Terms with Holes][Inserting Terms with Holes]], is
specifically intended for filling holes by deleting the selected hole
and inserting a Prolog term at once.

*** Highlighting Holes
:PROPERTIES:
:CUSTOM_ID: highlight-holes
:DESCRIPTION: Options for highlighting holes
:ALT_TITLE: Highlighting Holes
:END:

Sweep highlights holes in Prolog buffer by default so you can easily
identify missing terms.

- User Option: sweeprolog-highlight-holes :: If non-nil, highlight
  holes in ~sweeprolog-mode~ buffers with a dedicated face.  By default,
  this is set to ~t~.

When the user option ~sweeprolog-highlight-holes~ is set to non-nil,
holes in Prolog buffers are highlighted with a dedicated face, making
them easily distinguishable from regular Prolog variables.  Hole
highlighting is enabled by default, to disable it customize
~sweeprolog-highlight-holes~ to nil.

** Definitions and References
:PROPERTIES:
:CUSTOM_ID: sweeprolog-xref
:DESCRIPTION: Commands for finding cross-references for Prolog predicates
:ALT_TITLE: Cross References
:END:

#+CINDEX: cross reference
#+CINDEX: xref
#+KINDEX: M-.
~sweeprolog-mode~ integrates with the Emacs =xref= API to facilitate quick
access to predicate definitions and references in Prolog code buffers.
This enables the many commands that the =xref= interface provides, like
~M-.~ (~xref-find-definitions~) for jumping to the definition of the
predicate at point.  Refer to [[info:emacs#Find Identifiers][Find Identifiers]] in the Emacs manual for
an overview of the available commands.

#+CINDEX: imenu
#+KINDEX: M-g i
~sweeprolog-mode~ also integrates with Emacs's =imenu=, which provides a
simple facility for looking up and jumping to definitions in the
current buffer.  To jump to a definition in the current buffer, type
~M-x imenu~ (bound by default to ~M-g i~ in Emacs version 29).  For
information about customizing =imenu=, see [[info:emacs#Imenu][Imenu]] in the Emacs manual.

#+FINDEX: sweeprolog-xref-project-source-files
#+KINDEX: M-?
The command ~M-x sweeprolog-xref-project-source-files~ can be used to
update Sweep's cross reference data for all Prolog source files in the
current project, as determined by the function ~project-current~ (see
[[info:emacs#Projects][Projects]] in the Emacs manual).  When searching for references to
Prolog predicates with ~M-?~ (~xref-find-references~), this command is
invoked implicitly to ensure up to date references are found
throughout the current project.

** Predicate Definition Boundaries
:PROPERTIES:
:CUSTOM_ID: predicate-boundaries
:DESCRIPTION: Commands operating on a Prolog predicate definition as a single unit
:ALT_TITLE: Predicate Boundaries
:END:

#+CINDEX: predicate-based motion
The following commands act on entire Prolog predicate definitions as a
single unit:

- Key: M-n (sweeprolog-forward-predicate) :: Move forward from point
  to the next predicate definition in the current buffer.
- Key: M-p (sweeprolog-backward-predicate) :: Move backward from point
  to the previous predicate definition.
- Key: M-h (sweeprolog-mark-predicate) :: Select the current predicate
  as the active region, put point at the its beginning, and the mark
  at the end.

In ~sweeprolog-mode~, the commands ~M-n~ (~sweeprolog-forward-predicate~)
and ~M-p~ (~sweeprolog-backward-predicate~) are available for quickly
jumping to the first line of the next or previous predicate
definition in the current buffer.

The command ~M-h~ (~sweeprolog-mark-predicate~) marks the entire predicate
definition at point, along with its =PlDoc= comments if there are any.
This can be followed, for example, with killing the marked region to
relocate the defined predicate by typing ~M-h C-w~.

** Following File Specifications
:PROPERTIES:
:CUSTOM_ID: following-file-specs
:DESCRIPTION: Commands for jumping to files that appear in Prolog code
:ALT_TITLE: File Specifications
:END:

In SWI-Prolog, one often refers to source file paths using /file
specifications/, special Prolog terms that act as path aliases, such
as ~library(lists)~ which refers to a file ~lists.pl~ in any of the Prolog
library directories.

- Key: C-c C-o (sweeprolog-find-file-at-point) :: Resolve file
  specification at point and visit the specified file.
- Function: sweeprolog-file-at-point &optional point :: Return the
  file name specified by the Prolog file specification at POINT.

You can follow file specifications that occur in ~sweeprolog-mode~
buffers with ~C-c C-o~ (or ~M-x sweeprolog-find-file-at-point~) whenever
point is over a valid file specification.  For example, consider a
Prolog file buffer with the common directive ~use_module/1~:

#+begin_src prolog
  :- use_module(library(lists)).
#+end_src

With point in any position inside ~library(lists)~, typing ~C-c C-o~ will
open the =lists.pl= file in the Prolog library.

Sweep also extends Emacs's ~file-name-at-point-functions~ hook with the
function ~sweeprolog-file-at-point~ that returns the resolved Prolog
file specification at point, if any.  Emacs uses this hook to populate
the "future history" of minibuffer prompts that read file names, such
as the one you get when you type ~C-x C-f~ (~find-file~).  In particular
this means that if point is in a Prolog file specification, you can
type ~M-n~ after ~C-x C-f~ to populate the minibuffer with the
corresponding file name.  You can then go ahead and visit the file by
typing ~RET~, or you can edit the minibuffer contents and visit a nearby
file instead.

For more information about file specifications in SWI-Prolog, see
[[https://www.swi-prolog.org/pldoc/doc_for?object=absolute_file_name/3][absolute_file_name/3]] in the SWI-Prolog manual.

** Loading Buffers
:PROPERTIES:
:CUSTOM_ID: loading-buffers
:DESCRIPTION: Commands for loading Prolog predicates from the current buffer
:ALT_TITLE: Loading Buffers
:END:

#+CINDEX: loading
You can load a buffer of SWI-Prolog code with the following command:

- Key: C-c C-l (sweeprolog-load-buffer) :: Load the current buffer
  into the embedded SWI-Prolog runtime.

Use the command ~M-x sweeprolog-load-buffer~ to load the contents of a
~sweeprolog-mode~ buffer into the embedded SWI-Prolog runtime.  After a
buffer is loaded, the predicates it defines can be queried from Elisp
(see [[Querying Prolog]]) and from the Sweep top-level (see [[The Prolog
Top-Level]]).  In ~sweeprolog-mode~ buffers, ~sweeprolog-load-buffer~ is
bound to ~C-c C-l~.  By default this command loads the current buffer if
its major mode is ~sweeprolog-mode~, and prompts for an appropriate
buffer otherwise.  To choose a different buffer to load while visiting
a ~sweeprolog-mode~ buffer, invoke ~sweeprolog-load-buffer~ with a prefix
argument (~C-u C-c C-l~).

More relevant information about loading code in SWI-Prolog can be
found in [[https://www.swi-prolog.org/pldoc/man?section=consulting][Loading Prolog source files]] in the SWI-Prolog manual.

** Creating New Modules
:PROPERTIES:
:CUSTOM_ID: creating-new-modules
:DESCRIPTION: Commands for populating new Prolog modules with predefined contents
:ALT_TITLE: Creating New Modules
:END:

#+CINDEX: auto-insert
Sweep integrates with the Emacs =auto-insert= facility to simplify
creation of new SWI-Prolog modules.  =auto-insert= allows for populating
newly created files with templates defined by the relevant major mode.

- User Option: sweeprolog-module-header-comment-skeleton :: Additional
  content to put in the topmost comment in Prolog module headers.

Sweep associates a Prolog module skeleton with ~sweeprolog-mode~, the
skeleton begins with a "file header" multi-line comment which includes
the name and email address of the user based on the values of
~user-full-name~ and ~user-mail-address~ respectively.  A ~module/2~
directive is placed after the file header, with the module name set to
the base name of the file.  Lastly the skeleton inserts a =PlDoc= module
comment to be filled with the module's documentation (see [[https://www.swi-prolog.org/pldoc/man?section=sectioncomments][File
comments in the SWI-Prolog manual]]).

As an example, after inserting the module skeleton, a new Prolog file
=foo.pl= will have the following contents:

#+begin_src prolog
  /*
      Author:        John Doe
      Email:         john.doe@example.com

  ,*/

  :- module(foo, []).

  /** <module>

  ,*/

#+end_src

The multi-line comment included above the ~module/2~ directive can be
extended by customizing the user option
~sweeprolog-module-header-comment-skeleton~, which see.  This can be
useful for including e.g. copyright text in the file header.

To open a new Prolog file, use the standard ~C-x C-f~ (~find-file~)
command and select a location for the new file.  In the new
~sweeprolog-mode~ buffer, type ~M-x auto-insert~ to insert the Prolog
module skeleton.

To automatically insert the module skeleton when opening new files in
~sweeprolog-mode~, enable the minor mode ~auto-insert-mode~.  For detailed
information about =auto-insert= and its customization options, see
[[info:autotype#Autoinserting][Autoinserting in the Autotyping manual]].

** Documenting Predicates
:PROPERTIES:
:CUSTOM_ID: sweeprolog-pldoc
:DESCRIPTION: Commands for adding documentation to Prolog predicate definitions
:ALT_TITLE: Documenting Code
:END:

#+CINDEX: document code
#+CINDEX: comments
#+CINDEX: pldoc
SWI-Prolog predicates can be documented with specially structured
comments placed above the predicate definition, which are processed by
the =PlDoc= source documentation system.  Emacs comes with many useful
commands specifically intended for working with comments in
programming languages, which apply also to writing =PlDoc= comments for
Prolog predicates.  For an overview of the relevant standard Emacs
commands, see [[info:emacs#Comment Commands][Comment Commands in the Emacs manual]].

- Key: C-c C-d (sweeprolog-document-predicate-at-point) :: Insert
  =PlDoc= documentation comment for the predicate at or above point.
- User Option: sweeprolog-read-predicate-documentation-function :: Function
  to use for determining the initial contents of documentation
  comments inserted with ~sweeprolog-document-predicate-at-point~.
- Function: sweeprolog-read-predicate-documentation-default-function functor arity :: Prompt
  and read from the minibuffer the arguments modes, determinism
  specification and initial summary for the documentation of the
  predicate FUNCTOR/ARITY.
- Function: sweeprolog-read-predicate-documentation-with-holes functor arity :: Use
  holes for the initial documentation of the predicate FUNCTOR/ARITY.

Sweep also includes a dedicated command called
~sweeprolog-document-predicate-at-point~ for interactively creating
=PlDoc= comments for predicates in ~sweeprolog-mode~ buffers.  This
command, bound by default to ~C-c C-d~, finds the beginning of the
predicate definition under or right above the current cursor location,
and inserts a formatted =PlDoc= comment.  This command fills in initial
argument modes, determinism specification, and optionally a summary
line for the documented predicate.  There are different ways in which
~sweeprolog-document-predicate-at-point~ can obtain the needed initial
documentation information, depending on the value of the user option
~sweeprolog-read-predicate-documentation-function~ which specifies a
function to retrieve this information.  The default function prompts
you to insert the parameters one by one via the minibuffer.
Alternatively, you can use holes (see [[#holes][Holes]]) for the predicate's
argument modes and determinism specifiers by setting this option to
~sweeprolog-read-predicate-documentation-with-holes~, as follows:

#+begin_src emacs-lisp
  (setq sweeprolog-read-predicate-documentation-function
        #'sweeprolog-read-predicate-documentation-with-holes)
#+end_src

~sweeprolog-document-predicate-at-point~ leaves the cursor at the end of
the newly inserted documentation comment for the user to extend or
edit it if needed.  To add another comment line, use ~M-j~
(~default-indent-new-line~) which starts a new line with the comment
prefix filled in.  Emacs also has other powerful built-in features for
working with comments in code buffers that you can leverage to edit
=PlDoc= comments.  For full details, see [[info:emacs#Comments][Manipulating Comments]].
Furthermore you can make use of the rich support Emacs provides for
editing natural language text when working on =PlDoc= comments.  For
example, to nicely format a paragraph of text, use ~M-q~
(~fill-paragraph~).  Many useful commands for editing text are
documented in [[info:emacs#Text][Commands for Human Languages]], which see.

For more information about =PlDoc= and source documentation in
SWI-Prolog, see [[https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/pldoc.html%27)][the PlDoc manual]].

** Displaying Predicate Documentation
:PROPERTIES:
:CUSTOM_ID: eldoc-integration
:DESCRIPTION: Commands for showing documentation for Prolog predicates
:ALT_TITLE: Showing Prolog Docs
:END:

Sweep integrates with the Emacs minor mode ElDoc, which automatically
displays documentation for the predicate at point.  Whenever the
cursor enters a predicate definition or invocation, the signature and
summary of that predicate are displayed in the echo area at the bottom
of the frame.

- User Option: sweeprolog-enable-eldoc :: If non-nil, enable ElDoc
  support in ~sweeprolog-mode~ buffers.  Defaults to ~t~.

To disable the ElDoc integration in ~sweeprolog-mode~ buffers, customize
the user option ~sweeprolog-enable-eldoc~ to ~nil~.

For more information about ElDoc and its customization options, see [[info:emacs#Programming Language
Doc][Programming Language Doc]] in the Emacs manual.

** Examining Diagnostics
:PROPERTIES:
:CUSTOM_ID: diagnostics
:DESCRIPTION: Commands for finding errors in Prolog code
:ALT_TITLE: Showing Errors
:END:

#+CINDEX: flymake
#+CINDEX: diagnostics
~sweeprolog-mode~ can diagnose problems in Prolog code and report them
to the user by integrating with Flymake, a powerful interface for
on-the-fly diagnostics built into Emacs.

- User Option: sweeprolog-enable-flymake :: If non-nil, enable Flymake
  support in ~sweeprolog-mode~ buffers.  Defaults to ~t~.
- Key: C-c C-` (sweeprolog-show-diagnostics) :: List diagnostics for
  the current buffer or project in a dedicated buffer.

Flymake integration is enabled by default, to disable it customize the
user option ~sweeprolog-enable-flymake~ to nil.

#+FINDEX: next-error
#+KINDEX: M-g n
#+KINDEX: M-g p
When this integration is enabled, several Flymake commands are
available for listing and jumping between found errors.  For a full
description of these commands, see [[info:flymake#Finding diagnostics][Finding diagnostics]] in the Flymake
manual.  Additionally, ~sweeprolog-mode~ configures the standard command
~M-x next-error~ to operate on Flymake diagnostics.  This allows for
moving to the next (or previous) error location with the common ~M-g n~
(or ~M-g p~) keybinding.  For more information about these commands, see
[[info:emacs#Compilation Mode][Compilation Mode]] in the Emacs manual.

The command ~sweeprolog-show-diagnostics~ shows a list of Flymake
diagnostics for the current buffer.  It is bound by default to ~C-c C-`~
in ~sweeprolog-mode~ buffers with Flymake integration enabled.  When
called with a prefix argument (~C-u C-c C-`~), shows a list of
diagnostics for all buffers in the current project.

** Exporting Predicates
:PROPERTIES:
:CUSTOM_ID: exporting-predicates
:DESCRIPTION: Commands for adding Prolog predicates to their module's export list
:ALT_TITLE: Exporting Predicates
:END:

#+CINDEX: exported predicates
By default, a predicate defined in Prolog module is not visible to
dependent modules unless they it is /exported/, by including it in the
export list of the defining module (i.e. the second argument of the
~module/2~ directive).

- Key: C-c C-e (sweeprolog-export-predicate) :: Add the predicate
  predicate at point to the export list of the current Prolog module.

Sweep provides a convenient command for exporting predicates defined
in ~sweeprolog-mode~ buffer.  To add the predicate near point to the
export list of the current module, use the command ~C-c C-e~
(~sweeprolog-export-predicate~).  If the current predicate is documented
with a =PlDoc= comment, a comment with the predicate's mode is added
after the predicate name in the export list.  If point is not near a
predicate definition, calling ~sweeprolog-export-predicate~ will prompt
for a predicate to export, providing completion candidates based on
the non-exported predicates defined in the current buffer.  To force
prompting for a predicate, invoke ~sweeprolog-export-predicate~ with a
prefix argument (~C-u C-c C-e~).

** Code Completion
:PROPERTIES:
:CUSTOM_ID: code-completion
:DESCRIPTION: Auto-completion commands for Prolog code
:ALT_TITLE: Code Completion
:END:

#+CINDEX: code completion
#+CINDEX: completion-at-point
#+FINDEX: complete-symbol
#+FINDEX: completion-at-point
#+KINDEX: C-M-i
#+KINDEX: M-TAB
~sweeprolog-mode~ empowers Emacs's standard ~completion-at-point~ command,
bound by default to ~C-M-i~ and ~M-TAB~, with context-aware completion for
Prolog terms.  For background about completion-at-point in Emacs, see [[info:emacs#Symbol
Completion][Symbol Completion in the Emacs manual]].

In ~sweeprolog-mode~ buffers, the following enhancements are provided:

- Variable name completion :: If the text before point can be
  completed to one or more variable names that appear elsewhere in the
  current clause, ~completion-at-point~ suggests matching variable names
  as completion candidates.
- Predicate completion :: If point is at a callable position,
  ~completion-at-point~ suggests matching predicates as completion
  candidates.  Predicate calls are inserted as complete term.  If the
  chosen predicate takes arguments, holes are inserted in their places
  (see [[#holes][Holes]]).
- Atom completion :: If point is at a non-callable,
  ~completion-at-point~ suggests matching atoms as completion
  candidates.

** Context-Based Term Insertion
:PROPERTIES:
:CUSTOM_ID: insert-term-at-point
:DESCRIPTION: Commands for smart insertion of Prolog terms based on the surrounding context
:ALT_TITLE: Insert Term DWIM
:END:

#+CINDEX: context-based term insertion
#+CINDEX: term insertion at-point
As a means of automating common Prolog code editing tasks, such as
adding new clauses to an existing predicate, ~sweeprolog-mode~ provides
the "do what I mean" command ~M-x sweeprolog-insert-term-dwim~, bound by
default to ~C-M-m~ (or equivalently, ~M-RET~).  This command inserts a new
term at or after point according to the context in which
~sweeprolog-insert-term-dwim~ is invoked.

#+KINDEX: C-M-m
- Key: M-RET (sweeprolog-insert-term-dwim) :: Insert an appropriate
  Prolog term in the current buffer, based on the context at point.
- Variable: sweeprolog-insert-term-functions :: List of functions for
  ~sweeprolog-insert-term-dwim~ to try for inserting a Prolog term based
  on the current context.

To determine which term to insert and exactly where, this command
calls the functions in the list held by the variable
~sweeprolog-insert-term-functions~ one after the other until one of the
functions signal success by returning non-nil.

By default, ~sweeprolog-insert-term-dwim~ tries the following insertion
functions, in order:

#+VINDEX: sweeprolog-new-predicate-location-function
- Function: sweeprolog-maybe-insert-next-clause :: If the last token before
  point is a fullstop ending a predicate clause, insert a new clause
  below it.
- Function: sweeprolog-maybe-define-predicate :: If point is over a call to an
  undefined predicate, insert a definition for that predicate.  By
  default, the new predicate definition is inserted right below the
  last clause of the current predicate definition.  The user option
  ~sweeprolog-new-predicate-location-function~ can be customized to
  control where this function inserts new predicate definitions.

This command inserts holes as placeholders for the body term and the
head's arguments, if any.  See also [[#holes][Holes]].

** Writing Tests
:PROPERTIES:
:CUSTOM_ID: writing-tests
:DESCRIPTION: Commands that facilitate writing Prolog unit tests
:ALT_TITLE: Writing Tests
:END:

#+CINDEX: plunit
#+CINDEX: testing
SWI-Prolog includes the =PlUnit= unit testing framework[fn:3], in which
unit tests are written in special blocks of Prolog code enclosed
within the directives ~begin_tests/1~ and ~end_tests/1~.  To insert a new
block of unit tests (also known as a /test-set/) in a Prolog buffer, use
the command ~M-x sweeprolog-plunit-testset-skeleton~.

- Command: sweeprolog-plunit-testset-skeleton :: Insert a =PlUnit=
  test-set skeleton at point.

This command prompts for a name to give the new test-set and inserts a
template such as the following:

#+begin_src prolog
:- begin_tests(foo_regression_tests).

test() :- TestBody.

:- end_tests(foo_regression_tests).
#+end_src

The cursor is left between the parentheses of the ~test()~ head term,
and the ~TestBody~ variable is marked as a hole (see [[#holes][Holes]]).  To insert
another unit test, place point after a complete test case and type
~C-M-m~ or ~M-RET~ to invoke ~sweeprolog-insert-term-dwim~ (see
[[#insert-term-at-point][Context-Based Term Insertion]]).

[fn:3] See [[https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/plunit.html%27)][Prolog Unit Tests in the SWI-Prolog manual]].

** Managing Dependencies
:PROPERTIES:
:CUSTOM_ID: managing-dependencies
:DESCRIPTION: Commands for managing dependencies of Prolog source files on each other
:ALT_TITLE: Code Dependencies
:END:

#+CINDEX: dependencies
#+CINDEX: autoload
It is considered good practice for SWI-Prolog source files to
explicitly list their dependencies on predicates defined in other
files by using ~autoload/2~ and ~use_module/2~ directives.  To find all
implicitly autoloaded predicates in the current ~sweeprolog-mode~ buffer
and make the dependencies on them explicit, use the command ~M-x
sweeprolog-update-dependencies~ bound to ~C-c C-u~.

- Key: C-c C-u (sweeprolog-update-dependencies) :: Add explicit
  dependencies for implicitly autoloaded predicates in the current
  buffer.
- User Option: sweeprolog-note-implicit-autoloads :: If non-nil, have
  Flymake complain about implicitly autoloaded predicates in
  ~sweeprolog-mode~ buffers.

This command analyzes the current buffer and adds or updates
~autoload/2~ and ~use_module/2~ as needed.

By default, when Flymake integration is enabled (see [[#diagnostics][Examining
diagnostics]]), calls to implicitly autoloaded predicates are marked
and reported as Flymake diagnostics.  To inhibit Flymake from
diagnosing implicit autoloads, customize the user option
~sweeprolog-note-implicit-autoloads~ to nil.

** Term Search
:PROPERTIES:
:CUSTOM_ID: term-search
:DESCRIPTION: Search for Prolog terms matching with a given structure
:ALT_TITLE: Term Search
:END:

#+CINDEX: term search
#+CINDEX: search term
You can search for Prolog terms matching a given search term with the
command ~M-x sweeprolog-term-search~.

- Key: C-c C-s (sweeprolog-term-search) :: Search for Prolog terms
  matching a given search term in the current buffer.
- Command: sweeprolog-term-search-repeat-forward :: Repeat the last
  Term Search, searching forward from point.
- Command: sweeprolog-term-search-repeat-backward :: Repeat the last
  Term Search, searching backward from point.

This command, bound by default to ~C-c C-s~ in ~sweeprolog-mode~ buffers,
prompts for a Prolog term to search for and finds terms in the current
buffer that the search term subsumes.  It highlights all matching
terms in the buffer and moves the cursor to the beginning of the next
match after point.  For example, to find if-then-else constructs in
the current buffer do ~C-c C-s _ -> _ ; _ RET~.

While prompting for a search term in the minibuffer, this command
populates the "future history" with the Prolog terms at point, with
the most nested term at point on top.  Typing ~M-n~ once in the
minibuffer fills in the innermost term at point, typing ~M-n~ again
cycles up the syntax tree at point filling the minibuffer with larger
terms, up until the top-term at point.  For more information about
minibuffer history commands, see [[info:emacs#Minibuffer History][Minibuffer History]] in the Emacs
manual.

If you invoke ~sweeprolog-term-search~ with a prefix argument, e.g. by
typing ~C-u C-c C-c~, you can further refine the search with an
arbitrary Prolog goal for filtering out search results that fail it.
The given goal runs for each matching term, it may use variables from
the search term to refer to subterms of the matching term.

#+KINDEX: C-s (sweeprolog-term-search-map)
#+KINDEX: C-r (sweeprolog-term-search-map)
Typing ~C-s~ immediately after a successful search invokes the command
~sweeprolog-term-search-repeat-forward~ which moves forward to the next
match.  Likewise, typing ~C-r~ after a successful term search invokes
the command ~sweeprolog-term-search-repeat-backward~ which moves
backward to the previous match.

** Context Menu
:PROPERTIES:
:CUSTOM_ID: context-menu
:DESCRIPTION: Right-click on Prolog code to open contextual menus
:ALT_TITLE: Context Menu
:END:

#+CINDEX: context menu
#+CINDEX: right click menu
In addition to the keybindings that Sweep provides for invoking its
commands, it integrates with Emacs's standard Context Menu minor mode
to provide contextual menus that you operate with the mouse.

- Command: context-menu-mode :: Toggle Context Menu mode.  When
  enabled, clicking the mouse button ~down-mouse-3~ (i.e. right-click)
  activates a menu whose contents depends on its surrounding context.
- Variable: sweeprolog-context-menu-functions :: List of functions
  that create Context Menu entries for Prolog tokens.  Each function
  should receive as its arguments the menu that is being created, the
  Prolog token's description, its start position, its end position,
  and the position of the mouse click.  It should alter the menu
  according to that context.

To enable Context Menu, type ~M-x context-menu-mode~ or add a call to
~(context-menu-mode)~ in your Emacs initialization file to enable it in
all future sessions.  You access the context menu by right-clicking
anywhere in Emacs.  If you do it in a ~sweeprolog-mode~ buffer, you can
invoke several Prolog-specific commands based on where you click in
the buffer.

If you right-click on a Prolog file specification or module name,
Sweep suggests visiting it either in the current window or in another.
If you right-click on a predicate, it lets you view its documentation
in dedicated buffer.

You can further extend and customize the context menu that
~sweeprolog-mode~ provides by adding functions to the variable
~sweeprolog-context-menu-functions~.  Each function on this list
receives the menu that is being created and a description of the
clicked Prolog token, and it can extend the menu with entries before
it's displayed.

* Prolog Help
:PROPERTIES:
:CUSTOM_ID: prolog-help
:DESCRIPTION: Commands for displaying detailed Prolog documentation
:ALT_TITLE: Prolog Help
:END:

#+CINDEX: prolog help
Sweep provides a way to read SWI-Prolog documentation via the standard
Emacs ~help~ user interface, akin to Emacs's built-in ~describe-function~
(~C-h f~) and ~describe-variable~ (~C-h v~).  For more information about
Emacs ~help~ and its special major mode, ~help-mode~, see [[info:emacs#Help Mode][Help Mode in the
Emacs manual]].

- Command: sweeprolog-describe-module :: Prompt for a Prolog module
  and display its full documentation in a help buffer.
- Command: sweeprolog-describe-predicate :: Prompt for a Prolog
  predicate and display its full documentation in a help buffer.

#+KINDEX: s (help-mode)
The command ~M-x sweeprolog-describe-module~ prompts for the name of a
Prolog module and displays its documentation in the =*Help*= buffer.  To
jump to the source code from the documentation, press ~s~
(~help-view-source~).

Similarly, ~M-x sweeprolog-describe-predicate~ can be used to display
the documentation of a Prolog predicate.  This commands prompts for a
predicate with completion.  When the cursor is over a predicate
definition or invocation in a ~sweeprolog-mode~, that predicate is set
as the default selection and can be described by simply typing ~RET~ in
response to the prompt.

* The Prolog Top-Level
:PROPERTIES:
:CUSTOM_ID: prolog-top-level
:DESCRIPTION: Executing Prolog queries in a REPL-like interface
:ALT_TITLE: The Prolog Top-Level
:END:

#+CINDEX: top-level
#+FINDEX: sweeprolog-top-level
Sweep provides a classic Prolog top-level interface for interacting
with the embedded Prolog runtime.  To start the top-level, use =M-x
sweeprolog-top-level=.  This command opens a buffer called =*sweeprolog-top-level*=
which hosts the live Prolog top-level.

#+FINDEX: sweeprolog-top-level-mode
#+VINDEX: sweeprolog-top-level-mode
The top-level buffer uses a major mode named
=sweeprolog-top-level-mode=. This mode derives from =comint-mode=, which is the
common mode used in Emacs REPL interfaces.  As a result, the top-level
buffer inherits the features present in other =comint-mode= derivatives,
most of which are described in [[info:emacs#Shell Mode][the Emacs manual]].

Each top-level buffer is connected to distinct Prolog thread running
in the same process as Emacs and the main Prolog runtime.  In the
current implementation, top-level buffers communicate with their
corresponding threads via local TCP connections.  On the first
invocation of ~sweeprolog-top-level~, Sweep creates a TCP server socket
bound to a random port to accept incoming connections from top-level
buffers.  The TCP server only accepts connections from the local
machine, but note that _other users on the same host_ may be able to
connect to the TCP server socket and _get a Prolog top-level_.  This may
pose a security problem when sharing a host with untrusted users,
hence ~sweeprolog-top-level~ _should not be used on shared machines_.
This is the only Sweep feature that should be avoided in such cases.

** Multiple top-levels
:PROPERTIES:
:CUSTOM_ID: multiple-top-levels
:DESCRIPTION: Creating and handling multiple Prolog top-level buffers
:ALT_TITLE: Multiple Top-Levels
:END:

Any number of top-levels can be created and used concurrently, each in
its own buffer.  If a top-level buffer already exists, =sweeprolog-top-level=
will simply open it by default.  To create another one or more
top-level buffers, run =sweeprolog-top-level= with a prefix argument
(i.e. =C-u M-x sweeprolog-top-level-mode=) to choose a different buffer name.
Alternatively, run the command =C-x x u= (or =M-x rename-uniquely=) in the
buffer called =*sweeprolog-top-level*= and then run =M-x sweeprolog-top-level=
again.  This will change the name of the original top-level buffer to
something like =*sweeprolog-top-level*<2>= and allow the new top-level to
claim the buffer name =*sweeprolog-top-level*=.

** The Top-level Menu buffer
:PROPERTIES:
:DESCRIPTION: A special buffer for operating on active top-levels
:CUSTOM_ID: top-level-menu
:ALT_TITLE: Top-level Menu
:END:

#+CINDEX: Top-level Menu
Sweep provides a convenient interface for listing the active Prolog
top-levels and operating on them, called the Top-level Menu buffer.
This buffer shows the list of active Sweep top-level buffers in a
table that includes information and statistics for each top-level.

#+FINDEX: sweeprolog-list-top-levels
To open the Top-level Menu buffer, use the command ~M-x
sweeprolog-list-top-levels~.  By default, the buffer is will be named
=*sweep Top-levels*=.

The Top-level Menu buffer uses a special major mode named
~sweeprolog-top-level-menu-mode~.  This mode provides several commands
that operate on the top-level corresponding to the table row at point.
The available commands are:

- ~RET~ (~sweeprolog-top-level-menu-go-to~) ::

  #+FINDEX: sweeprolog-top-level-menu-go-to
  Open the specified top-level buffer.

- ~k~ (~sweeprolog-top-level-menu-kill~) ::

  #+FINDEX: sweeprolog-top-level-menu-kill
  Kill the specified top-level buffer.

- ~s~ (~sweeprolog-top-level-menu-signal~) ::

  #+FINDEX: sweeprolog-top-level-menu-signal
  Signal the specified top-level buffer (see [[*Sending signals to running top-levels][Sending signals to
  running top-levels]]).

- ~t~ (~sweeprolog-top-level-menu-new~) ::

  #+FINDEX: sweeprolog-top-level-menu-new
  Create a new top-level buffer.

- ~g~ (~revert-buffer~) ::

  Update the Top-level Menu contents.

** Sending signals to running top-levels
:PROPERTIES:
:CUSTOM_ID: top-level-signals
:DESCRIPTION: Commands for interrupting running Prolog top-levels
:ALT_TITLE: Top-Level Signaling
:END:

#+CINDEX: signaling Prolog threads
#+FINDEX: sweeprolog-top-level-signal
When executing long running Prolog queries in the top-level, there may
arise a need to interrupt the query, either to inspect the state of
the top-level or to free it for running other queries.  To signal a
Sweep top-level that it should stop executing the current query and do
something else instead, use the command
~sweeprolog-top-level-signal~. This command prompts for an active Sweep
top-level buffer followed by a Prolog goal, and interrupts the
top-level causing it to run the specified goal.

#+KINDEX: C-c C-c (sweeprolog-top-level-mode)
#+KINDEX: C-u C-c C-c (sweeprolog-top-level-mode)
#+FINDEX: sweeprolog-top-level-signal-current
#+VINDEX: sweeprolog-top-level-signal-default-goal
In ~sweeprolog-top-level-mode~ buffers, the command
~sweeprolog-top-level-signal-current~ is available for signaling the
current top-level.  It is bound by default to ~C-c C-c~.  Normally, this
command signals the goal specified by the user option
~sweeprolog-top-level-signal-default-goal~, which is set by default to a
predicate that interrupts the top-level thread returns control of the
top-level to the user.  When ~sweeprolog-top-level-signal-current~ is
called with a prefix argument (~C-u C-c C-c~), it prompts for the goal.

It is also possible to signal top-levels from the Sweep Top-level Menu
buffer with the command ~sweeprolog-top-level-menu-signal~ with point at
the entry corresponding to the wanted top-level (see [[The Top-level
Menu buffer]]).

For more information about interrupting threads in SWI-Prolog, see
[[https://www.swi-prolog.org/pldoc/man?section=thread-signal][Signaling threads in the SWI-Prolog manual]].

** Top-level history
:PROPERTIES:
:CUSTOM_ID: top-level-history
:DESCRIPTION: Accessing previous queries posted to the Prolog top-level
:ALT_TITLE: Top-level History
:END:

=sweeprolog-top-level-mode= buffers provide a history of previously user
inputs, similarly to other =comint-mode= derivatives such as =shell-mode=.
To insert the last input from the history at the prompt, use =M-p=
(=comint-previous-input=).  For a full description of history related
commands, see [[info:emacs#Shell History][Shell History in the Emacs manual]].

#+VINDEX: sweeprolog-top-level-min-history-length
The Sweep top-level history only records inputs whose length is at
least =sweeprolog-top-level-min-history-length=.  This user option is set to
3 by default, and should generally be set to at least 2 to keep the
history from being clobbered with single-character inputs, which are
common in the top-level interaction, e.g. =;= as used to invoke
backtracking.

** Completion in the top-level
:PROPERTIES:
:CUSTOM_ID: completion-in-top-level
:DESCRIPTION: Commands for completing partiat Prolog predicate names
:ALT_TITLE: Top-level Completion
:END:

The =sweeprolog-top-level-mode=, enabled in the Sweep top-level buffer,
integrates with the standard Emacs symbol completion mechanism to
provide completion for predicate names.  To complete a partial
predicate name in the top-level prompt, use =C-M-i= (or =M-TAB=).  For
more information see [[info:emacs#Symbol Completion][Symbol Completion in the Emacs manual]].

** Following Error Messages
:PROPERTIES:
:CUSTOM_ID: top-level-compilation-shell-minor-mode
:DESCRIPTION: Minor mode for visiting source locations in printed messages
:ALT_TITLE: Follow Messages
:END:

Many standard SWI-Prolog facilities generate messages that refer to
specific source code locations.  For example, loading a Prolog file
that contains singleton variables into the top-level will produce
warning messages pointing to the starting line of the clauses where
the singleton variables occur.  If you enable
~compilation-shell-minor-mode~ in the top-level buffer, Emacs recognizes
the Prolog messages that refer to source locations and provides
convenient commands for visiting such source locations from the
top-level buffer.  For more information about
~compilation-shell-minor-mode~, see [[info:emacs#Compilation Mode][Compilation Mode]] in the Emacs
manual.

To use ~compilation-shell-minor-mode~ automatically in all top-level
buffers, you can arrange for it to be enabled as part of the
~sweeprolog-top-level-mode~ hook, as follows:

#+begin_src emacs-lisp
  (add-hook 'sweeprolog-top-level-mode-hook
            #'compilation-shell-minor-mode)

#+end_src

** Sending Goals to the Top-level
:PROPERTIES:
:CUSTOM_ID: top-level-send-goal
:DESCRIPTION: Commands for sending goals to the be executed in the Top-level
:ALT_TITLE: Send to Top-level
:END:

#+FINDEX: sweeprolog-top-level-send-goal
You can send a goal to execute in a Prolog top-level from any buffer
with the command ~M-x sweeprolog-top-level-send-goal~.  This command
prompts for a Prolog goal in the minibuffer, executes it in a
top-level buffer and displays that buffer if it's not already visible.
While inserting the goal in the minibuffer, you can use ~TAB~ (or ~C-i~)
to get completion suggestions.

In ~sweeprolog-mode~ buffers, you can invoke
~sweeprolog-top-level-send-goal~ by typing ~C-c C-q~.  It also uses the
goal at point (if any) as the "future history" for the goal prompt,
which you can access with ~M-n~ in the minibuffer.

* Executing Prolog Asynchronously
:PROPERTIES:
:CUSTOM_ID: async-query
:DESCRIPTION: Running goals in seperate threads, redirecting their output to Emacs buffers
:ALT_TITLE: Async Queries
:END:

#+CINDEX: async queries
#+CINDEX: query asynchronously
#+CINDEX: Sweep Async Output mode
Sweep provides a facility for executing Prolog goals in separate
threads and capturing their output in Emacs buffers as it is produced.
You can use this for running queries without blocking Emacs.

- Key: C-c C-& (sweeprolog-async-goal) :: Execute a Prolog goal
  asynchronously and display its output in a dedicated buffer.

The command ~M-x sweeprolog-async-goal~, bound to ~C-c C-&~ in
~sweeprolog-mode~ buffers, prompts for a Prolog goal and executes it in
a new Prolog thread, redirecting its output and error streams to an
Emacs buffer that gets updated asynchronously.

This is similar in nature to running asynchronous shell commands with
the standard ~M-&~ (~async-shell-command~) or ~M-x compile~, expect that
~sweeprolog-async-goal~ runs a Prolog goal instead of a shell command.
For more information about these commands see [[info:emacs#Single Shell][Single Shell]] and
[[info:emacs#Compilation][Compilation]] in the Emacs manual.

The output buffer that ~sweeprolog-async-goal~ creates uses a dedicated
mode called /Sweep Async Output mode/.  This mode is derived from the
standard Compilation mode, it provides all of the usual commands
documented in [[info:emacs#Compilation Mode][Compilation Mode]].  Notably, you can run the same query
again by typing ~g~ (~sweeprolog-async-goal-restart~) in the output
buffer.  To interrupt the goal running in the current output buffer,
press ~C-c C-k~ (~kill-compilation~).

_Compatibility note_: asynchronous queries use pipe processes that
require Emacs 28 or later and SWI-Prolog 9.1.4 or later.

* Finding Prolog code
:PROPERTIES:
:CUSTOM_ID: finding-prolog-code
:DESCRIPTION: Commands for locating and opening Prolog files
:ALT_TITLE: Finding Prolog Code
:END:

#+FINDEX: sweeprolog-find-module
Sweep provides the command =M-x sweeprolog-find-module= for
selecting and jumping to the source code of a loaded or auto-loadable
Prolog module.  Sweep integrates with Emacs's standard completion API
to annotate candidate modules in the completion UI with their =PLDoc=
description when available.

#+FINDEX: sweeprolog-find-predicate
Along with =M-x sweeprolog-find-module=, Sweep provides the
command =M-x sweeprolog-find-predicate= jumping to the definition a
loaded or auto-loadable Prolog predicate.

** Prolog file specification expansion
:PROPERTIES:
:CUSTOM_ID: file-spec-expansion
:DESCRIPTION: Integration with standard Emacs file-finding commands
:ALT_TITLE: File Spec Expansion
:END:

Sweep defines a handler for the Emacs function =expand-file-name= that
recognizes Prolog file specifications, such as =library(lists)=, and
expands them to their corresponding absolute paths.  This means that
one can use Prolog file specifications with Emacs's standard =find-file=
(=C-x C-f=) to locate Prolog resources directly.

For example, typing =C-x C-f library(pldoc/doc_man)= will open the
source of the =pldoc_man= module from the Prolog library, and likewise
=C-x C-f pack(.)= will open the Prolog packages directory.

** Built-in Native Predicates
:PROPERTIES:
:CUSTOM_ID: goto-c-predicates
:DESCRIPTION: Finding and jumping to definitions of built-in SWI-Prolog predicates defined in C
:ALT_TITLE: Native Predicates
:END:

#+CINDEX: native built-in predicates
Some of the built-in predicates provided by SWI-Prolog, such as ~is/2~,
are implemented in C and included as native functions in the
SWI-Prolog runtime.  It is sometimes useful to examine the
implementation of such native built-in predicates by reading its
definition in the SWI-Prolog C sources.  Sweep knows about SWI-Prolog
native built-ins, and can find and jump to their definitions in C when
the user has the SWI-Prolog sources checked out locally.

#+VINDEX: sweeprolog-swipl-sources
The way Sweep locates the SWI-Prolog sources depends on the user
option ~sweeprolog-swipl-sources~.  When customized to a string, it is
taken to be the path to the root directory of the SWI-Prolog source
code.  If instead ~sweeprolog-swipl-sources~ is set to ~t~ (the default),
Sweep will try to locate a local checkout of the SWI-Prolog sources
automatically among known project root directories provided by Emacs's
built-in ~project-known-project-roots~ from =project.el= (see [[info:emacs#Projects][Projects in
the Emacs manual]] for more information about =project.el= projects).
Lastly, setting ~sweeprolog-swipl-sources~ to ~nil~ disables searching for
definitions of native built-ins.

With ~sweeprolog-swipl-sources~ set, the provided commands for finding
predicate definitions operate seamlessly on native built-ins to
display their C definitions in ~c-mode~ buffers (see [[info:ccmode#Top][the Emacs CC Mode
manual]] for information about working with C code in Emacs).  These
commands include:
- ~M-x sweeprolog-find-predicate~,
- ~M-.~ (~xref-find-definitions~) in ~sweeprolog-mode~ buffers (see
  [[#sweeprolog-xref][Definitions and References]]), and
- ~s~ (~help-view-source~) in the =*Help*= buffer produced by ~M-x
  sweeprolog-describe-predicate~ (see [[#prolog-help][Prolog Help]]).

* Quick access to sweep commands
:PROPERTIES:
:CUSTOM_ID: quick-command-access
:DESCRIPTION: Keymap for useful commands that can be invoked from any buffer
:ALT_TITLE: Quick Access Keymap
:END:

#+VINDEX: sweeprolog-prefix-map
Sweep defines a keymap called =sweeprolog-prefix-map= which provides
keybinding for several useful Sweep commands.  By default,
=sweeprolog-prefix-map= itself is not bound to any key.  To bind it globally
to a prefix key, e.g. =C-c p=, use:

#+begin_src emacs-lisp
  (keymap-global-set "C-c p" sweeprolog-prefix-map)
#+end_src

As an example, with the above binding the Sweep top-level can be
accessed from anywhere with =C-c p t=, which invokes the command
=sweeprolog-top-level=.

The full list of keybindings in ~sweeprolog-prefix-map~ is given below:

| Key | Command                              | Documentation                     |
|-----+--------------------------------------+-----------------------------------|
| ~F~   | ~sweeprolog-set-prolog-flag~           | [[*Setting Prolog flags][Setting Prolog Flags]]              |
| ~P~   | ~sweeprolog-pack-install~              | [[*Installing Prolog packages][Installing Prolog packages]]        |
| ~R~   | ~sweeprolog-restart~                   | [[#prolog-init][Prolog Initialization and Cleanup]] |
| ~T~   | ~sweeprolog-list-top-levels~           | [[#top-level-menu][The Top-level Menu Buffer]]         |
| ~X~   | ~sweeprolog-xref-project-source-files~ | [[#sweeprolog-xref][Definitions and References]]        |
| ~e~   | ~sweeprolog-view-messages~             | [[#prolog-messages][Examining Prolog Messages]]         |
| ~h p~ | ~sweeprolog-describe-predicate~        | [[#prolog-help][Prolog Help]]                       |
| ~h m~ | ~sweeprolog-describe-module~           | [[*Prolog Help][Prolog Help]]                       |
| ~l~   | ~sweeprolog-load-buffer~               | [[#loading-buffers][Loading Buffers]]                   |
| ~m~   | ~sweeprolog-find-module~               | [[#finding-prolog-code][Finding Prolog Code]]               |
| ~p~   | ~sweeprolog-find-predicate~            | [[*Finding Prolog code][Finding Prolog Code]]               |
| ~q~   | ~sweeprolog-top-level-send-goal~       | [[#top-level-send-goal][Sending Goals to the Top-level]]    |
| ~t~   | ~sweeprolog-top-level~                 | [[#prolog-top-level][The Prolog Top-level]]              |
| ~&~   | ~sweeprolog-async-goal~                | [[#async-query][Executing Prolog Asynchronously]]   |

* Examining Prolog messages
:PROPERTIES:
:CUSTOM_ID: prolog-messages
:DESCRIPTION: Messages emitted in the embedded Prolog runtime and how to display them
:ALT_TITLE: Prolog Messages
:END:

#+CINDEX: messages
#+VINDEX: sweeprolog-messages-buffer-name
Messages emitted by the embedded Prolog are redirected by Sweep to a
dedicated Emacs buffer.  By default, the Sweep messages buffer is
named =*sweep Messages*=.  To instruct Sweep to use another buffer name
instead, type =M-x customize-option RET sweeprolog-messages-buffer-name RET=
and set the option to a suitable value.

The Sweep messages buffer uses the minor mode =compilation-minor-mode=,
which allows for jumping to source locations indicated in errors and
warning directly from the corresponding message in the Sweep messages
buffer.  For more information about the features enabled by
=compilation-minor-mode=, see [[info:emacs#Compilation Mode][Compilation Mode in the Emacs manual]].

#+FINDEX: sweeprolog-view-messages
Sweep includes the command =sweeprolog-view-messages= for quickly switching
to the Sweep messages buffer.  This command is bound by default in
=sweeprolog-prefix-map= to the =e= key (see [[Quick access to sweep commands]]).

* Setting Prolog flags
:PROPERTIES:
:CUSTOM_ID: prolog-flags
:DESCRIPTION: Commands for modifying the configuration of the embedded Prolog runtime by setting Prolog flags
:ALT_TITLE: Prolog Flags
:END:

#+CINDEX: prolog flags
#+FINDEX: sweeprolog-set-prolog-flag
The command =M-x sweeprolog-set-prolog-flag= can be used to interactively
configure the embedded Prolog execution environment by changing the
values of Prolog flags.  This command first prompts the user for a
Prolog flag to set, with completion candidates annotated with their
current values as Prolog flags, and then prompts for a string that
will be read as a Prolog term and set as the value of the chosen flag.
For more information on Prolog flags in SWI-Prolog see [[https://www.swi-prolog.org/pldoc/man?section=flags][Environment
Control in the SWI-Prolog manual]].

As an example, the Prolog flag =double_quotes= controls the
interpretation of double quotes in Prolog code.  By default,
=double_quotes= is set to =string=, so e.g. ="foo"= is read as a SWI-Prolog
string as we can easily validate in the Sweep top-level:

#+begin_src prolog
?- A = "foo".
A = "foo".
#+end_src

We can change the interpretation of double quotes to denote lists of
character codes, by setting the value the =double_quotes= flag to =codes=
with =M-x sweeprolog-set-prolog-flag RET double_quotes RET codes RET=.
Evaluating =A = "foo"= again exhibits the different interpretation:

#+begin_src prolog
?- A = "foo".
A = [102, 111, 111].
#+end_src

* Installing Prolog packages
:PROPERTIES:
:CUSTOM_ID: prolog-packages
:DESCRIPTION: Commands for installing SWI-Prolog add-ons
:ALT_TITLE: Prolog Packages
:END:

#+FINDEX: sweeprolog-pack-install
The command =M-x sweeprolog-pack-install= can be used to install
or upgrade a SWI-Prolog =pack=. When selecting a =pack= to install, the
completion candidates are annotated with description and the version
of each package.

* Contributing
:PROPERTIES:
:CUSTOM_ID: contributing
:DESCRIPTION: Information for users and hackers looking to get involved in the development of this project
:ALT_TITLE: Contributing
:END:

We highly appreciate all contributions, including bug reports,
patches, improvement suggestions, and general feedback.

For a list of known desired improvements in Sweep, see [[*Things to do][Things to do]].

** Setting up sweep for local development
:PROPERTIES:
:CUSTOM_ID: development-setup
:DESCRIPTION: Instructions for preparing a local development environment for working on sweep
:ALT_TITLE: Developing Sweep
:END:

Since the Prolog and C parts of Sweep are intended to be distributed
and installed along with SWI-Prolog (see [[#installation][Installation]]), the easiest
way to set up Sweep for development is to start with a SWI-Prolog
development setup.  Clone the ~swipl-devel~ Git repository, and update
the included Sweep submodule from its master branch:

#+begin_src sh
  $ git clone --recursive https://github.com/SWI-Prolog/swipl-devel.git
  $ cd swipl-devel/packages/sweep
  $ git checkout master
  $ git pull
#+end_src

The directory =swipl-devel/packages/sweep= now contains the development
version of Sweep, you can make changes to source files and they will
apply when you (re)build SWI-Prolog.  See [[https://github.com/SWI-Prolog/swipl-devel/blob/master/CMAKE.md#building-from-source][Building SWI-Prolog using
cmake]] for instructions on how to build SWI-Prolog from source.

Changes in the Elisp library =sweeprolog.el= do not require rebuilding
SWI-Prolog, and can be applied and tested directly inside Emacs (see [[info:emacs#Lisp
Eval][Evaluating Elisp in the Emacs manual]]).

Most often rebuilding SWI-Prolog after changing =sweep.c= can be
achieved with the following command executed in
=swipl-devel/packages/sweep=:

#+begin_src sh
  $ ninja -C ../../build
#+end_src

** Submitting patches and bug reports
:PROPERTIES:
:CUSTOM_ID: submitting-patches
:DESCRIPTION: Commands for contacting the maintainers of this project
:ALT_TITLE: Submitting Patches
:END:

The best way to get in touch with the Sweep maintainers is via [[https://lists.sr.ht/~eshel/dev][the
sweep mailing list]].

#+FINDEX: sweeprolog-submit-bug-report
The command ~M-x sweeprolog-submit-bug-report~ can be used to easily
contact the Sweep maintainers from within Emacs.  This command opens a
new buffer with a message template ready to be sent to the Sweep
mailing list.

* Things to do
:PROPERTIES:
:CUSTOM_ID: things-to-do
:DESCRIPTION: Breakdown of topics that deserve more attention
:ALT_TITLE: Things To Do
:END:

While Sweep is ready to be used for effective editing of Prolog code,
some improvements remain to be pursued:

** Improvements around editing Prolog
:PROPERTIES:
:CUSTOM_ID: todo-editing
:DESCRIPTION: List of potential enhancements for reading and writing Prolog
:ALT_TITLE: Editing Improvements
:END:

- Inherit user customizations from ~prolog-mode~ :: Sweep should inherit
  user customizations from the standard =prolog.el= built into Emacs to
  accommodate users updating their configs to work with Sweep.
  Ideally, ~sweeprolog-mode~ should be derived from ~prolog-mode~ instead
  of the generic ~prog-mode~ to inherit user-set hooks and
  modifications, but careful consideration is required to make sure
  ~sweeprolog-mode~ overrides all conflicting ~prolog-mode~ features.

- Reflect buffer status in the mode line :: It may be useful to
  indicate in the mode line whether the current ~sweeprolog-mode~ buffer
  has been loaded into the Prolog runtime and/or if its
  cross-reference data is up to date.

- Make predicate completion aware of module-qualification :: predicate
  completion should detect when the prefix it's trying to complete
  starts with a module-qualification ~foo:ba<|>~ and restrict completion
  to matching candidates in the specified module.

- Respect ~font-lock-maximum-decoration~ :: We should take into account
  the value of ~font-lock-maximum-decoration~ while highlighting
  ~sweeprolog-mode~ buffers.  This variable conveys the user's preferred
  degree of highlighting.  A possible approach would be changing
  ~sweeprolog--colour-term-to-faces~ such that each color fragment in
  returned list states its target decoration level (i.e. 1, 2 or 3).
  ~sweeprolog--colourise~ would then compare this target to the value of

  #+begin_src emacs-lisp
    (font-lock-value-in-major-mode font-lock-maximum-decoration)
  #+end_src

  And decide whether or not to apply the fragment.

** Improvements around running Prolog
:PROPERTIES:
:CUSTOM_ID: todo-running
:DESCRIPTION: List of potential enhancements for executing Prolog
:ALT_TITLE: Running Improvements
:END:

- Persist top-level history across sessions :: Sweep should persist
  Prolog top-level histories across invocations of
  ~sweeprolog-top-level~, ideally also across different Emacs sessions.

** General improvements
:PROPERTIES:
:CUSTOM_ID: todo-general
:DESCRIPTION: List of potentially useful new features
:ALT_TITLE: General Improvements
:END:

- Facilitate interactive debugging :: Sweep should facilitate
  interactive debugging of SWI-Prolog code.  This is a big topic that
  we don't currently address.  Perhaps this should handled through
  some Debug Adapter Protocol integration similar to what was done in
  ~dap-swi-prolog~ (see [[https://github.com/eshelyaron/debug_adapter/blob/main/README.md][Debug Adapter Protocol for SWI-Prolog]]).

- Integrate with =project.el= adding support for SWI-Prolog packs :: It
  would be nice if Sweep would "teach" =project.el= to detect
  directories containing SWI-Prolog =pack.pl= package definitions as
  root project directories.

- Extend the provided Elisp-Prolog interface :: Currently, the Elisp
  interface that Sweep provides for querying Prolog only allows
  calling directly to predicates of arity 2 (see [[#querying-prolog][Querying Prolog]]),
  ideally we should provide a (backward-compatible) way for executing
  arbitrary Prolog queries.

#+html: <!--

* Indices
:PROPERTIES:
:CUSTOM_ID: indices
:DESCRIPTION:
:ALT_TITLE: Indices
:END:

** Function index
:PROPERTIES:
:INDEX: fn
:CUSTOM_ID: findex
:DESCRIPTION:
:ALT_TITLE: Function Index
:END:

** Variable index
:PROPERTIES:
:INDEX: vr
:CUSTOM_ID: vindex
:DESCRIPTION:
:ALT_TITLE: Variable Index
:END:

** Keystroke index
:PROPERTIES:
:INDEX: ky
:CUSTOM_ID: kindex
:DESCRIPTION:
:ALT_TITLE: Keystroke Index
:END:

** Concept index
:PROPERTIES:
:INDEX: cp
:CUSTOM_ID: cindex
:DESCRIPTION:
:ALT_TITLE: Concept Index
:END:

#+html: -->