Updates (#191)

Python to Prolog value exchange using string interpolation

README.md

@@ -18,7 +18,7 @@ See the [Change Log](https://pyswip.org/change-log.html).
 
 If you have SWI-Prolog installed, it's just:
 ```
-pip install pyswip
+pip install -U pyswip
 ```
 
 See [Get Started](https://pyswip.readthedocs.io/en/latest/get_started.html) for detailed instructions.

docs/source/api/examples.rst

@@ -9,3 +9,17 @@ Sudoku
 
 .. automodule:: pyswip.examples.sudoku
     :members:
+
+Hanoi
+^^^^^
+
+.. automodule:: pyswip.examples.hanoi
+    :members:
+
+
+Coins
+^^^^^
+
+.. automodule:: pyswip.examples.coins
+    :members:
+

docs/source/get_started.rst

@@ -29,7 +29,7 @@ PySwip is available to install from `Python Package Index <https://pypi.org/proj
 
 You can install PySwip using::
 
-    pip install pyswip
+    pip install -U pyswip
 
 You will need to have SWI-Prolog installed on your system.
 See :ref:`install_swi_prolog`.
@@ -153,8 +153,9 @@ SWI-Prolog can be installed using ``pkg``::
 Test Drive
 ----------
 
-Run a quick test by running following code at your Python console::
+Run a quick test by running following code at your Python console:
 
+.. code-block:: python
 
     from pyswip import Prolog
     Prolog.assertz("father(michael,john)")

docs/source/index.rst

@@ -14,6 +14,7 @@ It features an SWI-Prolog foreign language interface, a utility class that makes
    :caption: Contents:
 
    get_started
+   value_exchange
    api/modules
 
 Indices and Tables

docs/source/value_exchange.rst

@@ -0,0 +1,65 @@
+Value Exchange Between Python and Prolog
+========================================
+
+String Interpolation from Python to Prolog
+------------------------------------------
+
+Currently there's limited support for converting Python values automatically to Prolog via a string interpolation mechanism.
+This mechanism is available to be used with the following ``Prolog`` class methods:
+
+* ``assertz``
+* ``asserta``
+* ``retract``
+* ``query``
+
+These methods take one string format argument, and zero or more arguments to replace placeholders with in the format to produce the final string.
+Placeholder is ``%p`` for all types.
+
+The following types are recognized:
+
+* String
+* Integer
+* Float
+* Boolean
+* ``pyswip.Atom``
+* ``pyswip.Variable``
+* Lists of the types above
+
+Other types are converted to strings using the ``str`` function.
+
+.. list-table:: String Interpolation to Prolog
+    :widths: 50 50
+    :header-rows: 1
+
+    * - Python Value
+      - String
+    * - str ``"Some value"``
+      - ``"Some value"``
+    * - int ``38``
+      - ``38``
+    * - float ``38.42``
+      - ``38.42``
+    * - bool ``True``
+      - ``1``
+    * - bool ``False``
+      - ``0``
+    * - ``pyswip.Atom("carrot")``
+      - ``'carrot'``
+    * - ``pyswip.Variable("Width")``
+      - ``Width``
+    * - list ``["string", 12, 12.34, Atom("jill")]``
+      - ``["string", 12, 12.34, 'jill']``
+    * - Other ``value``
+      - ``str(value)``
+
+
+The placeholders are set using ``%p``.
+
+Example:
+
+.. code-block:: python
+
+    ids = [1, 2, 3]
+    joe = Atom("joe")
+    Prolog.assertz("user(%p,%p)", joe, ids)
+    list(Prolog.query("user(%p,IDs)", joe))

examples/README.md

@@ -4,9 +4,9 @@ This directory contains examples for PySwip.
 
 The ones marked with (clp) requires `clp` library of SWI-Prolog.
 
-* (clp) `coins/`
+* (clp) `coins/` : Moved to `pyswip.examples.coins` package
 * (clp) `draughts/`
-* `hanoi/` : Towers of Hanoi
+* `hanoi/` : Moved to `pyswip.examples.sudoku` package
 * (clp) `sendmoremoney/` : If, SEND * MORE = MONEY, what is S, E, N, D, M, O, R, Y?
 * (clp) `sudoku/` : Moved to `pyswip.examples.sudoku` package 
 * `create_term.py` : Shows creating a Prolog term

examples/coins/coins.pl

@@ -3,9 +3,9 @@
 
 :- use_module(library('bounds')).
 
-coins(S, Count, Total) :-
+coins(Count, Total, Solution) :-
  	% A=1, B=5, C=10, D=50, E=100
-	S = [A, B, C, D, E],
+	Solution = [A, B, C, D, E],
 
 	Av is   1,
 	Bv is   5,
@@ -31,8 +31,8 @@
 	VD #= D*Dv,
 	VE #= E*Ev,
 
-	sum(S, #=, Count),
+	sum(Solution, #=, Count),
 	VA + VB + VC + VD + VE #= Total,
 
-	label(S).
+	label(Solution).
 

examples/coins/coins_new.py

@@ -30,7 +30,7 @@ def main():
     total = int(input("What should be the total (default: 500)? ") or 500)
     coins = Functor("coins", 3)
     S = Variable()
-    q = Query(coins(S, count, total))
+    q = Query(coins(count, total, S))
     i = 0
     while q.nextSolution():
         ## [1,5,10,50,100]

examples/create_term.py

@@ -22,7 +22,7 @@
 # SOFTWARE.
 
 from pyswip.core import *
-from pyswip.prolog import Prolog
+from pyswip import Prolog
 
 
 def main():

examples/draughts/puzzle1.py

@@ -33,7 +33,7 @@
 # are four guards watching each wall.  How can they be rearranged such
 # that there are five watching each wall?"
 
-from pyswip.prolog import Prolog
+from pyswip import Prolog
 
 
 def main():

examples/knowledgebase.py

@@ -21,11 +21,11 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from pyswip import *
+from pyswip import Prolog, Functor, Variable, Query, newModule, call
 
 
 def main():
-    _ = Prolog()
+    _ = Prolog()  # not strictly required, but helps to silence the linter
 
     assertz = Functor("assertz")
     parent = Functor("parent", 2)

examples/register_foreign_simple.py

@@ -27,11 +27,8 @@
 from pyswip.easy import registerForeign
 
 
-def hello(t):
-    print("Hello,", t)
-
-
-hello.arity = 1
+def hello(who):
+    print("Hello,", who)
 
 
 def main():