public class Query extends java.lang.Object implements java.lang.Iterable<java.util.Map<java.lang.String,Term>>, java.util.Iterator<java.util.Map<java.lang.String,Term>>
A Query is either open or closed: when closed, it has no connection to the Prolog system; when open, it is linked to an active goal within a Prolog engine.
The Query class implements the Enumeration interface, through which one can obtain successive solutions. The Enumeration hasMoreElements() method returns true if the call or redo succeeded (otherwise false), and if the call or redo did succeed, the nextElement() method returns a Map representing variable bindings; the elements in the Map are Terms, indexed by the (String) names of the Variables with which they are associated. For example, if p(a) and p(b) are facts in the Prolog database, then the following is equivalent to printing all the solutions to the Prolog query p(X):
Variable X = new Variable("X"); Term arg[] = { X }; Query q = new Query("p", arg); while (q.hasMoreElements()) { Term bound_to_x = ((Map) q.nextElement()).get("X"); System.out.println(bound_to_x); }Make sure to close the Query (using the close() method) if you do not need any further solutions which it may have. It is safe (although redundant) to close a Query whose solutions are already exhausted, or which is already closed. To obtain just one solution from a Query, use the oneSolution() method. To obtain all solutions, use the allSolutions() method. To obtain at most N solutions, use the nSolutions() method. To determine merely whether the Query is provable, use the hasSolution() method (i.e. has at least one solution).
Copyright (C) 1998 Fred Dushin
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library Public License for more details.
Modifier and Type | Field and Description |
---|---|
protected java.lang.String |
contextModule |
protected Term |
goal_
the Compound or Atom (but not Dict, Float, Integer or Variable) corresponding to the goal of this Query
|
protected java.lang.String |
hostModule |
Constructor and Description |
---|
Query(java.lang.String text)
This constructor builds a Query from the given Prolog source text.
|
Query(java.lang.String text,
Term arg) |
Query(java.lang.String text,
Term[] args)
If text denotes an atom, this constructor is shorthand for new Query(new Compound(name,args)), but if text denotes a term containing N query (?)
|
Query(Term t)
This constructor creates a Query whose goal is the specified Term.
|
Modifier and Type | Method and Description |
---|---|
java.util.Map<java.lang.String,Term>[] |
allSolutions()
calls the Query's goal to exhaustion and returns an array of zero or more Maps of zero or more variablename-to-term bindings (each Map represents a solution, in the order in which they were
found).
|
static java.util.Map<java.lang.String,Term>[] |
allSolutions(java.lang.String text)
This static method creates a Query from the given Prolog source text fragment, calls it to exhaustion, and returns an array of zero or more Maps of zero or more variablename-to-term bindings
(each Map represents a solution, in the order in which they were found).
|
static java.util.Map<java.lang.String,Term>[] |
allSolutions(java.lang.String text,
Term[] params)
If text denotes (in traditional Prolog source syntax) a term containing N questionmark (?)
|
static java.util.Map<java.lang.String,Term>[] |
allSolutions(Term goal)
This static method creates a Query whose goal is the given Term, calls it to exhaustion, and returns an array of zero or more Maps of zero or more variablename-to-term bindings (each Map
represents a solution, in the order in which they were found).
|
void |
close()
This method can be used to close an open query before its solutions are exhausted.
|
java.util.Map<java.lang.String,Term> |
getSolution()
This method returns a java.util.Map, which represents a set of bindings from the names of query variables to terms within the solution.
|
java.util.Map<java.lang.String,Term> |
getSubstWithNameVars() |
Term |
goal()
Returns the Term (Atom or Compound) which is the goal of this Query
|
boolean |
hasMoreElements()
This method implements part of the java.util.Enumeration interface.
|
boolean |
hasMoreSolutions()
This method returns true if JPL was able to initiate a "call" of this Query within a Prolog engine.
|
boolean |
hasNext()
whether this Query has a (further) solution
|
boolean |
hasSolution()
This method will attempt to call this Query's goal within an available Prolog engine.
|
static boolean |
hasSolution(java.lang.String text)
This static method creates a Query from the given Prolog source text and calls it at most once, returning true if a solution was found, else false.
|
static boolean |
hasSolution(java.lang.String text,
Term[] params)
If text denotes (in traditional Prolog source syntax) a term containing N questionmark (?)
|
static boolean |
hasSolution(Term goal)
This static method creates a Query (whose goal is the specified Term) and calls it at most once, returning true if a solution was found, else false.
|
boolean |
isOpen()
isOpen() returns true iff the query is open.
|
java.util.Iterator<java.util.Map<java.lang.String,Term>> |
iterator()
a Query is its own Iterator
|
java.util.Map<java.lang.String,Term> |
next()
this Query's next solution
|
java.lang.Object |
nextElement()
This method implements part of the java.util.Enumeration interface.
|
java.util.Map<java.lang.String,Term> |
nextSolution()
This method returns a java.util.Map, which represents a binding from the names of query variables to terms within the solution.
|
java.util.Map<java.lang.String,Term>[] |
nSolutions(long n)
calls the Query's goal to exhaustion or until N solutions are found, whichever is sooner, and returns an array containing (as possibly empty Maps of variablename-to-term bindings) every found
solution (in the order in which they were found).
|
static java.util.Map<java.lang.String,Term>[] |
nSolutions(java.lang.String text,
long n)
This static method creates a Query from the given Prolog source text fragment, calls it to exhaustion or until N solutions are found, whichever is sooner, and returns an array containing (as
possibly empty Maps of variablename-to-term bindings) every found solution (in the order in which they were found).
|
static java.util.Map<java.lang.String,Term>[] |
nSolutions(java.lang.String text,
Term[] params,
long n)
If text denotes (in traditional Prolog source syntax) a term containing N questionmark (?)
|
static java.util.Map<java.lang.String,Term>[] |
nSolutions(Term goal,
long n)
This static method creates a Query whose goal is the given Term, calls it to exhaustion or until N solutions are found, whichever is sooner, and returns an array containing (as possibly empty
Maps of variablename-to-term bindings) every found solution (in the order in which they were found).
|
java.util.Map<java.lang.String,Term> |
oneSolution()
Returns the first solution, if any, as a (possibly empty) Map of variablename-to-term bindings, else null.
|
static java.util.Map<java.lang.String,Term> |
oneSolution(java.lang.String text)
This static method creates a Query from the given Prolog source text fragment, and calls it at most once, returning the first solution, if there is one, as a (possibly empty) Map, else null.
|
static java.util.Map<java.lang.String,Term> |
oneSolution(java.lang.String text,
Term[] params)
If text denotes (in traditional Prolog source syntax) a term containing N questionmark (?)
|
static java.util.Map<java.lang.String,Term> |
oneSolution(Term goal)
This static method creates a Query (whose goal is the specified Term) and calls it at most once, returning the first solution, if there is one, as a (possibly empty) Map, else null.
|
void |
open()
This method returns true if JPL was able to initiate a "call" of this Query within the Prolog engine.
|
void |
remove()
this method (required by Iterator interface) is a no-op
|
java.lang.String |
toString()
Returns a crude String representation of a Query.
|
protected final Term goal_
protected final java.lang.String hostModule
protected final java.lang.String contextModule
public Query(Term t)
t
- the goal of this Querypublic Query(java.lang.String text, Term[] args)
text
- the name of the principal functor of this Query's goalargs
- the arguments of this Query's goalpublic Query(java.lang.String text, Term arg)
public Query(java.lang.String text)
text
- the Prolog source text of this Querypublic final Term goal()
public java.util.Iterator<java.util.Map<java.lang.String,Term>> iterator()
iterator
in interface java.lang.Iterable<java.util.Map<java.lang.String,Term>>
Iterable.iterator()
public boolean hasNext()
hasNext
in interface java.util.Iterator<java.util.Map<java.lang.String,Term>>
Iterator.hasNext()
public java.util.Map<java.lang.String,Term> next()
next
in interface java.util.Iterator<java.util.Map<java.lang.String,Term>>
Iterator.next()
public void remove()
remove
in interface java.util.Iterator<java.util.Map<java.lang.String,Term>>
Iterator.remove()
public final boolean isOpen()
public final boolean hasMoreSolutions()
Query q = // obtain Query reference while (q.hasMoreSolutions()) { Map solution = q.nextSolution(); // process solution... }To ensure thread-safety, you should wrap sequential calls to this method in a synchronized block, using the static lock method to obtain the monitor.
Query q = // obtain Query reference synchronized ( jpl.Query.lock() ){ while ( q.hasMoreElements() ){ Map solution = q.nextSolution(); // process solution... } }
public final void open()
Query q = // obtain Query reference Map soln; q.open(); while ((soln = q.getSolution()) != null) { // process solution... }
If this method is called on an already-open Query, or if the query cannot be set up for whatever reason, then a JPLException will be thrown.
public final java.util.Map<java.lang.String,Term> getSolution()
For example, if a Query has an occurrence of a jpl.Variable, say, named "X", one can obtain the Term bound to "X" in the solution by looking up "X" in the Map.
Variable x = new Variable("X"); Query q = // obtain Query reference (with x in the Term array) while (q.hasMoreSolutions()) { Map solution = q.nextSolution(); // make t the Term bound to "X" in the solution Term t = (Term) solution.get("X"); // ... }Programmers should obey the following rules when using this method. This method will throw a JPLException if Query is not open.
public final java.util.Map<java.lang.String,Term> getSubstWithNameVars()
public final java.util.Map<java.lang.String,Term> nextSolution()
For example, if a Query has an occurrence of a jpl.Variable, say, named "X", one can obtain the Term bound to "X" in the solution by looking up "X" in the Map.
Variable x = new Variable("X"); Query q = // obtain Query reference (with x in the Term array) while (q.hasMoreSolutions()) { Map solution = q.nextSolution(); // make t the Term bound to "X" in the solution Term t = (Term) solution.get("X"); // ... }Programmers should obey the following rules when using this method. This method will throw a JPLException if Query is not open.
public final boolean hasMoreElements()
public final java.lang.Object nextElement()
public final void close()
Here is one way to get the first three solutions to a Query:
Query q = new Query(predicate, args); Map<String, Term> sub1 = q.nextSolution(); Map<String, Term> sub2 = q.nextSolution(); Map<String, Term> sub3 = q.nextSolution(); q.close();
public final java.util.Map<java.lang.String,Term>[] allSolutions()
NB in JPL 1.0.1, bindings were keyed (awkwardly) by Variable instances; in JPL 2.x onwards they are keyed by the (String) names of variables, which is consistent with the Term type being just a concrete syntax for terms (and hence queries).
public static final java.util.Map<java.lang.String,Term>[] allSolutions(Term goal)
goal
- the goal of this Querypublic static final java.util.Map<java.lang.String,Term>[] allSolutions(java.lang.String text)
text
- a Prolog source text fragment denoting a goalpublic static final java.util.Map<java.lang.String,Term>[] allSolutions(java.lang.String text, Term[] params)
text
- the Prolog source text of a goal, in which questionmarks are regarded as substitutible parametersparams
- terms to be substituted for the respective questionmarks in the query textpublic final java.util.Map<java.lang.String,Term>[] nSolutions(long n)
NB in JPL 1.0.1, bindings were keyed (awkwardly) by Variable instances; in JPL 2.x onwards they are keyed by the (String) names of variables, which is consistent with the Term type being just a concrete syntax for terms (and hence queries).
public static final java.util.Map<java.lang.String,Term>[] nSolutions(Term goal, long n)
goal
- the goal of this Querypublic static final java.util.Map<java.lang.String,Term>[] nSolutions(java.lang.String text, long n)
text
- a Prolog source text fragment denoting a goalpublic static final java.util.Map<java.lang.String,Term>[] nSolutions(java.lang.String text, Term[] params, long n)
text
- the Prolog source text of a goal, in which questionmarks are regarded as substitutible parametersparams
- terms to be substituted for the respective questionmarks in the query textpublic final java.util.Map<java.lang.String,Term> oneSolution()
public static final java.util.Map<java.lang.String,Term> oneSolution(Term goal)
goal
- the goal of this Querypublic static final java.util.Map<java.lang.String,Term> oneSolution(java.lang.String text)
text
- a Prolog source text fragment denoting a goalpublic static final java.util.Map<java.lang.String,Term> oneSolution(java.lang.String text, Term[] params)
text
- the Prolog source text of a goal, in which questionmarks are regarded as substitutible parametersparams
- terms to be substituted for the respective questionmarks in the query textpublic final boolean hasSolution()
Only the first solution (if there is one) will be found; any bindings will be discarded, and the Query will be closed.
This method will throw a JPLException if this Query is already open.
public static final boolean hasSolution(Term goal)
goal
- the goal of this Querypublic static final boolean hasSolution(java.lang.String text)
text
- the goal of this Query, as Prolog source textpublic static final boolean hasSolution(java.lang.String text, Term[] params)
text
- the Prolog source text of a goal, in which questionmarks are regarded as substitutible parametersparams
- terms to be substituted for the respective questionmarks in the query textpublic java.lang.String toString()
toString
in class java.lang.Object