tclsh(1tcl)

tclsh -- simple shell containing Tcl interpreter

Synopsis

tclsh [-qn] [-f] [script]|[-c command] [args]

Description

tclsh is a shell-like application that reads Tcl commands from its standard input or from a file, and evaluates them. If invoked with no arguments then it runs interactively, reading Tcl commands from standard input and printing command results and error messages to standard output. It runs until the exit(1tcl) command is invoked or until it reaches end-of-file on its standard input. If a file called .tclshrc exists in the home directory of the user, tclsh evaluates the file as a Tcl script just before reading the first command from standard input.

Script files

If script is specified, then the script is executed non-interactively with any additional arguments, args, being supplied in the global Tcl variable argv. If command is supplied, then this command (or semicolon-separated series of commands) is executed, with argv containing any args.

The Tcl shell is intended as an environment for Tcl program development and execution. While it is not a full-featured interactive shell, it provides a comfortable environment for the interactive development of Tcl code. Note that the package library code described here overrides the unknown command provided as part of the standard Berkeley Tcl library facility, although Tcl source libraries coded to that standard can be loaded and used by Extended Tcl.

The following command-line flags are recognized by the Tcl shell command line parser:

-q: Quick initialization flag. The Tcl initialization file is not evaluated and the auto_path variable is not set. Tcl auto-load libraries will not be available.
-n: No procedure call stack dump. The procedure call stack will not be displayed when an error occurs, only the error message. Useful in the ``#!'' line of already debugged scripts.
-f: Takes the next argument as a script for Tcl to source, rather than entering interactive mode. The -f flag is optional. Normally the first argument that does not start with a ``-'' is taken as the script to execute unless the -c option is specified. Any following arguments are passed to the script via argv, thus any other Tcl shell command-line flags must precede this option.
-c: Take the next argument as a Tcl command to execute. It may contain series of commands to execute, separated by ``;''. Any following arguments are passed in argv, thus, as with -f, any other Tcl shell flags must precede this option.
--: Mark the end of the arguments to the Tcl shell. All arguments following this are passed in the Tcl variable argv. This is useful to pass arguments without attempting to execute a Tcl script.

If you create a Tcl script in a file whose first line is

   #!/bin/tcl

then you can invoke the script file directly from your shell if you mark the file as executable.

Variables

tclsh sets the following Tcl variables:

argv0: Contains the name of the Tcl program specified on the command line or the name that the Tcl shell was invoked under if no program was specified.
argc: Contains a count of the number of argv arguments (0 if none).
argv: A list containing the arguments passed in from the command line, excluding arguments used by the Tcl shell. The first element is the first passed argument, not the program name.
tcl_interactive: Set to 1 if the Tcl shell is invoked interactively, or 0 if the Tcl shell is directly executing a script. Scripts can check whether this variable should function as a standalone application if specified on the command line, or simply load it in and not execute it, if loaded during an interactive invocation of Tcl.
auto_path: Path to search to locate Tcl scripts. Used by the auto_load command and the unknown(1tcl) command handler. The path is a Tcl list of directory names.
tcl_prompt1: Contains code to generate the prompt used when interactively prompting for commands.
tcl_prompt2: Contains code to generate the prompt used when interactively prompting for continuation of an incomplete command.
TCLXENV: Array that contains information used internally by various Tcl procedures that are part of the TclX shell.

Prompts

When tclsh is invoked interactively it normally prompts for each command with ``% ''. You can change the prompt by setting the variables tcl_prompt1 and tcl_prompt2. If variable tcl_prompt1 exists then it must consist of a Tcl script to output a prompt; instead of outputting a prompt tclsh will evaluate the script in tcl_prompt1. The variable tcl_prompt2 is used in a similar way when a newline is typed but the current command isn't yet complete; if tcl_prompt2 isn't set then no prompt is output for incomplete commands.

The result string returned by a command executed from the command line is normally echoed back to the user. If an error occurs, then the result string is displayed, along with the error message. The error message will be preceded by the string ``Error:''.

The set command is a special case. If the command is called to set a variable (that is, with two arguments), then the result will not be echoed. If only one argument, the name of a variable, is supplied to set, then the result will be echoed.

If an unknown Tcl command is entered from the command line, then the UNIX command path, specified in the environment variable PATH, will be searched for a command of the same name. If the command is found, it will be executed with any arguments remaining on the Tcl command line being passed as arguments to the command. This feature is provided to enhance the interactive environment for developing Tcl scripts. Automatic execution of programs in this manner is only supported from the command line, not in script files in Tcl. Scripts should use the Tcl exec or system commands to run UNIX commands.

Initialization

The standard runtime files reside in the Tcl master directory. This master directory normally contains the Tcl initialization file (TclInit.tcl), the standard Tcl library file (tcl.tlib) and the help files. The Tcl master directory is named after the version of Tcl it is associated with, for example /usr/local/tclX/7.0a. The path to the Tcl master directory is available from the info library command. The location of the Tcl master directory can be overridden with the TCL_LIBRARY environment variable.

The first step in initializing the Tcl shell is to locate the Tcl initialization file, normally TclInit.tcl. If an environment variable TCLINIT exists, it contains the path to the Tcl initialization file. If the TCLINIT environment variable is not set, the file TclInit.tcl is used from the default Tcl master directory.

Tcl then evaluates the Tcl initialization file. The auto_path variable is initialized to the Tcl master directory and may be augmented by the initialization file or the application. Other procedures and variables used by the Extended Tcl shell are also defined by this file.

If the Tcl is invoked interactively, it will source a file named .tclrc in the user's home directory, if it exists. Tcl is viewed primarily as a programming language, not as an interactive shell, so the .tclrc is intended for loading development utilities, not for supporting applications, which should not have to rely on the user's environment in such a manner.