[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/sweeprolog d3c4102c0a 07/11: * README.org ("Querying Prolo
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/sweeprolog d3c4102c0a 07/11: * README.org ("Querying Prolog"): improve function listing |
Date: |
Sun, 15 Jan 2023 05:02:49 -0500 (EST) |
branch: elpa/sweeprolog
commit d3c4102c0a185cb587da79c28d92f14efb07f835
Author: Eshel Yaron <me@eshelyaron.com>
Commit: Eshel Yaron <me@eshelyaron.com>
* README.org ("Querying Prolog"): improve function listing
---
README.org | 62 +++++++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 43 insertions(+), 19 deletions(-)
diff --git a/README.org b/README.org
index 28c2f19e5d..8b24f81186 100644
--- a/README.org
+++ b/README.org
@@ -215,7 +215,33 @@ runtime on startup.
:ALT_TITLE: Querying Prolog
:END:
-#+FINDEX: sweeprolog-open-query
+This section describes a set of Elisp functions that interfaces with
+the embedded Prolog runtime:
+
+- Function: sweeprolog-open-query context module functor input reverse ::
Query
+ the Prolog predicate MODULE:FUNCTOR/2 in the context of the module
+ CONTEXT. Converts INPUT to a Prolog term and uses it as the first
+ argument, unless REVERSE is non-nil, in which can it uses INPUT as
+ the second argument. The other argument is called the output
+ argument of the query, it is expected to be unified with some output
+ that the query wants to return to Elisp. The output argument can be
+ retrieved with ~sweeprolog-next-solution~. Always returns ~t~ if called
+ with valid arguments, otherwise returns ~nil~.
+- Function: sweeprolog-next-solution :: Return the next solution of
+ the last Prolog query. Returns a cons cell ~(DET . OUTPUT)~ if the
+ query succeed, where ~DET~ is the symbol ~!~ if no choice points remain
+ and ~t~ otherwise, and ~OUTPUT~ is the output argument of the query
+ converted to an Elisp sexp. If there are no more solutions, return
+ ~nil~ instead. If a Prolog exception was thrown, return a cons cell
+ ~(exception . EXP)~ where ~EXP~ is the exception term converted to
+ Elisp.
+- Function: sweeprolog-cut-query :: Cut the last Prolog query. This
+ releases any resources reserved for it and makes further calls to
+ ~sweeprolog-next-solution~ invalid until you open a new query.
+- Function: sweeprolog-cut-query :: Close the last Prolog query.
+ Similar to ~sweeprolog-cut-query~ expect that any unifications created
+ by the last query are dropped.
+
Sweep provides the Elisp function =sweeprolog-open-query= for invoking Prolog
predicates. The invoked predicate must be of arity two and will be
called in mode =p(+In, -Out)= i.e. the predicate should treat the first
@@ -224,7 +250,7 @@ should be unified with some output. This restriction is
placed in
order to facilitate a natural calling convention between Elisp, a
functional language, and Prolog, a logical one.
-The =sweeprolog-open-query= function takes five arguments, the first three
+The ~sweeprolog-open-query~ function takes five arguments, the first three
are strings which denote:
- The name of the Prolog context module from which to execute the
query,
@@ -232,32 +258,30 @@ are strings which denote:
and
- The name of the predicate to call.
-The fourth argument to =sweeprolog-open-query= is converted into a Prolog
+The fourth argument to ~sweeprolog-open-query~ is converted into a Prolog
term and used as the first argument of the predicate (see [[Conversion
of Elisp objects to Prolog terms]]). The fifth argument is an
optional "reverse" flag, when this flag is set to non-nil, the order
of the arguments is reversed such that the predicate is called in mode
-=p(-Out, +In)= rather than =p(+In, -Out)=.
+~p(-Out, +In)~ rather than ~p(+In, -Out)~.
-#+FINDEX: sweeprolog-next-solution
-The function =sweeprolog-next-solution= can be used to examine the results of
-a query. If the query succeeded, =sweeprolog-next-solution= returns a cons
-cell whose =car= is either the symbol =!= when the success was
-deterministic or =t= otherwise, and the =cdr= is the current value of the
+The function ~sweeprolog-next-solution~ can be used to examine the results of
+a query. If the query succeeded, ~sweeprolog-next-solution~ returns a cons
+cell whose ~car~ is either the symbol ~!~ when the success was
+deterministic or ~t~ otherwise, and the ~cdr~ is the current value of the
second (output) Prolog argument converted to an Elisp object (see
[[Conversion of Prolog terms to Elisp objects]]). If the query failed,
-=sweeprolog-next-solution= returns nil.
+~sweeprolog-next-solution~ returns nil.
-#+FINDEX: sweeprolog-cut-query
-#+FINDEX: sweeprolog-close-query
Sweep only executes one Prolog query at a given time, thus queries
-opened with =sweeprolog-open-query= need to be closed before other queries
-can be opened. When no more solutions are available for the current
-query (i.e. after =sweeprolog-next-solution= returned nil), or when otherwise
-further solutions are not of interest, the query must be closed with
-either =sweeprolog-cut-query= or =sweeprolog-close-query=. Both of these
functions
-close the current query, but =sweeprolog-close-query= also destroys any
-Prolog bindings created by the query.
+opened with ~sweeprolog-open-query~ need to be closed before other
+queries can be opened. When no more solutions are available for the
+current query (i.e. after ~sweeprolog-next-solution~ returned ~nil~), or
+when otherwise further solutions are not of interest, the query must
+be closed with either ~sweeprolog-cut-query~ or
+~sweeprolog-close-query~. Both of these functions close the current
+query, but ~sweeprolog-close-query~ also destroys any Prolog bindings
+created by the query.
** Conversion of Elisp objects to Prolog terms
:PROPERTIES:
- [nongnu] elpa/sweeprolog 95fbd1388e 01/11: Refer to Sweep as a whole as "Sweep" without verbatim format, (continued)
- [nongnu] elpa/sweeprolog 95fbd1388e 01/11: Refer to Sweep as a whole as "Sweep" without verbatim format, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog 4576120f54 04/11: Bind C-c S-TAB to sweeprolog-backward-hole for symmetry, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog 471fc1aada 05/11: DOC: improve listings in the "Editing Prolog Code" section, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog 9823b09f6a 02/11: * sweeprolog.el: fix some typos in docstrings, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog 3a8d0d1626 09/11: * README.org ("High-level Architecture"): fix out-of-date docs, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog 98cfbd1999 08/11: * README.org ("Initialization and Cleanup"): use title case, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog 2b254c432f 11/11: * README.org ("Initialization and Cleanup"): improve listings, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog 3e02ab91fd 03/11: Add a couple of missing docstrings, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog 4028141133 06/11: * (sweeprolog-prefix-map): bind sweeprolog-top-level-send-goal to q, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog b02213d87f 10/11: * README.org: use ~code~ over =verbatim= more consistently, ELPA Syncer, 2023/01/15
- [nongnu] elpa/sweeprolog d3c4102c0a 07/11: * README.org ("Querying Prolog"): improve function listing,
ELPA Syncer <=