The cltcl Reference Manual

Table of Contents

The cltcl Reference Manual

This is the cltcl Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:40:00 2021 GMT+0.

1 Introduction

cltcl

Embed Tcl/Tk scripts in Common Lisp

Forked version from lisper99/cltcl in order to get it into QuickLisp.

Documentation from http://lisper99.github.io/cltcl/ added into folder doc.

Example package-viewer slightly modified and added to folder ex such that a quick test by (load "package-viewer.lisp") may be performed. You probably have to adjust the following paths at the top of the file:

;; Setup QuickLisp and load clTcl
(load "~/quicklisp/setup")
(ql:quickload :cltcl)

;; Define Tcl interpreter 
(defparameter *wish* "C:/Tcl/bin/wish86.exe")    ;; Windows
; (defparameter *wish* "/usr/bin/wish")          ;; Unix

See http://lisper99.github.io/cltcl/examples.html.

Loadable from Quicklisp since 1-NOV-2016

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cltcl

Author

Paul Griffioen

License

MIT, see file LICENSE

Description

Embed Tcl/Tk scripts in Common Lisp

Version

0.0.1

Source

cltcl.asd (file)

Components

• package.lisp (file)
• cltcl.lisp (file)
• communication.lisp (file)
• protocol.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cltcl.asd

Location

cltcl.asd

Systems

cltcl (system)

3.1.2 cltcl/package.lisp

Parent

cltcl (system)

Location

package.lisp

Packages

cltcl

3.1.3 cltcl/cltcl.lisp

Dependency

package.lisp (file)

Parent

cltcl (system)

Location

cltcl.lisp

Exported Definitions

• escape (function)
• format-script (function)
• read-list (function)
• read-script (function)
• read-tcl-list-from-string1 (function)
• read-word (function)
• write-list-to-tcl-string (function)

Internal Definitions

• clean-script (function)
• read-braced (function)
• read-comment (function)
• read-double-quoted (function)
• read-white-space (function)
• read-word-aux (function)
• write-escaped (function)
• write-escaped-char (function)
• write-tcl-string (function)

3.1.4 cltcl/communication.lisp

Dependency

cltcl.lisp (file)

Parent

cltcl (system)

Location

communication.lisp

Exported Definitions

• close-tcl/tk-stream (function)
• open-tcl/tk-stream (function)
• receive-line (function)
• send-script (function)
• with-tcl/tk (macro)

3.1.5 cltcl/protocol.lisp

Dependency

communication.lisp (file)

Parent

cltcl (system)

Location

protocol.lisp

Exported Definitions

• *debug* (special variable)
• *interpreter* (special variable)
• *stream* (special variable)
• *trace-level* (special variable)
• call (function)
• event-loop (function)
• keep-listening (function)
• post (function)
• repl (function)
• run (function)

Internal Definitions

• funa (function)
• func (function)
• handle-event (function)
• handshake (function)
• listen-for-reply (function)
• log-status (function)
• message-data (function)
• message-tag (function)
• receive-message (function)
• run-repl (function)
• run-script (function)
• run-sub-script (function)
• script-for-command (function)
• send-message (function)
• tcl/tk-setup-script (function)
• test (function)

4 Packages

Packages are listed by definition order.

4.1 cltcl

Source

package.lisp (file)

Use List

• common-lisp-user
• common-lisp

Exported Definitions

• *debug* (special variable)
• *interpreter* (special variable)
• *stream* (special variable)
• *trace-level* (special variable)
• call (function)
• close-tcl/tk-stream (function)
• escape (function)
• event-loop (function)
• format-script (function)
• keep-listening (function)
• open-tcl/tk-stream (function)
• post (function)
• read-list (function)
• read-script (function)
• read-tcl-list-from-string1 (function)
• read-word (function)
• receive-line (function)
• repl (function)
• run (function)
• send-script (function)
• with-tcl/tk (macro)
• write-list-to-tcl-string (function)

Internal Definitions

• clean-script (function)
• funa (function)
• func (function)
• handle-event (function)
• handshake (function)
• listen-for-reply (function)
• log-status (function)
• message-data (function)
• message-tag (function)
• read-braced (function)
• read-comment (function)
• read-double-quoted (function)
• read-white-space (function)
• read-word-aux (function)
• receive-message (function)
• run-repl (function)
• run-script (function)
• run-sub-script (function)
• script-for-command (function)
• send-message (function)
• tcl/tk-setup-script (function)
• test (function)
• write-escaped (function)
• write-escaped-char (function)
• write-tcl-string (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *debug*

If not nil the commands of a script are send one by one to the interpreter. This eases localization of errors. Default nil.

Package

cltcl

Source

protocol.lisp (file)

Special Variable: *interpreter*

The default Tcl/Tk interpreter. Default value is /usr/bin/wish.

Package

cltcl

Source

protocol.lisp (file)

Special Variable: *stream*

A two-way-stream connected to a Tcl/Tk interpreter or NIL if no such interpreter is running. This stream is used by functions CALL, POST and RUN.

Package

cltcl

Source

protocol.lisp (file)

Special Variable: *trace-level*

An integer that determines which events are traced in clTcl’s communication protocol between Lisp and Tcl/Tk. Setting a larger number gives trace messages. Level -1 (the default) is complete silence, level 0 is errors only, level 1 is errors and events, level 2 is errors, events and event details.

Package

cltcl

Source

protocol.lisp (file)

5.1.2 Macros

Macro: with-tcl/tk (VAR &rest ARGS) &body BODY

Uses OPEN-TCL/TK-STREAM to start a Tcl/Tk interpreter and connect to it by a two-way stream. Arguments ARGS are used as keyword arguments to OPEN-TCL/TK-STREAM. The forms in BODY are evaluated as an implicit progn with VAR bound to the stream returned by OPEN-TCL/TK-STREAM. When control leaves the body, either normally or abnormally, the stream is closed with CLOSE-TCL/TK-STREAM.

Package

cltcl

Source

communication.lisp (file)

5.1.3 Functions

Function: call COMMAND &rest ARGS

Calls Tcl/Tk command COMMAND with arguments ARGS properly escaped. Arguments of type symbol are writting to a string and prefixed with a hyphen to support keyword for Tcl options. Other arguments are written to string if necessary and properly escaped. This function is typically used in a event that was invoked in a clTcl script run by EVENT-LOOP. Sends the command to *STREAM*.

Package

cltcl

Source

protocol.lisp (file)

Function: close-tcl/tk-stream STREAM

Instructs the Tcl/Tk process associated with STREAM to exit and closes the stream. Arguments STREAM must be a stream created by OPEN-TCL/TK-STREAM. This function is implementation dependent.

Package

cltcl

Source

communication.lisp (file)

Function: escape X

Escapes all characters that have a special meaning for Tcl (includes whitespace) with a backslash.

Package

cltcl

Source

cltcl.lisp (file)

Function: event-loop SCRIPT &key INTERPRETER OPTIONS ARGUMENTS

Starts Tcl/Tk interpreter located at INTERPRETER, binds *STREAM* to the stream that connects to Tcl/Tk, binds *INTERPRETER* to INTERPRETER, runs SCRIPT on ARGUMENTS and starts listening on the stream. Use command ’exit’ to end the listener. Establishes a binding for restart KEEP-LISTENING to recover from errors in an event handler. The default value for INTERPRETER is *INTERPRETER. Keyword OPTIONS is passed to the interpreter.

Package

cltcl

Source

protocol.lisp (file)

Function: format-script SCRIPT &rest ARGS

Applies function FORMAT to SCRIPT’s commands sequentially. Each element consumes its required formatter arguments from ARGS, leaving the rest of the arguments for the rest of the commands. For clTcl script written with #TCL[...] this gives the effect of a single format on the entire Tcl code.

Package

cltcl

Source

cltcl.lisp (file)

Function: keep-listening ()

A restart applicable during errors in events. Transfers control back to Tcl and resumes listening.

Package

cltcl

Source

protocol.lisp (file)

Function: open-tcl/tk-stream &key INTERPRETER OPTIONS

Starts a Tcl/Tk interpreter and creates and returns a two-way stream connected to this Tcl/Tk process. This function and the meaning of arguments INTERPRETER and OPTIONS are implementation dependent.

Package

cltcl

Source

communication.lisp (file)

Function: post COMMAND &rest ARGS

Posts Tcl/Tk command COMMAND with arguments ARGS properly escaped as an event and does not wait for a reply. Arguments of type symbol are writting to a string and prefixed with a hyphen to support keyword for Tcl options. Other arguments are written to string if necessary and properly escaped. Sends the command to *STREAM*.

Package

cltcl

Source

protocol.lisp (file)

Function: read-list &optional STREAM TERMINATOR

Reads a Tcl list from STREAM. Reads Tcl words until an end of file occurs or READ-WORD finds TERMINATOR (when given), a semi-colon or a newline. The Tcl list is returned as a string. The default value for STREAM is *STANDARD-INPUT*. Returns NIL if end of file is found immediately.

Package

cltcl

Source

cltcl.lisp (file)

Function: read-script &optional STREAM TERMINATOR

Reads a Tcl script from STREAM. Reads Tcl commands until READ-LIST finds TERMINATOR (when given) or an end of file occurs. Returns the commands as a list of strings. The default value for STREAM is *STANDARD-INPUT*.

Package

cltcl

Source

cltcl.lisp (file)

Function: read-tcl-list-from-string1 STRING

Converts Tcl list STRING into a list of strings. Items are delimited by whitespace.

Package

cltcl

Source

cltcl.lisp (file)

Function: read-word STREAM &optional EOF-ERROR-P EOF-VALUE RECURSIVE-P TERMINATOR ECHO-P

Reads a Tcl word from STREAM and returns it as a string. Reads characters untill the next one is a terminator. The terminator itself is not read. Terminators are TERMINATOR (when given), whitespace or Tcl list terminators. Throws an error if an end of file occurs, unless EOF-ERROR-P is nil, in which case it returns EOF-VALUE. If ECHO-P is non nil then escape characters are not handled and the word is literally copied.

Package

cltcl

Source

cltcl.lisp (file)

Function: receive-line STREAM

Reads a Tcl list from STREAM including the terminating character. Returns nil if an end of file occurs.

Package

cltcl

Source

communication.lisp (file)

Function: repl ()

A read-eval-print loop. Useful for development. Prompts for commands to send to the Tcl/Tk interpreter and prints the reply.

Package

cltcl

Source

protocol.lisp (file)

Function: run SCRIPT &rest ARGS

Sends SCRIPT via *STREAM* to Tcl/Tk and waits for a reply. This function is typically used in a event that was invoked in a clTcl script run by EVENT-LOOP. Sets Tcl/Tk variable argv to ARGS, properly escaped.

Package

cltcl

Source

protocol.lisp (file)

Function: send-script STREAM SCRIPT

Sends clTcl script SCRIPT to a running Tcl/Tk interpreter via stream STREAM. The stream must be one that was opened with OPEN-TCL/TK-STREAM. The script must be a list of strings, each string being a valid Tcl command.

Package

cltcl

Source

communication.lisp (file)

Function: write-list-to-tcl-string LIST

Converts list to a Tcl string. Nested lists are converted recursively. Strings are escaped. Other values are written to string and escaped.

Package

cltcl

Source

cltcl.lisp (file)

5.2 Internal definitions

5.2.1 Functions

Function: clean-script SCRIPT

Removes all empty strings and comments from command list SCRIPT.

Package

cltcl

Source

cltcl.lisp (file)

Function: funa ()

Helper for TEST

Package

cltcl

Source

protocol.lisp (file)

Function: func ()

Helper for TEST

Package

cltcl

Source

protocol.lisp (file)

Function: handle-event EVENT

Handles EVENT that was read from a Tcl/Tk stream. Calls the requested Lisp function and returns the results. Restart KEEP-LISTENING is available during the event.

Package

cltcl

Source

protocol.lisp (file)

Function: handshake STREAM

Sends a message to Tcl/Tk stream to test if it responds. Throws an error when no appropriate message comes back.

Package

cltcl

Source

protocol.lisp (file)

Function: listen-for-reply STREAM

Receives messages from STREAM until a reply is received. Incoming events and errors are handled. Returns the data from the reply.

Package

cltcl

Source

protocol.lisp (file)

Function: log-status LEVEL CONTROL-STRING &rest ARGUMENTS

Writes formatted text to *TRACE-OUTPUT* if LEVEL is at least as high as *TRACE-LEVEL*. Level 0 is for errors, level 1 is for events, level 2 is for event details.

Package

cltcl

Source

protocol.lisp (file)

Function: message-data MESSAGE

The data of the message obtained with RECEIVE-MESSAGE. The contents depends on the type of message.

Package

cltcl

Source

protocol.lisp (file)

Function: message-tag MESSAGE

The tag of the message obtained with RECEIVE-MESSAGE. One of the symbols :reply, :event or :error.

Package

cltcl

Source

protocol.lisp (file)

Function: read-braced STREAM &optional ECHO-P

Reads a Tcl braced expression from STREAM.

Package

cltcl

Source

cltcl.lisp (file)

Function: read-comment STREAM

Reads a line of Tcl comment from STREAM but leaves the newline.

Package

cltcl

Source

cltcl.lisp (file)

Function: read-double-quoted STREAM &optional ECHO-P

Reads a Tcl double quoted expression from STREAM.

Package

cltcl

Source

cltcl.lisp (file)

Function: read-white-space STREAM

Reads white space from STREAM, except newlines.

Package

cltcl

Source

cltcl.lisp (file)

Function: read-word-aux STREAM EOF-ERROR-P TERMINATOR ECHO-P

Helper for READ-WORD.

Package

cltcl

Source

cltcl.lisp (file)

Function: receive-message STREAM

Attempts to read a message from stream. Functions MESSAGE-TAG yields the tag of the message. Function MESSAGE-DATA yields the data. Counterpart of Tcl proc sendMessage

Package

cltcl

Source

protocol.lisp (file)

Function: run-repl &rest ARGS &key TRACE-LEVEL &allow-other-keys

Stub to test function REPL. Demonstrates how the repl might be added to an application via an event-handler.

Package

cltcl

Source

protocol.lisp (file)

Function: run-script SCRIPT &optional STREAM

Sends a script directly to the Tcl/Tk interpreter and waits for a reply.

Package

cltcl

Source

protocol.lisp (file)

Function: run-sub-script SCRIPT &optional STREAM

Sends a script to the listener that triggered the event that triggered this call and waits for a reply. The script is picked up and evaluated by a listener at the Tcl/Tk side.

Package

cltcl

Source

protocol.lisp (file)

Function: script-for-command COMMAND ARGUMENTS

Script that performs command with all arguments safely escaped.

Package

cltcl

Source

protocol.lisp (file)

Function: send-message STREAM TAG MESSAGE

Counterpart is Tcl proc receiveMessage

Package

cltcl

Source

protocol.lisp (file)

Function: tcl/tk-setup-script ()

Script that creates Tcl procedures in Tcl/Tk to communicate to Lisp.

Package

cltcl

Source

protocol.lisp (file)

Function: test &rest ARGS &key TRACE-LEVEL &allow-other-keys

Tests the connection with Tcl/Tk and displays systems
information. Sets *TRACE-LEVEL* to TRACE-LEVEL. The other keywords are passed to the event handler. See OPEN-TCL/TK-STREAM for allowed keywords.

Package

cltcl

Source

protocol.lisp (file)

Function: write-escaped X STREAM

Escapes all characters that have a special meaning for Tcl (includes whitespace) with a backslash.

Package

cltcl

Source

cltcl.lisp (file)

Function: write-escaped-char CHAR STREAM

Writes character CHAR to stream. Special Tcl escape characters \b, \f, \r,\n and \t are converted.

Package

cltcl

Source

cltcl.lisp (file)

Function: write-tcl-string OBJECT &optional STREAM RECURSIVEP

Converts list to a Tcl string. Nested lists are converted recursively. Strings are escaped. Other values are written to string and escaped.

Package

cltcl

Source

cltcl.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types