
set_var_name(?Vars, ++BaseName)

   Give a unique name to each variable in Vars based on BaseName and a counter.

Arguments
   Vars                Variable(s) to be named (Prolog term)
   BaseName            BaseName of variable (atom or string)

Type
   library(var_name)

Description
    
      Give unique and stable names to the variables in Vars. The names have
      the format BaseName#N where N is the value of a counter, which is
      incremented each time a variable is named by set_var_name/2. 
      Thus all such named variables are given a unique name. This name is 
      printed wherever the `source name' of a variable would otherwise
      be printed.  Wherever the system would normally add an arbitrary
      number to the printed name (e.g. the 'V' option in printf, or the
      variables(full) option in write_term printing Name_Number), this
      is not done with named variables.

    
      BaseName must begin with a capital letter, thus the name looks like a
      normal ECLiPSe variable name, but they can be recognised as named
      variables because a normal variable name cannot contain the '#'
      symbol.  Each BaseName has its own counter, which by default starts
      at 0 and is incremented each time a variable with that BaseName is
      named. The default starting value can be changed by
      set_var_name_counter/2 before any calls to set_var_name/2 with the
      BaseName.  Note that the counter value is backtrackable.
      
    
      Vars is usually a variable, or a list of variables that the user would
      like to have the same base name BaseName. Vars is traversed in the usual
      depth-first left-to-right manner and the variables found numbered 
      consecutively with the same base name BaseName. 

    
      The main feature of this name is that the name is unique and stable.
      The name is unique in that at any given time during an ECLiPSe
      execution, the combination of the BaseName and counter can only refer
      to one variable. The name is stable in that this unique name would
      not change between runs of the program or running the program on
      different platforms. Thus, this allows the user to for example
      uniquely identify a variable between a normal and a debugging run of
      the program.

    
      The predicate fails if any variables in Vars has already been given a
      name. In particular, this means that all variables in Vars should
      occur only once. When two named variable are unified, the older name
      is retained, as in existing rules for variable names.

   
      The variable name is implemented as an attribute. Thus all named
      variables become attributed variables, which is recognised by
      ECLiPSe and treated specially when a named variable is printed. It is
      possible to construct a named variable by directly creating the
      attribute, either by reading in a previous named variable written
      using writeq, or by the user explicitly constructing the
      attribute. In such cases, the name is not recorded by the system and
      may not be unique in that set_var_name/2 would not take it into
      account in naming new variables.



Fail Conditions
   Var contain variable(s) that have already been named by set_var_name/2.

Resatisfiable
   no

Exceptions
     5 --- BaseName is not an atom or string.
     6 --- BaseName does not begin with a capital letter.

Examples
   
[eclipse 1]: lib(var_name).
var_name.ecl compiled traceable 1308 bytes in 0.02 seconds

Yes (0.03s cpu)
[eclipse 2]: 


[eclipse 3]: set_var_name(X, 'Myname'), set_var_name(Y, "Myname").

X = Myname#0
Y = Myname#1
Yes (0.00s cpu)
[eclipse 4]: set_var_name(X, 'Count'), writeln(X).
Count#0

X = Count#0
Yes (0.00s cpu)

% name is backtrackable. Original source name printed in second branch
[eclipse 5]: (set_var_name(X, 'Name') ; true), writeln(X), fail.       
Name#0
X

No (0.00s cpu)

% naming more than one variable at a time...
[eclipse 10]: length(L,5), set_var_name(L, 'Start').

L = [Start#0, Start#1, Start#2, Start#3, Start#4]
Yes (0.00s cpu)

% counter is backtrackable
[eclipse 11]: (set_var_name([X,Y], 'Name') ; set_var_name(Y, 'Name')), writeln(X-Y), fail.
Name#0 - Name#1
X - Name#0

No (0.00s cpu)

% each base name has its own counter
[eclipse 12]: set_var_name(X, 'First'), set_var_name(Y, 'Second'), writeln(X-Y).
First#0 - Second#0

X = First#0
Y = Second#0
Yes (0.00s cpu)

% older name is retained on unification
[eclipse 9]:  set_var_name(X, 'First'), set_var_name(Y, 'Second'), X = Y, writeln(Y).
First#0

X = First#0
Y = First#0
Yes (0.00s cpu)

[eclipse 10]: lib(fd), X::[1..5], set_var_name(X, 'Domain'), writeln(X).
fd_domain.pl compiled traceable 22556 bytes in 0.04 seconds
fd_arith.pl compiled traceable 72296 bytes in 0.13 seconds
fd_util.pl compiled traceable 2128 bytes in 0.02 seconds
fd_chip.pl compiled traceable 4720 bytes in 0.05 seconds
fd_elipsys.pl compiled traceable 11036 bytes in 0.02 seconds
fd.pl      compiled traceable 17256 bytes in 0.29 seconds
Domain#0{[1..5]}

X = Domain#0{[1..5]}
Yes (0.29s cpu)

% fails if variable already named
[eclipse 7]: set_var_name(X, 'Name'), set_var_name(X, 'New').

No (0.00s cpu)

% no number is attached to name when printed with 'V' option
[eclipse 14]: set_var_name(X, 'Myname'), printf("%Vw%n%Vw%n", [X,Y]).
Myname#0
Y_177

X = Myname#0
Y = Y
Yes (0.00s cpu)

% writeq does not print the name
[eclipse 15]: set_var_name(X, 'Myname'), writeq(X).
_282{suspend : _285, var_name : vname("Myname", 0)}
X = Myname#0
Yes (0.00s cpu)

[eclipse 12]: set_var_name(X, 123).
out of range in set_var_name(X, 123)
Abort
[eclipse 13]: set_var_name(X, atomic).
out of range in set_var_name(X, atomic)
Abort
[eclipse 14]: set_var_name(X, f(structure)).
type error in set_var_name(X, f(structure))
Abort




See Also
   get_var_name / 2, set_var_name_counter / 2
