TIP 485: Remove Deprecated API

Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.
Author:         Jan Nijtmans <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        08-Nov-2017
Tcl-Version:    9.0
Tcl-Branch:     tip-485


The "case" command, and the "read|puts ... nonewline" construct are replaced by better commands long ago (resp. "switch" and "read|puts -nonewline ..."), but the old forms were never actually removed from the Tcl code base. They still work. See also bug #3151675. For Tcl 9.0 it is finally time to actually remove it.

In addition, there are a number of C API's which have better successors by now. Finally, there are a few C routines and other macros which were never been properly documented before, like CONST, or macros needed for supporting deprecated C features, like _ANSI_ARGS_ and TCL_VARARGS. This TIP proposes to finally remove all of those in Tcl 9.0, and mark them as deprecated in Tcl 8.7.


The "case" command is superseded by the "switch" command.

The "read <chan> nonewline" construct is superseded by "read -nonewline <chan>".

The "puts <chan> <line> nonewline" construct is superseded by "read -nonewline <chan> <line>".

The following C routines -- mostly macros -- like the "case" command have never been part of the documented interface of Tcl 8, and should be removed:

The following C macros don't serve any purpose any more, they will be removed in Tcl 9.0:

Minor note: The macro CONST86 is still kept, as this can be used for extensions wanting to keep compatibility with Tcl 8.5. This macro will become DEPRECATED in Tcl 9.0, but will not be removed yet.

The following types don't serve any purpose any more, they will be removed in Tcl 9.0:

The function Tcl_Backslash is superseded by Tcl_UtfBackslash

The function Tcl_GetDefaultEncodingDir is superseded by Tcl_GetEncodingSearchPath

The function Tcl_SetDefaultEncodingDir is superseded by Tcl_SetEncodingSearchPath

The function Tcl_EvalTokens is superseded by Tcl_EvalTokensStandard

Finally, the functions Tcl_CreateMathFunc, Tcl_GetMathFuncInfo and Tcl_ListMathFuncs are superseded by TIP #232

Proposed Change

If Tcl 8.7 is compiled with the flag -DTCL_NO_DEPRECATED, the "case" command, the "read <chan> nonewline", and the "puts <chan> <line> nonewline" constructs will be disabled. In Tcl 9.0 all related code will actually be removed from the Tcl code base.

The following API's are declared deprecated in Tcl 8.7 and will be fully removed in Tcl 9.0. If Tcl 8.7 is compiled with the flag -DTCL_NO_DEPRECATED, all deprecated API is disabled, by making those entries MODULE_SCOPE, and putting 0 in the corresponding stub entries. This can be used by extensions to see whether they are compatible with the next major Tcl release or not. Those functions are already removed in the "novem" branch:

An implementation of this TIP can be found in the tip-485 branch. This branch is based on "core-8-branch" (Tcl 8.7), but can be trivially merged forward to trunk (Tcl 9.0).

Rejected Alternatives

Originally, Tcl_EvalFile was a candidate for removal as well.


This document has been placed in the public domain.