Builtin predicates - Term creation and decomposition

Predicates in this group create and decompose terms dynamically.

(.)/2, (=..)/2, arg/3, copy_term/2, functor/3

(.)/2, [_|_]/2 - constructs a list from head and tail terms.

Usage: X = [Head | Tail]

: X = '.'(Head, Tail)

Description: Unifies X with a list constructed from the specified Head and Tail terms. The [Head | Tail] form is the recommended syntax for expressing list construction.

Examples

 [H | T] = [a, b]             succeeds with H = a, T = [b]
 [a, b] = '.'(a, '.'(b, []))  succeeds

A common use for (.)/2 is to decompose a predicate argument into its head and tail components for walking every element in a list:

 is_member(X, [X|T]).
 is_member(X, [_|T]) { is_member(X, T); }

Compatibility: Standard Prolog

See Also: arg/3, functor/3, (=..)/2

(=..)/2 - decomposes a term into a list containing the term's functor name and arguments.

Usage: Term =.. List

Description: If Term is an atomic term, then List is unified with [Term].

: If Term is a compound term, then List is unified with [Name, Arg1, ..., ArgN], where Name is the name of the functor of Term, and Arg1, ... ArgN are its arguments.

: If Term is a variable, and List contains a single atomic value then Term is unified with that atomic value.

: If Term is a variable, and List contains two or more members, and the first is an atom, then Term is unified with a new compound term with the first element as its name, and the remaining list members as its arguments.

Errors

instantiation_error - Term is a variable and List is not a list, or the tail of List is not the [] atom.
instantiation_error - Term is a variable and the first member of List is also a variable.
domain_error(non_empty_list, List) - Term is a variable and List is an empty list.
type_error(atom, Name) - Term is a variable, List has two or more members, and the first member is not an atom.
type_error(atomic, Name) - Term is a variable, List has one member, and it is not atomic.
type_error(list, List) - Term is not a variable and List is not a list or variable.

Examples

 foo =.. [foo]                    succeeds
 1.5 =.. [1.5]                    succeeds
 [a, b, c] =.. ['.', a, [b, c]]   succeeds
 f(a, b, c) =.. [f, X, Y, Z]      succeeds with X = a, Y = b, Z = c
 f(a, b) =.. List                 succeeds with List = [f, a, b]
 Term =.. [foo]                   succeeds with Term = foo
 Term =.. [1.5]                   succeeds with Term = 1.5
 Term =.. [f, a, b]               succeeds with Term = f(a, b)
 Term =.. ['.', a, []]            succeeds with Term = [a]
 Term =.. List                    instantiation_error
 Term =.. f(a, b)                 instantiation_error
 Term =.. [f|X]                   instantiation_error
 Term =.. []                      domain_error(non_empty_list, [])
 Term =.. [f(a, b)]               type_error(atomic, f(a, b))
 Term =.. [1.5, a, b]             type_error(atom, 1.5)
 f(a, b) =.. g(a)                 type_error(list, g(a))

Compatibility: Standard Prolog

See Also: (.)/2, arg/3, functor/3

arg/3 - extracts the n'th argument from a term.

Usage: arg(N, Term, Arg)

Description: Unifies Arg with argument N of the compound Term. The first argument of Term is numbered 1. Fails if N is out of range or Arg does not unify with the extracted argument.

Errors

instantiation_error - N or Term is a variable.
type_error(integer, N) - N is not an integer.
domain_error(not_less_than_zero, N) - N is an integer that is less than zero.
type_error(compound, Term) - Term is not a compound term (functor or list).

Examples

 arg(1, foo(a, b), X)         succeeds with X = a
 arg(2, foo(a, b), X)         succeeds with X = b
 arg(3, foo(a, b), X)         fails
 arg(0, foo(a, b), X)         fails
 arg(1, [a, b], X)            succeeds with X = a
 arg(2, [a, b], X)            succeeds with X = [b]
 arg(1, foo(a, b), a)         succeeds
 arg(1, foo(a, b), b)         fails
 arg(1, foo(X, b), f(X))      fails due to occurs check
 arg(N, foo(a, b), X)         instantiation_error
 arg(1, Term, X)              instantiation_error
 arg(a, [a, b], X)            type_error(integer, a)
 arg(-3, [a, b], X)           domain_error(not_less_than_zero, -3)
 arg(1, a, X)                 type_error(compound, a)

Compatibility: Standard Prolog

See Also: (.)/2, (=..)/2, functor/3

copy_term/2 - unifies the second argument with a freshly renamed copy of the first.

Usage: copy_term(Term1, Term2)

Description: Creates a copy of Term1 where all variables have been replaced with freshly renamed variables, and then unifies the copy with Term2.

Examples

In the following examples X and Y are renamed to A and B respectively:

 copy_term(f(X, Y), Z)        succeeds with Z = f(A, B)
 copy_term(X, a)              succeeds with A = a, X still unbound
 copy_term(f(a, X), f(X, b))  succeeds with X = a
 copy_term(f(X, X), f(Y, Z))  succeeds with Y = Z
 copy_term(foo, bar)          fails

Compatibility: Standard Prolog

functor/3 - extracts the name and arity of a functor term.

Usage: functor(Term, Name, Arity)

Description: If Term is a compound functor term, then Name is unified with the name of the functor, and Arity with its arity.

: If Term is a list, then Name is unified with the atom "." and Arity is unified with 2.

: If Term is an atomic term, then Name is unified with Term, and Arity is unified with 0.

: If Term is a variable, Name is an atomic term, and Arity is zero, then Term is unified with Name.

: If Term is a variable and Name and Arity are not variables, then Term is bound to a new compound term of type Name / Arity, with new free variables as the arguments.

Errors

instantiation_error - Term and Name are both variables.
instantiation_error - Term and Arity are both variables.
type_error(atomic, Name) - Name is not an atomic term and Term is a variable.
type_error(integer, Arity) - Arity is not an integer and Term is a variable.
domain_error(not_less_than_zero, Arity) - Arity is an integer that is less than zero and Term is a variable.
type_error(atom, Name) - Name is not an atom, Arity is not zero, and Term is a variable.

Examples

 functor(a, Name, Arity)          succeeds with Name = a, Arity = 0
 functor(1.5, Name, Arity)        succeeds with Name = 1.5, Arity = 0
 functor(f(a, b), Name, Arity)    succeeds with Name = f, Arity = 2
 functor([H|T], Name, Arity)      succeeds with Name = '.', Arity = 2
 functor(Term, a, 0)              succeeds with Term = a
 functor(Term, 1.5, 0)            succeeds with Term = 1.5
 functor(Term, f, 2)              succeeds with Term = f(X, Y)
 functor(Term, '.', 2)            succeeds with Term = [X|Y]
 functor(Term, Name, 2)           instantiation_error
 functor(Term, f, Arity)          instantiation_error
 functor(Term, f(a), 1)           type_error(atomic, f(a))
 functor(Term, f, 1.5)            type_error(integer, 1.5)
 functor(Term, f, -1)             domain_error(not_less_than_zero, -1)
 functor(Term, 1.5, 1)            type_error(atom, 1.5)

Compatibility: Standard Prolog

See Also: (.)/2, arg/3, (=..)/2