From: Eshel Yaron Date: Thu, 12 Jan 2023 19:20:42 +0000 (+0200) Subject: Refer to Sweep as a whole as "Sweep" without verbatim format X-Git-Tag: V9.1.3-sweep-0.11.3~11 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=95fbd1388efcf6995cb8da431f2d2160bfc7270a;p=dict.git Refer to Sweep as a whole as "Sweep" without verbatim format --- diff --git a/README.org b/README.org index 4da79be..7fae727 100644 --- a/README.org +++ b/README.org @@ -1,4 +1,4 @@ -#+title: sweep: SWI-Prolog Embedded in Emacs +#+title: Sweep: SWI-Prolog Embedded in Emacs #+author: Eshel Yaron #+email: me@eshelyaron.com #+language: en @@ -14,8 +14,8 @@ #+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=), which -provides an embedded SWI-Prolog runtime inside of Emacs. +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 @@ -26,9 +26,9 @@ provides an embedded SWI-Prolog runtime inside of Emacs. :ALT_TITLE: Overview :END: -=sweep= is an embedding of SWI-Prolog in Emacs. It provides an +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 +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. @@ -39,12 +39,12 @@ advanced features for developing SWI-Prolog programs in Emacs. :ALT_TITLE: Architecture :END: -=sweep= uses the C interfaces of both SWI-Prolog and Emacs Lisp to +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 +runtime. As such, Sweep has parts written in C, in Prolog and in Emacs Lisp. -The different parts of =sweep= are structured as follows: +The different parts of Sweep are structured as follows: #+CINDEX: sweep-module - =sweep.c= defines a dynamic Emacs module which is referred to from @@ -61,7 +61,7 @@ The different parts of =sweep= are structured as follows: dynamically loaded =sweep-module=. #+CINDEX: sweep.pl -- =sweep.pl= defines a Prolog module (named, unsurprisingly, =sweep=) +- =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 @@ -83,9 +83,9 @@ The =sweeprolog= Elisp package is available on NonGNU ELPA, to install =sweeprolog= simply type =M-x package-install RET sweeprolog RET=. An alternative to installing from ELPA is to get the Elisp library -from the =sweep= Git repository: +from the Sweep Git repository: -1. Clone the =sweep= repository: +1. Clone the Sweep repository: #+begin_src sh git clone https://git.sr.ht/~eshel/sweep #+end_src @@ -96,7 +96,7 @@ from the =sweep= Git repository: git clone https://github.com/SWI-Prolog/packages-sweep sweep #+end_src -2. Add =sweep= to Emacs's =load-path=: +2. Add Sweep to Emacs's =load-path=: #+begin_src emacs-lisp (add-to-list 'load-path "/path/to/sweep") #+end_src @@ -116,12 +116,12 @@ After installing the =sweeprolog= Elisp library, load it into Emacs: #+end_src #+VINDEX: sweeprolog-swipl-path -~sweep~ tries to find SWI-Prolog by looking for the =swipl= executable in +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 +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 @@ -130,12 +130,12 @@ the variable ~sweeprolog-swipl-path~ to point to it: All set! =sweeprolog= automatically loads =sweep-module= and initializes the embedded SWI-Prolog runtime. For a description of the different -features of =sweep=, see the following sections of this manual. +features of Sweep, see the following sections of this manual. _Important note for Linux users_: prior to version 29, Emacs would load dynamic modules in a way that is not fully compatible with the way the SWI-Prolog native library, =libswipl=, loads its own native extensions. -This may lead to =sweep= failing after loading =sweep-module=. To work +This may lead to Sweep failing after loading =sweep-module=. To work around this issue, users running Emacs 28 or earlier on Linux can start Emacs with =libswipl= loaded upfront via =LD_PRELOAD=, for example: @@ -152,7 +152,7 @@ start Emacs with =libswipl= loaded upfront via =LD_PRELOAD=, for example: #+FINDEX: sweeprolog-initialize The embedded SWI-Prolog runtime must be initialized before it can -start executing queries. In =sweep=, Prolog initialization is done via +start executing queries. In Sweep, Prolog initialization is done via the C-implemented =sweeprolog-initialize= Elisp function defined in =sweep-module=. =sweeprolog-initialize= takes one or more arguments, which must all be strings, and initializes the embedded Prolog as if it were @@ -161,7 +161,7 @@ line arguments, where the first argument to =sweeprolog-initialize= corresponds to =argv[0]=. #+VINDEX: sweeprolog-init-args -~sweep~ loads and initializes Prolog on-demand at the first invocation +Sweep loads and initializes Prolog on-demand at the first invocation of a command that requires the embedded Prolog. The arguments used to initialize Prolog are then determined by the value of the user-option ~sweeprolog-init-args~ which the user is free to extend with e.g.: @@ -172,14 +172,14 @@ initialize Prolog are then determined by the value of the user-option #+CINDEX: sweep Prolog flag The default value of ~sweeprolog-init-args~ is set to load the Prolog -helper library =sweep.pl= and to create a boolean Prolog flag ~sweep~, set -to ~true~, which indicates to SWI-Prolog that it is running under ~sweep~. +helper library =sweep.pl= and to create a boolean Prolog flag Sweep, set +to ~true~, which indicates to SWI-Prolog that it is running under Sweep. #+CINDEX: command line arguments #+FINDEX: sweeprolog-handle-command-line-args 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 +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 @@ -191,7 +191,7 @@ Emacs's command line options), for example: 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 +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: @@ -216,7 +216,7 @@ runtime on startup. :END: #+FINDEX: sweeprolog-open-query -=sweep= provides the Elisp function =sweeprolog-open-query= for invoking Prolog +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 @@ -250,7 +250,7 @@ second (output) Prolog argument converted to an Elisp object (see #+FINDEX: sweeprolog-cut-query #+FINDEX: sweeprolog-close-query -=sweep= only executes one Prolog query at a given time, thus queries +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 @@ -266,11 +266,11 @@ Prolog bindings created by the query. :ALT_TITLE: Elisp to Prolog :END: -=sweep= converts Elisp objects into Prolog terms to allow the Elisp +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 +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. @@ -287,7 +287,7 @@ we convert /trees of strings and numbers/: :ALT_TITLE: Prolog to Elisp :END: -=sweep= converts Prolog terms into Elisp object to allow efficient +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. @@ -314,7 +314,7 @@ processing of Prolog query results in Elisp (see =sweeprolog-next-solution=). :ALT_TITLE: Example Query :END: -As an example of using the =sweep= interface for executing Prolog +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)=: @@ -362,7 +362,7 @@ function without any arguments. #+CINDEX: sweeprolog-mode #+FINDEX: sweeprolog-mode #+VINDEX: sweeprolog-mode -=sweep= includes a dedicated major mode for reading and editing Prolog +Sweep includes a dedicated major mode for reading and editing Prolog code, called =sweeprolog-mode=. 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= like so: @@ -541,13 +541,13 @@ highlighting can be set via the user option =sweeprolog-analyze-buffer-min-interval=. #+CINDEX: sweeprolog-faces -=sweep= defines three highlighting /styles/, each containing more than 60 +Sweep defines three highlighting /styles/, each containing more than 60 different faces (named sets of properties that determine the appearance of a specific text in Emacs buffers, see also [[info:emacs#Faces][Faces in the Emacs manual]]) to signify the specific semantics of each token in a Prolog code buffer. -To view and customize all of the faces defined and used in =sweep=, type +To view and customize all of the faces defined and used in Sweep, type =M-x customize-group RET sweeprolog-faces RET=. *** Available styles @@ -557,7 +557,7 @@ To view and customize all of the faces defined and used in =sweep=, type :ALT_TITLE: Available Styles :END: -=sweep= comes with three highlighting styles: +Sweep comes with three highlighting styles: - The =default= style includes faces that mostly inherit from standard Emacs faces commonly used in programming modes. @@ -583,7 +583,7 @@ existing buffer, use =C-x x f= (=font-lock-update=) in that buffer. =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 +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]]). @@ -647,7 +647,7 @@ the /start/ of the opening parenthesis or operator, as follows: #+end_src To simplify maintaining the desired layout without manually counting -spaces, ~sweep~ provides a command ~sweeprolog-align-spaces~ that updates +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 @@ -686,7 +686,7 @@ the expected layout: 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 +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. @@ -793,7 +793,7 @@ 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 +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 @@ -801,7 +801,7 @@ 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[fn:2] -that allows ~sweep~ to recognize them as holes needed to be filled. +that allows Sweep to recognize them as holes needed to be filled. #+FINDEX: sweeprolog-insert-term-with-holes #+KINDEX: C-c C-m @@ -829,7 +829,7 @@ keeping the buffer syntactically correct, this command adds a comma 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. -Several other ~sweep~ commands insert holes in place of unknown terms, +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]]). @@ -908,7 +908,7 @@ 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 +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 @@ -976,7 +976,7 @@ For more information about file specifications in SWI-Prolog, see The command =M-x sweeprolog-load-buffer= can be used 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 +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 by default to =C-c C-l=. By default this command loads the current buffer if its major mode is @@ -996,11 +996,11 @@ found in [[https://www.swi-prolog.org/pldoc/man?section=consulting][Loading Prol :END: #+CINDEX: auto-insert -=sweep= integrates with the Emacs =auto-insert= facility to simplify +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. -=sweep= associates a Prolog module skeleton with =sweeprolog-mode=, the +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= @@ -1065,7 +1065,7 @@ commands, see [[info:emacs#Comment Commands][Comment Commands in the Emacs manua #+FINDEX: sweeprolog-document-predicate-default-function #+FINDEX: sweeprolog-document-predicate-with-holes #+VINDEX: sweeprolog-document-predicate-function -=sweep= also includes a dedicated command called +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 @@ -1110,7 +1110,7 @@ SWI-Prolog, see [[https://www.swi-prolog.org/pldoc/doc_for?object=section(%27pac :ALT_TITLE: Showing Prolog Docs :END: -=sweep= integrates with the Emacs minor mode =ElDoc=, which automatically +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 @@ -1174,7 +1174,7 @@ export list of the defining module (i.e. the second argument of the #+FINDEX: sweeprolog-export-predicate #+KINDEX: C-c C-e #+KINDEX: C-u C-c C-e -~sweep~ provides a convenient command for exporting predicates defined +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 @@ -1375,7 +1375,7 @@ backward to the previous match. :END: #+CINDEX: prolog help -~sweep~ provides a way to read SWI-Prolog documentation via the standard +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 @@ -1405,7 +1405,7 @@ response to the prompt. #+CINDEX: top-level #+FINDEX: sweeprolog-top-level -=sweep= provides a classic Prolog top-level interface for interacting +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. @@ -1422,14 +1422,14 @@ 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 +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 entrusted 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. +This is the only Sweep feature that should be avoided in such cases. ** Multiple top-levels :PROPERTIES: @@ -1457,9 +1457,9 @@ claim the buffer name =*sweeprolog-top-level*=. :END: #+CINDEX: Top-level Menu -=sweep= provides a convenient interface for listing the active Prolog +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 +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 @@ -1509,9 +1509,9 @@ The available commands are: 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 +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= +~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. @@ -1528,7 +1528,7 @@ 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 +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]]). @@ -1550,7 +1550,7 @@ To insert the last input from the history at the prompt, use =M-p= commands, see [[info:emacs#Shell History][Shell History in the Emacs manual]]. #+VINDEX: sweeprolog-top-level-min-history-length -The =sweep= top-level history only records inputs whose length is at +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 @@ -1564,7 +1564,7 @@ backtracking. :ALT_TITLE: Top-level Completion :END: -The =sweeprolog-top-level-mode=, enabled in the =sweep= top-level buffer, +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 @@ -1627,14 +1627,14 @@ which you can access with ~M-n~ in the minibuffer. :END: #+FINDEX: sweeprolog-find-module -=sweep= provides the command =M-x sweeprolog-find-module= for +Sweep provides the command =M-x sweeprolog-find-module= for selecting and jumping to the source code of a loaded or auto-loadable -Prolog module. =sweep= integrates with Emacs's standard completion API +Prolog module. Sweep integrates with Emacs's standard completion API to annotate candidate modules in the completion UI with their =PLDoc= description when available. #+FINDEX: sweeprolog-find-predicate -Along with =M-x sweeprolog-find-module=, =sweep= provides the +Along with =M-x sweeprolog-find-module=, Sweep provides the command =M-x sweeprolog-find-predicate= jumping to the definition a loaded or auto-loadable Prolog predicate. @@ -1645,7 +1645,7 @@ loaded or auto-loadable Prolog predicate. :ALT_TITLE: File Spec Expansion :END: -=sweep= defines a handler for the Emacs function =expand-file-file= that +Sweep defines a handler for the Emacs function =expand-file-file= that recognizes Prolog file specifications, such as =library(lists)=, and expands them to their corresponding absolute paths. This means that one can use Prolog file specifications with Emacs's standard =find-file= @@ -1667,16 +1667,16 @@ 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 +definition in the SWI-Prolog C sources. Sweep knows about SWI-Prolog native built-ins, and can find and jump to their definitions in C when the user has the SWI-Prolog sources checked out locally. #+VINDEX: sweeprolog-swipl-sources -The way ~sweep~ locates the SWI-Prolog sources depends on the user +The way Sweep locates the SWI-Prolog sources depends on the user option ~sweeprolog-swipl-sources~. When customized to a string, it is taken to be the path to the root directory of the SWI-Prolog source code. If instead ~sweeprolog-swipl-sources~ is set to ~t~ (the default), -~sweep~ will try to locate a local checkout of the SWI-Prolog sources +Sweep will try to locate a local checkout of the SWI-Prolog sources automatically among known project root directories provided by Emacs's built-in ~project-known-project-roots~ from =project.el= (see [[info:emacs#Projects][Projects in the Emacs manual]] for more information about =project.el= projects). @@ -1702,8 +1702,8 @@ commands include: :END: #+VINDEX: sweeprolog-prefix-map -=sweep= defines a keymap called =sweeprolog-prefix-map= which provides -keybinding for several useful =sweep= commands. By default, +Sweep defines a keymap called =sweeprolog-prefix-map= which provides +keybinding for several useful Sweep commands. By default, =sweeprolog-prefix-map= itself is not bound to any key. To bind it globally to a prefix key, e.g. =C-c p=, use: @@ -1711,7 +1711,7 @@ to a prefix key, e.g. =C-c p=, use: (keymap-global-set "C-c p" sweeprolog-prefix-map) #+end_src -As an example, with the above binding the =sweep= top-level can be +As an example, with the above binding the Sweep top-level can be accessed from anywhere with =C-c p t=, which invokes the command =sweeprolog-top-level=. @@ -1741,21 +1741,21 @@ The full list of keybindings in ~sweeprolog-prefix-map~ is given below: #+CINDEX: messages #+VINDEX: sweeprolog-messages-buffer-name -Messages emitted by the embedded Prolog are redirected by =sweep= to a -dedicated Emacs buffer. By default, the =sweep= messages buffer is -named =*sweep Messages*=. To instruct =sweep= to use another buffer name +Messages emitted by the embedded Prolog are redirected by Sweep to a +dedicated Emacs buffer. By default, the Sweep messages buffer is +named =*sweep Messages*=. To instruct Sweep to use another buffer name instead, type =M-x customize-option RET sweeprolog-messages-buffer-name RET= and set the option to a suitable value. -The =sweep= messages buffer uses the minor mode =compilation-minor-mode=, +The Sweep messages buffer uses the minor mode =compilation-minor-mode=, which allows for jumping to source locations indicated in errors and -warning directly from the corresponding message in the =sweep= messages +warning directly from the corresponding message in the Sweep messages buffer. For more information about the features enabled by =compilation-minor-mode=, see [[info:emacs#Compilation Mode][Compilation Mode in the Emacs manual]]. #+FINDEX: sweeprolog-view-messages -=sweep= includes the command =sweeprolog-view-messages= for quickly switching -to the =sweep= messages buffer. This command is bound by default in +Sweep includes the command =sweeprolog-view-messages= for quickly switching +to the Sweep messages buffer. This command is bound by default in =sweeprolog-prefix-map= to the =e= key (see [[Quick access to sweep commands]]). * Setting Prolog flags @@ -1779,7 +1779,7 @@ 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: +string as we can easily validate in the Sweep top-level: #+begin_src prolog ?- A = "foo". @@ -1819,7 +1819,7 @@ of each package. 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]]. +For a list of known desired improvements in Sweep, see [[*Things to do][Things to do]]. ** Setting up sweep for local development :PROPERTIES: @@ -1828,11 +1828,11 @@ For a list of known desired improvements in ~sweep~, see [[*Things to do][Things :ALT_TITLE: Developing Sweep :END: -Since the Prolog and C parts of ~sweep~ are intended to be distributed +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 +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: +the included Sweep submodule from its master branch: #+begin_src sh $ git clone --recursive https://github.com/SWI-Prolog/swipl-devel.git @@ -1842,7 +1842,7 @@ the included ~sweep~ submodule from its master branch: #+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 +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. @@ -1865,13 +1865,13 @@ achieved with the following command executed in :ALT_TITLE: Submitting Patches :END: -The best way to get in touch with the ~sweep~ maintainers is via [[https://lists.sr.ht/~eshel/dev][the +The best way to get in touch with the Sweep maintainers is via [[https://lists.sr.ht/~eshel/dev][the sweep mailing list]]. #+FINDEX: sweeprolog-submit-bug-report The command ~M-x sweeprolog-submit-bug-report~ can be used to easily -contact the ~sweep~ maintainers from within Emacs. This command opens a -new buffer with a message template ready to be sent to the ~sweep~ +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 @@ -1881,7 +1881,7 @@ mailing list. :ALT_TITLE: Things To Do :END: -While ~sweep~ is ready to be used for effective editing of Prolog code, +While Sweep is ready to be used for effective editing of Prolog code, there some further improvements that we want to pursue: ** Improvements around editing Prolog @@ -1891,9 +1891,9 @@ there some further improvements that we want to pursue: :ALT_TITLE: Editing Improvements :END: -- Inherit user customizations from ~prolog-mode~ :: ~sweep~ should inherit +- Inherit user customizations from ~prolog-mode~ :: Sweep should inherit user customizations from the standard =prolog.el= built into Emacs to - accommodate users updating their configs to work with ~sweep~. + accommodate users updating their configs to work with Sweep. Ideally, ~sweeprolog-mode~ should be derived from ~prolog-mode~ instead of the generic ~prog-mode~ to inherit user-set hooks and modifications, but careful consideration is required to make sure @@ -1940,7 +1940,7 @@ there some further improvements that we want to pursue: :ALT_TITLE: Running Improvements :END: -- Persist top-level history across sessions :: ~sweep~ should persist +- Persist top-level history across sessions :: Sweep should persist Prolog top-level histories across invocations of ~sweeprolog-top-level~, ideally also across different Emacs sessions. @@ -1951,19 +1951,19 @@ there some further improvements that we want to pursue: :ALT_TITLE: General Improvements :END: -- Facilitate interactive debugging :: ~sweep~ should facilitate +- 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 + 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 + 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.