Reference 0.13
In-line datalog, datalog program and datalog string
An in-line datalog statement is a Python statement:
- that follows the syntax of a datalog statement (see grammar below),
- where datalog constants, variables and unprefixed predicates have been previously declared globally using
pyDatalog.create_atoms()
(thus not declared in a method or class), - and where the prefix of prefixed predicates is the name of a class inheriting from
pyDatalog.Mixin
.
Similarly, an in-line query is a Python statement that follows the syntax of a body (see grammar below).
By contrast, a datalog program is a set of datalog statements in a function prefixed by @pyDatalog.program()
. It is executed only once, e.g. to load a set of clauses. Atoms do not need to be declared.
Finally, a datalog string can be submitted to the pyDatalog engine using pyDatalog.load()
or pyDatalog.ask()
. Atoms do not need to be declared. Constants cannot be python objects.
Grammar of pyDatalog
The terminal symbols in this grammar are defined in BNF as follows :
- simple_predicate ::= [a-fA-F_] [0-9a-fA-F_]*
- constant ::= [a-f] [0-9a-fA-F_]* | python literals | python object
- variable ::= [A-F_] [0-9a-fA-F_]*, thus starting with an uppercase
- Note : words starting with
_pyD_
are reserved for pyDatalog
Please note:
- although the order of pyDatalog statements is indifferent, the order of literals within a body is significant:
- an expression used as the argument of a logic function must be bound by a previous literal (otherwise no result is returned)
- the right hand side of
X==expr
must be bound by a previous literal (otherwise, no result is returned) - the right hand side of
p[X]< expr
must be bound (otherwise, no result is returned). - the left and right hand sides of
expr1 < expr2
comparisons must be bound (otherwise, an error is raised) - an inequality must be surrounded by parenthesis, and can only appear in the body of a clause
- an aggregate function can only appear in the head of a clause. Note the
_
suffix (e.g.sum_
) to differentiate with the python aggregate function - "
=
" defines a logic formula, while "==
" appears in a fact, clause or query and must always be surrounded by parenthesis - the head of a clause can only contain constant or variable (but no expressions).
Built-in functions are:
(Y==len_(X))
: Y is the length of the list bound to X(Y==range_(X))
: Y is a list containing numbers from0
to X-1(Y==format_(F, X1, X2, ..))
: Y is the formatting of X1, X2, ... according to the F specifications (see format() in python documentation)
Aggregate functions:
- len_
(P[X]==len_(Y)) <= body
: P[X] is the count of values of Y (associated to X by the body of the clause) - sum_
(P[X]==sum_(Y, for_each=Z)) <= body
: P[X] is the sum of Y for each Z. (Z is used to distinguish possibly identical Y values) - min_, max_
(P[X]==min_(Y, order_by=Z)) <= body
: P[X] is the minimum (or maximum) of Y sorted by Z. - tuple_
(P[X]==tuple_(Y, order_by=Z)) <= body
: P[X] is a tuple containing all values of Y sorted by Z. - concat_
(P[X]==concat_(Y, order_by=Z, sep=',')) <= body
: same as 'sum' but for string. The strings are sorted by Z, and separated by ','. - rank_
(P[X]==rank_(for_each=Y, order_by=Z)) <= body
: P[X] is the sequence number of X in the list of Y values when the list is sorted by Z. - running_sum_
(P[X]==running_sum_(N, for_each=Y, order_by=Z)) <= body
: P[X] is the sum of the values of N, for each Y that are before or equal to X when Y's are sorted by Z. - The named arguments must be specified in the given order. X and the named arguments can be a list of variables (instead of just one variable), to represent more complex grouping. Variables in
order_by
arguments can be preceded by '-' for descending sort order. If the aggregation function does not depend on a variable, use a constant (e.g.P[None] == len_(Y)
).
Methods and classes
The pyDatalog module has the following methods :
- create_atoms(*args) : adds "logic atoms" in the scope of the caller.
create_atoms
must be called at module level (not in a function or class definition) It can have any number of arguments : each arg is a string containing the names of the logic atoms to be created, separated by commas. The created logic atoms are eitherpyDatalog.Variable
(when they start with an upper case) orpyParser.Symbol
(otherwise). create_atoms also creates symbols for the aggregate functions. - assert_fact(predicate_name, *terms) : asserts
predicate_name(terms[0], terms[1], ...)
- retract_fact( predicate_name, *terms) : retracts
predicate_name(terms[0], terms[1], ...)
- load(code) : where code is a string containing a set of datalog statements, with identical indentation and separated by line feeds. This method can be used to add facts and clauses to the datalog database.
- program() : a function decorator that loads the datalog program contained in the decorated function.
- predicate() : a function decorator that declares a custom predicate resolver written in python
- ask(query) : where query is a string containing a logic query. It returns an instance of
pyDatalog.Answer
, orNone
. - clear() : removes all facts and clauses from the datalog database.
An instance of the pyDatalog.Variable class has the following attributes and methods:
data
: list of possible values for the variable. Updated on request after each in-line query.v(self)
: returns the first value of the variable, orNone
- the methods inherited from collections.UserList
An instance of the pyParser.Query class is returned by an in-line query and has the following attributes and methods:
data
: a list of tuples that satisfy the query, orTrue
, or[]
. Each tuple contains as many items as there are variables in the query. If the query leaves some variables unbound, its data isTrue
. If the query is not satisfiable, its answer is [].__eq__(self, other)
: returnsTrue
if the result of the query is equal toother
, after converting both of them to sets__ge__(self, other)
: returns the first value ofother
, whereother
is a pyDatalog.Variable appearing in the query__str__(self)
: pretty prints the result of the query, in tabular format- the methods inherited from collections.UserList
After an in-line query is resolved, each variable in the query contains the list of possible values. It should be noted that the result of the query is determined when it is first needed (and thus not in the statement that defines the query).
p(X)
print(X) # the p(X) query is resolved here !
An instance of the pyDatalog.Answer class is returned by pyDatalog.ask("query"
) and has the following attributes and methods:
name
: name of the predicate that was queriedarity
: arity of the predicateanswers
: a list of tuples that satisfy the query, orTrue
, orNone
. Each tuple contains as many items as there are variables in the query. If the query leaves some variables unbound, its answer isTrue
. If the query is not satisfiable, its answer isNone
.__eq__(other)
: facilitates comparison to another set of tuples__str__()
: prints the answer
pyEngine has the following attribute :
Logging
= true : activates the logging. You must also activate python logging, usingimport logging
and configuring it (e.g.logging.basicConfig(level=logging.DEBUG)
).Logging.INFO
logs derived facts when they are established, whileLogging.DEBUG
logs a deeper trace of pyDatalog's reasoning
Note
Beware that, when loading a datalog program, a symbol could become a constant. For example,
@pyDatalog.program()
def _():
+ a(i)
for i in range(3):
+ b(i)
print(pyDatalog.ask("a('i')")) # prints a set with 1 element : the ('i',) tuple
print(pyDatalog.ask("b(X)")) # prints a set with 3 elements, each containing one element : 0, 1 or 2
The for
loop assigns an integer to i, which is inserted as a constant in + b(i)
.