+++ /dev/null
-#+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.
-
-** Main Features
-:PROPERTIES:
-:CUSTOM_ID: main-features
-:DESCRIPTION: Most important features that Sweep provides
-:ALT_TITLE: Main Features
-:END:
-
-Some of the main benefits that Sweep brings to working with Prolog
-code in Emacs are:
-
-- [[#semantic-highlighting][Semantic highlighting]]
-- [[#indentation][Automatic indentation]]
-- [[#term-based-commands][Structural editing and navigation]]
-- [[#sweeprolog-xref][Jumping to predicate definitions and references]]
-- [[#diagnostics][On-the-fly diagnostics]]
-- [[#code-completion][Intelligent code completion]]
-- [[#rename-variable][Refactoring support]]
-- [[#prolog-top-level][Integrated SWI-Prolog top-level]]
-- [[#querying-prolog][Ability to run Prolog queries directly from Emacs Lisp]]
-
-These features and others are documented in the rest of this manual,
-along with many options that Sweep provides for you to customize its
-behavior.
-
-** 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 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.
-
-** Comparison with Emacs's built-in Prolog mode
-:PROPERTIES:
-:CUSTOM_ID: alternatives
-:DESCRIPTION: Comparing Sweep with other Prolog Emacs packages
-:ALT_TITLE: Alternatives
-:END:
-
-Emacs has a built-in mode for Prolog code, defined in the library
-=prolog.el= that comes bundled with Emacs. =prolog.el= aims to work
-with a wide variety of Prolog systems and dialects, unlike Sweep that
-is very tightly integrated with SWI-Prolog specifically.
-
-*If you are working with SWI-Prolog, you'll find Sweep to be far more powerful*
-than the built-in =prolog.el=. This is because Sweep leverages the Prolog
-parser and other analysis tools that SWI-Prolog itself uses, these give Sweep
-access to highly accurate and rich information about SWI-Prolog code. If you're
-using another Prolog implementation, you should stick to =prolog.el= as Sweep
-won't work with other Prolog systems.
-
-* Installation
-:PROPERTIES:
-:CUSTOM_ID: installation
-:DESCRIPTION: Intructions for installing sweep
-:ALT_TITLE: Installation
-:END:
-
-#+CINDEX: requirements
-Installing Sweep requires:
-
-- Emacs 27 or later, and
-- SWI-Prolog 8.5.18 or later.
-
-#+CINDEX: install
-Sweep is available from NonGNU ELPA, to install it simply type in
-Emacs ~M-x package-install RET sweeprolog RET~.
-
-Note that in Emacs prior to version 28, you need to explicitly enable
-NonGNU ELPA by adding something like the following to your Emacs
-configuration:
-
-#+begin_src emacs-lisp
- (with-eval-after-load 'package
- (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))
-#+end_src
-
-#+CINDEX: update
-#+CINDEX: upgrade
-To upgrade Sweep to a newer version, do ~M-x package-upgrade sweeprolog RET~.
-
-* 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! You can now use Sweep for Prolog development ([[#editing-prolog-code][Editing Prolog code]]) and
-for integrating Prolog into your Emacs Lisp code ([[#querying-prolog][Querying Prolog]]). In the next
-section ([[#discovering-sweep][Discovering Sweep]]) you'll find some useful tips for learning to work
-with Sweep.
-
-_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= ([[#high-level-architecture][High-level Architecture]]). 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
-
-* Discovering Sweep
-:PROPERTIES:
-:CUSTOM_ID: discovering-sweep
-:DESCRIPTION: Tips for finding out about Sweep features
-:ALT_TITLE: Discovering Sweep
-:END:
-
-Sweep comes with many useful commands and features for working with
-SWI-Prolog. This section lists suggested ways for you to get to know
-the provided commands and make the most out of Sweep.
-
-The main documentation resource for Sweep is this very manual. It
-describes almost every command and customization option that Sweep
-provides. Since Sweep includes many features, describing all them makes
-this manual longer then you'd probably want to read upfront. Instead
-it's recommended that you skim this manual to get an idea of the
-available features, and then return to it as a reference during your
-work with Sweep.
-
-To open this manual from within Emacs, type ~C-h i~ (~info~) to open the
-Info reader, followed by ~d m sweep RET~ to go to the top Info directory
-and select the Sweep manual. Sweep also provides a convenient command
-for opening the manual:
-
-#+FINDEX: sweeprolog-info-manual
-- Command: sweeprolog-info-manual :: Display the Sweep manual in Info.
-
-To open the relevant part of the manual for a specific command that you
-want to learn more about, type ~C-h F~ followed by the name of that
-command. For example, typing ~C-h F sweeprolog-info-manual RET~ brings up
-this manual section in Info. If the command you're interested in is
-bound to a key sequence, you can go to its Info node by typing ~C-h K~
-followed by the key sequence that invokes it.
-
-Other than the text in this manual, Sweep commands and user options have
-Elisp documentation strings that describe them individually. The
-various Emacs Help commands (~C-h k~, ~C-h f~, ~C-h v~, etc.) display these
-documentation strings in a dedicated Help buffer (see [[info:emacs#Help][Help]] in the Emacs
-manual). From the Help buffer, you can jump to the relevant Info node
-typing ~i~ (~help-goto-info~) to read more about related commands and
-customization options.
-
-You can also view an HTML version of this manual online at
-[[https://eshelyaron.com/sweep.html]].
-
-To learn about recent changes and new features in Sweep, check out the NEWS file
-that comes with Sweep. You can open it with the command ~sweeprolog-view-news~:
-
-- Command: sweeprolog-view-news :: View the Sweep NEWS file.
-
-* 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:
-
-#+FINDEX: sweeprolog-initialize
-- 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~.
-#+FINDEX: sweeprolog-handle-command-line-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.
-#+VINDEX: sweeprolog-init-args
-- 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.
-#+FINDEX: sweeprolog-restart
-- 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 string arguments 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 user option
-~sweeprolog-init-args~ says which arguments to pass to Prolog
-initialization. Its value is a list of strings that you can extend if
-you want to pass specific command line flags SWI-Prolog. For example,
-to limit the embedded Prolog stack to 512 MB, add the following to
-your Emacs configuration:
-
-#+begin_src emacs-lisp
- (with-eval-after-load 'sweeprolog
- (push "--stack-limit=512m" sweeprolog-init-args))
-#+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 called
-~sweep~ with value ~true~. You can check for this flag in Prolog code
-to detect at runtime that you're 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:
-
-#+FINDEX: sweeprolog-open-query
-- 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~.
-#+FINDEX: sweeprolog-next-solution
-- 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.
-#+FINDEX: sweeprolog-cut-query
-- 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.
-#+FINDEX: sweeprolog-close-query
-- Function: sweeprolog-close-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~:
-
-#+FINDEX: sweeprolog-mode
-- Command: sweeprolog-mode :: Enable Sweep major mode for reading and
- editing SWI-Prolog code in the current buffer.
-#+VINDEX: sweeprolog-mode-hook
-- 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 '("\\.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.
-
-To list all of the commands available in a ~sweeprolog-mode~ buffer, type
-~C-h m~ (~describe-mode~). When Menu Bar mode is enabled, you can run many
-of these commands via the Sweep menu. For more information about Menu
-Bar mode, see [[info:emacs#Menu Bars][Menu Bars]] 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: TAB
-#+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.
-#+FINDEX: sweeprolog-indent-line
-- 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.
-#+FINDEX: sweeprolog-infer-indent-style
-- 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.
-
-#+FINDEX: sweeprolog-analyze-buffer
-- Key: C-c C-c (sweeprolog-analyze-buffer) :: Analyze the current
- buffer and update cross-references.
-#+VINDEX: sweeprolog-analyze-buffer-on-idle
-- User Option: sweeprolog-analyze-buffer-on-idle :: If non-nil,
- analyze ~sweeprolog-mode~ buffers on idle. Defaults to ~t~.
-#+VINDEX: sweeprolog-analyze-buffer-max-size
-- 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.
-#+VINDEX: sweeprolog-analyze-buffer-min-interval
-- 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~.
-
-To view and customize the various faces that Sweep defines and uses, type
-~M-x customize-group RET sweeprolog-faces RET~. For more information about
-text faces in Emacs, see [[info:emacs#Faces][Faces]].
-
-*** PceEmacs Highlighting Emulation
-:PROPERTIES:
-:CUSTOM_ID: pce-theme
-:DESCRIPTION: Custom theme that mimics PceEmacs, the SWI-Prolog built-in editor
-:ALT_TITLE: PceEmacs Theme
-:END:
-
-#+CINDEX: PceEmacs theme
-#+CINDEX: theme, PceEmacs
-#+CINDEX: sweeprolog-pce
-Sweep comes with a custom theme, called ~sweeprolog-pce~, that emulates the
-Prolog code highlighting provided by /PceEmacs/, the SWI-Prolog built-in
-Emacs-like editor (see [[https://www.swi-prolog.org/pldoc/man?section=pceemacs][Using the PceEmacs built-in editor]] in the SWI-Prolog
-manual). If you are starting out with Sweep after coming from PceEmacs,
-enabling this theme may soften your landing by providing a more familiar
-experience.
-
-The ~sweeprolog-pce~ theme only affects faces that Sweep itself defines, so you
-can use it along other themes that you may have enabled. To enable this theme
-or the current Emacs session, type ~M-x load-theme RET sweeprolog-pce RET~. To
-enable it for future sessions, add the following to your Emacs configuration:
-
-#+begin_src emacs-lisp
- (load-theme 'sweeprolog-pce t)
-#+end_src
-
-For more information about custom themes in Emacs, see [[info:emacs#Custom Themes][Custom Themes]].
-
-#+VINDEX: sweeprolog-faces-style
-In versions up to and including 0.20.0, Sweep used to provide a different
-mechanism for emulating the highlighting of PceEmacs that involved customizing
-the user option ~sweeprolog-faces-style~. When that option was set to ~light~
-or ~dark~, Sweep would use different sets of faces that mimic the highlighting
-of PceEmacs. ~sweeprolog-faces-style~ is now deprecated, and you should instead
-use the ~sweeprolog-pce~ theme. Still, in benefit of users that have
-~sweeprolog-faces-style~ set and expect Sweep to use PceEmacs highlighting,
-Sweep checks if ~sweeprolog-faces-style~ is either ~light~ or ~dark~ when you
-first open a Prolog buffer, and if so it simply enables the ~sweeprolog-pce~
-theme to get the same effect.
-
-*** 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]]).
-
-#+FINDEX: sweeprolog-highlight-variable
-- 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.
-
-#+VINDEX: sweeprolog-enable-cursor-sensor
-- 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.
-
-#+VINDEX: sweeprolog-qq-mode-alist
-- 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~, Sweep highlights the quoted content with the
-~sweeprolog-qq-content~ face.
-
-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.
-
-#+VINDEX: sweeprolog-enable-help-echo
-- 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:
-
-#+FINDEX: sweeprolog-align-spaces
-- 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.
-#+VINDEX: sweeprolog-enable-cycle-spacing
-- 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~ inserts 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:
-
-#+FINDEX: sweeprolog-electric-layout-mode
-- 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
-#+FINDEX: sweeprolog-insert-term-with-holes
-- 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
-#+FINDEX: sweeprolog-forward-hole
-- Key: C-c TAB (sweeprolog-forward-hole) :: Move point to the next
- hole in the buffer and select it as the region. With numeric prefix
- argument /n/, move forward over /n/ - 1 holes and select the next one.
-#+KINDEX: C-c C-S-i
-#+FINDEX: sweeprolog-backward-hole
-- Key: C-c S-TAB (sweeprolog-backward-hole) :: Move point to the
- previous hole in the buffer and select it as the region. With
- numeric prefix argument /n/, move backward over /n/ - 1 holes and select
- the next one.
-#+FINDEX: sweeprolog-count-holes
-- Key: C-0 C-c TAB (sweeprolog-count-holes) :: Display the number of
- holes that are present in the buffer.
-#+FINDEX: sweeprolog-forward-hole-on-tab-mode
-- 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 use ~C-c S-TAB~ (~sweeprolog-backward-hole~), or call
-~sweeprolog-forward-hole~ with a negative prefix argument (~C-- C-c TAB~).
-
-You can also call ~sweeprolog-forward-hole~ and ~sweeprolog-backward-hole~
-with a numeric prefix argument to jump over the specified number of
-holes. For example, typing ~C-3 C-c TAB~ skips the next two holes in
-the buffer and selects the third as the region. As a special case, if
-you call these commands with a zero prefix argument (~C-0 C-c TAB~),
-they invoke the command ~sweeprolog-count-holes~ instead of jumping.
-This command counts how many holes are left in the current buffer and
-reports its finding via a message in the echo area.
-
-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.
-
-#+VINDEX: sweeprolog-highlight-holes
-- 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:
-
-#+FINDEX: sweeprolog-forward-predicate
-- Key: M-n (sweeprolog-forward-predicate) :: Move forward from point
- to the next predicate definition in the current buffer.
-#+FINDEX: sweeprolog-backward-predicate
-- Key: M-p (sweeprolog-backward-predicate) :: Move backward from point
- to the previous predicate definition.
-#+FINDEX: sweeprolog-mark-predicate
-- 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.
-
-#+FINDEX: sweeprolog-find-file-at-point
-- Key: C-c C-o (sweeprolog-find-file-at-point) :: Resolve file
- specification at point and visit the specified file.
-#+FINDEX: sweeprolog-file-at-point
-- 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~
-opens 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:
-
-#+FINDEX: sweeprolog-load-buffer
-- 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~).
-
-The mode line displays the work "Loaded" next to the "Sweep" major
-mode indicator if the current buffer has is loaded and it hasn't been
-modified since. See [[info:emacs#Mode Line][Mode Line]] in the Emacs manual for more
-information about the mode line.
-
-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.
-
-** Setting Breakpoints
-:PROPERTIES:
-:CUSTOM_ID: breakpoints
-:DESCRIPTION: Commands for setting breakpoints in Prolog buffers
-:ALT_TITLE: Setting Breakpoints
-:END:
-
-#+CINDEX: breakpoints
-You can set /breakpoints/ in ~sweeprolog-mode~ buffers to have SWI-Prolog
-break before specific goals in the code (see [[https://www.swi-prolog.org/pldoc/man?section=trace-breakpoints][Breakpoints]] in the
-SWI-Prolog manual).
-
-#+FINDEX: sweeprolog-set-breakpoint
-- Key: C-c C-b (sweeprolog-set-breakpoint) :: Set a breakpoint.
-#+VINDEX: sweeprolog-highlight-breakpoints
-- User Option: sweeprolog-highlight-breakpoints :: If non-nil,
- highlight breakpoints in ~sweeprolog-mode~ buffers. Defaults to ~t~.
-
-The command ~sweeprolog-set-breakpoint~, bound to ~C-c C-b~, sets a
-breakpoint at the position of the cursor. If you call it with a
-positive prefix argument (e.g. ~C-u C-c C-b~), it creates a conditional
-breakpoint with a condition goal that you insert in the minibuffer.
-If you call it with a non-positive prefix argument (e.g. ~C-0 C-c C-b~),
-it deletes the breakpoint at point instead.
-
-When Context Menu mode is enabled, you can also create and delete
-breakpoints in ~sweeprolog-mode~ buffers through right-click context
-menus (see [[#context-menu][Context Menu]]).
-
-By default, Sweep highlights terms with active breakpoints in
-~sweeprolog-mode~ buffers. To inhibit breakpoint highlighting,
-customize the user option ~sweeprolog-highlight-breakpoints~ to ~nil~.
-
-*** Breakpoint Menu
-:PROPERTIES:
-:CUSTOM_ID: breakpoint-menu
-:DESCRIPTION: Special mode for managing breakpoints
-:ALT_TITLE: Breakpoint Menu
-:END:
-
-Sweep provides a /breakpoint menu/ that lets you manage breakpoints
-across your codebase.
-
-#+FINDEX: sweeprolog-list-breakpoints
-- Command: sweeprolog-list-breakpoints :: Display a list of active
- breakpoints.
-
-To open the breakpoint menu, type ~M-x sweeprolog-list-breakpoints~.
-This command opens the breakpoint menu in the =*Sweep Breakpoints*=
-buffer. The major mode of this buffer is Sweep Breakpoint Menu,
-which is a special mode that includes useful commands for managing
-Prolog breakpoints:
-
-#+FINDEX: sweeprolog-breakpoint-menu-find
-- Key: RET (sweeprolog-breakpoint-menu-find) :: Go to the position of
- the breakpoint corresponding to the breakpoint menu entry at point.
-#+FINDEX: sweeprolog-breakpoint-menu-find-other-window
-- Key: o (sweeprolog-breakpoint-menu-find-other-window) :: Show the
- position of the breakpoint corresponding to the breakpoint menu
- entry at point, in another window.
-#+FINDEX: sweeprolog-breakpoint-menu-set-condition
-- Key: c (sweeprolog-breakpoint-menu-set-condition) :: Set the
- condition goal for the breakpoint corresponding to the breakpoint
- menu entry at point.
-
-** 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.
-
-#+VINDEX: sweeprolog-module-header-comment-skeleton
-- 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]].
-
-#+FINDEX: sweeprolog-document-predicate-at-point
-- Key: C-c C-d (sweeprolog-document-predicate-at-point) :: Insert
- =PlDoc= documentation comment for the predicate at or above point.
-#+VINDEX: sweeprolog-read-predicate-documentation-function
-- 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~.
-#+FINDEX: sweeprolog-read-predicate-documentation-default-function
-- Function: sweeprolog-read-predicate-documentation-default-function :: Prompt
- and read from the minibuffer the argument modes, determinism
- specification and initial summary of the given predicate.
-#+FINDEX: sweeprolog-read-predicate-documentation-with-holes
-- Function: sweeprolog-read-predicate-documentation-with-holes :: Use
- holes for the initial documentation of the given predicate.
-
-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]].
-
-** Example Usage Comments
-:PROPERTIES:
-:CUSTOM_ID: usage-comments
-:DESCRIPTION: Commands for inserting comments that show example usage of your code
-:ALT_TITLE: Usage Comments
-:END:
-
-Beyond documenting your code with =PlDoc= comments as described in
-[[#sweeprolog-pldoc][Documenting Predicates]], you may want to have comments in your source
-code that demonstrate example usage of some predicate or another.
-Creating such comments usually involves posting queries in a Prolog
-top-level, copying the queries and their results into the relevant
-source code buffer, and formatting them as comments. Sweep provides
-the following command to streamline this process:
-
-#+FINDEX: sweeprolog-make-example-usage-comment
-- Key: C-c C-% (sweeprolog-make-example-usage-comment) :: Start a
- new top-level for recording example usage. When you finish
- interacting with the top-level its contents are formatted as a
- comment in the buffer and position where you invoked this command.
-
-The command ~sweeprolog-make-example-usage-comment~, bound to ~C-c
-C-%~ in ~sweeprolog-mode~ buffers, creates and switches to a new
-top-level buffer for recording example usage that you want to
-demonstrate. The /example usage top-level/ is a regular top-level
-buffer (see [[*The Prolog Top-Level][The Prolog Top-Level]]), except that it's tied to the
-specific position in the source buffer where you invoke this command.
-You can post queries in the example usage top-level and edit it
-freely, then type ~C-c C-q~ in to quit the top-level buffer and format
-its contents as a comment in the source buffer.
-
-You can have multiple example usage top-levels for different parts of
-your code at the same time. To display the source position where you
-created a certain usage example top-level buffer by, type ~C-c C-b~ in
-that buffer.
-
-** 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.
-
-#+VINDEX: sweeprolog-enable-eldoc
-- 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.
-
-#+VINDEX: sweeprolog-enable-flymake
-- User Option: sweeprolog-enable-flymake :: If non-nil, enable Flymake
- support in ~sweeprolog-mode~ buffers. Defaults to ~t~.
-#+FINDEX: sweeprolog-show-diagnostics
-- 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).
-
-#+FINDEX: sweeprolog-export-predicate
-- 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~ prompts
-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
-In Emacs, major modes for different programming languages provide in-buffer
-code completion via a standard generic command called ~completion-at-point~
-([[info:emacs#Symbol Completion][Symbol Completion]]). This command is normally bound to ~C-M-i~ and ~M-TAB~.
-Sweep extends and empowers ~completion-at-point~ with context-aware
-completion for Prolog code in Prolog buffers.
-
-When providing candidates for in-buffer completion, Sweep takes into account
-the code surrounding the cursor to determine what kind of completion makes
-most sense:
-
-- 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 predicate calls as completion
- candidates. If the predicate you choose takes arguments, Sweep inserts
- holes in their places, and moves point to the first argument ([[#holes][Holes]]).
-- Atom completion :: If point is at a non-callable position,
- ~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
-#+FINDEX: sweeprolog-insert-term-dwim
-- Key: M-RET (sweeprolog-insert-term-dwim) :: Insert an appropriate
- Prolog term in the current buffer, based on the context at point.
-#+VINDEX: sweeprolog-insert-term-functions
-- 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
-#+FINDEX: sweeprolog-maybe-insert-next-clause
-- 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.
-#+FINDEX: sweeprolog-maybe-define-predicate
-- 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~.
-
-#+FINDEX: 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~.
-
-#+FINDEX: sweeprolog-update-dependencies
-- Key: C-c C-u (sweeprolog-update-dependencies) :: Add explicit
- dependencies for implicitly autoloaded predicates in the current
- buffer.
-#+VINDEX: sweeprolog-dependency-directive
-- User Option: sweeprolog-dependency-directive :: Determines which
- Prolog directive to use in ~sweeprolog-update-dependencies~ when
- adding new directives. The value of this user option is one of the
- symbols ~use-module~, ~autoload~ or ~infer~. If it is ~use-module~,
- ~sweeprolog-update-dependencies~ adds ~use_module/2~ directives,
- ~autoload~ means to add ~autoload/2~ directives, and ~infer~ says to infer
- which directive to use based on the existing dependency directives
- in the buffer, if any. Defaults to ~infer~.
-#+VINDEX: sweeprolog-note-implicit-autoloads
-- User Option: sweeprolog-note-implicit-autoloads :: If non-nil, have
- Flymake complain about implicitly autoloaded predicates in
- ~sweeprolog-mode~ buffers.
-
-The command ~sweeprolog-update-dependencies~, bound to ~C-c C-u~, analyzes
-the current buffer and adds or updates ~autoload/2~ and ~use_module/2~ as
-needed.
-
-When this command adds a new directive, rather than updating an
-existing one, it can use either ~autoload/2~ or ~use_module/2~ to declare
-the new dependency based on the value of the user option
-~sweeprolog-dependency-directive~. If you set this option is to
-~use-module~, new dependencies use the ~use_module/2~ directive. If it's
-~autoload~, new dependencies use ~autoload/2~. If it's ~infer~, as it is by
-default, new dependencies use ~autoload/2~ unless the buffer already
-contains dependency directives and they are all ~use_module/2~
-directives, in which case they also use ~use_module/2~.
-
-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~.
-
-#+FINDEX: sweeprolog-term-search
-- Key: C-c C-s (sweeprolog-term-search) :: Search for Prolog terms
- matching a given search term in the current buffer.
-#+FINDEX: sweeprolog-term-search-repeat-forward
-- Command: sweeprolog-term-search-repeat-forward :: Repeat the last
- Term Search, searching forward from point.
-#+FINDEX: sweeprolog-term-search-repeat-backward
-- 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 interact with using 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 depend on its surrounding context.
-#+VINDEX: sweeprolog-context-menu-functions
-- 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 a dedicated buffer (see also [[#prolog-help][Prolog Help]]). For variables, it
-enables the ~Rename Variable~ menu entry that you can use to rename the
-variable you click on across its containing clause (see [[#rename-variable][Renaming
-Variables]]).
-
-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.
-
-** Renaming Variables
-:PROPERTIES:
-:CUSTOM_ID: rename-variable
-:DESCRIPTION: Replacing occurrences of one Prolog variable with another
-:ALT_TITLE: Renaming Variables
-:END:
-
-You can rename a Prolog variable across the current top-term with the
-following command:
-
-#+FINDEX: sweeprolog-rename-variable
-- Key: C-c C-r (sweeprolog-rename-variable) :: Rename a variable
- across the topmost Prolog term at point.
-#+VINDEX: sweeprolog-rename-variable-allow-existing
-- User Option: sweeprolog-rename-variable-allow-existing :: If
- non-nil, allow selecting an existing variable name as the new name
- of a variable being renamed with ~sweeprolog-rename-variable~. If it
- is the symbol ~confirm~, allow but ask for confirmation first.
- Defaults to ~confirm~.
-
-The command ~sweeprolog-rename-variable~, bound to ~C-c C-r~, prompts for
-two variable names and replaces all occurrences of the first variable
-in the term at point with the second. The prompt for the first (old)
-variable name provides completion based on the existing variable names
-in the current term, and it uses the variable at point as its default.
-
-The user option ~sweeprolog-rename-variable-allow-existing~ controls
-what happens if the second (new) variable name that you insert in the
-minibuffer already occurs in the current clause. By default it is set
-to ~confirm~, which says to ask for confirmation before selecting an
-existing variable name as the new name. This is because renaming a
-variable to another existing variable name potentially alters the
-semantics of the term by merging the two variables. Other
-alternatives for this user option are ~t~ for allowing such merges
-without confirmation, and ~nil~ for refusing them altogether.
-
-If Context Menu mode is enabled, you can also rename variables by
-right-clicking on them with the mouse and selecting =Rename Variable=
-from the top of the context menu. See [[#context-menu][Context Menu]] for more
-information about context menus in Sweep.
-
-** Numbered Variables
-:PROPERTIES:
-:CUSTOM_ID: numbered-variables
-:DESCRIPTION: Commands for managing numbers in names of related variables
-:ALT_TITLE: Numbered Variables
-:END:
-
-A widespread convention in Prolog is using a common prefix with a
-numeric suffix to name related variables, such as ~Foo0~, ~Foo1~, etc..
-Sweep provides convenient commands for managing such /numbered variable/
-sequences consistently:
-
-#+FINDEX: sweeprolog-increment-numbered-variables
-- Key: C-c C-+ (sweeprolog-increment-numbered-variables) :: Prompt for
- a numbered variable and increment it and all numbered variables with
- the same base name and a greater number in the current clause.
-#+FINDEX: sweeprolog-decrement-numbered-variables
-- Key: C-c C-- (sweeprolog-decrement-numbered-variables) :: Prompt for
- a numbered variable and decrement it and all numbered variables with
- the same base name and a greater number in the current clause.
-
-Numbering variables is often used to convey the order in which they
-are bound. For example:
-
-#+begin_src prolog
- %! process(+State0, -State) is det.
-
- process(State0, State) :-
- foo(State0, State1),
- bar(State2, State1),
- baz(State2, State).
-#+end_src
-
-Here ~State0~ and ~State~ are respectively the input and output arguments
-of ~process/2~, and ~State1~ and ~State2~ represent intermediary stages
-between them.
-
-The command ~C-c C-+~ (~sweeprolog-increment-numbered-variables~) prompts
-you for a numbered variable in the current clause, and increments the
-number of that variable along with all other numbered variables with
-the same base name and a greater number. You can use it to "make
-room" for another intermediary variable between two sequentially
-numbered variables. If you call this command with point on a numeric
-variable, it suggests that variable as the default choice. If you
-call this command with a prefix argument, it increments by the numeric
-value of the prefix argument, otherwise it increments by one.
-
-For instance, typing ~C-c C-+ State1 RET~ with point anywhere in the
-definition of ~process/2~ from the above example results in the
-following code:
-
-#+begin_src prolog
- process(State0, State) :-
- foo(State0, State2),
- bar(State3, State2),
- baz(State3, State).
-#+end_src
-
-Note how all occurrences of ~State1~ are replaced with ~State2~, while
-occurrences of ~State2~ are replaced with ~State3~. The overall semantics
-of the clause doesn't change, but we can now replace the call to ~foo/2~
-with two goals and reintroduce ~State1~ as an intermediary result
-between them while keeping our numbering consistent, e.g.:
-
-#+begin_src prolog
- process(State0, State) :-
- one(State0, State1), two(State1, State2),
- bar(State3, State2),
- baz(State3, State).
-#+end_src
-
-If Context Menu mode is enabled, you can also invoke
-~sweeprolog-increment-numbered-variables~ by right-clicking on a
-numbered variables and selecting =Increment Variable Numbers= from the
-context menu. See [[#context-menu][Context Menu]].
-
-The command ~C-c C--~ (~sweeprolog-decrement-numbered-variables~) is
-similar to ~C-c C-+~ except it decrements all numbered variables
-starting with a given numbered variable rather than incrementing them.
-You can use this function after you delete a numbered variable,
-leaving you with a gap in the variable numbering sequence, to
-decrement the following numbered variables accordingly.
-
-After invoking either ~C-c C--~ or ~C-c C-+~, you can continue to
-decrement or increment the same set of numbered variables by repeating
-with ~-~ and ~+~.
-
-** Macro Expansion
-:PROPERTIES:
-:CUSTOM_ID: macro-expansion
-:DESCRIPTION: Commands for expanding SWI-Prolog macros
-:ALT_TITLE: Macro Expansion
-:END:
-
-Recent versions of SWI-Prolog include a pre-processing mechanism called
-/Prolog macros/, implemented in ~library(macros)~. It provides a convenient
-way for computing terms at compile time and using them in code.
-
-Macros are defined using special rules with ~#define(Macro, Replacement)~
-head terms. Then, when SWI-Prolog reads a term of the form ~#(Macro)~
-during compilation, it invokes the macro replacement rule and uses the
-expanded term instead.
-
-Sweep can replace macro invocations with their expansions. To expand a
-macro in your source code, use the following command:
-
-#+FINDEX: sweeprolog-expand-macro-at-point
-- Command: sweeprolog-expand-macro-at-point :: Replace the Prolog macro
- invocation starting at point with its expansion.
-
-You can call this command with point on the ~#~ macro indicator to expand
-the macro inline. To undo the expansion, use ~C-/~ (~undo~).
-
-With Context Menu mode enabled, you can also expand macros by right-clicking
-on the ~#~ and selecting =Expand Macro= from the context menu. See also
-[[#context-menu][Context Menu]].
-
-
-* 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]].
-
-#+FINDEX: sweeprolog-describe-module
-- Command: sweeprolog-describe-module :: Prompt for a Prolog module
- and display its full documentation in a help buffer.
-#+FINDEX: sweeprolog-describe-predicate
-- 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=
-simply opens 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 changes 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 called
-=*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:
-
-Sweep top-level buffers provide a history of previous 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
-- User Option: sweeprolog-top-level-min-history-length :: Minimum
- input length to record in the history of Sweep top-levels.
-#+VINDEX: sweeprolog-top-level-persistent-history
-- User Option: sweeprolog-top-level-persistent-history :: Controls if
- and where Sweep top-level buffers persist their input history.
-
-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.
-
-Sweep can optionally persist top-level input history. The user option
-~sweeprolog-top-level-persistent-history~ controls if and where
-top-levels store their persistent history: when this option is
-non-~nil~, Sweep top-level buffers that you create read their input
-history from a persistent history file, and write their history back
-to it when you delete them. If this option is a string, it is treated
-as a file name, and top-level buffers use that file to persistent
-their input history. If it's a function, it is called with no
-arguments and should return either a file name for the persistent
-history, or ~nil~ to disable persistent history for that top-level
-buffer. The file name that this user option specifies can be either
-absolute or relative, in which case it is expanded relative to the
-default directory of the top-level buffer (see [[info:emacs#File Names][File Names]]). This
-option can also be a list of the form ~(project REL DEF)~, in which
-case the persistent history file that a top-level buffer uses depends
-on the current project of the of that buffer (see [[info:emacs#Projects][Projects]] in the
-Emacs manual). If there is no current project, the top-level
-persistent history file is ~DEF~. Otherwise, the history file is
-~REL~ relative to the project's root directory. You can leave ~DEF~
-nil or omit it entirely to disable persistent history for top-levels
-that are not associated with any project. By default, this option is
-set to ~nil~ which says not to keep persistent top-level history.
-
-** 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 produces 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]].
-
-To use ~compilation-shell-minor-mode~ automatically in all top-level
-buffers, you can arrange for the ~sweeprolog-top-level-mode~ hook to
-enable it 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:
-
-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~.
-
-#+FINDEX: sweeprolog-top-level-send-goal
-- Key: C-c C-q (sweeprolog-top-level-send-goal) :: Execute a Prolog goal
- in a top-level buffer and display that buffer.
-
-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.
-
-#+FINDEX: sweeprolog-async-goal
-- 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:
-
-The following commands let you jump to a piece of Prolog code from
-anywhere in Emacs:
-
-#+FINDEX: sweeprolog-find-module
-- Command: sweeprolog-find-module :: Prompt for a known Prolog module
- and find its source code.
-#+FINDEX: sweeprolog-find-predicate
-- Command: sweeprolog-find-predicate :: Prompt for a known Prolog
- predicate and find its source code.
-
-~sweeprolog-find-module~ and ~sweeprolog-find-predicate~ prompt you for a
-Prolog identifier (respectively, a module name or a predicate indicator),
-and jump to its source definition. Sweep integrates with Emacs's standard
-completion API to annotate candidate modules in the completion UI with a
-summary line derived from their documentation, when available.
-
-By default, these commands use the current window to display the selected
-module or predicate. To have it in another window instead, invoke these
-commands with a prefix argument (e.g. ~C-u M-x sweeprolog-find-predicate~).
-
-#+FINDEX: sweeprolog-read-predicate
-#+VINDEX: sweeprolog-predicate-visible-p-function
-The command ~sweeprolog-find-predicate~ uses the function
-~sweeprolog-read-predicate~ for prompting you to insert a predicate
-indicator in the minibuffer. This is the standard function that Sweep
-commands use for this purpose, it provides completion candidates based on
-known predicates, and it uses the predicate at point, if any, as the
-default minibuffer argument. By default, ~sweeprolog-read-predicate~
-includes all predicates that Sweep knows about as completion candidates,
-except for predicate whose functor name begins with ~$~, because that's the
-convention in in SWI-Prolog for internal predicates that are usually of
-little interest to users. To include also these predicates as completion
-candidates, customize the user option
-~sweeprolog-predicate-visible-p-function~ to ~nil~.
-
-** 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 you
-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)~ opens the source of
-the ~pldoc_man~ module from the Prolog library, and ~C-x C-f pack(.)~
-opens 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
-- User Option: sweeprolog-swipl-sources :: Location of the SWI-Prolog
- source code root directory.
-
-The way Sweep locates the SWI-Prolog sources depends on the user
-option ~sweeprolog-swipl-sources~. Setting it to ~nil~ disables
-searching for definitions of native built-ins altogether. To point
-Sweep to the root directory of the SWI-Prolog source code, set
-~sweeprolog-swipl-sources~ to the name of that directory. Any
-non-~nil~ non-string value says to try and locate a checkout of the
-SWI-Prolog sources among known project root directories (Sweep
-consults Emacs's built-in ~project-known-project-roots~ to find your
-project roots, see also [[info:emacs#Projects][Projects]] in the Emacs manual).
-
-With ~sweeprolog-swipl-sources~ set, the provided commands for finding
-predicate definitions operate seamlessly on native built-ins to
-display their C definitions. These commands include:
-- ~M-x sweeprolog-find-predicate~,
-- ~M-.~ (~xref-find-definitions~) in ~sweeprolog-mode~
- buffers ([[#sweeprolog-xref][Definitions and References]]), and
-- ~s~ (~help-view-source~) in the =*Help*= buffer produced by
- ~M-x sweeprolog-describe-predicate~ ([[#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~ that provides global
-keybindings for several useful Sweep commands. By default,
-~sweeprolog-prefix-map~ itself is not bound to any key. To bind it to ~C-c p~,
-add the following to your Emacs configuration:
-
-#+begin_src emacs-lisp
- (keymap-global-set "C-c p" 'sweeprolog-prefix-map)
-#+end_src
-
-~C-c p~ is the recommended binding for ~sweeprolog-prefix-map~, but you're free
-to pick any key sequence you like. As an example, with the above binding you
-can access the Sweep top-level from anywhere with ~C-c p t~.
-
-The full list of keybindings in ~sweeprolog-prefix-map~, assuming the
-recommended key binding, is given below:
-
-- Key: C-c p m (sweeprolog-find-module) :: See [[#finding-prolog-code][Finding Prolog Code]].
-- Key: C-c p p (sweeprolog-find-predicate) :: See [[#finding-prolog-code][Finding Prolog Code]].
-- Key: C-c p t (sweeprolog-top-level) :: See [[#prolog-top-level][The Prolog Top-Level]].
-- Key: C-c p q (sweeprolog-top-level-send-goal) :: See [[#top-level-send-goal][Sending Goals to the Top-level]].
-- Key: C-c p l (sweeprolog-load-buffer) :: See [[#loading-buffers][Loading Buffers]].
-- Key: C-c p & (sweeprolog-async-goal) :: See [[#async-query][Executing Prolog Asynchronously]].
-- Key: C-c p B (sweeprolog-list-breakpoints) :: See [[#breakpoint-menu][Breakpoint Menu]].
-- Key: C-c p P (sweeprolog-pack-install) :: See [[#prolog-packages][Installing Prolog Packages]].
-- Key: C-c p R (sweeprolog-restart) :: See [[#prolog-init][Prolog Initialization and Cleanup]].
-- Key: C-c p F (sweeprolog-set-prolog-flag) :: See [[#prolog-flags][Setting Prolog Flags]].
-- Key: C-c p T (sweeprolog-list-top-levels) :: See [[#top-level-menu][The Top-level Menu buffer]].
-- Key: C-c p X (sweeprolog-xref-project-source-files) :: See [[#sweeprolog-xref][Definitions and References]].
-- Key: C-c p h m (sweeprolog-describe-module) :: See [[#prolog-help][Prolog Help]].
-- Key: C-c p h p (sweeprolog-describe-predicate) :: See [[#prolog-help][Prolog Help]].
-- Key: C-c p h e (sweeprolog-view-messages) :: See [[#prolog-messages][Examining Prolog Messages]].
-- Key: C-c p h n (sweeprolog-view-news) :: See [[#discovering-sweep][Discovering Sweep]].
-
-* 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
-Sweep redirects messages that the embedded Prolog runtime emits to a
-dedicated Emacs buffer. By default, the Sweep messages buffer is named
-=*sweep Messages*=. To instruct Sweep to use another buffer name
-instead, customize the user option ~sweeprolog-messages-buffer-name~ to
-a suitable value.
-
-The Sweep messages buffer enables the minor mode
-~compilation-minor-mode~ ([[info:emacs#Compilation Mode][Compilation Mode]]). This let's you jump to
-source locations that appear in errors and warning by clicking on them.
-
-#+FINDEX: sweeprolog-view-messages
-- Command: sweeprolog-view-messages :: Display the Sweep messages buffer.
-
-You can use the command ~sweeprolog-view-messages~ to display the Sweep
-messages buffer. This command is bound to ~h e~ in
-~sweeprolog-prefix-map~ ([[#quick-command-access][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
-SWI-Prolog has a set of /flags/ that let you examine and configure the
-Prolog execution runtime. You can set Prolog flags from Emacs directly
-with the following command:
-
-#+FINDEX: sweeprolog-set-prolog-flag
-- Command: sweeprolog-set-prolog-flag :: Set the value of a Prolog flag.
-
-This command let's you interactively configure the embedded Prolog
-execution environment by changing the values of Prolog flags. It
-prompts you for a Prolog flag, with completion candidates annotated with
-their current values. Then, it prompts again for a Prolog term and sets
-the flag's value to that term.
-
-For more information about 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
-
-Note that some flags have a thread-local value, and
-~sweeprolog-set-prolog-flag~ always operates only on the main thread.
-To set flags in an existing top-level thread, use the predicate
-~set_prolog_flag/2~ directly in that top-level.
-
-* Installing Prolog Packages
-:PROPERTIES:
-:CUSTOM_ID: prolog-packages
-:DESCRIPTION: Commands for installing SWI-Prolog add-ons
-:ALT_TITLE: Prolog Packages
-:END:
-
-You can install SWI-Prolog add-ons, also known as /packs/, with the
-following command:
-
-#+FINDEX: sweeprolog-pack-install
-- Command: sweeprolog-pack-install :: Install or upgrade a Prolog pack.
-
-This command prompts from a pack name, with completion, and installs it
-or upgrades it to the latest available version. (See also [[https://www.swi-prolog.org/pldoc/man?section=packs][Packs]] in the
-SWI-Prolog manual.)
-
-* 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: Bug Reports
-: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
-- Command: sweeprolog-submit-bug-report :: Report a bug in Sweep to
- the maintainers via mail.
-
-You can use the command ~M-x sweeprolog-submit-bug-report~ 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:
-
-- 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 ~(font-lock-value-in-major-mode font-lock-maximum-decoration)~
- and decide whether or not to apply the fragment.
-
-** 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: -->
projects / sweep.git / commitdiff