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 from 0 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 inorder_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 either pyDatalog.Variable (when they start with an upper case) or pyParser.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, or None.
• 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, or None
• 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, or True, or []. Each tuple contains as many items as there are variables in the query. If the query leaves some variables unbound, its data is True. If the query is not satisfiable, its answer is [].
• __eq__(self, other) : returns True if the result of the query is equal to other, after converting both of them to sets
• __ge__(self, other) : returns the first value of other, where other 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 queried
• arity : arity of the predicate
• answers : a list of tuples that satisfy the query, or True, or None. Each tuple contains as many items as there are variables in the query. If the query leaves some variables unbound, its answer is True. If the query is not satisfiable, its answer is None.
• __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, using import logging and configuring it (e.g. logging.basicConfig(level=logging.DEBUG)). Logging.INFO logs derived facts when they are established, while Logging.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).