cltcl

API Reference

cltcl

Embed Tcl/Tk scripts in Common Lisp

CLTCL

  • Function READ-SCRIPT (&optional (stream *standard-input*) 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*.
  • Function READ-LIST (&optional (stream *standard-input*) 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.
  • Function READ-WORD (stream &optional (eof-error-p t) 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.
  • Function READ-TCL-LIST-FROM-STRING1 (string)
    Converts Tcl list STRING into a list of strings. Items are delimited by whitespace.
  • 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.
  • 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.
  • Function ESCAPE (x)
    Escapes all characters that have a special meaning for Tcl (includes whitespace) with a backslash.
  • 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.
  • 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.
  • 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.
  • 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.
  • Function RECEIVE-LINE (stream)
    Reads a Tcl list from STREAM including the terminating character. Returns nil if an end of file occurs.
  • Variable *INTERPRETER*
    "/usr/bin/wish"
    The default Tcl/Tk interpreter. Default value is /usr/bin/wish.
  • Variable *STREAM*
    nil
    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.
  • Variable *TRACE-LEVEL*
    -1
    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.
  • Variable *DEBUG*
    nil
    If not nil the commands of a script are send one by one to the interpreter. This eases localization of errors. Default nil.
  • Function EVENT-LOOP (script &key (interpreter *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.
  • 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*.
  • 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*.
  • 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.
  • Function KEEP-LISTENING
    A restart applicable during errors in events. Transfers control back to Tcl and resumes listening.
  • Function REPL
    A read-eval-print loop. Useful for development. Prompts for commands to send to the Tcl/Tk interpreter and prints the reply.