Variable naming/numbering

### 6.5 Variable naming/numbering

#### 6.5.1 `name_singleton_vars/1`

Templates

  `name_singleton_vars(?term)`

Description
`name_singleton_vars(Term)` binds each singleton variable appearing in `Term` with a term of the form `'$VARNAME'('_')`. Such a term can be output by `write_term/3` as a variable name (section 6.14.6).
Errors
None.
Portability
GNU Prolog predicates.

#### 6.5.2 `name_query_vars/2`

Templates

  `name_query_vars(+list, ?list)`

Description
`name_query_vars(List, Rest)` for each element of `List` of the form `Name = Var` where `Name` is an atom and `Var` a variable, binds `Var` with the term `'$VARNAME'(Name)`. Such a term can be output by `write_term/3` as a variable name (section 6.14.6). `Rest` is unified with the list of elements of `List` that have not given rise to a binding. This predicate is provided as a way to name the variable lists obtained returned by `read_term/3` with `variable_names(List)` or `singletons(List)` options (section 6.14.1).
Errors

`List` is a partial list |  | `instantiation_error`
`List` is neither a partial list nor a list |  | `type_error(list, List)`
`Rest` is neither a partial list nor a list |  | `type_error(list, Rest)`

Portability
GNU Prolog predicate.

#### 6.5.3 `bind_variables/2`, `numbervars/3`, `numbervars/1`

Templates

  `bind_variables(?term, +var_binding_option_list)
  numbervars(?term, +integer, ?integer)
  numbervars(?term)`

Description
`bind_variables(Term, Options)` binds each variable appearing in `Term` according to the options given by `Options`.
Variable binding options: `Options` is a list of variable binding options. If this list contains contradictory options, the rightmost option is the one which applies. Possible options are:

- `numbervars`: specifies that each variable appearing in `Term` should be bound to a term of the form `'$VAR'(N)` where `N` is an integer. Such a term can be output by `write_term/3` as a variable name (section 6.14.6). This is the default.
- `namevars`: specifies that each variables appearing in `Term` shall be bound to a term of the form `'$VARNAME'(Name)` where `Name` is the atom that would be output by `write_term/3` seeing a term of the `'$VAR'(N)` where `N` is an integer. Such a term can be output by `write_term/3` as a variable name (section 6.14.6). This is the alternative to `numbervars`.
- `from(From)`: the first integer `N` to use for number/name variables of `Term` is `From`. The default value is `0`.
- `next(Next)`: when `bind_variables/2` succeeds, `Next` is unified with the (last integer `N`)+1 used to bind the variables of `Term`.
- `exclude(List)`: collects all variable names appearing in `List` to avoid a clash when binding a variable of `Term`. Precisely a number `N` ³ `From` will not be used to bind a variable of `Term` if:
  - there is a sub-term of `List` of the form `'$VAR'(N)` or `'$VARNAME'(Name)` where `Name` is the constant that would be output by `write_term/3` seeing a term of the `'$VAR'(N)`.
  - an element of `List` is of the form `Name = Var` where `Name` is an atom that would be output by `write_term/3` on seeing a term of the from `'$VAR'(N)`. This case allows for lists returned by `read_term/3` (with `variable_names(List)` or `singletons(List)` options) (section 6.14.1) and by `name_query_vars/2` (section 6.5.2).

`numbervars(Term, From, Next)` is equivalent to `bind_variables(Term, [from(From), next(Next)]`, i.e. each variable of `Term` is bound to `'$VAR'(N)` where `From` `£` `N` < `Next`.
`numbervars(Term)` is equivalent to `numbervars(Term, 0, _)`.
Errors

`Options` is a partial list or a list with an element `E` which is a variable |  | `instantiation_error`
`Options` is neither a partial list nor a list |  | `type_error(list, Options)`
an element `E` of the `Options` list is neither a variable nor a variable binding option |  | `domain_error(var_binding_option, E)`
`From` is a variable |  | `instantiation_error`
`From` is neither a variable nor an integer |  | `type_error(integer, From)`
`Next` is neither a variable nor an integer |  | `type_error(integer, Next)`
`List` is a partial list |  | `instantiation_error`
`List` is neither a partial list nor a list |  | `type_error(list, List)`

Portability
GNU Prolog predicates.

#### 6.5.4 `term_ref/2`

Templates

  `term_ref(+term, ?integer)
  term_ref(?term, +integer)`

Description
`term_ref(Term, Ref`) succeeds if the internal reference of `Term` is `Ref`. This predicate can be used either to obtain the internal reference of a term or to obtain the term associated to a given reference. Note that two identical terms can have different internal references. A good way to use this predicate is to first record the internal reference of a given term and to later re-obtain the term via this reference.
Errors

`Term` and `Ref` are both variables |  | `instantiation_error`
`Ref` is neither a variable nor an integer |  | `type_error(integer, Ref)`
`Ref` is an integer < 0 |  | `domain_error(not_less_than_zero, Ref)`

Portability
GNU Prolog predicate.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
More about the copyright