diff options
Diffstat (limited to 'doc/Tcl_Main.3')
| -rw-r--r-- | doc/Tcl_Main.3 | 117 |
1 files changed, 82 insertions, 35 deletions
diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index 85a1101..5fd5002 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.3 @@ -6,37 +6,49 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Tcl_Main.3,v 1.9 2002/07/01 18:24:39 jenglish Exp $ -'\" -.so man.macros .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME -Tcl_Main, Tcl_SetMainLoop \- main program and event loop definition for Tcl-based applications +Tcl_Main, Tcl_SetStartupScript, Tcl_GetStartupScript, Tcl_SetMainLoop \- main program, startup script, and event loop definition for Tcl-based applications .SH SYNOPSIS .nf \fB#include <tcl.h>\fR .sp \fBTcl_Main\fR(\fIargc, argv, appInitProc\fR) .sp +\fBTcl_SetStartupScript\fR(\fIpath, encoding\fR) +.sp +Tcl_Obj * +\fBTcl_GetStartupScript\fR(\fIencodingPtr\fR) +.sp \fBTcl_SetMainLoop\fR(\fImainLoopProc\fR) .SH ARGUMENTS -.AS Tcl_AppInitProc *appInitProc +.AS Tcl_MainLoopProc *mainLoopProc .AP int argc in Number of elements in \fIargv\fR. .AP char *argv[] in -Array of strings containing command-line arguments. +Array of strings containing command-line arguments. On Windows, when +using -DUNICODE, the parameter type changes to wchar_t *. .AP Tcl_AppInitProc *appInitProc in Address of an application-specific initialization procedure. The value for this argument is usually \fBTcl_AppInit\fR. +.AP Tcl_Obj *path in +Name of file to use as startup script, or NULL. +.AP "const char" *encoding in +Encoding of file to use as startup script, or NULL. +.AP "const char" **encodingPtr out +If non-NULL, location to write a copy of the (const char *) +pointing to the encoding name. .AP Tcl_MainLoopProc *mainLoopProc in Address of an application-specific event loop procedure. .BE - .SH DESCRIPTION .PP \fBTcl_Main\fR can serve as the main program for Tcl-based shell -applications. A ``shell application'' is a program +applications. A +.QW "shell application" +is a program like tclsh or wish that supports both interactive interpretation of Tcl and evaluation of a script contained in a file given as a command line argument. \fBTcl_Main\fR is offered as a convenience @@ -46,7 +58,7 @@ library and interactive shell operation. Other styles of embedding Tcl in an application are not supported by \fBTcl_Main\fR. Those must be achieved by calling lower level functions in the Tcl library directly. - +.PP The \fBTcl_Main\fR function has been offered by the Tcl library since release Tcl 7.4. In older releases of Tcl, the Tcl library itself defined a function \fBmain\fR, but that lacks flexibility @@ -75,38 +87,76 @@ restriction is not a problem with normal use described above. channels to their default values. See \fBTcl_StandardChannels\fR for more information. .PP -\fBTcl_Main\fR supports two modes of operation, depending on the -values of \fIargc\fR and \fIargv\fR. If \fIargv[1]\fR exists and -does not begin with the character \fI-\fR, it is taken to be the -name of a file containing a \fIstartup script\fR, which \fBTcl_Main\fR -will attempt to evaluate. Otherwise, \fBTcl_Main\fR will enter an -interactive mode. +\fBTcl_Main\fR supports two modes of operation, depending on +whether the filename and encoding of a startup script has been +established. The routines \fBTcl_SetStartupScript\fR and +\fBTcl_GetStartupScript\fR are the tools for controlling this +configuration of \fBTcl_Main\fR. +.PP +\fBTcl_SetStartupScript\fR registers the value \fIpath\fR +as the name of the file for \fBTcl_Main\fR to evaluate as +its startup script. The value \fIencoding\fR is Tcl's name +for the encoding used to store the text in that file. A +value of \fBNULL\fR for \fIencoding\fR is a signal to use +the system encoding. A value of \fBNULL\fR for \fIpath\fR +erases any existing registration so that \fBTcl_Main\fR +will not evaluate any startup script. .PP -In either mode, \fBTcl_Main\fR will define in its master interpreter +\fBTcl_GetStartupScript\fR queries the registered file name +and encoding set by the most recent \fBTcl_SetStartupScript\fR +call in the same thread. The stored file name is returned, +and the stored encoding name is written to space pointed to +by \fIencodingPtr\fR, when that is not NULL. +.PP +The file name and encoding values managed by the routines +\fBTcl_SetStartupScript\fR and \fBTcl_GetStartupScript\fR +are stored per-thread. Although the storage and retrieval +functions of these routines work in any thread, only those +calls in the same master thread as \fBTcl_Main\fR can have +any influence on it. +.PP +The caller of \fBTcl_Main\fR may call \fBTcl_SetStartupScript\fR +first to establish its desired startup script. If \fBTcl_Main\fR +finds that no such startup script has been established, it consults +the first few arguments in \fIargv\fR. If they match +?\fB\-encoding \fIname\fR? \fIfileName\fR, +where \fIfileName\fR does not begin with the character \fI\-\fR, +then \fIfileName\fR is taken to be the name of a file containing +a \fIstartup script\fR, and \fIname\fR is taken to be the name +of the encoding of the contents of that file. \fBTcl_Main\fR +then calls \fBTcl_SetStartupScript\fR with these values. +.PP +\fBTcl_Main\fR then defines in its master interpreter the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR. .PP When it has finished its own initialization, but before it processes commands, \fBTcl_Main\fR calls the procedure given by the -\fIappInitProc\fR argument. This procedure provides a ``hook'' for -the application to perform its own initialization of the interpreter +\fIappInitProc\fR argument. This procedure provides a +.QW hook +for the application to perform its own initialization of the interpreter created by \fBTcl_Main\fR, such as defining application-specific -commands. The procedure must have an interface that matches the -type \fBTcl_AppInitProc\fR: +commands. The application initialization routine might also +call \fBTcl_SetStartupScript\fR to (re-)set the file and encoding +to be used as a startup script. The procedure must have an interface +that matches the type \fBTcl_AppInitProc\fR: +.PP .CS -typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR); +typedef int \fBTcl_AppInitProc\fR( + Tcl_Interp *\fIinterp\fR); .CE - +.PP \fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more details on this procedure, see the documentation for \fBTcl_AppInit\fR. .PP -When the \fIappInitProc\fR is finished, \fBTcl_Main\fR enters one -of its two modes. If a startup script has been provided, \fBTcl_Main\fR -attempts to evaluate it. Otherwise, interactive mode begins with -examination of the variable \fItcl_rcFileName\fR in the master -interpreter. If that variable exists and holds the name of a readable -file, the contents of that file are evaluated in the master interpreter. -Then interactive operations begin, +When the \fIappInitProc\fR is finished, \fBTcl_Main\fR calls +\fBTcl_GetStartupScript\fR to determine what startup script has +been requested, if any. If a startup script has been provided, +\fBTcl_Main\fR attempts to evaluate it. Otherwise, interactive +mode begins with examination of the variable \fItcl_rcFileName\fR +in the master interpreter. If that variable exists and holds the +name of a readable file, the contents of that file are evaluated +in the master interpreter. Then interactive operations begin, with prompts and command evaluation results written to the standard output channel, and commands read from the standard input channel and then evaluated. The prompts written to the standard output @@ -116,7 +166,6 @@ The prompts and command evaluation results are written to the standard output channel only if the Tcl variable \fItcl_interactive\fR in the master interpreter holds a non-zero integer value. .PP -.VS 8.4 \fBTcl_SetMainLoop\fR allows setting an event loop procedure to be run. This allows, for example, Tk to be dynamically loaded and set its event loop. The event loop will run following the startup script. If you @@ -126,10 +175,10 @@ When the loop procedure returns in interactive mode, interactive operation will continue. The main loop procedure must have an interface that matches the type \fBTcl_MainLoopProc\fR: +.PP .CS -typedef void Tcl_MainLoopProc(void); +typedef void \fBTcl_MainLoopProc\fR(void); .CE -.VE 8.4 .PP \fBTcl_Main\fR does not return. Normally a program based on \fBTcl_Main\fR will terminate when the \fBexit\fR command is @@ -140,10 +189,8 @@ procedure (if any) returns. In non-interactive mode, after \fBTcl_Main\fR evaluates the startup script, and the main loop procedure (if any) returns, \fBTcl_Main\fR will also evaluate the \fBexit\fR command. - .SH "SEE ALSO" tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3), -exit(n) - +exit(n), encoding(n) .SH KEYWORDS application-specific initialization, command-line arguments, main program |