TIP#258 IMPLEMENTATION

        * doc/Encoding.3:       New subcommand [encoding dirs].
        * doc/encoding.n:       New routine Tcl_GetEncodingNameFromEnvironment.
        * generic/tcl.decls:    Made public:
        * generic/tclBasic.c:   TclGetEncodingFromObj
        * generic/tclCmdAH.c:           -> Tcl_GetEncodingFromObj
        * generic/tclEncoding.c:TclGetEncodingSearchPath
        * generic/tclInt.decls:         -> Tcl_GetEncodingSearchPath
        * generic/tclInt.h:     TclSetEncodingSearchPath
        * generic/tclTest.c:            -> Tcl_SetEncodingSearchPath
        * library/init.tcl:     Removed commands:
        * tests/cmdAH.test:             [tcl::unsupported::EncodingDirs]
        * tests/encoding.test:          [testencoding path] (Tcltest)
        * unix/tclUnixInit.c:   [Patch 1413934].
        * win/tclWinInit.c:

        * generic/tclDecls.h:   make genstubs
        * generic/tclIntDecls.h:
        * generic/tclStubInit.c:

2 files changed, 106 insertions, 7 deletions

diff --git a/doc/Encoding.3 b/doc/Encoding.3
index c365aaf..efdc8ca 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Encoding.3,v 1.20 2004/10/07 15:15:37 dkf Exp $
+'\" RCS: @(#) $Id: Encoding.3,v 1.21 2006/02/08 21:41:27 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
@@ -21,6 +21,11 @@ Tcl_Encoding
 void
 \fBTcl_FreeEncoding\fR(\fIencoding\fR)
 .sp
+.VS 8.5
+int
+\fBTcl_GetEncodingFromObj\fR(\fIinterp, objPtr, encodingPtr\fR)
+.VE 8.5
+.sp
 char *
 \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
 .sp
@@ -47,12 +52,25 @@ const char *
 int
 \fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
 .sp
+.VS 8.5
+const char *
+\fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)in
+.VE 8.5
+.sp
 void
 \fBTcl_GetEncodingNames\fR(\fIinterp\fR)
 .sp
 Tcl_Encoding
 \fBTcl_CreateEncoding\fR(\fItypePtr\fR)
 .sp
+.VS 8.5
+Tcl_Obj *
+\fBTcl_GetEncodingSearchPath\fR()
+.sp
+int
+\fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
+.VE 8.5
+.sp
 const char *
 \fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
 .sp
@@ -69,6 +87,14 @@ Name of encoding to load.
 .AP Tcl_Encoding encoding in
 The encoding to query, free, or use for converting text.  If \fIencoding\fR is 
 NULL, the current system encoding is used.
+.AP Tcl_Obj *objPtr in
+.VS 8.5
+Name of encoding to get token for.
+.VE 8.5
+.AP Tcl_Encoding *encodingPtr out
+.VS 8.5
+Points to storage where encoding token is to be written.
+.VE 8.5
 .AP "const char" *src in
 For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
 specified encoding that are to be converted to UTF-8.  For the
@@ -121,8 +147,16 @@ buffer as a result of the conversion.  May be NULL.
 .AP int *dstCharsPtr out
 Filled with the number of characters that correspond to the number of bytes
 stored in the output buffer.  May be NULL.
+.AP Tcl_DString *bufPtr out
+.VS 8.5
+Storage for the prescribed system encoding name.
+.VE 8.5
 .AP Tcl_EncodingType *typePtr in
 Structure that defines a new type of encoding.  
+.AP Tcl_Obj *searchPath in
+.VS 8.5
+List of filesystem directories in which to search for encoding data files.
+.VE 8.5
 .AP "const char" *path in
 A path to the location of the encoding file.  
 .BE
@@ -171,6 +205,25 @@ anywhere (i.e., it has been freed as many times as it has been gotten)
 \fBTcl_FreeEncoding\fR will release all storage the encoding was using
 and delete it from the database. 
 .PP
+.VS 8.5
+\fBTcl_GetEncodingFromObj\fR treats the string representation of \fIobjPtr\fR
+as an encoding name, and finds an encoding with that name, just as
+\fBTcl_GetEncoding\fR does.  When an encoding is found, its \fBTcl_Encoding\fB
+token is written to the storage pointed to by \fIencodingPtr\fR, and the value
+\fBTCL_OK\fR is returned.  In addition, a copy of the \fBTcl_Encoding\fR is
+kept as the internal representation of \fIobjPtr\fR.  If no such encoding is
+found, the value \fBTCL_ERROR\fR is returned, and no writing to
+\fI*encodingPtr\fR takes place.
+.PP
+The reference count of the \fBTcl_Encoding\fR token may be incremented twice,
+once for the reference written to \fI*encodingPtr\fR and once for the
+reference stored in \fIobjPtr\fR, if a reference is not already in place
+there.  The caller should call \fBTcl_FreeEncoding\fR on \fI*encodingPtr\fR
+when the token will no longer be used.  The usual mechanisms for freeing the
+internal representation of a \fBTcl_Obj\fR will take care of calling
+\fBTcl_FreeEncoding\fR on that reference at the appropriate time.
+.VE 8.5
+.PP
 \fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the
 specified \fIencoding\fR into UTF-8.  The converted bytes are stored in 
 \fIdstPtr\fR, which is then null-terminated.  The caller should eventually
@@ -277,6 +330,15 @@ procedure increments the reference count of the new system encoding,
 decrements the reference count of the old system encoding, and returns
 \fBTCL_OK\fR.
 .PP
+.VS 8.5
+\fBTcl_GetEncodingNameFromEnvironment\fR provides a means for the Tcl
+library to report the encoding name it believes to be the correct one
+to use as the system encoding, based on system calls and examination of
+the environment suitable for the platform.  It accepts \fIbufPtr\fR,
+a pointer to an uninitialized or freed \fBTcl_DString\fR and writes
+the encoding name to it.  The \fBTcl_DStringValue\fR is returned.
+.VE 8.5
+.PP
 \fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
 consisting of the names of all the encodings that are currently defined
 or can be dynamically loaded, searching the encoding path specified by
@@ -376,12 +438,34 @@ This \fIfreeProc\fR function is called when the encoding is deleted.  The
 \fIclientData\fR parameter is the same as the \fIclientData\fR field
 specified to \fBTcl_CreateEncoding\fR when the encoding was created.  
 .PP
-
+.VS 8.5
+\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR
+are called to access and set the list of filesystem directories searched
+for encoding data files.  
+.PP
+The value returned by \fBTcl_GetEncodingSearchPath\fR
+is the value stored by the last successful call to
+\fBTcl_SetEncodingSearchPath\fR.  If no calls to
+\fBTcl_SetEncodingSearchPath\fR have occurred, Tcl will compute an initial
+value based on the environment.  There is one encoding search path for the
+entire process, shared by all threads in the process.
+.PP
+\fBTcl_SetEncodingSearchPath\fR stores \fIsearchPath\fR and returns
+\fBTCL_OK\fR, unless \fIsearchPath\fR is not a valid Tcl list, which
+causes \fBTCL_ERROR\fR to be returned.  The elements of \fIsearchPath\fR
+are not verified as existing readable filesystem directories.  When
+searching for encoding data files takes place, and non-existent or
+non-readable filesystem directories on the \fIsearchPath\fR are silently
+ignored.
+.PP
 \fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR
-access and set the directory to use when locating the default encoding
-files.  If this value is not NULL, the \fBTclpInitLibraryPath\fR routine
-appends the path to the head of the search path, and uses this path as
-the first place to look into when trying to locate the encoding file.
+are obsolete interfaces best replaced with calls to
+\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR.
+They are called to access and set the first element of the \fIsearchPath\fR
+list.  Since Tcl searches \fIsearchPath\fR for encoding data files in
+list order, these routines establish the ``default'' directory in which
+to find encoding data files.
+.VE 8.5
 
 .SH "ENCODING FILES"
 Space would prohibit precompiling into Tcl every possible encoding
diff --git a/doc/encoding.n b/doc/encoding.n
index 36db314..69d6d21 100644
--- a/doc/encoding.n
+++ b/doc/encoding.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: encoding.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
+'\" RCS: @(#) $Id: encoding.n,v 1.7 2006/02/08 21:41:27 dgp Exp $
 '\" 
 .so man.macros
 .TH encoding n "8.1" Tcl "Tcl Built-In Commands"
@@ -41,6 +41,21 @@ string.  Each byte is stored in the lower 8-bits of a Unicode
 character.  If \fIencoding\fR is not specified, the current
 system encoding is used.
 .TP
+\fBencoding dirs\fR ?\fIdirectoryList\fR?
+.VS 8.5
+Tcl can load encoding data files from the file system that describe
+additional encodings for it to work with.  This command
+sets the search path for \fB*.enc\fR encoding data files to
+the list of directories \fIdirectoryList\fR.  If
+\fIdirectoryList\fR is omitted then the command returns the
+current list of directories that make up the search path.
+If \fIdirectoryList\fR is present, but is not a valid Tcl
+list, an error is raised.  Any elements in \fIdirectoryList\fR
+that are not in fact readable directories in the filesystem are ignored
+without raising an error when searches for encoding data files
+take place.
+.VE 8.5
+.TP
 \fBencoding names\fR
 Returns a list containing the names of all of the encodings that are
 currently available.