:END:
#+CINDEX: sweeprolog-mode
-#+FINDEX: sweeprolog-mode
-#+VINDEX: sweeprolog-mode
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:
+code, called =sweeprolog-mode=:
+
+- Command: sweeprolog-mode :: Enable Sweep major mode for reading and
+ editing SWI-Prolog code in the current buffer.
+- Variable: sweeprolog-mode-hook :: Hook run after entering
+ ~sweeprolog-mode~. For more information about major mode hooks in
+ Emacs see [[info:emacs#Hooks][Hooks]] in the Emacs manual.
+
+To activate this mode in a buffer, type =M-x sweeprolog-mode=. To
+instruct Emacs to always open Prolog files in =sweeprolog-mode=, modify
+the Emacs variable ~auto-mode-alist~ accordingly:
#+begin_src emacs-lisp
(add-to-list 'auto-mode-alist '("\\.pl\\'" . sweeprolog-mode))
(add-to-list 'auto-mode-alist '("\\.plt\\'" . sweeprolog-mode))
#+end_src
+For more information about how Emacs chooses a major mode to use when
+you visit a file, see [[info:emacs#Choosing Modes][Choosing Modes]] in the Emacs manual.
+
** Indentation
:PROPERTIES:
:CUSTOM_ID: indentation
analyses the syntactic context of a given line and determines the
appropriate indentation to apply based on a set of rules.
-#+FINDEX: sweeprolog-indent-line
+#+KINDEX: C-i
+- Key: TAB (indent-for-tab-command) :: Indent the current line. If
+ the region is active, indent all the lines within it. Calls the
+ mode-dependent function specified by the variable
+ ~indent-line-function~ to do the work.
+- Function: sweeprolog-indent-line :: Indent the current line
+ according to SWI-Prolog conventions. This function is used as an
+ ~indent-line-function~ in ~sweeprolog-mode~ buffers.
+- Command: sweeprolog-infer-indent-style :: Infer indentation style
+ for the current buffer from its contents.
+
The entry point of the indentation engine is the function
=sweeprolog-indent-line= which takes no arguments and indents that line
at point. =sweeprolog-mode= supports the standard Emacs interface for
full description of the available commands and options that pertain to
indentation, see [[info:emacs#Indentation][Indentation]] in the Emacs manual.
-#+FINDEX: sweeprolog-infer-indent-style
-#+KINDEX: C-c C-I
#+CINDEX: indentation style
#+VINDEX: indent-tabs-mode
#+VINDEX: sweeprolog-indent-offset
predicate/3.
#+end_src
-** Semantic highlighting
+** Semantic Highlighting
:PROPERTIES:
:CUSTOM_ID: semantic-highlighting
:DESCRIPTION: Rich fontification for Prolog code
invoked to updated the semantic highlighting in response to changes in
the buffer.
-#+KINDEX: C-c C-c (sweeprolog-mode)
-#+FINDEX: sweeprolog-analyze-buffer
+- Key: C-c C-c (sweeprolog-analyze-buffer) :: Analyze the current
+ buffer and update cross-references.
+- User Option: sweeprolog-analyze-buffer-on-idle :: If non-nil,
+ analyze ~sweeprolog-mode~ buffers on idle. Defaults to ~t~.
+- User Option: sweeprolog-analyze-buffer-max-size :: Maximum number
+ characters in a ~sweeprolog-mode~ buffer to analyze on idle. Larger
+ buffers are not analyzed on idle. Defaults to 100,000 characters.
+- User Option: sweeprolog-analyze-buffer-min-interval :: Minimum
+ number of idle seconds to wait before analyzing a ~sweeprolog-mode~
+ buffer. Defaults to 1.5.
+
At any point in a =sweeprolog-mode= buffer, the command =C-c C-c= (or =M-x
sweeprolog-analyze-buffer=) can be used to update the cross reference
-cache and highlight the buffer accordingly. When ~flymake~ integration
+cache and highlight the buffer accordingly. When Flymake integration
is enabled, this command also updates the diagnostics for the current
-buffer (see [[*Examining diagnostics][Examining diagnostics]]). This may be useful e.g. after
+buffer (see [[#diagnostics][Examining Diagnostics]]). This may be useful e.g. after
defining a new predicate.
-#+VINDEX: sweeprolog-analyze-buffer-on-idle
-#+VINDEX: sweeprolog-analyze-buffer-max-size
-#+VINDEX: sweeprolog-analyze-buffer-min-interval
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,
To view and customize all of the faces defined and used in Sweep, type
=M-x customize-group RET sweeprolog-faces RET=.
-*** Available styles
+*** Available Styles
:PROPERTIES:
:CUSTOM_ID: highlighting-styles
:DESCRIPTION: Available 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.
-- The =light= style mimics the colors used in the SWI-Prolog built-in
- editor.
-- The =dark= style mimics the colors used in the SWI-Prolog built-in
- editor in dark mode.
+1. The default style includes faces that mostly inherit from standard
+ Emacs faces commonly used in programming modes.
+2. The =light= style mimics the colors used in the SWI-Prolog built-in
+ editor.
+3. The =dark= style mimics the colors used in the SWI-Prolog built-in
+ editor in dark mode.
+
+- User Option: sweeprolog-faces-style :: Style of faces to use for
+ semantic highlighting in ~sweeprolog-mode~ buffers. Defaults to ~nil~.
-#+VINDEX: sweeprolog-faces-style
To choose a style, customize the user option =sweeprolog-faces-style= with
=M-x customize-option RET sweeprolog-faces-style RET=. The new style will
apply to all new =sweeprolog-mode= buffers. To apply the new style to an
when the cursor enters or leaves certain text regions (see also [[info:elisp#Special
Properties][Special Properties in the Elisp manual]]).
-#+VINDEX: sweeprolog-enable-cursor-sensor
+- Command: sweeprolog-highlight-variable :: Highlight occurrences of a
+ Prolog variable in the clause at point. With a prefix argument,
+ clear variable highlighting in the clause at point instead.
+
+- User Option: sweeprolog-enable-cursor-sensor :: If non-nil, use
+ ~cursor-sensor-mode~ to highlight Prolog variables sharing with the
+ variable at point in ~sweeprolog-mode~ buffers. Defaults to ~t~.
+
To disable automatic variable highlighting based on the variable at
point, customize the variable =sweeprolog-enable-cursor-sensor= to nil.
-#+FINDEX: sweeprolog-highlight-variable
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
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
:DESCRIPTION: Commands for adjusting whitespace according to Prolog conventions
:ALT_TITLE: Aligning Spaces
:END:
-#+FINDEX: sweeprolog-align-spaces
-#+FINDEX: cycle-spacing
+
+- Command: sweeprolog-align-spaces :: Insert or remove spaces around
+ point to such that the next Prolog token starts at a column
+ distanced from the beginning of the previous token by a multiple of
+ four columns.
+- User Option: sweeprolog-enable-cycle-spacing :: If non-nil, add
+ ~sweeprolog-align-spaces~ as the first element of
+ ~cycle-spacing-actions~ in ~sweeprolog-mode~ buffers. Defaults to ~t~.
+
To insert or update whitespace around point, use the command ~M-x
sweeprolog-align-spaces~. For example, consider a ~sweeprolog-mode~
buffer with the following contents, where =^= designates the location of
^
#+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.
:END:
#+CINDEX: electric layout
-#+FINDEX: sweeprolog-electric-layout-mode
-#+VINDEX: sweeprolog-mode-hook
The minor mode ~sweeprolog-electric-layout-mode~ adjusts whitespace
-around point automatically as you type. It works by examining the
-context of point whenever a character is inserted in the current
-buffer, and applying the following layout rules:
+around point automatically as you type:
+
+- Command: sweeprolog-electric-layout-mode :: Toggle automatic
+ whitespace adjustment according to SWI-Prolog conventions.
+
+It works by examining the context of point whenever a character is
+inserted in the current buffer, and applying the following layout
+rules:
- =PlDoc= Comments :: Insert two consecutive spaces after the ~%!~ or ~%%~
starting a =PlDoc= predicate documentation structured comment.
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~[fn:1]:
+~sweeprolog-electric-layout-mode~ to ~sweeprolog-mode-hook~:
#+begin_src emacs-lisp
(add-hook 'sweeprolog-mode-hook #'sweeprolog-electric-layout-mode)
#+end_src
-[fn:1] For more information about major mode hooks in Emacs, which
-~sweeprolog-mode-hook~ is one of, see [[info:emacs#Hooks][Hooks]].
-
** Term-based editing and motion commands
:PROPERTIES:
:CUSTOM_ID: term-based-commands
notion of syntactic expressions to accommodate for Prolog terms, which
allows the standard sexp-based commands to operate on them seamlessly.
-#+KINDEX: C-M-^
-#+FINDEX: raise-sexp
-[[info:emacs#Expressions][Expressions 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. 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:
+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 :-
variables, but they are annotated with a special text property[fn:2]
that allows Sweep to recognize them as holes needed to be filled.
-#+FINDEX: sweeprolog-insert-term-with-holes
#+KINDEX: C-c C-m
-#+KINDEX: C-c RET
+- 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.
+#+KINDEX: C-c C-i
+- Key: C-c TAB (sweeprolog-forward-hole) :: Move point to the next
+ hole in the buffer.
+#+KINDEX: C-c C-S-i
+- Key: C-c S-TAB (sweeprolog-backward-hole) :: Move point to the
+ previous hole in the buffer.
+- User Option: sweeprolog-highlight-holes :: If non-nil, highlight
+ holes in ~sweeprolog-mode~ buffers with a dedicated face. Defaults to
+ ~t~.
+- 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.
+
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
Insertion]]) and ~M-x sweeprolog-plunit-testset-skeleton~ (see [[#writing-tests][Writing
Tests]]).
-#+VINDEX: sweeprolog-highlight-holes
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.
-#+FINDEX: sweeprolog-backward-hole
-#+FINDEX: sweeprolog-forward-hole
-#+KINDEX: C-c C-i
-#+KINDEX: C-c TAB
-#+KINDEX: C-- C-c C-i
-#+KINDEX: C-- C-c TAB
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
hole instead, use ~sweeprolog-backward-hole~ or call
~sweeprolog-forward-hole~ with a negative prefix argument (~C-- C-c TAB~).
-#+FINDEX: sweeprolog-forward-hole-on-tab-mode
-#+KINDEX: TAB (sweeprolog-forward-hole-on-tab-mode)
-#+KINDEX: C-i (sweeprolog-forward-hole-on-tab-mode)
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
[fn:2] see [[info:elisp#Text Properties][Text Properties in the Elisp manual]]
-** Definitions and references
+** Definitions and References
:PROPERTIES:
:CUSTOM_ID: sweeprolog-xref
:DESCRIPTION: Commands for finding cross-references for Prolog predicates
#+CINDEX: cross reference
#+CINDEX: xref
#+KINDEX: M-.
-=sweeprolog-mode= integrates with the Emacs =xref= API to facilitate quick
+~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-.= 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.
+~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]].
+~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
+[[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
+** Predicate Definition Boundaries
:PROPERTIES:
:CUSTOM_ID: predicate-boundaries
:DESCRIPTION: Commands operating on a Prolog predicate definition as a single unit
:END:
#+CINDEX: predicate-based motion
-#+FINDEX: sweeprolog-forward-predicate
-#+FINDEX: sweeprolog-backward-predicate
-#+KINDEX: M-n
-#+KINDEX: M-p
+The following commands act on entire Prolog predicate definitions as a
+single unit:
+
+- Key: M-n (sweeprolog-forward-predicate) :: Move forward from point
+ to the next predicate definition in the current buffer.
+- Key: M-p (sweeprolog-backward-predicate) :: Move backward from point
+ to the previous predicate definition.
+- Key: M-h (sweeprolog-mark-predicate) :: Select the current predicate
+ as the active region, put point at the its beginning, and the mark
+ at the end.
+
In ~sweeprolog-mode~, the commands ~M-n~ (~sweeprolog-forward-predicate~)
and ~M-p~ (~sweeprolog-backward-predicate~) are available for quickly
jumping to the first line of the next or previous predicate
definition in the current buffer.
-#+KINDEX: M-h
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
+** 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:
-#+KINDEX: C-c C-o
-#+FINDEX: sweeprolog-find-file-at-point
-File specifications that occur in =sweeprolog-mode= buffers can be followed
-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=:
+In SWI-Prolog, one often refers to source file paths using /file
+specifications/, special Prolog terms that act as path aliases, such
+as ~library(lists)~ which refers to a file ~lists.pl~ in any of the Prolog
+library directories.
+
+- Key: C-c C-o (sweeprolog-find-file-at-point) :: Resolve file
+ specification at point and visit the specified file.
+
+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)).
+ :- use_module(library(lists)).
#+end_src
With point in any position inside =library(lists)=, typing =C-c C-o= will
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
+** Loading Buffers
:PROPERTIES:
:CUSTOM_ID: loading-buffers
:DESCRIPTION: Commands for loading Prolog predicates from the current buffer
:ALT_TITLE: Loading Buffers
:END:
-#+KINDEX: C-c C-l
-#+KINDEX: C-u C-c C-l
#+CINDEX: loading
-#+FINDEX: sweeprolog-load-buffer
-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
-(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
-=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=).
+You can load a buffer of SWI-Prolog code with the following command:
+
+- Key: C-c C-l (sweeprolog-load-buffer) :: Load the current buffer
+ into the embedded SWI-Prolog runtime.
+
+Use the command ~M-x sweeprolog-load-buffer~ to load the contents of a
+~sweeprolog-mode~ buffer into the embedded SWI-Prolog runtime. After a
+buffer is loaded, the predicates it defines can be queried from Elisp
+(see [[Querying Prolog]]) and from the Sweep top-level (see [[The Prolog
+Top-Level]]). In ~sweeprolog-mode~ buffers, ~sweeprolog-load-buffer~ is
+bound to ~C-c C-l~. By default this command loads the current buffer if
+its major mode is ~sweeprolog-mode~, and prompts for an appropriate
+buffer otherwise. To choose a different buffer to load while visiting
+a ~sweeprolog-mode~ buffer, invoke ~sweeprolog-load-buffer~ with a prefix
+argument (~C-u C-c C-l~).
More relevant information about loading code in SWI-Prolog can be
found in [[https://www.swi-prolog.org/pldoc/man?section=consulting][Loading Prolog source files]] in the SWI-Prolog manual.
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
+- 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=
+~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
#+end_src
-#+VINDEX: sweeprolog-module-header-comment-skeleton
-The multi-line comment included above the =module/2= directive can be
+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
+~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=) 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 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
+~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
+** Documenting Predicates
:PROPERTIES:
:CUSTOM_ID: sweeprolog-pldoc
:DESCRIPTION: Commands for adding documentation to Prolog predicate definitions
Prolog predicates. For an overview of the relevant standard Emacs
commands, see [[info:emacs#Comment Commands][Comment Commands in the Emacs manual]].
-#+KINDEX: C-c C-d
-#+FINDEX: sweeprolog-document-predicate-at-point
-#+FINDEX: sweeprolog-document-predicate-default-function
-#+FINDEX: sweeprolog-document-predicate-with-holes
-#+VINDEX: sweeprolog-document-predicate-function
+- Key: C-c C-d (sweeprolog-document-predicate-at-point) :: Insert
+ =PlDoc= documentation comment for the predicate at or above point.
+- User Option: sweeprolog-read-predicate-documentation-function :: Function
+ to use for determining the initial contents of documentation
+ comments inserted with ~sweeprolog-document-predicate-at-point~.
+- Function: sweeprolog-read-predicate-documentation-default-function functor arity :: Prompt
+ and read from the minibuffer the arguments modes, determinism
+ specification and initial summary for the documentation of the
+ predicate FUNCTOR/ARITY.
+- Function: sweeprolog-read-predicate-documentation-with-holes functor arity :: Use
+ holes for the initial documentation of the predicate FUNCTOR/ARITY.
+
Sweep also includes a dedicated command called
-=sweeprolog-document-predicate-at-point= for interactively creating
-=PlDoc= comments for predicates in =sweeprolog-mode= buffers. This
-command, bound by default to =C-c C-d=, finds the beginning of the
+~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
~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
+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]].
For more information about =PlDoc= and source documentation in
SWI-Prolog, see [[https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/pldoc.html%27)][the PlDoc manual]].
-** Displaying predicate documentation
+** 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
+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
-To disable the =ElDoc= integration in =sweeprolog-mode= buffers, customize
-the user option =sweeprolog-enable-eldoc= to nil.
+- 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
+** Examining Diagnostics
:PROPERTIES:
:CUSTOM_ID: diagnostics
:DESCRIPTION: Commands for finding errors in Prolog code
#+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
+to the user by integrating with Flymake, a powerful interface for
on-the-fly diagnostics built into Emacs.
-#+FINDEX: sweeprolog-enable-flymake
-~flymake~ integration is enabled by default, to disable it customize the
+- User Option: sweeprolog-enable-flymake :: If non-nil, enable Flymake
+ support in ~sweeprolog-mode~ buffers. Defaults to ~t~.
+- Key: C-c C-` (sweeprolog-show-diagnostics) :: List diagnostics for
+ the current buffer or project in a dedicated buffer.
+
+Flymake integration is enabled by default, to disable it customize the
user option ~sweeprolog-enable-flymake~ to nil.
#+FINDEX: next-error
#+KINDEX: M-g n
#+KINDEX: M-g p
-When this integration is enabled, several ~flymake~ commands are
+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]].
-
-#+FINDEX: sweeprolog-show-diagnostics
-#+KINDEX: C-c C-`
-#+KINDEX: C-u C-c C-`
-The command ~sweeprolog-show-diagnostics~ shows a list of ~flymake~
+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
+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
+** Exporting Predicates
:PROPERTIES:
:CUSTOM_ID: exporting-predicates
:DESCRIPTION: Commands for adding Prolog predicates to their module's export list
export list of the defining module (i.e. the second argument of the
~module/2~ directive).
-#+FINDEX: sweeprolog-export-predicate
-#+KINDEX: C-c C-e
-#+KINDEX: C-u C-c C-e
+- 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~
#+CINDEX: code completion
#+CINDEX: completion-at-point
+#+FINDEX: complete-symbol
+#+FINDEX: completion-at-point
#+KINDEX: C-M-i
#+KINDEX: M-TAB
~sweeprolog-mode~ empowers Emacs's standard ~completion-at-point~ command,
#+CINDEX: context-based term insertion
#+CINDEX: term insertion at-point
-#+FINDEX: sweeprolog-insert-term-dwim
-#+KINDEX: M-RET
-#+KINDEX: C-M-m
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
term at or after point according to the context in which
~sweeprolog-insert-term-dwim~ is invoked.
-#+VINDEX: sweeprolog-insert-term-functions
+#+KINDEX: C-M-m
+- Key: M-RET (sweeprolog-insert-term-dwim) :: Insert an appropriate
+ Prolog term in the current buffer, based on the context at point.
+- Variable: sweeprolog-insert-term-functions :: List of functions for
+ ~sweeprolog-insert-term-dwim~ to try for inserting a Prolog term based
+ on the current context.
+
To determine which term to insert and exactly where, this command
calls the functions in the list held by the variable
~sweeprolog-insert-term-functions~ one after the other until one of the
By default, ~sweeprolog-insert-term-dwim~ tries the following insertion
functions, in order:
-#+FINDEX: sweeprolog-maybe-insert-next-clause
-#+FINDEX: sweeprolog-maybe-define-predicate
#+VINDEX: sweeprolog-new-predicate-location-function
-- ~sweeprolog-maybe-insert-next-clause~ :: If the last token before
+- 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.
-- ~sweeprolog-maybe-define-predicate~ :: If point is over a call to an
+- 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
:ALT_TITLE: Writing Tests
:END:
-#+FINDEX: sweeprolog-plunit-testset-skeleton
#+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~. This command
-prompts for a name to give the new test-set and inserts a template
-such as the following:
+the command ~M-x sweeprolog-plunit-testset-skeleton~.
+
+- Command: sweeprolog-plunit-testset-skeleton :: Insert a =PlUnit=
+ test-set skeleton at point.
+
+This command prompts for a name to give the new test-set and inserts a
+template such as the following:
#+begin_src prolog
:- begin_tests(foo_regression_tests).
:ALT_TITLE: Code Dependencies
:END:
-#+FINDEX: sweeprolog-update-dependencies
-#+KINDEX: C-c C-u
#+CINDEX: dependencies
#+CINDEX: autoload
It is considered good practice for SWI-Prolog source files to
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~. This command
-analyzes the current buffer and adds or updates ~autoload/2~ and
-~use_module/2~ as needed.
+sweeprolog-update-dependencies~ bound to ~C-c C-u~.
+
+- Key: C-c C-u (sweeprolog-update-dependencies) :: Add explicit
+ dependencies for implicitly autoloaded predicates in the current
+ buffer.
+- User Option: sweeprolog-note-implicit-autoloads :: If non-nil, have
+ Flymake complain about implicitly autoloaded predicates in
+ ~sweeprolog-mode~ buffers.
-#+VINDEX: sweeprolog-note-implicit-autoloads
-By default, when ~flymake~ integration is enabled (see [[#diagnostics][Examining
+This command analyzes the current buffer and adds or updates
+~autoload/2~ and ~use_module/2~ as needed.
+
+By default, when Flymake integration is enabled (see [[#diagnostics][Examining
diagnostics]]), calls to implicitly autoloaded predicates are marked
-and reported as ~flymake~ diagnostics. To inhibit ~flymake~ from
+and reported as Flymake diagnostics. To inhibit Flymake from
diagnosing implicit autoloads, customize the user option
~sweeprolog-note-implicit-autoloads~ to nil.
:ALT_TITLE: Term Search
:END:
-#+FINDEX: sweeprolog-term-search
-#+KINDEX: C-c C-s
#+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~. 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~.
+command ~M-x sweeprolog-term-search~.
+
+- Key: C-c C-s (sweeprolog-term-search) :: Search for Prolog terms
+ matching a given search term in the current buffer.
+- Command: sweeprolog-term-search-repeat-forward :: Repeat the last
+ Term Search, searching forward from point.
+- Command: sweeprolog-term-search-repeat-backward :: Repeat the last
+ Term Search, searching backward from point.
+
+This command, bound by default to ~C-c C-s~ in ~sweeprolog-mode~ buffers,
+prompts for a Prolog term to search for and finds terms in the current
+buffer that the search term subsumes. It highlights all matching
+terms in the buffer and moves the cursor to the beginning of the next
+match after point. For example, to find if-then-else constructs in
+the current buffer do ~C-c C-s _ -> _ ; _ RET~.
While prompting for a search term in the minibuffer, this command
populates the "future history" with the Prolog terms at point, with
The given goal runs for each matching term, it may use variables from
the search term to refer to subterms of the matching term.
-#+FINDEX: sweeprolog-term-search-repeat-forward
-#+FINDEX: sweeprolog-term-search-repeat-backward
#+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
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.
+- 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~).
-#+FINDEX: sweeprolog-describe-predicate
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
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,
+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.
commands include:
- ~M-x sweeprolog-find-predicate~,
- ~M-.~ (~xref-find-definitions~) in ~sweeprolog-mode~ buffers (see
- [[#sweeprolog-xref][Definitions and references]]), and
+ [[#sweeprolog-xref][Definitions and References]]), and
- ~s~ (~help-view-source~) in the =*Help*= buffer produced by ~M-x
sweeprolog-describe-predicate~ (see [[#prolog-help][Prolog Help]]).
projects / dict.git / commitdiff