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 import java.util.Map;
29
30 /**
31 * Prolog Provider is the class to interact with all prolog components (data
32 * types, constants, logger, parser, converter and engine). Allow create data
33 * types like atoms, numbers, lists, structures and variable terms.
34 *
35 * Allow interact with the under-lying prolog engine to realize inferences
36 * operations. Other used components are the prolog parser to parse prolog terms
37 * in string form. The Prolog Provider offer a prolog system logger to report
38 * every errors or exceptions.
39 *
40 * @author Jose Zalacain
41 * @since 1.0
42 */
43 public interface PrologProvider extends PrologParser {
44
45 /**
46 * True if wrapped engine implement ISO Prolog and false in other case
47 *
48 * @return true if wrapped engine implement ISO Prolog and false in other case
49 * @since 1.0
50 */
51 public boolean isCompliant();
52
53 /**
54 * Get the prolog nil term representing the null data type for prolog data type
55 * system.
56 *
57 * @return prolog nil term.
58 * @since 1.0
59 */
60 public PrologTerm prologNil();
61
62 /**
63 * Get the prolog term that represent the prolog cut built-in.
64 *
65 * @return prolog cut term
66 * @since 1.0
67 */
68 public PrologTerm prologCut();
69
70 /**
71 * Get the prolog fail term that represent fail built-in.
72 *
73 * @return prolog fail term
74 * @since 1.0
75 */
76 public PrologTerm prologFail();
77
78 /**
79 * Get the prolog true term that represent true built-in.
80 *
81 * @return prolog true term
82 * @since 1.0
83 */
84 public PrologTerm prologTrue();
85
86 /**
87 * Get the prolog false term that represent false built-in.
88 *
89 * @return prolog false term
90 * @since 1.0
91 */
92 public PrologTerm prologFalse();
93
94 /**
95 * Get the prolog empty list term.
96 *
97 * @return prolog empty list term.
98 * @since 1.0
99 */
100 public PrologTerm prologEmpty();
101
102 /**
103 * Get the prolog term representing the directive use by under-laying prolog
104 * implementation for file inclusion. This directive is implementation
105 * depending. Prolog engines use at least one of
106 * (<tt>include/1 or consult/1 or ensure_loaded/1</tt>). A string file path is
107 * used to create the directive with the file to be include at runtime. In other
108 * words invoke this method for <tt>foo.pl</tt> return
109 * <tt>:-consult('foo.pl')</tt> prolog term if the under-laying prolog
110 * implementation use consult/1 directive for file inclusion.
111 *
112 * @param file file path to be include
113 * @return prolog term representing include directive
114 * @since 1.0
115 */
116 public PrologTerm prologInclude(String file);
117
118 /**
119 * Create a new prolog engine instance ready to be operate. The created engine
120 * is clause empty and only have the defaults supported built-ins.
121 *
122 * @return new prolog engine instance
123 * @since 1.0
124 */
125 public PrologEngine newEngine();
126
127 /**
128 * Create a new prolog engine instance ready to be operate. The created engine
129 * consult the given file loading the clauses present in this file and the
130 * defaults supported built-ins. Is equivalent to
131 * {@code newEngine().consult(file);}
132 *
133 * @param file file path to be consulted
134 * @return new prolog engine instance
135 * @since 1.0
136 */
137 public PrologEngine newEngine(String file);
138
139 /**
140 * Create a prolog atom term setting like atom value the given string.
141 *
142 * @param functor string value for the atom
143 * @return a prolog atom term
144 * @since 1.0
145 */
146 public PrologAtom newAtom(String functor);
147
148 /**
149 * Create a prolog float number instance with 0.0 value.
150 *
151 * @return prolog float number with 0.0 value.
152 * @since 1.0
153 */
154 public PrologFloat newFloat();
155
156 /**
157 * Create a prolog float number instance with 0.0 value.
158 *
159 * @param value numeric value
160 * @return prolog float number with 0.0 value.
161 * @since 1.0
162 */
163 public PrologFloat newFloat(Number value);
164
165 /**
166 * Create a prolog double number instance with 0.0 value.
167 *
168 * @return prolog double number with 0.0 value.
169 * @since 1.0
170 */
171 public PrologDouble newDouble();
172
173 /**
174 * Create a prolog double number instance with the given value.
175 *
176 * @param value numeric value
177 * @return prolog double number
178 * @since 1.0
179 */
180 public PrologDouble newDouble(Number value);
181
182 /**
183 * Create a prolog integer number instance with 0 value.
184 *
185 * @return prolog integer number with 0 value.
186 * @since 1.0
187 */
188 public PrologInteger newInteger();
189
190 /**
191 * Create a prolog integer number instance with the given value.
192 *
193 * @param value numeric value
194 * @return prolog integer number
195 * @since 1.0
196 */
197 public PrologInteger newInteger(Number value);
198
199 /**
200 * Create a prolog long number instance with 0 value.
201 *
202 * @return prolog long number with 0 value.
203 * @since 1.0
204 */
205 public PrologLong newLong();
206
207 /**
208 * Create a prolog long number instance with the given value.
209 *
210 * @param value numeric value
211 * @return prolog long number
212 * @since 1.0
213 */
214 public PrologLong newLong(Number value);
215
216 /**
217 * Create an anonymous variable instance with associated index. Index is a non
218 * negative integer that represent the variable position of the Structure where
219 * the variable is first time declared.
220 *
221 * @param position Position of its Structure where the variable is first time
222 * declared.
223 * @return An anonymous variable instance with associated index.
224 * @throws IllegalArgumentException if position is a negative number
225 * @since 1.0
226 */
227 public PrologVariable newVariable(int position);
228
229 /**
230 * Create an named variable instance with associated index. Index is a non
231 * negative integer that represent the variable position of the Structure where
232 * the variable is first time declared.
233 *
234 * @param name variable name (upper case beginning)
235 *
236 * @param position Position of its Structure where the variable is first time
237 * declared.
238 * @return A named variable instance with associated index.
239 * @throws IllegalArgumentException if position is a negative number
240 * @since 1.0
241 */
242 public PrologVariable newVariable(String name, int position);
243
244 /**
245 * Create an empty prolog list term. The created prolog list is equivalent to
246 * empty list term if the returned instance is not the prolog empty list itself.
247 *
248 * @return an empty prolog list term
249 * @since 1.0
250 */
251 public PrologList newList();
252
253 /**
254 * Create a prolog list with one term item.
255 *
256 * @param head term item to be include in the prolog list
257 * @return prolog list with one term item.
258 * @since 1.0
259 */
260 public PrologList newList(PrologTerm head);
261
262 /**
263 * Create a prolog list from prolog terms arguments array and the tail item is
264 * an empty list.
265 *
266 * @param arguments prolog terms arguments array.
267 * @return a prolog list contained all terms in the prolog term array.
268 * @since 1.0
269 */
270 public PrologList newList(PrologTerm[] arguments);
271
272 /**
273 * Create a prolog list with two terms items [head | tail].
274 *
275 * @param head term item to be include like head in the prolog list.
276 * @param tail term item to be include like tail in the prolog list.
277 * @return prolog list with two terms items [head | tail].
278 * @since 1.0
279 */
280 public PrologList newList(PrologTerm head, PrologTerm tail);
281
282 /**
283 * Create a prolog list from prolog terms arguments array and the tail item is
284 * the given prolog term.
285 *
286 * @param arguments prolog terms arguments array.
287 * @param tail prolog term to be the tail item.
288 * @return a prolog list contained all terms in the prolog term array and tail
289 * item the specific term.
290 * @since 1.0
291 */
292 public PrologList newList(PrologTerm[] arguments, PrologTerm tail);
293
294 /**
295 * Create a prolog list with one object item.
296 *
297 * @param head object item to be include in the prolog list
298 * @return prolog list with one term item.
299 * @since 1.0
300 */
301 public PrologList newList(Object head);
302
303 /**
304 * Create a prolog list from java objects arguments array and the tail item is
305 * an empty list.
306 *
307 * @param arguments java objects arguments array.
308 * @return a prolog list contained all terms in the prolog term array.
309 * @since 1.0
310 */
311 public PrologList newList(Object[] arguments);
312
313 /**
314 * Create a prolog list with two java objects items [head | tail].
315 *
316 * @param head object item to be include like head in the prolog list.
317 * @param tail object item to be include like tail in the prolog list.
318 * @return prolog list with two terms items [head | tail].
319 * @since 1.0
320 */
321 public PrologList newList(Object head, Object tail);
322
323 /**
324 * Create a prolog list from java objects arguments array and the tail item is
325 * the given java object.
326 *
327 * @param arguments java objects arguments array.
328 * @param tail java object to be the tail item.
329 * @return a prolog list contained all terms in the prolog term array and tail
330 * item the specific term.
331 * @since 1.0
332 */
333 public PrologList newList(Object[] arguments, Object tail);
334
335 /**
336 * Create a prolog structure with the functor (structure name) and prolog terms
337 * arguments array.
338 *
339 * <pre>
340 * PrologAtom bob = provider.newAtom("bob");
341 * PrologAtom tom = provider.newAtom("tom");
342 * PrologStructure parent = provider.newStructure("parent", tom, bob);
343 * System.out.println(parent);
344 * </pre>
345 *
346 * @param functor structure name.
347 * @param arguments prolog terms arguments array.
348 * @return prolog structure instance with the given functor and arguments.
349 * @since 1.0
350 */
351 public PrologStructure newStructure(String functor, PrologTerm... arguments);
352
353 /**
354 * Create a prolog structure with the functor (structure name) and java objects
355 * arguments array. The java objects arguments array is converter to prolog
356 * terms arguments array.
357 *
358 * <pre>
359 * PrologStructure parent = provider.newStructure("parent", "tom", "bob");
360 * System.out.println(parent);
361 * </pre>
362 *
363 * @param functor structure name.
364 * @param arguments java objects arguments array.
365 * @return prolog structure instance with the given functor and arguments.
366 * @since 1.0
367 */
368 public PrologTerm newStructure(String functor, Object... arguments);
369
370 /**
371 * Create a prolog structure that represent an expression defined by your left
372 * and right operands separated by infix operator. The structure instance have
373 * like functor the expression operator and have two operands arguments terms.
374 * In other words the indicator for the resulting instance term is
375 * <tt>operator/2</tt>. The term creation not check operator definition and for
376 * this reason during inference process if the operator is not a supported
377 * built-in or define by <tt>op/3</tt> the inference fail.
378 *
379 * <pre>
380 * PrologVariable x = provider.newVariable("X", 0);
381 * PrologDouble pi = provider.newDouble(Math.PI);
382 * PrologStructure plusExp = provider.newStructure(x, "+", pi);
383 * System.out.println(plusExp);
384 * </pre>
385 *
386 * @param left left hand operand
387 * @param operator infix operand
388 * @param right right hand operand
389 * @return a prolog structure that represent an expression
390 * @since 1.0
391 */
392 public PrologTerm newStructure(PrologTerm left, String operator, PrologTerm right);
393
394 /**
395 * Create a prolog structure that represent an expression defined by your left
396 * and right operands separated by infix operator. The structure instance have
397 * like functor the expression operator and have two operands arguments terms.
398 * In other words the indicator for the resulting instance term is
399 * <tt>operator/2</tt>. The term creation not check operator definition and for
400 * this reason during inference process if the operator is not a supported
401 * built-in or define by <tt>op/3</tt> the inference fail.
402 *
403 * <pre>
404 * PrologVariable x = provider.newVariable("X", 0);
405 * PrologDouble pi = provider.newDouble(Math.PI);
406 * PrologStructure plusExp = provider.newStructure(x, "+", pi);
407 * System.out.println(plusExp);
408 * </pre>
409 *
410 * @param left left hand operand
411 * @param operator infix operand
412 * @param right right hand operand
413 * @return a prolog structure that represent an expression
414 * @since 1.0
415 */
416 public PrologTerm newStructure(Object left, String operator, Object right);
417
418 /**
419 * Constructs a new {@link PrologMap} with the same mappings as the specified
420 * {@link Map} of {@link PrologTerm} keys and values. The {@link PrologMap} is
421 * created with an initial capacity sufficient to hold the mappings in the
422 * specified {@link Map}. The resulting term is an implementation of {@link Map}
423 * and {@link PrologTerm}.
424 *
425 * @param map the map whose mappings are to be placed in this map
426 * @return a PrologMap with the given maps entries.
427 * @since 1.1
428 */
429 public PrologTerm newMap(Map<PrologTerm, PrologTerm> map);
430
431 /**
432 * Create a new PrologEntry using key-value pair of PrologTerm type. The
433 * resulting term is an implementation of {@link PrologEntry} and
434 * {@link PrologTerm}.
435 *
436 * @param key key of the entry
437 * @param value value of the entry
438 * @return new PrologEntry term
439 * @since 1.1
440 */
441 abstract PrologTerm newEntry(PrologTerm key, PrologTerm value);
442
443 /**
444 * Create a new PrologEntry using key-value pair of Java object type.The given
445 * objects are converted to PrologTerm before entry creation. The resulting term
446 * is an implementation of {@link PrologEntry} and {@link PrologTerm}.
447 *
448 * @param key key of the entry
449 * @param value value of the entry
450 * @return new PrologEntry term
451 * @since 1.1
452 */
453 abstract PrologTerm newEntry(Object key, Object value);
454
455 /**
456 * Constructs an empty {@link PrologMap} with the specified initial capacity.
457 * The resulting term is an implementation of {@link Map} and
458 * {@link PrologTerm}.
459 *
460 * @param initialCapacity the initial capacity.
461 * @return an empty PrologMap
462 * @since 1.1
463 */
464 public PrologTerm newMap(int initialCapacity);
465
466 /**
467 * Constructs an empty {@link PrologMap} with the default initial capacity (16).
468 * The resulting term is an implementation of {@link Map} and
469 * {@link PrologTerm}.
470 *
471 * @return an empty PrologMap
472 * @since 1.1
473 */
474 public PrologTerm newMap();
475
476 /**
477 * Create a prolog object reference term that hold the given object. This
478 * reference term is equivalent on JPL JRef. This term is like a structure
479 * compound term that have like argument the object identification atom. The
480 * functor is the <tt>@</tt> character and the arity is 1. An example of this
481 * prolog term is e.g <tt>@(J#00000000000000425)</tt>. To access to the
482 * referenced object we need use {@link PrologTerm#getObject()}.
483 *
484 * @param object object to be referenced
485 * @return a prolog object reference term
486 * @since 1.0
487 */
488 public PrologTerm newReference(Object object);
489
490 /**
491 * Create a prolog object reference term that hold the Java false object
492 * i.e. @(false). This reference term is equivalent on JPL JFALSE.
493 *
494 * @return a prolog object reference term that hold the Java false object.
495 * @since 1.1
496 */
497 public PrologTerm falseReference();
498
499 /**
500 * Create a prolog object reference term that hold the Java true object
501 * i.e. @(true). This reference term is equivalent on JPL JTRUE.
502 *
503 * @return a prolog object reference term that hold the Java true object.
504 * @since 1.1
505 */
506 public PrologTerm trueReference();
507
508 /**
509 * Create a prolog object reference term that hold the Java null object
510 * i.e. @(null). This reference term is equivalent on JPL JNULL.
511 *
512 * @return a prolog object reference term that hold the Java null object.
513 * @since 1.1
514 */
515 public PrologTerm nullReference();
516
517 /**
518 * Create a prolog object reference term that hold the Java void object
519 * i.e. @(void). This reference term is equivalent on JPL JVOID.
520 *
521 * @return a prolog object reference term that hold the Java void object.
522 * @since 1.1
523 */
524 public PrologTerm voidReference();
525
526 /**
527 * Casts a PrologTerm to the class or interface represented by this
528 * {@code Class} object.
529 *
530 * @param term the object to be cast
531 * @return the PrologTerm after casting, or null if term is null
532 *
533 * @throws ClassCastException if the object is not null and is not assignable to
534 * the type T.
535 * @since 1.1
536 */
537 public <T extends PrologTerm> T cast(PrologTerm term);
538
539 /**
540 * Get a Java to Prolog converter instance to map the abstract prolog data types
541 * to Java types.
542 *
543 * @return Java to Prolog converter instance.
544 * @since 1.0
545 */
546 public PrologJavaConverter getJavaConverter();
547
548 /**
549 * Get a prolog converter instance to map the abstract prolog data types to
550 * under-laying prolog implementations data types.
551 *
552 * @param <K> under-laying prolog data types
553 * @return prolog converter instance
554 * @since 1.0
555 */
556 public <K> PrologConverter<K> getConverter();
557
558 /**
559 * Get a prolog parser instance to parser the strings with prolog syntax.
560 *
561 * @return prolog parser instance
562 * @since 1.0
563 */
564 public PrologParser getParser();
565
566 /**
567 * Get the prolog system logger instance to report any errors or exceptions
568 *
569 * @return prolog system logger instance
570 * @since 1.0
571 */
572 public PrologLogger getLogger();
573
574 /**
575 * Version of the wrapped engine.
576 *
577 * @return String version of the wrapped engine.
578 * @since 1.0
579 */
580 public String getVersion();
581
582 /**
583 * Name of the wrapped engine.
584 *
585 * @return String name of the wrapped engine.
586 * @since 1.0
587 */
588 public String getName();
589
590 }