From 471fc1aada9e9c96636d79cf62d05138ebb2a04b Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Sat, 14 Jan 2023 11:07:19 +0200 Subject: [PATCH] DOC: improve listings in the "Editing Prolog Code" section --- README.org | 458 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 278 insertions(+), 180 deletions(-) diff --git a/README.org b/README.org index 7fae727..4bc658e 100644 --- a/README.org +++ b/README.org @@ -360,18 +360,27 @@ function without any arguments. :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 @@ -385,7 +394,17 @@ 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. -#+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 @@ -394,8 +413,6 @@ 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. -#+FINDEX: sweeprolog-infer-indent-style -#+KINDEX: C-c C-I #+CINDEX: indentation style #+VINDEX: indent-tabs-mode #+VINDEX: sweeprolog-indent-offset @@ -500,7 +517,7 @@ rules: predicate/3. #+end_src -** Semantic highlighting +** Semantic Highlighting :PROPERTIES: :CUSTOM_ID: semantic-highlighting :DESCRIPTION: Rich fontification for Prolog code @@ -519,18 +536,24 @@ editing and moving around the buffer, a faster, local analysis is 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, @@ -550,7 +573,7 @@ Prolog code buffer. To view and customize all of the faces defined and used in Sweep, type =M-x customize-group RET sweeprolog-faces RET=. -*** Available styles +*** Available Styles :PROPERTIES: :CUSTOM_ID: highlighting-styles :DESCRIPTION: Available highlighting styles @@ -559,14 +582,16 @@ To view and customize all of the faces defined and used in Sweep, type 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 @@ -588,11 +613,17 @@ 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]]). -#+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 @@ -610,7 +641,11 @@ clears all variable highlighting in the current clause instead. 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 @@ -660,8 +695,15 @@ Layout mode]]). :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 @@ -684,12 +726,14 @@ the expected layout: ^ #+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. @@ -711,12 +755,15 @@ lines to Emacs's initialization file (see [[info:emacs#Init File][The Emacs Init :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. @@ -729,15 +776,12 @@ buffer, and applying the following layout rules: 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 @@ -753,15 +797,18 @@ 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. -#+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 :- @@ -803,9 +850,23 @@ 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. -#+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 @@ -834,19 +895,12 @@ including ~C-M-i~ (see [[#code-completion][Code Completion]]), ~C-M-m~ (see [[#i 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 @@ -854,9 +908,6 @@ leaving the cursor at right after the hole. To jump to the previous hole instead, use ~sweeprolog-backward-hole~ or call ~sweeprolog-forward-hole~ with a negative prefix argument (~C-- C-c TAB~). -#+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 @@ -880,7 +931,7 @@ active (see also [[info:emacs#Using Region][Using Region in the Emacs manual]]). [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 @@ -890,32 +941,32 @@ active (see also [[info:emacs#Using Region][Using Region in the Emacs manual]]). #+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 @@ -923,37 +974,49 @@ throughout the current project. :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 @@ -962,28 +1025,29 @@ open the =lists.pl= file in the Prolog library. 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. @@ -1000,10 +1064,13 @@ 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 +- 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 @@ -1027,22 +1094,22 @@ As an example, after inserting the module skeleton, a new Prolog 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 @@ -1060,15 +1127,22 @@ 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]]. -#+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 @@ -1089,8 +1163,8 @@ argument modes and determinism specifiers by setting this option to ~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]]. @@ -1103,24 +1177,29 @@ documented in [[info:emacs#Text][Commands for Human Languages]], which see. For more information about =PlDoc= and source documentation in SWI-Prolog, see [[https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/pldoc.html%27)][the PlDoc manual]]. -** Displaying predicate documentation +** 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 @@ -1130,35 +1209,36 @@ the user option =sweeprolog-enable-eldoc= to nil. #+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 @@ -1171,9 +1251,9 @@ 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 -#+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~ @@ -1195,6 +1275,8 @@ prefix argument (~C-u 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, @@ -1226,9 +1308,6 @@ In ~sweeprolog-mode~ buffers, the following enhancements are provided: #+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 @@ -1236,7 +1315,13 @@ 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. -#+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 @@ -1245,13 +1330,11 @@ functions signal success by returning non-nil. 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 @@ -1268,16 +1351,19 @@ head's arguments, if any. See also [[#holes][Holes]]. :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). @@ -1302,8 +1388,6 @@ another unit test, place point after a complete test case and type :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 @@ -1311,14 +1395,21 @@ 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~. 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. @@ -1329,18 +1420,24 @@ diagnosing implicit autoloads, customize the user option :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 @@ -1357,8 +1454,6 @@ 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. -#+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 @@ -1381,14 +1476,17 @@ Emacs ~help~ user interface, akin to Emacs's built-in ~describe-function~ 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 @@ -1427,7 +1525,7 @@ 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, +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. @@ -1690,7 +1788,7 @@ manual]] for information about working with C code in Emacs). These commands include: - ~M-x sweeprolog-find-predicate~, - ~M-.~ (~xref-find-definitions~) in ~sweeprolog-mode~ buffers (see - [[#sweeprolog-xref][Definitions and references]]), and + [[#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]]). -- 2.39.2