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.