# Basic term manipulation

**Author(s):**Daniel Cabeza, Manuel Hermenegildo.

This module provides basic term manipulation.

## Usage and interface

**Library usage:**

These predicates are builtin in Ciao, so nothing special has to be done to use them.**Exports:***Predicates:*`\=/2`,`arg/3`,`functor/3`,`=../2`,`copy_term/2`,`copy_term_nat/2`,`cyclic_term/1`,`C/3`.*Properties:*`=/2`,`const_head/1`.*Regular Types:*`non_empty_list/1`,`list_functor/1`.

**Imports:***System library modules:*`assertions/native_props`.*Packages:*`prelude`,`nonpure`,`assertions`,`nativeprops`,`isomodes`,`nortchecks`.

## Documentation on exports

X=Y :- X=Y.

**General properties:**

**Trust:**`X=Y`

X and Y unify.

*The following properties hold globally:*

(basic_props:sideff/2)X=Y is side-effect free.

(basic_props:native/1)This predicate is understood natively by CiaoPP.

(basic_props:eval/1)X=Y is evaluable at compile-time.

(native_props:is_det/1)All calls of the form X=Y are deterministic.

(native_props:relations/2)Goal X=Y produces inf solutions.

(native_props:test_type/2)Indicates the type of test that a predicate performs. Required by the nonfailure analyisis.

**(Trust) Usage:**ISO`X\=Y`

X and Y are not unifiable.

*The following properties hold globally:*

(basic_props:sideff/2)X\=Y is side-effect free.

(basic_props:bind_ins/1)X\=Y is binding insensitive.

(native_props:is_det/1)All calls of the form X\=Y are deterministic.

**General properties:**

**Trust:**`X\=Y`

*If the following properties hold at call time:*

(term_typing:ground/1)X is currently ground (it contains no variables).

(term_typing:ground/1)Y is currently ground (it contains no variables).*then the following properties hold globally:*

(basic_props:eval/1)X\=Y is evaluable at compile-time.

**Trust:**`X\=Y`

*The following properties hold globally:*

(basic_props:sideff/2)X\=Y is side-effect free.

**(Trust) Usage 1:**`arg(ArgNo,Term,Arg)`

*The following properties should hold at call time:*

(basic_props:num/1)ArgNo is a number.*The following properties hold globally:*

(native_props:is_det/1)All calls of the form arg(ArgNo,Term,Arg) are deterministic.

(native_props:relations/2)Goal arg(ArgNo,Term,Arg) produces inf solutions.

**(Trust) Usage 2:**`arg(ArgNo,Term,Arg)`

*The following properties should hold at call time:*

(basic_props:num/1)ArgNo is a number.

(basic_props:gnd/1)Term is ground.*The following properties hold upon exit:*

(basic_props:gnd/1)Arg is ground.

**(Trust) Usage 3:**ISO`arg(ArgNo,Term,Arg)`

Argument ArgNo of the term Term is Arg.

*The following properties should hold at call time:*

(basic_props:nnegint/1)ArgNo is a non-negative integer.

(basic_props:struct/1)Term is a compound term.*The following properties hold globally:*

(basic_props:sideff/2)arg(ArgNo,Term,Arg) is side-effect free.

(basic_props:native/1)This predicate is understood natively by CiaoPP.

(basic_props:bind_ins/1)arg(ArgNo,Term,Arg) is binding insensitive.

**(Trust) Usage 4:**`arg(ArgNo,Term,Arg)`

*The following properties should hold at call time:*

(basic_props:nnegint/1)ArgNo is a non-negative integer.

(basic_props:gnd/1)Term is ground.*The following properties hold upon exit:*

(basic_props:gnd/1)Arg is ground.

**(Trust) Usage 1:**ISO`functor(Term,Name,Arity)`

*The following properties should hold at call time:*

(term_typing:nonvar/1)Term is currently a term which is not a free variable.*The following properties hold upon exit:*

(basic_props:atm/1)Name is an atom.

(basic_props:nnegint/1)Arity is a non-negative integer.*The following properties hold globally:*

(basic_props:not_further_inst/2)Term is not further instantiated.

(basic_props:sideff/2)functor(Term,Name,Arity) is side-effect free.

(basic_props:native/1)This predicate is understood natively by CiaoPP.

(basic_props:bind_ins/1)functor(Term,Name,Arity) is binding insensitive.

(basic_props:eval/1)functor(Term,Name,Arity) is evaluable at compile-time.

**(Trust) Usage 2:**ISO`functor(Term,Name,Arity)`

The principal functor of the term Term has name Name and arity Arity.

*The following properties should hold at call time:*

(term_typing:nonvar/1)Name is currently a term which is not a free variable.

(term_typing:nonvar/1)Arity is currently a term which is not a free variable.*The following properties hold upon exit:*

(term_typing:nonvar/1)Term is currently a term which is not a free variable.

(basic_props:atm/1)Name is an atom.

(basic_props:nnegint/1)Arity is a non-negative integer.*The following properties hold globally:*

(basic_props:sideff/2)functor(Term,Name,Arity) is side-effect free.

(basic_props:native/1)This predicate is understood natively by CiaoPP.

(basic_props:bind_ins/1)functor(Term,Name,Arity) is binding insensitive.

(basic_props:eval/1)functor(Term,Name,Arity) is evaluable at compile-time.

(native_props:not_fails/1)All the calls of the form functor(Term,Name,Arity) do not fail.

**(Trust) Usage 3:**`functor(Term,Name,Arity)`

*The following properties should hold at call time:*

(term_typing:nonvar/1)Term is currently a term which is not a free variable.

(term_typing:var/1)Name is a free variable.

(term_typing:var/1)Arity is a free variable.

(term_typing:nonvar/1)Term is currently a term which is not a free variable.*The following properties hold upon exit:*

(native_props:size/2)1 is the size of argument Name, for any approximation.

(native_props:size/2)arity(Term) is the size of argument Arity, for any approximation.*The following properties hold globally:*

(native_props:size_metric/3)arity is the metric of the variable Term, for any approximation.

**General properties:**

**Trust:**

*The following properties hold globally:*

(basic_props:sideff/2)functor(Arg1,Arg2,Arg3) is side-effect free.

(basic_props:native/1)This predicate is understood natively by CiaoPP.

(native_props:is_det/1)All calls of the form functor(Arg1,Arg2,Arg3) are deterministic.

**(Trust) Usage:**ISO`Term=..List`

The functor and arguments of the term Term comprise the list List.

*The following properties hold upon exit:*

(basic_props:list/1)List is a list.*The following properties hold globally:*

(basic_props:sideff/2)Term=..List is side-effect free.

(basic_props:native/1)This predicate is understood natively by CiaoPP.

**General properties:**

**True:**

*If the following properties hold at call time:*

(term_typing:nonvar/1)Arg1 is currently a term which is not a free variable.*then the following properties hold globally:*

(basic_props:eval/1)Arg1=..Arg2 is evaluable at compile-time.

**True:**`Arg1=..List`

*If the following properties hold at call time:*

(basic_props:list/1)List is a list.

(term_basic:const_head/1)term_basic:const_head(List)*then the following properties hold globally:*

(basic_props:eval/1)Arg1=..List is evaluable at compile-time.

**Usage:**ISO`copy_term(Term,Copy)`

Copy 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 attributes, the copied variables will have copies of the attributes as well. It behaves as if defined by:

:- data 'copy of'/1. copy_term(X, Y) :- asserta_fact('copy of'(X)), retract_fact('copy of'(Y)).

*The following properties should hold globally:*

(basic_props:sideff/2)copy_term(Term,Copy) is side-effect free.

(basic_props:native/1)This predicate is understood natively by CiaoPP.

**General properties:**

**True:**`copy_term(Term,Copy)`

*If the following properties hold at call time:*

(term_typing:ground/1)Term is currently ground (it contains no variables).*then the following properties hold globally:*

(basic_props:eval/1)copy_term(Term,Copy) is evaluable at compile-time.

**(Trust) Usage:**`copy_term_nat(Term,Copy)`

Same as `copy_term/2`, except that attributes of variables are not copied.

*The following properties hold globally:*

(basic_props:sideff/2)copy_term_nat(Term,Copy) is side-effect free.

**(Trust) Usage 1:**`C(S1,Terminal,S2)`

*The following properties hold upon exit:*

(term_basic:list_functor/1)term_basic:list_functor(S1)

**(Trust) Usage 2:**`C(S1,Terminal,S2)`

S1 is connected by the terminal Terminal to S2. Internally used in *DCG grammar rules*. Defined as if by the single clause: `'C'([X|S], X, S).`

*The following properties hold globally:*

(basic_props:sideff/2)C(S1,Terminal,S2) is side-effect free.

(basic_props:native/1)This predicate is understood natively by CiaoPP.

**General properties:**

**Trust:**`C(S1,Terminal,S2)`

*If the following properties hold at call time:*

(term_basic:non_empty_list/1)A list that is not the empty list [].*then the following properties hold upon exit:*

(basic_props:list/1)S2 is a list.

**True:**

*If the following properties hold at call time:*

(term_typing:nonvar/1)Arg1 is currently a term which is not a free variable.*then the following properties hold globally:*

(basic_props:eval/1)C(Arg1,Arg2,Arg3) is evaluable at compile-time.

## Known bugs and planned improvements

- Run-time checks have been reported not to work with this code. That means that either the assertions here, or the code that implements the run-time checks are erroneous.