py-xsb 1.0.0

py-xsb
======

A Python - XSB bridge enabling querying XSB in your Python programs. It
features a ctypes mapping of XSB’s C-Interface as well as some higher
level convenience wrappers.

Constructive comments, patches and pull-requests are very welcome.

Examples
--------

### High Level Wrappers (demo\_highlevel.py)

Setup XSB engine:

from pyxsb import pyxsb_start_session, pyxsb_end_session, pyxsb_command, \
pyxsb_query, XSBFunctor, XSBVariable, xsb_to_json, json_to_xsb

pyxsb_start_session()
# in case auto-detection fails, you can pass the XSB arch dir here like so:
# pyxsb_start_session('/opt/xsb-3.8.0/config/x86_64-redhat-linux-gnu')
#
# to determine the location of the XSB arch dir on your machine, run this query in XSB:
# xsb_configuration:xsb_configuration(config_dir,Dir).

run a string XSB command:

pyxsb_command('consult(ft).')

run a string query:

for row in pyxsb_query('label(X, L).'):
print u"label of %s is %s" % (row[0], row[1])

queries and commands can also be constructed structurally:

for row in pyxsb_query(XSBFunctor('descend', [XSBVariable('X'), XSBVariable('Y')])):
print u"decendant of %s is %s" % (row[0], row[1])

the wrappers (XSBFunctor, XSBVariable, XSBString, XSBAtom) are the same
ones used to represent the query results. For integers, floats and lists
primitive python types are used:

for row in pyxsb_query(u'A = 1, B = 0.5, C = "hello", D = yes, E = foo(bar), F = [1.1,2.2], G = \'günter\'.'):
for i, r in enumerate(row):
print u"#%d: %-10s (type: %-20s, class: %-20s)" % (i, r, type(r), r.__class__)

the wrappers can also converted to and from JSON:

js = xsb_to_json(row)
print "json: %s" % js

row2 = json_to_xsb(js)
print "restored: %s" % str(row2)

close the session:

pyxsb_end_session()

### XSB Low Level API (demo\_lowlevel.py)

First, import xsb and init the library:

from pyxsb import pyxsb_start_session
pyxsb_start_session()

from pyxsb import *

execute an XSB command:

c2p_functor("consult", 1, reg_term(1))
c2p_string("ctest",p2p_arg(reg_term(1),1))
if xsb_command():
raise Exception ("Error consulting ctest")

same thing using the string interface:

if xsb_command_string("consult(basics)."):
raise Exception ("Error (string) consulting basics.")

run a query:

# Create the query p(300,X,Y) and send it.
c2p_functor("p",3,reg_term(1))
c2p_int(300,p2p_arg(reg_term(1),1))

rcode = xsb_query()

# Print out answer and retrieve next one.
while not rcode:
if not is_string(p2p_arg(reg_term(2),1)) and is_string(p2p_arg(reg_term(2),2)):
print "2nd and 3rd subfields must be atoms"
else:
print "Answer: %d, %s(%s), %s(%s)" % ( p2c_int(p2p_arg(reg_term(1),1)),
p2c_string(p2p_arg(reg_term(1),2)),
xsb_var_string(1),
p2c_string(p2p_arg(reg_term(1),3)),
xsb_var_string(2))
rcode = xsb_next()

run a string query:

xsb_make_vars(3)
xsb_set_var_int(300,1)
rcode = xsb_query_string("p(X,Y,Z).")

# Print out answer and retrieve next one.
while not rcode:
if not is_string(p2p_arg(reg_term(2),2)) and is_string(p2p_arg(reg_term(2),3)):
print "2nd and 3rd subfields must be atoms"
else:
print "Answer: %d, %s, %s" % (xsb_var_int(1),
xsb_var_string(2),
xsb_var_string(3))
rcode = xsb_next()

close the connection:

pyxsb_end_session()

Installation Notes
------------------

`py-xsb` needs the XSB dynamic library to work: First, follow the
standard XSB build instructions:

tar xfvz XSB.tar.gz
cd XSB/build
./configure
./makexsb

now, in order to build `libxsb.so`, execute this command:

[guenter@dagobert build]$ ./makexsb dynmodule

Links
-----

- <http://xsb.sourceforge.net/> [XSB]

Requirements
------------

- Python 2.7 or Python 3.6

- libxsb.so shared library installed and in ld’s path

License
-------

My own code is Apache-2.0 licensed unless otherwise noted in the
script’s copyright headers.

Authors
-------

- Guenter Bartsch \<<guenter@zamia.org>\>

- Many improvements and bugfixes by Michael Kifer, Annie Liu, David
Warren (XSB team at Stony Brook University of New York)