Manual Pages for UNIX Darwin command on man Tcl

Manual Pages for UNIX Darwin command on man Tcl_SetMainLoop

TclMain(3) Tcl Library Procedures TclMain(3)

NAME

TclMain, TclSetMainLoop - main program and event loop definition for

Tcl-based applications

SYNOPSIS

##iinncclluuddee <>

TTccllMMaaiinn(argc, argv, appInitProc) TTccllSSeettMMaaiinnLLoooopp(mainLoopProc) AARRGGUUMMEENNTTSS int argc (in) Number of elements in argv. char *argv[] (in) Array of strings containing

command-line arguments.

TclAppInitProc *appInitProc (in) Address of an application-

specific initialization pro-

cedure. The value for this argument is usually TTccllAAppppIInniitt.

TclMainLoopProc *mainLoopProc (in) Address of an application-

specific event loop proce-

dure.

DESCRIPTION

TTccllMMaaiinn can serve as the main program for Tcl-based shell applica-

tions. A ``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. TTccllMMaaiinn is offered as a convenience to developers of shell applications, so they do not have to reproduce all of the code for proper initialization of the Tcl library and interactive shell operation. Other styles of embedding Tcl in an application are not supported by TTccllMMaaiinn. Those must be achieved by calling lower level functions in the Tcl library directly. The TTccllMMaaiinn 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 mmaaiinn, but that lacks flexibility of embedding style and having a function mmaaiinn in a library (particularly a shared library) causes problems on many systems. Having mmaaiinn in the Tcl library would also make it hard to use Tcl in C++ programs, since C++ programs must have special C++ mmaaiinn functions. Normally each shell application contains a small mmaaiinn function that does nothing but invoke TTccllMMaaiinn. TTccllMMaaiinn then does all the work of

creating and running a ttccllsshh-like application.

TTccllMMaaiinn is not provided by the public interface of Tcl's stub library. Programs that call TTccllMMaaiinn must be linked against the standard Tcl

library. Extensions (stub-enabled or not) are not intended to call

TTccllMMaaiinn.

TTccllMMaaiinn is not thread-safe. It should only be called by a single mas-

ter thread of a multi-threaded application. This restriction is not a

problem with normal use described above. TTccllMMaaiinn and therefore all applications based upon it, like ttccllsshh, use TTccllGGeettSSttddCChhaannnneell to initialize the standard channels to their default values. See TTccllSSttaannddaarrddCChhaannnneellss for more information. TTccllMMaaiinn supports two modes of operation, depending on the values of argc and argv. If argv[1] exists and does not begin with the character

-, it is taken to be the name of a file containing a startup script,

which TTccllMMaaiinn will attempt to evaluate. Otherwise, TTccllMMaaiinn will enter an interactive mode. In either mode, TTccllMMaaiinn will define in its master interpreter the Tcl variables argc, argv, argv0, and tclinteractive, as described in the documentation for ttccllsshh. When it has finished its own initialization, but before it processes

commands, TTccllMMaaiinn calls the procedure given by the appInitProc argu-

ment. This procedure provides a ``hook'' for the application to per-

form its own initialization of the interpreter created by TTccllMMaaiinn,

such as defining application-specific commands. The procedure must

have an interface that matches the type TTccllAAppppIInniittPPrroocc: typedef int TclAppInitProc(TclInterp *interp); AppInitProc is almost always a pointer to TTccllAAppppIInniitt; for more details on this procedure, see the documentation for TTccllAAppppIInniitt. When the appInitProc is finished, TTccllMMaaiinn enters one of its two modes. If a startup script has been provided, TTccllMMaaiinn attempts to evaluate

it. Otherwise, interactive mode begins with examination of the vari-

able tclrcFileName 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 stan-

dard output channel, and commands read from the standard input channel and then evaluated. The prompts written to the standard output channel may be customized by defining the Tcl variables tclprompt1 and tclprompt2 as described in the documentation for ttccllsshh. The prompts

and command evaluation results are written to the standard output chan-

nel only if the Tcl variable tclinteractive in the master interpreter

holds a non-zero integer value.

TTccllSSeettMMaaiinnLLoooopp 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 | are in interactive mode, setting the main loop procedure will cause the | prompt to become fileevent based and then the loop procedure is called. |

When the loop procedure returns in interactive mode, interactive opera- |

tion will continue. The main loop procedure must have an interface | that matches the type TTccllMMaaiinnLLooooppPPrroocc: | typedef void TclMainLoopProc(void); | TTccllMMaaiinn does not return. Normally a program based on TTccllMMaaiinn will terminate when the eexxiitt command is evaluated. In interactive mode, if an EOF or channel error is encountered on the standard input channel, then TTccllMMaaiinn itself will evaluate the eexxiitt command after the main loop

procedure (if any) returns. In non-interactive mode, after TTccllMMaaiinn

evaluates the startup script, and the main loop procedure (if any) returns, TTccllMMaaiinn will also evaluate the eexxiitt command.