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 * Represent prolog list compound term. List are an special compound term that
31 * have like functor a dot (.) and arity equals 2. Prolog list are recursively
32 * defined. The first item in the list is referred like list head and the second
33 * item list tail. The list tail can be another list that contains head and
34 * tail. An special list case is the empty list denoted by no items brackets
35 * ([]). The arity for this empty list is zero.
36 * </p>
37 * <p>
38 * The Prolog Provider is the mechanism to create a new Prolog structures
39 * invoking {@link PrologProvider#newList()} for empty list or
40 * {@link PrologProvider#newList(PrologTerm)} for one item list or
41 * {@link PrologProvider#newList(PrologTerm[])} for many items.
42 * </p>
43 * <p>
44 * Two list are equals if and only if are list and have equals arguments. List
45 * terms unify only with the same arguments list, with free variable or with
46 * lists where your arguments unify.
47 * </p>
48 *
49 * <pre>
50 * PrologList empty = provider.newList();
51 * </pre>
52 *
53 * <pre>
54 * PrologInteger one = provider.newInteger(1);
55 * PrologInteger two = provider.newInteger(2);
56 * PrologInteger three = provider.newInteger(3);
57 * PrologList list = provider.newList(new PrologTerm[] { one, two, three });
58 * </pre>
59 *
60 * PrologList implement {@link Iterable} interface to be used in for each
61 * sentence iterating over every element present in the list.
62 *
63 * <pre>
64 * for (PrologTerm prologTerm : list) {
65 * System.out.println(prologTerm);
66 * }
67 * </pre>
68 *
69 * <pre>
70 * Iterator<PrologTerm> i = list.iterator();
71 * while (i.hasNext()) {
72 * PrologTerm prologTerm = i.next();
73 * System.out.println(prologTerm);
74 * }
75 * </pre>
76 *
77 * <pre>
78 * for (Iterator<PrologTerm> i = list.iterator(); i.hasNext();) {
79 * PrologTerm prologTerm = i.next();
80 * System.out.println(prologTerm);
81 * }
82 * </pre>
83 *
84 * @author Jose Zalacain
85 * @since 1.0
86 */
87 public interface PrologList extends PrologTerm, Iterable<PrologTerm> {
88
89 /**
90 * Return the head term of the current list if the current list have at least
91 * one element. If the list is an instance of {@link Prolog} empty list term,
92 * the result for invoke get head is the empty list term properly.
93 *
94 * @return the head term of the current list if the current list have at least
95 * one element.
96 * @since 1.0
97 */
98 public PrologTerm getHead();
99
100 /**
101 * Return the tail term of the current list if the current list have tail. If
102 * the list is a sole term list, the result for invoke get tail is the empty
103 * list term.
104 *
105 * @return the tail term of the current list if the current list have tail.
106 * @since 1.0
107 */
108 public PrologTerm getTail();
109
110 /**
111 * Return true if the current list don't have any elements, false in other case.
112 * More formally {@code return #size()==0}
113 *
114 * @return true if the current list don't have any elements, false in other
115 * case.
116 * @since 1.0
117 */
118 public boolean isEmpty();
119
120 /**
121 * Clear the current list removing all contained prolog term. After clear the
122 * list the resulting list is equal and unify with empty list.
123 *
124 * @since 1.0
125 */
126 public void clear();
127
128 /**
129 * Returns the number of elements in this list.
130 *
131 * @return the number of elements in this list.
132 * @since 1.0
133 */
134 public int size();
135
136 }