View Javadoc

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   * <p>
30   * Prolog clause builder to create prolog clauses. The mechanism to create a new
31   * clause builder is using {@link PrologEngine#newClauseBuilder()}. The clause
32   * builder emulate the clause creation process. After define all participant
33   * terms with the {@link #begin(PrologTerm)} method, we specify the head of the
34   * clause.
35   * </p>
36   * <p>
37   * If the clause is a rule, after head definition, the clause body is created
38   * with {@link #neck(PrologTerm)} for the first term in the clause body. If the
39   * clause body have more terms, they are created using
40   * {@link #comma(PrologTerm)} for every one.
41   * </p>
42   * <p>
43   * Clause builder have a {@link #getClauseString()} for string representation of
44   * the clause in progress. After clause definition this builder have
45   * {@link #asserta()},{@link #assertz()},{@link #clause()},{@link #retract()}
46   * that use the wrapped engine invoking the correspondent methods for check,
47   * insert or remove clause respectively.
48   * </p>
49   * 
50   * <pre>
51   * PrologStructure blackZ = provider.newStructure("black", z);
52   * PrologStructure brownZ = provider.newStructure("brown", z);
53   * PrologClauseBuilder builder = engine.newClauseBuilder();
54   * builder.begin(darkZ).neck(blackZ).assertz();
55   * builder.begin(darkZ).neck(brownZ).assertz();
56   * </pre>
57   * 
58   * Prolog result.
59   * 
60   * <pre>
61   * dark(Z) :- 
62   *	black(Z).
63   * dark(Z) :- 
64   *	brown(Z).
65   * </pre>
66   * 
67   * @author Jose Zalacain
68   * @since 1.0
69   */
70  public interface PrologClauseBuilder extends PrologBuilder {
71  
72  	/**
73  	 * Append to the clause builder the head term in the clause. The term passed to
74  	 * the builder for this case is an structure created using the given functor and
75  	 * arguments array. Return the current builder instance after append the term in
76  	 * the clause.
77  	 * 
78  	 * @param functor   string name for the structure term.
79  	 * @param arguments prolog term arguments for the structure.
80  	 * @return the current builder instance after append the term in the clause.
81  	 * @since 1.0
82  	 */
83  	public PrologClauseBuilder begin(String functor, PrologTerm... arguments);
84  
85  	/**
86  	 * Append to the clause builder the head term in the clause. Return the current
87  	 * builder instance after append the term in the clause.
88  	 * 
89  	 * @param term term to be the head in the clause.
90  	 * @return the current builder instance after append the term in the clause.
91  	 * @since 1.0
92  	 */
93  	public PrologClauseBuilder begin(PrologTerm term);
94  
95  	/**
96  	 * Append to the clause builder the first term in the clause body. The term
97  	 * passed to the builder for this case is an expression created using the given
98  	 * operator and operands. Return the current builder instance after append the
99  	 * term in the clause body
100 	 * 
101 	 * @param operator expression operator.
102 	 * @param left     left hand prolog term operand.
103 	 * @param right    right hand prolog term operand.
104 	 * @return the current builder instance after append the term in the clause
105 	 *         body.
106 	 * @since 1.0
107 	 */
108 	public PrologClauseBuilder neck(PrologTerm left, String operator, PrologTerm right);
109 
110 	/**
111 	 * Append to the clause builder the first term in the clause body. The term
112 	 * passed to the builder for this case is an structure created using the given
113 	 * functor and arguments array. Return the current builder instance after append
114 	 * the term in the clause body
115 	 * 
116 	 * @param functor   string name for the structure term.
117 	 * @param arguments prolog term arguments for the structure term.
118 	 * @return the current builder instance after append the term in the clause
119 	 *         body.
120 	 * @since 1.0
121 	 */
122 	public PrologClauseBuilder neck(String functor, PrologTerm... arguments);
123 
124 	/**
125 	 * Append to the clause builder the first term in the clause body. Return the
126 	 * current builder instance after append the term in the clause body.
127 	 * 
128 	 * @param term term to be append in the clause body.
129 	 * @return the current builder instance after append the term in the clause
130 	 *         body.
131 	 * @since 1.0
132 	 */
133 	public PrologClauseBuilder neck(PrologTerm term);
134 
135 	/**
136 	 * Append to the clause builder other term in the clause body in conjunctive
137 	 * mode. The term passed to the builder for this case is an expression created
138 	 * using the given operator and operands. Return the current builder instance
139 	 * after append the term in the clause body.
140 	 * 
141 	 * @param operator expression operator.
142 	 * @param left     left hand prolog term operand.
143 	 * @param right    right hand prolog term operand.
144 	 * @return the current builder instance after append the term in the clause
145 	 *         body.
146 	 * @since 1.0
147 	 */
148 	public PrologClauseBuilder comma(PrologTerm left, String operator, PrologTerm right);
149 
150 	/**
151 	 * Append to the clause builder other term in the clause body in conjunctive
152 	 * mode. The term passed to the builder for this case is an structure created
153 	 * using the given functor and arguments array. Return the current builder
154 	 * instance after append the term in the clause body.
155 	 * 
156 	 * @param functor   string name for the structure term.
157 	 * @param arguments prolog term arguments for the structure term.
158 	 * @return the current builder instance after append the term in the clause
159 	 *         body.
160 	 * @since 1.0
161 	 */
162 	public PrologClauseBuilder comma(String functor, PrologTerm... arguments);
163 
164 	/**
165 	 * Append to the clause builder other term in the clause body in conjunctive
166 	 * mode. Return the current builder instance after append the term in the clause
167 	 * body.
168 	 * 
169 	 * @param term term to be query.
170 	 * @return the current builder instance after append the term in the clause
171 	 *         body.
172 	 * @since 1.0
173 	 */
174 	public PrologClauseBuilder comma(PrologTerm term);
175 
176 	/**
177 	 * Get the clause in string format.
178 	 * 
179 	 * @return string clause.
180 	 * @since 1.0
181 	 */
182 	public String getClauseString();
183 
184 	/**
185 	 * Check if the clause in the main memory program unify with the current clause
186 	 * and return true. If the clause not exist in main memory program or exist but
187 	 * not unify with the given clause false value is returned.
188 	 * 
189 	 * @return true if the clause in the main memory program unify with the current
190 	 *         clause, false otherwise.
191 	 * @since 1.0
192 	 */
193 	public boolean clause();
194 
195 	/**
196 	 * Add the current clause in the main memory program if the clause non exist. If
197 	 * the clause exist, will not overwritten and the clause will not added. The
198 	 * added clause will be the first clause for a clause lot with the same
199 	 * predicate indicator (PI).
200 	 * 
201 	 * @since 1.0
202 	 */
203 	public void asserta();
204 
205 	/**
206 	 * Add the clause in the main memory program if the clause non exist. If the
207 	 * clause exist, will not overwritten and the clause will not added. The added
208 	 * clause will be the last clause for a clause lot with the same predicate
209 	 * indicator (PI).
210 	 * 
211 	 * @since 1.0
212 	 */
213 	public void assertz();
214 
215 	/**
216 	 * Remove the clause in the main memory program if the clause exist.
217 	 * 
218 	 * @since 1.0
219 	 */
220 	public void retract();
221 
222 }