Term creation and decomposition

These predicates enable a term to be assembled from its component parts, or split into its component parts, or copied.

1. `functor/3`

functor(Term, Name, Arity) is true iff:

Term is a compound term with a functor whose identifier is Name and arity Arity, or
Term is an atomic term equal to Name and Arity 0.

Templates and modes for the predicate are as follows:

functor(-nonvar, +atomic, +integer)
functor(+nonvar, ?atomic, ?integer)

1.1 Example tests

Let's start with some simple tests verifying success of failure of single goals.

alice.tuprolog.SimpleGoalFixture
goal	success()
functor(foo(a, b, c), foo, 3).	true
functor(foo(a), foo, 2).	false
functor(foo(a), fo, 1).	false
functor([_\|_], '.', 2).	true
functor([], [], 0).	true

Now we run some tests also verifying the unification for some of the variables in goals.

First of all, let's start an appropriate fixture containing an engine.

fit.ActionFixture
start	alice.tuprolog.EngineFixture

Then, ask the engine to solve a query, and check variable bindings.

fit.ActionFixture
enter	query	functor(foo(a, b, c), X, Y).
check	hasSolution	true
enter	variable	X
check	binding	foo
enter	variable	Y
check	binding	3
enter	query	functor(X, foo, 3).
check	hasSolution	true
enter	variable	X
check	binding	foo(_, _, _)
enter	query	functor(X, foo, 0).
check	hasSolution	true
enter	variable	X
check	binding	foo
enter	query	functor(mats(A, B), A, B).
check	hasSolution	true
enter	variable	A
check	binding	mats
enter	variable	B
check	binding	2
enter	query	functor(1, X, Y).
check	hasSolution	true
enter	variable	X
check	binding	1
enter	variable	Y
check	binding	0
enter	query	functor(X, 1.1, 0).
check	hasSolution	true
enter	variable	X
check	binding	1.1

The remaining tests cover the cases when an error or exception is thrown by the engine while solving a query.

alice.tuprolog.PrologActionFixture
enter	query	functor(X, Y, 3).
check	hasSolution	false
check	exception	instantiation_error
enter	query	functor(X, foo, N).
check	hasSolution	false
check	exception	instantiation_error
enter	query	functor(X, foo, a).
check	hasSolution	false
check	exception	type_error(integer, a)
enter	query	functor(F, 1.5, 1).
check	hasSolution	false
check	exception	type_error(atom, 1.5)
enter	query	functor(F, foo(a), 1).
check	hasSolution	false
check	exception	type_error(atomic, foo(a))
enter	query	current_prolog_flag(max_arity, A), X is A + 1, functor(T, foo, X).
check	hasSolution	false
check	exception	representation_error(max_arity)
enter	query	Minus1 is 0 - 1, functor(F, foo, Minus1).
check	hasSolution	false
check	exception	domain_error(not_less_than_zero, -1)

2. `arg/3`

arg(N, Term, Arg) is true iff the Nth argument of Term is Arg.

Templates and modes for the predicate are as follows:

arg(+integer, +compound_term, ?term)

2.1 Example tests

Let's start with some simple tests verifying success of failure of single goals.

alice.tuprolog.SimpleGoalFixture
goal	success()
arg(1, foo(a, b), a).	true
arg(1, foo(a, b), b).	false
arg(0, foo(a, b), foo).	false
arg(3, foo(3, 4), N).	false
arg(1, foo(X), u(X)).

Now we run some tests also verifying the unification for some of the variables in goals.

We first start an appropriate fixture containing an engine.

fit.ActionFixture
start	alice.tuprolog.EngineFixture

Then, ask the engine to solve a query, and check variable bindings.

fit.ActionFixture
enter	query	arg(1, foo(a, b), X).
check	hasSolution	true
enter	variable	X
check	binding	a
enter	query	arg(1, foo(X, b), a).
check	hasSolution	true
enter	variable	X
check	binding	a
enter	query	arg(1, foo(X, b), Y).
check	hasSolution	true
enter	variable	X
check	binding	Y

The remaining tests cover the cases when an error or exception is thrown by the engine while solving a query.

alice.tuprolog.PrologActionFixture
enter	query	arg(X, foo(a, b), a).
check	hasSolution	false
check	exception	instantiation_error
enter	query	arg(1, X, a).
check	hasSolution	false
check	exception	instantiation_error
enter	query	arg(0, atom, a).
check	hasSolution	false
check	exception	type_error(compound, atom)
enter	query	arg(0, 3, a).
check	hasSolution	false
check	exception	type_error(compound, 3)

3. `=../2` (univ)

'=..'(Term, List) is true iff:

Term is an atomic term and List is the list whose only element is Term, or
Term is a compound term and List is the list whose head is the functor name of Term and whose tail is a list of the arguments of Term

Templates and modes for the predicate are as follows:

'=..'(+nonvar, ?list)
'=..'(-nonvar, +list)

Note that =.. is a predefined operator.

3.1 Example tests

Let's start with some simple tests verifying success of failure of single goals.

alice.tuprolog.SimpleGoalFixture
goal	success()
'=..'(foo(a, b), [foo, a, b]).	true
'=..'(1, [1]).	true
'=..'(foo(a, b), [foo, b, a]).	false
'=..'(f(X), [f, u(X)]).

Let's now run some tests also verifying the unification for some of the variables in goals.

We first start an appropriate fixture containing an engine.

fit.ActionFixture
start	alice.tuprolog.EngineFixture

Then, ask the engine to solve a query, and check variable bindings.

fit.ActionFixture
enter	query	'=..'(X, [foo, a, b]).
check	hasSolution	true
enter	variable	X
check	binding	foo(a, b)
enter	query	'=..'(foo(a, b), L).
check	hasSolution	true
enter	variable	L
check	binding	[foo, a, b]
enter	query	'=..'(foo(X, b), [foo, a, Y]).
check	hasSolution	true
enter	variable	X
check	binding	a
enter	variable	Y
check	binding	b

The remaining tests cover the cases when an error or exception is thrown by the engine while solving a query.

alice.tuprolog.PrologActionFixture
enter	query	'=..'(X, Y).
check	hasSolution	false
check	exception	instantiation_error
enter	query	'=..'(X, [foo, a \| Y]).
check	hasSolution	false
check	exception	instantiation_error
enter	query	'=..'(X, [foo \| bar]).
check	hasSolution	false
check	exception	type_error(list, [foo \| bar])
enter	query	'=..'(X, [Foo, bar]).
check	hasSolution	false
check	exception	instantiation_error
enter	query	'=..'(X, [3, 1]).
check	hasSolution	false
check	exception	type_error(atom, 3)
enter	query	'=..'(X, [1.1, foo]).
check	hasSolution	false
check	exception	type_error(atom, 1.1)
enter	query	'=..'(X, [a(b), 1]).
check	hasSolution	false
check	exception	type_error(atom, a(b))
enter	query	'=..'(X, 4).
check	hasSolution	false
check	exception	type_error(list, 4)

4. `copy_term/2`

copy_term(Term1, Term2) is true iff Term2 unifies with a term T which is a renamed copy of Term1.

Templates and modes for the predicate are as follows:

copy_term(?term, ?term)

4.1 Example tests

Let's start with some simple tests verifying success of failure of single goals.

alice.tuprolog.SimpleGoalFixture
goal	success()
copy_term(X, Y).	true
copy_term(X, 3).	true
copy_term(_, a).	true
copy_term(_, _).	true
copy_term(a, b).	false
copy_term(a+X, X+b), copy_term(a+X, X+b).	false
copy_term(demoen(X, X), demoen(Y, f(Y))).

Let's now run some tests also verifying the unification for some of the variables in goals.

We first start an appropriate fixture containing an engine.

fit.ActionFixture
start	alice.tuprolog.EngineFixture

Then, ask the engine to solve a query, and check variable bindings.

fit.ActionFixture
enter	query	copy_term(a+X, X+b).
check	hasSolution	true
enter	variable	X
check	binding	a
enter	query	copy_term(X+X+Y, A+B+B).
check	hasSolution	true
enter	variable	A
check	binding	B

Note that there are no error or exception cases for this predicate.

Run the tests!

The results of the tests for Term creation and decomposition are as follows:

fit.Summary

Term creation and decomposition

1. functor/3

1.1 Example tests

2. arg/3

2.1 Example tests

3. =../2 (univ)

3.1 Example tests

4. copy_term/2

4.1 Example tests

1. `functor/3`

2. `arg/3`

3. `=../2` (univ)

4. `copy_term/2`