8.7 Meta-Logic

The predicates in this section are meta-logical and perform operations that require reasoning about the current instantiation of terms or decomposing terms into their constituents. Such operations cannot be expressed using predicate definitions with a finite number of clauses.

`var(`?X`) `ISO,meta-logical
Tests whether X is currently uninstantiated (`var` is short for variable). An uninstantiated variable is one that has not been bound to anything, except possibly another uninstantiated variable. Note that a compound term with some components that are uninstantiated is not itself considered to be uninstantiated. Thus the query
```          | ?- var(foo(X, Y)).
```

always fails, despite the fact that X and Y are uninstantiated.

`nonvar(`?X`) `ISO,meta-logical
Tests whether X is currently instantiated. This is the opposite of `var/1`.
`ground(`?X`) `meta-logical
Tests whether X is completely instantiated, i.e. free of unbound variables. In this context, mutable terms are treated as nonground, so as to make `ground/1` a monotone predicate.
`atom(`?X`) `ISO,meta-logical
Checks that X is currently instantiated to an atom (i.e. a non-variable term of arity 0, other than a number).
`float(`?X`) `ISO,meta-logical
Checks that X is currently instantiated to a float.
`integer(`?X`) `ISO,meta-logical
Checks that X is currently instantiated to an integer.
`number(`?X`) `ISO,meta-logical
Checks that X is currently instantiated to a number.
`atomic(`?X`) `ISO,meta-logical
Checks that X is currently instantiated to an atom or number.
`simple(`?X`) `meta-logical
Checks that X is currently uninstantiated or instantiated to an atom or number.
`compound(`?X`) `ISO,meta-logical
Checks that X is currently instantiated to a compound term.
`callable(`?X`) `meta-logical
Checks that X is currently instantiated to a term valid as a goal i.e. a compound term or an atom.
`is_mutable(`?X`) `meta-logical
Checks that X is currently instantiated to a mutable term (see Modify Term).
`functor(`+Term`,`?Name`,`?Arity`) `ISO,meta-logical
`functor(`?Term`,`+Name`,`+Arity`) `ISO,meta-logical
The principal functor of Term has name Name and arity Arity, where Name is either an atom or, provided Arity is 0, a number. Initially, either Term must be instantiated, or Name and Arity must be instantiated to, respectively, either an atom and an integer in [0,255] or an atomic term and 0. In the case where Term is initially uninstantiated, the result of the call is to instantiate Term to the most general term having the principal functor indicated.
`arg(`+ArgNo`,`+Term`,`?Arg`) `ISO,meta-logical
Arg is the argument ArgNo of the compound term Term. The arguments are numbered from 1 upwards, ArgNo must be instantiated to a positive integer and Term to a compound term.
+Term` =.. `?List ISO
?Term` =.. `+List ISO
List is a list whose head is the atom corresponding to the principal functor of Term, and whose tail is a list of the arguments of Term. e.g.
```          | ?- product(0, n, n-1) =.. L.

L = [product,0,n,n-1]

| ?- n-1 =.. L.

L = [-,n,1]

| ?- product =.. L.

L = [product]
```

If Term is uninstantiated, then List must be instantiated either to a list of determinate length whose head is an atom, or to a list of length 1 whose head is a number. Note that this predicate is not strictly necessary, since its functionality can be provided by `arg/3` and `functor/3`, and using the latter two is usually more efficient.

`name(`+Const`,`?CharList`) `obsolescent
`name(`?Const`,`+CharList`) `obsolescent
If Const is an atom or number, CharList is a code-list of the characters comprising the name of Const. e.g.
```          | ?- name(product, L).

L = [112,114,111,100,117,99,116]

| ?- name(product, "product").

| ?- name(1976, L).

L = [49,57,55,54]

| ?- name('1976', L).

L = [49,57,55,54]

| ?- name((:-), L).

L = [58,45]
```

If Const is uninstantiated, CharList must be instantiated to a code-list. If CharList can be interpreted as a number, Const is unified with that number; otherwise, with the atom whose name is CharList. E.g.:

```          | ?- name(X, [58,45]).

X = :-

| ?- name(X, ":-").

X = :-

| ?- name(X, [49,50,51]).

X = 123
```

Note that there are atoms for which `name(`Const`,`CharList`)` is true, but which will not be constructed if `name/2` is called with Const uninstantiated. One such atom is the atom `'1976'`. It is recommended that new programs use `atom_codes/2` or `number_codes/2`, as these predicates do not have this inconsistency.

`atom_codes(`+Const`,`?CodeList`) `ISO
`atom_codes(`?Const`,`+CodeList`) `ISO
The same as `name(`Const`,`CodeList`)`, but Const is constrained to be an atom.
`number_codes(`+Const`,`?CodeList`) `ISO
`number_codes(`?Const`,`+CodeList`) `ISO
The same as `name(`Const`,`CodeList`)`, but Const is constrained to be a number.
`atom_chars(`+Const`,`?CharList`) `ISO only
`atom_chars(`?Const`,`+CharList`) `ISO only
Analogous to `atom_codes/2`, but CharList is a char-list instead of a code-list.
`atom_chars(`+Const`,`?CodeList`) `SICStus only
`atom_chars(`?Const`,`+CodeList`) `SICStus only
The same as `atom_codes(`Const`,`CharList`)`.
`number_chars(`+Const`,`?CharList`) `ISO only
`number_chars(`?Const`,`+CharList`) `ISO only
Analogous to `number_codes/2`, but CharList is a char-list instead of a code-list.
`number_chars(`+Const`,`?CodeList`) `SICStus only
`number_chars(`?Const`,`+CodeList`) `SICStus only
The same as `number_codes(`Const`,`CharList`)`.
`char_code(`+Char`,`?Code`) `ISO
`char_code(`?Char`,`+Code`) `ISO
Code is the character code of the one-char atom Char.
`atom_length(`+Atom`,`?Length`) `ISO
Length is the number of characters of the atom Atom.
`atom_concat(`+Atom1`,`+Atom2`,`?Atom12`) `ISO
`atom_concat(`?Atom1`,`?Atom2`,`+Atom12`) `ISO
The characters of the atom Atom1 concatenated with those of Atom2 are the same as the characters of atom Atom12. If the last argument is instantiated, nondeterminately enumerates all possible atom-pairs that concatenate to the given atom, e.g.:
```          | ?- atom_concat(A, B, 'ab').

A = '',
B = ab ? ;

A = a,
B = b ? ;

A = ab,
B = '' ? ;

no
```

`sub_atom(`+Atom`,`?Before`,`?Length`,`?After`,`?SubAtom`) `ISO
The characters of SubAtom form a sublist of the characters of Atom, such that the number of characters preceding SubAtom is Before, the number of characters after SubAtom is After, and the length of SubAtom is Length. Capable of nondeterminately enumerating all sub-atoms and their all possible placements, e.g.:
```          | ?- sub_atom(abrakadabra, Before, _, After, ab).

After = 9,
Before = 0 ? ;

After = 2,
Before = 7 ? ;

no
```

`copy_term(`?Term`,`?CopyOfTerm`) `ISO,meta-logical
CopyOfTerm is a renaming of Term, such that brand new variables have been substituted for all variables in Term. If any of the variables of Term have goals blocked on them, the copied variables will have copies of the goals blocked on them as well. Similarly, independent copies are substituted for any mutable terms in term. It behaves as if defined by:
```          copy_term(X, Y) :-
assert('copy of'(X)),
retract('copy of'(Y)).
```

The implementation of `copy_term/2` conserves space by not copying ground subterms.