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.

Copyright (C) 1999,2000 Daniel Diaz
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
More about the copyright