Built-In List

Built-in predicates currently implemented:

=/2 \=/2 ==/2 \==/2 >/2 </2 >=/2 <=/2 =:=/2 =\=/2 =../2 \+/1 !/0 ^/2 ;/2 abolish/1 abort/0 append/3 arg/3 assert/1 asserta/1

atom/1 atomic/1 call/1 callable/1 compound/1 cons/1 consult/1 date/3 export/1 extern/1 fail/0 findall/3 float/1 functor/1 functor/3 garbage_collect/0 get/1 integer/1 import/1 is/2 length/2

listing/0 lst/1 member/2 member/3 module/1 ms/2 nil/1 nl/0 nonvar/1 not/1 notify/2 number/1 phrase/2 phrase/3 repeat/0 repeat/1 retract/1 retractall/1 reverse/2 reconsult/1 sort/2

statistics/0 time/1 time/4 unify/2,  var/1 ver/0 wdialog/3 winputbox/2 wmsgbox/1 write/1 xcall/3 xlisting/0

=/2 : term1 = term2

Succeeds if term1 and term2 unify.
The following example tests that two given lists can be unified, and binds the variables as required:
   query: [1,X,Y] = [Z,2,3].
   yes
   X = 2 ,
   Y = 3 ,
   Z = 1

\=/2 : term1 \= term2

Succeeds if term1 does not unify with term2, and never binds any variables.
The following call succeeds, because the two specified terms do not unify:
    query: foo(bar) \= foo(sux).
    yes
The following call fails, because although the given terms are different, they can unify:
    query:  foo(bar) \= foo(X).
    no
The \=/2 predicate is the exact opposite of =/2, and is effectively defined as:
   X \= Y :-
       \+ X = Y.

==/2 : term1 == term2

Succeeds if term1 is identical to term2. No variables in term1 and term2 are bound as a result of the testing.
The following call succeeds because both given terms are identical:
   query: foo(Q,W) == foo(Q,W).
   Q = ? ,
   W = ?
The following call fails, because the terms are not identical:
   query: foo(Q,a) == foo(Q,W).
   no

\==/2 : term1 \== term2

Succeeds if term1 is not identical to term2
The following call succeeds, because the two specified terms are different from each other:
   query: foo(bar) \== foo(sux).
   yes
The following call also succeeds, because even though the two terms could unify, nonetheless they are different:
   query: foo(bar) \== foo(X). <enter>
   X = ?
The \==/2 predicate is the exact opposite of ==/2, and is effectively defined as:
   X \== Y :-
        \+ X == Y.

>/2 : exp1 > exp2

Succeeds if the arithmetic expression exp1 is greater than exp2.
An arithmetic expression can be a number or an arithmetic function.

</2 : exp1 < exp2

Succeeds if the arithmetic expression exp1 is less than exp2.
An arithmetic expression can be a number or an arithmetic function.

>=/2 : exp1 >= exp2

Succeeds if the arithmetic expression exp1 is greater than or equal to exp2.
An arithmetic expression can be a number or an arithmetic function.

<=/2 : exp1 <= exp2

Succeeds if the arithmetic expression exp1 is less than or equal to exp2.
An arithmetic expression can be a number or an arithmetic function.

=:=/2 : exp1 =:= exp2

Succeeds if the arithmetic expression exp1 evaluates to exp2.
An arithmetic expression can be a number or an arithmetic function.

=\=/2 : exp1 =:= exp2

Succeeds if the arithmetic expression exp1 doesn't evaluates to exp2.
An arithmetic expression can be a number or an arithmetic function.

=../2 : Term =.. List

List is a list whose first element is the principal functor of the Term, and whose tail is the list of arguments of Term. 
If Term is an uninstantiated variable, then List must be instantiated to a list of determinate length. A compound term will be constructed from the list. The functor of the term will be the head of the list, while the arguments of the term will be the tail of the list. If Term is not a variable, then the corresponding list is constructed and unified with List.

The following call creates a compound term from the given list:
JIP:- X =.. [likes,brian,prolog]. <enter>
X = likes(brian,prolog)

When a single-element list is provided, an atomic term is returned:
JIP:- X =.. [123]. <enter>
X = 123

You can also convert a compound term into a list:
JIP:- foo(bar) =.. L. <enter>
L = [foo,bar]

The conversion can work in both directions at once, filling in any variables automatically:
JIP:- foo(123,A,789,bar) =.. [X,123,456|Y]. <enter>
A = 456 ,
X = foo ,
Y = [789,bar]

The =../2 predicate is usually called "univ", and is widely used in meta-programming, where terms representing calls are pulled apart, modified as lists, and rebuilt into terms which are then executed.

\+/1 : \+ call

Logical not. Succeeds if call fails.

see also: not/1

!/0

The predicate !/0 always succeeds, but it has the important side effect of removing pending choice points within the current clause and relation. Its purpose is to enable programs to commit to solutions, and to retrieve space that would otherwise be tied up in unnecessary choice points.

^/2 : X ^ Goal.

Existential quantification. ^/2 means "there exists an X such that Goal is true". This predicate is not really programmed into ^/2 at all: normally this predicate simply calls the given Goal, completely ignoring the value of X. 

;/2 : Either ; Or.

Disjunction. This predicate succeeds if either or both of its goals, Either and Or, are succeed. Either call may itself be a conjunction or disjunction, or a simple goal.

abolish/1 : abolish(Pred).

Delete all occurences of the predicate Pred. Pred must be in the format name/arity.

Ex. abolish(foo/1)

abort/0 : abort.

abort the current program

Abandons the program that is currently being executed and return abruptly to the top level of Prolog.
Because the abort/0 predicate directly resets all internal stacks and forces JIP to stop the execution , it is normally only used to abandon execution of a query when an error has occurred for which there is no other method of recovery.

append/3 : append(First, Second, Whole)

if First and Second are instantiated, the Second list is appended to the end of the First list to give the Whole list

append([a,b,c,d], [1,2,3,4], Whole ).
Whole = [a,b,c,d,1,2,3,4].

If Whole is instantiated, the Whole list is split at an arbitrary place to form two new sub-lists First and Second. Alternative solutions will be provided on backtracking.

append(First, Second, [a,b,c,d,1,2,3,4] ).
First = []
Second = [a,b,c,d,1,2,3,4]

<NextSol>
First = [a]
Second = [b,c,d,1,2,3,4].

If First and Whole are instantiated and the Whole list starts with the First list, then the remainder of the Whole list is returned as Second.

append([a,b,c,d], Second, [a,b,c,d,1,2,3,4] ).
Second = [1,2,3,4].

If Second and Whole are instantiated and the Whole list ends with the Second list then the beginning of the Whole list is returned as First.

append(First, [1,2,3,4], [a,b,c,d,1,2,3,4] ).
First = [a,b,c,d].

If First, Second and Whole are instantiated, then test that the Whole list begins with the First list and that the remainder of the Whole list is the Second list.

append([a,b,c,d], [1,2,3,4], [a,b,c,d,1,2,3,4] ).
yes.

arg/3 : arg(N, Term, Arg)

Find the Nth argument of a term.
Unifies Arg with the Nth argument of Term. N must be a positive integer, and Term must be a compound term (or a list). The arguments are numbered 1 upwards.

assert/1 : assert(clause)

add clause to the database at the end of the sequence of clauses defining its predicate name.
clause maybe a fact:
  atom
  atom(arg1, arg2, ...)
or a rule (in that case it must be enclosed in parentheses):
   (atom:-term1,term2,...)
   (atom(arg1, arg2, ...):-term1, term2, ...)

- You cannot assert a clause defined as built-in predicate.

see also: asserta/1

asserta/1 : asserta(clause)

add clause to the database at the beginning of the sequence of clauses defining its predicate name.
clause maybe a fact:
  atom
  atom(arg1, arg2, ...)
or a rule (in that case it must be enclosed in parentheses):
   (atom:-term1,term2, ...)
   (atom(arg1, arg2, ...):-term1, term2, ...)

- You cannot assert a clause defined as built-in predicate.

see also: assert/1

atom/1 : atom(Atom)

Succeeds if Atom is currently instantiated to an atom.

atomic/1 : atomic(Term)

Succeeds if Term is currently instantiated to an integer, float, atom or string. It will fail if term is an unbounded variable or a compound term.

call/1 : call(Call)

Calls the goal Call. Succeeds if Call succeeds, and fails otherwise.

callable/1 : collable(Term)

Succeeds if Term is currently instantiated to a term that can be used as a query (i.e. a functor); otherwise it fails.

compound/1 : compound(Term)

Succeeds if Term is currently instantiated to a compund term. It wil fail if Term is an atom, integer, float, string or an unbounded variable.

consult/1 : consult(filename) 
reconsult/1 : reconsult(filename)

consult/1 loads the source file specified by filename. 
If filename does not specify a file extension then '.PL' is assumed.
   query: consult('foo.pl').
   query: consult(foo).

If filename specify a full path name the following apply:
   query: consult('d:\\prolog\\foo.pl').  (double backslash to separate directory)
   query: consult('d:/prolog/foo.pl').    (single slash to separate directory)
   query: consult('d:/prolog/foo').       (extension .pl is assumed)

reconsult/1 is identical to consult. It is defined only to compatibility with other prolog interpreters

cons/1 : cons(Term)

Succeeds if Term is currently instantiated to a list.

date/3 : date3(Day, Month, Year)

Succeeds if Day, Month and Year are uninstantiated and instatiates them to the current date.

export/1 : :-export(predicate).

Declares predicate as exported. It would be used only in a directive (see the section "Directives")  to export a predicate defined in the current module. If it is used in the body of a clause it does nothing when called.

see: module/1, import/1

extern/3 : extern(Pred, DBClassName, DBAttributes).

Declares Pred as an external database of clauses (i.e a database of clauses not stored in the prolog database but in an external device such as JDBC database, text database and so on). 
Pred must be in the format name/arity, DBClassName must be derived from from JIPClausesDatabase and is the class that implements the functionality to manage the external database of clauses (see the section "How to write an external database of clauses"), DBAttributes specifies some attributes needed to the database (such as db filename, userid and password, etc.).

Es. extern(foo/3, "MyPackage.JDBCDatabase", "filename=foo.db+userid=me+pass=hello").

fail/0

Always fails. Can be used to force backtracking in a query.

findall/3 : findall(Term, Call, List)

Returns a List of all instances of Term for which Call holds. Term may be any type of Prolog term. Call must be a goal to be called. List will be unified with a list of instantiated copies of Term.
The solution list List is not sorted. Solutions appear in the list in the same order as they are found.
The solutions in List are not necessarily unique. If a different solution to Call results in the same value for Term, then a duplicate entry will appear in the list.
At the end of an evaluation, any variables in Term and Call will still be unbound.

float/1 : float(Term)

Succeeds if Term is currently instantiated to a float number

functor/1 : functor(Term)

Succeeds if Term is currently instantiated to a functor

functor/3 : functor(Term, Name, Arity)

Succeeds if Term is a functor with the specified Name and Arity.
If Term is an uninstantiated variable, then Name must be an atom and Arity must be an integer greater than 0.
If Arity is greater than 0, then Term will be bound to a compound term whose functor is the term Name, and with arity Arity. Each argument of this compound term will be a distinct unbounded variable.

garbage_collect/0 : garbage_collect.

Invokes the immediate garbage collection of the memory area.
Note: when a program is running automatic garbage collection will always be done.

get/1 : get(Atom)

Read an atom (as a string) from a prompt dialog and assign it to Atom. Atom must be an unbounded variable.

integer/1 : integer(Term)

Succeeds if Term is currently instantiated to an integer number.

import/1 : :-import(predicate).

Declares predicate as imported. It would be used only in a directive (see the section "Directives") to import a predicate defined in a module other then the current one. If it is used in the body of a clause it does nothing when called.

see: module/1, export/1

is/2 : exp1 is exp2

Evaluates the expression exp2 and unifies the result with the value of the expression exp1.
An arithmetic expression can be a number or an arithmetic function.

- if exp2 contains some uninstantiated variable is/2 fails.

length/2 : length(List, Length)

gets the length of a Prolog list
If Term is a list, Length will be unified with the number of items in the list: 

JIP:- length( [a,b,c], Length ).
Length = 3

The length/2 predicate can also be used to create a list of either a specified or infinite length.
If Term is unbound and Length is an integer, Term will be unified with a list of variables of the specified Length.

JIP:- length( Term, 3 ).
Term = [_32356,_32358,_32360]

If both Term and Length are unbound, Term will be unified, through backtracking, with a list of variables of infinite Length:

JIP:- length( Term, Length ). 
Term = [] ,
Length = 0
more (y/n)?: y

Term = [_32580] ,
Length = 1 ;
more (y/n)?: y

Term = [_32580,_34760] ,
Length = 2 ;

listing/0 : listing

Alwais succeeds showing all defined predicates.

lst/1 : lst(Term)

Succeeds if Term is currently instantiated to a list.

member/2 : member(element, list)

Succeeds if element is a member of the list list.
If element is instantiated, member/2 will check that it is a member of the list (if list is a variable, it will be bound to a list that contains element).
If element is a variable, it will be bound to the first element of list. On backtracking, it will be bound to successive elements of list.

member/3 : member(element, list, pos)

Succeeds if the element is in the list list at pos position.
If element is instantiated, member/2 will check that it is the posth member of the list (if list is a variable, it will be bound to a list that contains element). 
If element is a variable, it will be bound to the first element of list and pos is bounded to 1. On backtracking, element  will be bound to successive elements of list.

module/1 : :-module(moduleName).

Defines the name of the current module. It would be used only in a directive (see the section "Directives") to hide predicates not declared as exported or imported by export/1 or import/1 .  If it is used in the body of a clause it does nothing when called.

see: export/1, import/1 

ms/2 : ms(Call, Time)

Runs the given Call and returns the Time in milliseconds (10 ^ -3 seconds) it took the goal to run.

nil/3 : nil(Term)

Succeeds if Term is instantiated to [].

nl/0 : nl

Start a new line on the current output stream. Writes a carriage return followed by line feed to the current stream.

nonvarl/1 : nonvar(Term)

Succeeds if Term is instantiated to a non variable term.

not/1 : not predicate

Logical not. Succeeds if predicate fails and vice versa

see also: \+/1

notify/2 : notify(Exp, Term)

Notify the JIPEventListeners that an Event occurred with ID in the expression Exp and term in Term

number/1 : number(Term)

Succeeds if Term is instantiated to a float or an integer number.

phrase/2 : phrase(Phrase, List)

Invokes the currently defined grammar rules in order to parse a sequence of symbols.
It succeeds if List is a phrase of type Phrase (according to the current grammar rules).

see also: phrase/3, Grammar Rule

phrase3/ : phrase(Phrase, List, Rest)

Invokes the currently defined grammar rules in order to parse a sequence of symbols.
It succeeds when the list List starts with a phrase of type Phrase, according to the currently defined grammar rules. Rest is that part of List that is left over after you have found the phrase.

see also: phrase/2, Grammar Rule

repeat/0 : repeat

Succeeds when called and on backtracking. Any calls which textually precede the repeat in the body of a clause will never be reached on backtracking. 
repeat is defined as:

repeat.
repeat :- repeat.

repeat/1 : repeat(Number)

Succeeds when initially called, and succeeds for the given Number of times on backtracking. Any calls which precede the repeat in the body of a clause will not be reached until the repeat/1 predicate has been backtracked into the given Number of times.

retract/1 : retract(clause)

Searches for the first clause in the database that matches clause. If such a clause is found, it is deleted. Any variables in clause are bound as a result of the unification. This predicate is non-deterministic. On backtracking there is an attempt to find and delete another matching clause. This search always starts at the beginning of the list of clauses for the relation name of clause. So all clauses asserted between the retract and the redo of the call (even if added using asserta/1) are candidates for deletion on the redo. The call to retract/1 fails when there are no (more) clauses that match clause.

- You cannot retract a clause defined as built-in predicate.

retractall/1 : retractall(head)

Deletes every clause in the database whose head matches head. Variables in head are left uninstantiated by the call. On backtracking there is no attempt to redo the call, even though matching clauses may have been asserted.

- You cannot retract a clause defined as built-in predicate.

reverse/2 : reverse(List, RevList)

Checks or gets the reverse of a list.

sort/2 : sort(List, SortedList)

Each member of the list List is compared and sorted into ascending order according to the standard ordering of terms. The sorted copy of List is bound to the variable SortedList.

statistics/0 : statistics

Writes memory statistics: Total and Free memory.

time/1 : time(Milliseconds)

Succeeds if Milliseconds is an uninstatiated variable and instantiates it to current millisecond tick.

time/4 : time(Hour, Minute, Second, Milliseconds)

Succeeds if Hour, Minute, Second Milliseconds are uninstatiated variables and instantiates them to current time.

unify/2 : unify(term1, term2)

Succeeds if Term1 unify with Term2

see also: =/2

var/1 : var(Term).

Succeeds if Term is instantiated to a variable.

ver/0 : ver.

Print the JIP version.

wdialog/3 : wdialog(DialogName, Input, Output).

Creates and shows a custom Java™ dialog (derived from JIPDialog) which name is specified in DialogName, passing it the Input  term. When wdialog returns Output is instantiated to the term returned by the method getOutput() of the JIPDialog class.
The developer can create your own Dialog class and use it from JIP

Es. 
wdialog("my.package.MyDialog", "my input", Output).
Creates and shows the Dialog "my.package.MyDialog" passing it the string "my input".

See the section "How to write a custom Dialog"

Note: 
1) The Custom Dialog must implement the interface JIPDialog and must have a public constructor as follows:

public MyDialog extend Dialog implements JIPDialog
{
       MyDialog(Frame parent, JIPTerm input)
       ....
       ....
^}

2) The custom dialog should be modal, otherwise wdialog raises an error

winputbox/2 : winputbox(Message, Output).

Shows a dialog with the message contained in Message, an input field and an OK and Cancel buttons. If the user click on OK, when winputbox returns Output is instantiated to the string obtained from the text typed in the input field.

wmsgbox/1 : wmsgbox(Message).

Shows a dialog with the message contained in Message.

write/1 : write(Term)

Writes the term Term to the current output stream.

see also: nl/0, get/1

winputbox/2 : winputbox(Message, Output).

Shows a dialog with the message contained in Message, an input field and an OK and Cancel buttons. If the user click on OK, when winputbox returns Output is instantiated to the string obtained from the text typed in the input field.

xcall/3 : xcall(ClassName, Input, Output).

Create an instance of the extension class (a class that implements JIPXCall interface) specified in ClassName and calls the method invoke (JIPXCall.invoke) passing the Input argument. If the function succeeds (as returned by JIPXCall.succeeds) Output is instantiated to the term returned by the method JIPXCall.getOutput.

The developer can create your own extension class simply implementing the JIPXClass interface
See the section "How to write a custom extension class"

Es. 
xcall(("my.package.MyRandomNumGen", [1, 6], RanNum).
Creates an instance of the class "my.package.MyRandomNumGen" passing it the list [1, 6]

Note: 
1) An extension class must implement the interface JIPXCall and must have a public constructor with no parameters :

public MyXClass extend AnyClass implements JIPXCall
{
       MyXClass()
       ....
       ....
^}

xlisting/0 : xlisting

Alwais succeeds showing all built-in predicates.