'''`[http://tcl.tk/man/tcl/TclCmd/rename.htm%|%rename]`''', a [Tcl Commands%|%built-in] command, renames or removes a command.



** Synopsis **

    :   '''rename''' ''oldName newName''



** Documentation **

   [http://tcl.tk/man/tcl/TclCmd/rename.htm%|%official reference]:   



** Description **

To remove a command, rename it to the [empty string]:

======
rename foo {}
======

To rename a command to the [empty string] instead of removing it:

======
rename foo ::
======

To rename a command only if a command by the new name doesn't exist:

======
if {[namespace which newname] eq {}} {
    rename oldname newname
}
======

----

[DGP]: Be aware that if you `rename` a command into another
namespace, its evaluation context will change to that namespace.

======none
% namespace eval one {
  variable message "I'm in one"
  proc test {} {variable message; return $message}
}
% namespace eval two {variable message "I'm in two"}
% rename one::test two::test
% two::test
I'm in two
======

----

[aspect]: Also watch out for where you're renaming commands to:

======none
% proc foo args {}
% namespace eval ddd {namespace which -command foo}
::foo
% namespace eval ddd {rename foo foo}
% namespace eval ddd {namespace which -command foo}
::ddd::foo
======

----

[HaO] 2010-04-10: ([http://groups.google.com/group/comp.lang.tcl/browse_thread/thread/20a6f0cb2e9912a9#%|%discussion on CLT%|%]): rename or delete from inside targeted proc is allowed:

======
proc ::runOnceAndDelete {} {
    # do something
    rename ::runOnceAndDelete ""
}
======



** See Also **


   [wrapping commands]:   One common use of `[rename]` is to replace a command with another comand that calls the original command, performing additional steps before or afterwards.  Some examples of this are [Overloading widgets], [Text variable for text widget], and [Forward compatibility].



** Page Contributors **

   [Lars H]:   

   [PYK]:   

   [RS]:   

<<categories>> Tcl syntax | Arts and crafts of Tcl-Tk programming | Command