From db7ef44a61c2771f336f474ac43e9d4b80668fea Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Thu, 8 Sep 2022 10:49:27 +0300
Subject: [PATCH] DOC: add manual section about setting Prolog flags

---
 README.org | 39 +++++++++++++++++++++++++++++++++++++++
 sweep.el   |  8 ++++++--
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/README.org b/README.org
index 819fa37..f3f37ec 100644
--- a/README.org
+++ b/README.org
@@ -429,6 +429,9 @@ accessed from anywhere with =C-c p t=, which invokes the command
 =sweep-top-level=.
 
 * Examining Prolog messages
+:PROPERTIES:
+:CUSTOM_ID: prolog-messages
+:END:
 
 #+CINDEX: messages
 #+VINDEX: sweep-messages-buffer-name
@@ -449,6 +452,42 @@ buffer.  For more information about the features enabled by
 to the =sweep= messages buffer.  This command is bound by default in
 =sweep-prefix-map= to the =e= key (see [[Quick access to =sweep= commands]]).
 
+* Setting Prolog flags
+:PROPERTIES:
+:CUSTOM_ID: prolog-flags
+:END:
+
+#+CINDEX: prolog flags
+#+FINDEX: sweep-set-prolog-flag
+The command =M-x sweep-set-prolog-flag= can be used to interactively
+configure the embedded Prolog execution environment by changing the
+values of Prolog flags.  This command first prompts the user for a
+Prolog flag to set, with completion candidates annotated with their
+current values as Prolog flags, and then prompts for a string that
+will be read as a Prolog term and set as the value of the chosen flag.
+For more information on Prolog flags in SWI-Prolog see [[https://www.swi-prolog.org/pldoc/man?section=flags][Environment
+Control in the SWI-Prolog manual]].
+
+As an example, the Prolog flag =double_quotes= controls the
+interpretation of double quotes in Prolog code.  By default,
+=double_quotes= is set to =string=, so e.g. ="foo"= is read as a SWI-Prolog
+string as we can easily validate in the =sweep= top-level:
+
+#+begin_src prolog
+?- A = "foo".
+A = "foo".
+#+end_src
+
+We can change the interpretation of double quotes to denote lists of
+character codes, by setting the value the =double_quotes= flag to =codes=
+with =M-x sweep-set-prolog-flag RET double_quotes RET codes RET=.
+Evaluating =A = "foo"= again exhibits the different interpretation:
+
+#+begin_src prolog
+?- A = "foo".
+A = [102, 111, 111].
+#+end_src
+
 * Installing Prolog packages
 :PROPERTIES:
 :CUSTOM_ID: prolog-packages
diff --git a/sweep.el b/sweep.el
index 0778c7f..6ab1d6c 100644
--- a/sweep.el
+++ b/sweep.el
@@ -200,6 +200,8 @@ is used to find a the swipl executable."
     (completing-read sweep-read-flag-prompt col)))
 
 (defun sweep-set-prolog-flag (flag value)
+  "Set the Prolog flag FLAG to VALUE.
+FLAG and VALUE are specified as strings and read as Prolog terms."
   (interactive (let ((f (sweep-read-prolog-flag)))
                  (list f (read-string (concat "Set " f " to: ")))))
   (sweep-open-query "user"
@@ -208,8 +210,9 @@ is used to find a the swipl executable."
                     (cons flag value))
   (let ((sol (sweep-next-solution)))
     (sweep-close-query)
-    (when (sweep-true-p sol)
-      (cdr sol))))
+    (if (sweep-true-p sol)
+        (message "Prolog flag %s set to %s" flag value)
+      (user-error "Setting %s to %s failed" flag value))))
 
 (defun sweep-setup-message-hook ()
   (with-current-buffer (get-buffer-create sweep-messages-buffer-name)
@@ -928,6 +931,7 @@ Interactively, a prefix arg means to prompt for BUFFER."
     (define-key map "p" #'sweep-find-predicate)
     (define-key map "t" #'sweep-top-level)
     (define-key map "P" #'sweep-pack-install)
+    (define-key map "F" #'sweep-set-prolog-flag)
     (define-key map "e" #'sweep-view-messages)
     map)
   "Keymap for `sweep' global commands.")
-- 
2.39.2