SYNOPSIS

cc <source> -ljim

or

jimsh [<scriptfile>]
jimsh -e '<immediate-script>'
jimsh --version
Quick Index

INTRODUCTION

Jim Tcl is a small footprint reimplementation of the Tcl scripting language. The core language engine is compatible with Tcl 8.5+, while implementing a significant subset of the Tcl 8.6 command set, plus additional features available only in Jim Tcl.

Some notable differences with Tcl 8.5/8.6 are:

  1. Object-based I/O (aio), but with a Tcl-compatibility layer

  2. I/O: Support for sockets and pipes including udp, unix domain sockets and IPv6

  3. Integers are 64bit

  4. Support for references (ref/getref/setref) and garbage collection

  5. Builtin dictionary type (dict) with some limitations compared to Tcl 8.6

  6. env command to access environment variables

  7. Operating system features: os.fork, os.wait, os.uptime, signal, alarm, sleep

  8. Much better error reporting. info stacktrace as a replacement for $errorInfo, $errorCode

  9. Support for "static" variables in procedures

  10. Threads and coroutines are not supported

  11. Command and variable traces are not supported

  12. Built-in command line editing

  13. Expression shorthand syntax: $(…)

  14. Modular build allows many features to be omitted or built as dynamic, loadable modules

  15. Highly suitable for use in an embedded environment

  16. Support for UDP, IPv6, Unix-Domain sockets in addition to TCP sockets

RECENT CHANGES

Changes between 0.74 and 0.75

  1. binary, pack and unpack now support floating point

  2. file copy -force handles source and target as the same file

  3. format now supports %b for binary conversion

  4. lsort now supports -unique and -real

  5. Add support for half-close with aio close ?r|w?

  6. Add socket pair for a bidirectional pipe

  7. Add --random-hash to randomise hash tables for greater security

  8. dict now supports for, values, incr, append, lappend, update, info and replace

  9. file stat no longer requires the variable name

Changes between 0.73 and 0.74

  1. Numbers with leading zeros are treated as decimal, not octal

  2. Add aio isatty

  3. Add LFS (64 bit) support for aio seek, aio tell, aio copyto, file copy

  4. string compare and string equal now support -length

  5. glob now supports -directory

Changes between 0.72 and 0.73

  1. Built-in regexp now support non-capturing parentheses: (?:…)

  2. Add string replace

  3. Add string totitle

  4. Add info statics

  5. Add build-jim-ext for easy separate building of loadable modules (extensions)

  6. local now works with any command, not just procs

  7. Add info alias to access the target of an alias

  8. UTF-8 encoding past the basic multilingual plane (BMP) is supported

  9. Add tcl::prefix

  10. Add history

  11. Most extensions are now enabled by default

  12. Add support for namespaces and the namespace command

  13. Add apply

Changes between 0.71 and 0.72

  1. procs now allow args and optional parameters in any position

  2. Add Tcl-compatible expr functions, rand(), srand() and pow()

  3. Add support for the -force option to file delete

  4. Better diagnostics when source fails to load a script with a missing quote or bracket

  5. New tcl_platform(pathSeparator)

  6. Add support settings the modification time with file mtime

  7. exec is now fully supported on win32 (mingw32)

  8. file join, pwd, glob etc. now work for mingw32

  9. Line editing is now supported for the win32 console (mingw32)

  10. Add aio listen command

Changes between 0.70 and 0.71

  1. Allow args to be renamed in procs

  2. Add $(…) shorthand syntax for expressions

  3. Add automatic reference variables in procs with &var syntax

  4. Support jimsh --version

  5. Additional variables in tcl_platform()

  6. local procs now push existing commands and upcall can call them

  7. Add loop command (TclX compatible)

  8. Add aio buffering command

  9. info complete can now return the missing character

  10. binary format and binary scan are now (optionally) supported

  11. Add string byterange

  12. Built-in regexp now support non-greedy repetition (*?, +?, ??)

TCL INTRODUCTION

Tcl stands for tool command language and is pronounced tickle. It is actually two things: a language and a library.

First, Tcl is a simple textual language, intended primarily for issuing commands to interactive programs such as text editors, debuggers, illustrators, and shells. It has a simple syntax and is also programmable, so Tcl users can write command procedures to provide more powerful commands than those in the built-in set.

Second, Tcl is a library package that can be embedded in application programs. The Tcl library consists of a parser for the Tcl language, routines to implement the Tcl built-in commands, and procedures that allow each application to extend Tcl with additional commands specific to that application. The application program generates Tcl commands and passes them to the Tcl parser for execution. Commands may be generated by reading characters from an input source, or by associating command strings with elements of the application’s user interface, such as menu entries, buttons, or keystrokes.

When the Tcl library receives commands it parses them into component fields and executes built-in commands directly. For commands implemented by the application, Tcl calls back to the application to execute the commands. In many cases commands will invoke recursive invocations of the Tcl interpreter by passing in additional strings to execute (procedures, looping commands, and conditional commands all work in this way).

An application program gains three advantages by using Tcl for its command language. First, Tcl provides a standard syntax: once users know Tcl, they will be able to issue commands easily to any Tcl-based application. Second, Tcl provides programmability. All a Tcl application needs to do is to implement a few application-specific low-level commands. Tcl provides many utility commands plus a general programming interface for building up complex command procedures. By using Tcl, applications need not re-implement these features.

Third, Tcl can be used as a common language for communicating between applications. Inter-application communication is not built into the Tcl core described here, but various add-on libraries, such as the Tk toolkit, allow applications to issue commands to each other. This makes it possible for applications to work together in much more powerful ways than was previously possible.

Fourth, Jim Tcl includes a command processor, jimsh, which can be used to run standalone Tcl scripts, or to run Tcl commands interactively.

This manual page focuses primarily on the Tcl language. It describes the language syntax and the built-in commands that will be available in any application based on Tcl. The individual library procedures are described in more detail in separate manual pages, one per procedure.

JIMSH COMMAND INTERPRETER

A simple, but powerful command processor, jimsh, is part of Jim Tcl. It may be invoked in interactive mode as:

jimsh

or to process the Tcl script in a file with:

jimsh filename

It may also be invoked to execute an immediate script with:

jimsh -e "script"

Interactive Mode

Interactive mode reads Tcl commands from standard input, evaluates those commands and prints the results.

$ jimsh
Welcome to Jim version 0.73, Copyright (c) 2005-8 Salvatore Sanfilippo
. info version
0.73
. lsort [info commands p*]
package parray pid popen proc puts pwd
. foreach i {a b c} {
{> puts $i
{> }
a
b
c
. bad
invalid command name "bad"
[error] . exit
$

If jimsh is configured with line editing (it is by default) and a VT-100-compatible terminal is detected, Emacs-style line editing commands are available, including: arrow keys, ^W to erase a word, ^U to erase the line, ^R for reverse incremental search in history. Additionally, the h command may be used to display the command history.

Command line history is automatically saved and loaded from ~/.jim_history

In interactive mode, jimsh automatically runs the script ~/.jimrc at startup if it exists.

INTERPRETERS

The central data structure in Tcl is an interpreter (C type Jim_Interp). An interpreter consists of a set of command bindings, a set of variable values, and a few other miscellaneous pieces of state. Each Tcl command is