Author:         Jan Nijtmans <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        08-Nov-2017
Post-History:   
Tcl-Version:    9.0
Tcl-Branch:     tip-485

---

Abstract

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.

Rationale

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:

• Tcl_DStringTrunc
• Tcl_Ckalloc
• Tcl_Ckfree
• Tcl_Ckrealloc
• Tcl_Return
• Tcl_TildeSubst
• panic

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

• CONST84_RETURN (just use const)
• CONST84 (just use const)
• CONST (just use const)
• INLINE (just remove it)
• TCL_RESULT_SIZE (use TCL_DSTRING_STATIC_SIZE in stead, if you really have to)
• TCL_VARARGS (just use ...)
• TCL_VARARGS_DEF (just use ...)
• TCL_VARARGS_START (just use va_start())
• _ANSI_ARGS_ (just use '(' and ')')
• VOID, CHAR, SHORT, LONG (windows-only, just use lower-case variant)
• TCL_PARSE_PART1 (flag for variable-related functions, has no effect any more)
• __WIN32__, WIN32 (just use _WIN32)

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:

• Tcl_ValueType (enum, used by deprecated math-related functions)

• Tcl_Value (struct, used by deprecated math-related functions)

The function Tcl_Backslash is superseded by Tcl_UtfBackslash

• The routine Tcl_Backslash returns a single-byte char. It cannot return all possible character values produced in Tcl backslash sequences. Moving to the successor routine fixes bugs.

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

• The routine Tcl_EvalTokens is incapable of reporting back to the caller the return code produced by evaluation. Moving to the successor routine fixes bugs inherent in not distinguishing different return codes.

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:

• Tcl_Backslash

• Tcl_GetDefaultEncodingDir

• Tcl_SetDefaultEncodingDir

• Tcl_EvalTokens

• Tcl_CreateMathFunc

• Tcl_GetMathFuncInfo

• Tcl_ListMathFuncs

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.

Copyright

This document has been placed in the public domain.