1. Introduction

This document describes the use of the Xtal language in interactive mode in Tcl shells. You can of course call the xtal::xtal command to invoke Xtal scripts in any standard Tcl interpreter with the xtal package loaded. However, using syntax like

xtal { i = 1 }

is inconvenient.

Instead the Xtal shell provides a means where Xtal syntax can be used alongside Tcl without having to be wrapped within xtal::xtal commands. So for instance you can type both the following equivalent Xtal and Tcl commands in the Xtal shell:

my_dict.key = "value"
dict set my_dict key value

2. Running the shell

The Xtal shell is not a separate program but rather a plug-in that is compatible several Tcl shells. In all cases, the Xtal shell is started in the same fashion - by running the xtal::shell command after loading the xtal package.

The Xtal shell can be used within the tclsh command line shell.

Xtal tclsh shell
Figure 1. Xtal shell in tclsh

It can also be used within the Wish console.

Xtal wish shell
Figure 2. Xtal shell in the wish console

And finally, it is also compatible with the popular tkcon enhanced Tk console.

Xtal tkcon shell
Figure 3. Xtal shell in tkcon

Notice the use of both Xtal and Tcl syntax in the shell.

3. Command execution

The Xtal shell reads the command input and uses heuristics to make a determination as to whether it is Xtal or Tcl and executes it accordingly.

When the command is added to the Tcl event history though, it is always added as a valid Tcl script, not Xtal. For example,

x = 10

would be added as

xtal::xtal { x = 10 }

This is to allow Tcl’s history command, which obviously knows nothing about Xtal, to work correctly.

You can use the -lang option to the shell at any time to control which languages are accepted by the shell.

4. Shell options

The shell supports several options shown in Xtal shell options. These may be specified when the shell is started or changed when it is running, in both cases using the xtal::shell command.

Table 1. Xtal shell options


Specifies the language for input commands. The default value auto results in the shell accepting both Tcl and Xtal syntax. If set it to tcl or xtal, the shell will only interpret input for that language.

-prettify BOOLEAN

If true (default), the Xtal shell tries to format the output of commands in a more user-friendly format. If false, command output is printed as a raw string as in the standard Tcl shell. See Result formatting.

5. Result formatting

Unlike the standard Tcl shells, the Xtal shell does not print the raw string values but rather tries to present a more readable format as shown in the example below.

Xtal shell output
Figure 4. Xtal shell output

In the case of large tables or columns, the output will only include the first few and last few items separated by ellipsis. To see all items, you need to explicitly use the tarray::print command with the appropriate options.

Similarly, to see the string format as in Tcl shells, use the puts command to explicitly print results.

Alternatively, you can turn pretty-printing on and off with the -prettify option to the shell.

6. Bugs and caveats

Error traces

Because Xtal is translated to Tcl for execution, the error stack reflects the translated Tcl code, not the original Xtal source for nested calls.


The heuristics for determining Xtal are a work-in-progress and may in some cases guess wrong. In such cases, you can explicitly wrap Xtal as


and Tcl as



Syntax confusion

It is worth stressing the different syntax used by Xtal and Tcl, particularly with respect to variable referencing and list construction as illustrated by the following short sequence in an Xtal shell.

% x = 1
→ 1
% a = x                 1
→ 1
% set a x               2
→ x
% set a $x              3
→ 1
% l = {a, x, 1}         4
→ 1 1 1
% set l {a, x, 1}       5
→ a, x, 1
% set l [list $a $x 1]  6
→ 1 1 1
1 (Xtal) Assigns content of variable x
2 (Tcl) Assigns string "x"
3 (Tcl) Assigns content of variable x
4 (Xtal) List construction
5 (Tcl) Assigns string
6 (Tcl) List construction

It is easy to get tripped up by these differences.