1 /*
2 * #%L
3 * prolobjectlink-jpi
4 * %%
5 * Copyright (C) 2019 Prolobjectlink Project
6 * %%
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23 * THE SOFTWARE.
24 * #L%
25 */
26 package io.github.prolobjectlink.prolog;
27
28 /**
29 * Prolog query builder to create prolog queries. The mechanism to create a new
30 * query builder is using {@link PrologEngine#newQueryBuilder()}. The query
31 * builder emulate the query creation process. After define all participant
32 * terms with the {@link #begin(PrologTerm)} method, we specify the first term
33 * in the query. If the query have more terms, they are created using
34 * {@link #comma(PrologTerm)} for every one. Clause builder have a
35 * {@link #getQueryString()} for string representation of the clause in
36 * progress. After clause definition this builder have {@link #query()} method
37 * that create the final query instance ready to be used.
38 *
39 * <pre>
40 * PrologVariable x = provider.newVariable("X", 0);
41 * PrologStructure big = provider.newStructure("big", x);
42 * PrologStructure dark = provider.newStructure("dark", x);
43 * PrologQueryBuilder builder = engine.newQueryBuilder();
44 * PrologQuery query = builder.begin(dark).comma(big).query();
45 * </pre>
46 *
47 * Prolog result
48 *
49 * <pre>
50 * ?- big(X), dark(X).
51 * </pre>
52 *
53 * @author Jose Zalacain
54 * @since 1.0
55 */
56 public interface PrologQueryBuilder extends PrologBuilder {
57
58 /**
59 * Append to the query builder the first term to be query. Return the current
60 * builder instance after append the term to be query.
61 *
62 * @param term term to be query.
63 * @return the current builder instance after append the term to be query.
64 * @since 1.0
65 */
66 public PrologQueryBuilder begin(PrologTerm term);
67
68 /**
69 * Append to the query builder the first term to be query. The term passed to
70 * the builder for this case is an structure created using the given functor and
71 * arguments array. Return the current builder instance after append the term to
72 * be query.
73 *
74 * @param functor string name for the structure term to be query.
75 * @param arguments prolog term arguments for the structure term to be query.
76 * @return the current builder instance after append the term to be query.
77 * @since 1.0
78 */
79 public PrologQueryBuilder begin(String functor, PrologTerm... arguments);
80
81 /**
82 * Append to the query builder other term to be query in disjunctive mode. The
83 * term passed to the builder for this case is an expression created using the
84 * given operator and operands. Return the current builder instance after append
85 * the term to be query.
86 *
87 * @param operator expression operator.
88 * @param left left hand prolog term operand.
89 * @param right right hand prolog term operand.
90 * @return the current builder instance after append the term to be query.
91 * @since 1.0
92 */
93 public PrologQueryBuilder semicolon(PrologTerm left, String operator, PrologTerm right);
94
95 /**
96 * Append to the query builder other term to be query in disjunctive mode. The
97 * term passed to the builder for this case is an structure created using the
98 * given functor and arguments array. Return the current builder instance after
99 * append the term to be query.
100 *
101 * @param functor string name for the structure term to be query.
102 * @param arguments prolog term arguments for the structure term to be query.
103 * @return the current builder instance after append the term to be query.
104 * @since 1.0
105 */
106 public PrologQueryBuilder semicolon(String functor, PrologTerm... arguments);
107
108 /**
109 * Append to the query builder other term to be query in disjunctive mode.
110 * Return the current builder instance after append the term to be query.
111 *
112 * @param term term to be query.
113 * @return the current builder instance after append the term to be query.
114 * @since 1.0
115 */
116 public PrologQueryBuilder semicolon(PrologTerm term);
117
118 /**
119 * Append to the query builder other term to be query in conjunctive mode. The
120 * term passed to the builder for this case is an expression created using the
121 * given operator and operands. Return the current builder instance after append
122 * the term to be query.
123 *
124 * @param operator expression operator.
125 * @param left left hand prolog term operand.
126 * @param right right hand prolog term operand.
127 * @return the current builder instance after append the term to be query.
128 * @since 1.0
129 */
130 public PrologQueryBuilder comma(PrologTerm left, String operator, PrologTerm right);
131
132 /**
133 * Append to the query builder other term to be query in conjunctive mode. The
134 * term passed to the builder for this case is an structure created using the
135 * given functor and arguments array. Return the current builder instance after
136 * append the term to be query.
137 *
138 * @param functor string name for the structure term to be query.
139 * @param arguments prolog term arguments for the structure term to be query.
140 * @return the current builder instance after append the term to be query.
141 * @since 1.0
142 */
143 public PrologQueryBuilder comma(String functor, PrologTerm... arguments);
144
145 /**
146 * Append to the query builder other term to be query in conjunctive mode.
147 * Return the current builder instance after append the term to be query.
148 *
149 * @param term term to be query.
150 * @return the current builder instance after append the term to be query.
151 * @since 1.0
152 */
153 public PrologQueryBuilder comma(PrologTerm term);
154
155 /**
156 * Get the query in string format.
157 *
158 * @return string query.
159 * @since 1.0
160 */
161 public String getQueryString();
162
163 /**
164 * Create and return the result query.
165 *
166 * @return the result query.
167 * @since 1.0
168 */
169 public PrologQuery query();
170
171 }