1 /*-
2 * #%L
3 * prolobjectlink-jpi
4 * %%
5 * Copyright (C) 2012 - 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.List;
29 import java.util.Map;
30
31 /**
32 * Converter for convert {@code PrologTerm} to the equivalent Java object taking
33 * like reference the following equivalence table.
34 *
35 * <table BORDER > <caption>Equivalence table</caption>
36 * <tr>
37 * <td ALIGN=CENTER><b>Java Object</b></td>
38 * <td ALIGN=CENTER><b>Prolog Term</b></td>
39 * </tr>
40 * <tr>
41 * <td><code>null</code></td>
42 * <td>{@link PrologProvider#prologNil()}</td>
43 * </tr>
44 * <tr>
45 * <td>{@link String}</td>
46 * <td>{@link PrologAtom}</td>
47 * </tr>
48 * <tr>
49 * <td>{@link Boolean#FALSE}</td>
50 * <td>{@link PrologProvider#prologFalse()}</td>
51 * </tr>
52 * <tr>
53 * <td>{@link Boolean#TRUE}</td>
54 * <td>{@link PrologProvider#prologTrue()}</td>
55 * </tr>
56 * <tr>
57 * <td>{@link Integer}</td>
58 * <td>{@link PrologInteger}</td>
59 * </tr>
60 * <tr>
61 * <td>{@link Float}</td>
62 * <td>{@link PrologFloat}</td>
63 * </tr>
64 * <tr>
65 * <td>{@link Double}</td>
66 * <td>{@link PrologDouble}</td>
67 * </tr>
68 * <tr>
69 * <td>{@link Long}</td>
70 * <td>{@link PrologLong}</td>
71 * </tr>
72 * <tr>
73 * <td>{@link Object}[]</td>
74 * <td>{@link PrologList}</td>
75 * </tr>
76 * </table>
77 *
78 * There are special cases of Java object that can be converted to Prolog
79 * equivalent but the inverse case it's not possible. They are {@link Byte},
80 * {@link Character}, {@link Short} that can be converted to
81 * {@link PrologInteger} using your numeric value. The main problems is that
82 * after {@link PrologInteger} conversion this value will be converted in
83 * {@link Integer}.
84 *
85 * @author Jose Zalacain
86 * @since 1.0
87 */
88 public interface PrologJavaConverter {
89
90 /**
91 * Create an equivalent Java object map list using the given Prolog terms map
92 * array. The resulting map list contains maps that have the same string key and
93 * the value for every key is a conversion from Prolog term to Java object.
94 *
95 * @param maps Prolog terms map list to be converted in Java objects map list.
96 * @return an equivalent Java objects map array using the given Prolog terms map
97 * list.
98 * @since 1.0
99 */
100 public List<Map<String, Object>> toObjectMaps(Map<String, PrologTerm>[] maps);
101
102 /**
103 * Create an equivalent Java object map using the given Prolog terms map. The
104 * resulting map have the same string key and the value for every key is a
105 * conversion from Prolog term to Java object.
106 *
107 * @param map Prolog terms map representation to be converted
108 * @return an equivalent Java object map using the given Prolog terms map.
109 * @since 1.0
110 */
111 public Map<String, Object> toObjectMap(Map<String, PrologTerm> map);
112
113 /**
114 * Create a Java objects list from given Prolog term array.
115 *
116 * @param terms Prolog term array to be converted to Java objects array.
117 * @return Java objects list representation from given Prolog term array.
118 * @since 1.0
119 */
120 public List<Object> toObjectList(PrologTerm[] terms);
121
122 /**
123 * Create an equivalent list of objects lists using the given Prolog terms
124 * matrix.
125 *
126 * @param terms Prolog terms matrix to be converted
127 * @return an equivalent list of objects lists using the given Prolog terms
128 * matrix representation.
129 * @since 1.0
130 */
131 public List<List<Object>> toObjectLists(PrologTerm[][] terms);
132
133 /**
134 * Create a Java objects array from given Prolog term array.
135 *
136 * @param terms Prolog term array to be converted to Java objects array.
137 * @return Java objects array representation from given Prolog term array.
138 * @since 1.0
139 */
140 public Object[] toObjectsArray(PrologTerm[] terms);
141
142 /**
143 * Create an equivalent Prolog terms array using the given Java objects array.
144 *
145 * @param objects Java objects array representation to be converted
146 * @return an equivalent Prolog terms array using the given Java objects array.
147 * @since 1.0
148 */
149 public PrologTerm[] toTermsArray(Object[] objects);
150
151 /**
152 * Create a Java object from given Prolog term.
153 *
154 * @param term Prolog term to be converted to Java object.
155 * @return a Java object from given Prolog term.
156 * @since 1.0
157 */
158 public Object toObject(PrologTerm term);
159
160 /**
161 * Create an equivalent Prolog term using the given Java object.
162 *
163 * @param object Java object to be converted
164 * @return an equivalent Prolog term using the given Java object.
165 * @since 1.0
166 */
167 public PrologTerm toTerm(Object object);
168
169 /**
170 * Check if the current functor have quotes at the start and end of the given
171 * functor. Return true if the current functor is enclosing between functors or
172 * false in other case.
173 *
174 * @param functor string functor to be checked
175 * @return true if the current functor is enclosing between functors or false in
176 * other case.
177 * @since 1.0
178 */
179 public boolean containQuotes(String functor);
180
181 /**
182 * Remove functor quotes if they are present. If the string functor don't have
183 * quotes, this method return the functor itself.
184 *
185 * @param functor string functor to remove quotes if they are present.
186 * @return functor without quotes if they are present. The functor itself if
187 * quotes are not present.
188 * @since 1.0
189 */
190 public String removeQuotes(String functor);
191
192 }