tcl

README

tcl

Package tcl is a CGo-free port of the Tool Command Language (Tcl).

Tcl is a very powerful but easy to learn dynamic programming language, suitable for a very wide range of uses, including web and desktop applications, networking, administration, testing and many more.

Documentation

Overview

Package tcl is a CGo-free port of the Tool Command Language (Tcl).

Tcl is a very powerful but easy to learn dynamic programming language, suitable for a very wide range of uses, including web and desktop applications, networking, administration, testing and many more.

A separate Tcl shell is in the gotclsh directory.

Changelog:

2020-09-13 v1.4.0 supports linux/{amd64,386,arm,arm64}. The arm, arm64 ports fail the http tests.

2020-09-03 v1.2.0 is now completelely CGo-free.

2020-08-04: beta2 released for linux/amd64 only. Support for threads, sockets and fork is not yet implemented. Some tests still crash, those are disabled at the moment.

Index

• func Library(directory string) error
• func LibraryFileSystem() http.FileSystem
• func MountFileSystem(point string, files map[string]string) error
• func MountLibraryVFS() (string, error)
• func UnmountFileSystem(point string) error
• type CmdProc
• type Command
• type DeleteProc
• type Interp
  • func MustNewInterp() *Interp
  • func NewInterp() (*Interp, error)
  • func (in *Interp) Close() error
  • func (in *Interp) Eval(script string) (string, error)
  • func (in *Interp) Handle() uintptr
  • func (in *Interp) MustClose()
  • func (in *Interp) MustEval(script string) string
  • func (in *Interp) MustNewCommand(name string, proc CmdProc, clientData interface{}, del DeleteProc) *Command
  • func (in *Interp) NewCommand(name string, proc CmdProc, clientData interface{}, del DeleteProc) (*Command, error)
  • func (in *Interp) SetResult(s string) error
  • func (in *Interp) TLS() *libc.TLS

Examples

• Interp.Eval
• Interp.NewCommand

Functions

func Library

func Library(directory string) error

Library writes the Tcl library to directory.

func LibraryFileSystem

func LibraryFileSystem() http.FileSystem

LibraryFileSystem returns a http.FileSystem containing the Tcl library.

func MountFileSystem

func MountFileSystem(point string, files map[string]string) error

MountFileSystem mounts a virtual file system at point, which should be an absolute, slash separated path. The map keys must be rooted unix slash-separated paths. The file content is whatever the associated map value is. The resulting path of the VFS is the join of point and the map key.

func MountLibraryVFS

func MountLibraryVFS() (string, error)

MountLibraryVFS mounts the Tcl library virtual file system and returns the mount point. This is how it's used, for example, in gotclsh:

package main

import (
	"os"

	"modernc.org/libc"
	"modernc.org/tcl"
	"modernc.org/tcl/internal/tclsh"
)

const envVar = "TCL_LIBRARY"

func main() {
	if os.Getenv(envVar) == "" {
		if s, err := tcl.MountLibraryVFS(); err == nil {
			os.Setenv(envVar, s)
		}
	}
	libc.Start(tclsh.Main)
}

func UnmountFileSystem

func UnmountFileSystem(point string) error

UnmountFileSystem unmounts a virtual file system at point, which should be an absolute, slash separated path.

Types

type CmdProc

type CmdProc func(clientData interface{}, in *Interp, args []string) int

CmdProc is a Tcl command implemented in Go.

type Command

type Command struct {
	// contains filtered or unexported fields
}

Command represents a Tcl command.

type DeleteProc

type DeleteProc func(clientData interface{})

DeleteProc is a function called when CmdProc is deleted.

type Interp

type Interp struct {
	// contains filtered or unexported fields
}

Interp represents a Tcl interpreter.

func MustNewInterp

func MustNewInterp() *Interp

MustNewInterp is like NewInterp but panics on error.

func NewInterp

func NewInterp() (*Interp, error)

NewInterp returns a newly created Interp or an error, if any.

func (*Interp) Close

func (in *Interp) Close() error

Close invalidates the interpreter and releases all its associated resources.

func (*Interp) Eval

func (in *Interp) Eval(script string) (string, error)

Eval evaluates script and returns the interpreter; result and error, if any.

Example

in := MustNewInterp()
s := in.MustEval(`

# This is the Tcl script
# ----------------------
set a 42
incr a
# ----------------------

`)
in.MustClose()
fmt.Println(s)

Output:

43

func (*Interp) Handle

func (in *Interp) Handle() uintptr

Handle returns the handle of the underlying interpreter. It is used when calling libtcl directly. For example:

import (
	"modernc.org/libc"
	"modernc.org/tcl"
	libtcl "modernc.org/tcl/lib"
)

in := tcl.MustNewInterp()
returnCode := libtcl.XTcl_Eval(in.TLS(), in.Handle(), "set a 42")
returnString := libc.GoString(libtcl.XTcl_GetStringResult(in.TLS(), in.Handle()))

func (*Interp) MustClose

func (in *Interp) MustClose()

MustClose is like Close but panics on error.

func (*Interp) MustEval

func (in *Interp) MustEval(script string) string

MustEval is like Eval but panics on error.

func (*Interp) MustNewCommand

func (in *Interp) MustNewCommand(name string, proc CmdProc, clientData interface{}, del DeleteProc) *Command

MustNewCommand is like NewCommand but panics on error.

func (*Interp) NewCommand

func (in *Interp) NewCommand(name string, proc CmdProc, clientData interface{}, del DeleteProc) (*Command, error)

NewCommand returns a newly created Tcl command or an error, if any.

Example

in := MustNewInterp()
var delTrace string
in.MustNewCommand(
	"::go::echo",
	func(clientData interface{}, in *Interp, args []string) int {
		// Go implementation of the Tcl ::go::echo command
		args = append(args[1:], fmt.Sprint(clientData))
		in.SetResult(strings.Join(args, " "))
		return tcl.TCL_OK
	},
	42, // client data
	func(clientData interface{}) {
		// Go implemetation of the command delete handler
		delTrace = fmt.Sprint(clientData)
	},
)
fmt.Println(in.MustEval("::go::echo 123 foo bar"))
in.MustClose()
fmt.Println(delTrace)

Output:

123 foo bar 42
42

func (*Interp) SetResult

func (in *Interp) SetResult(s string) error

SetResult sets the result of the interpreter.

func (*Interp) TLS

func (in *Interp) TLS() *libc.TLS

TLS returns the thread local storage of the underlying interpreter. It is used when calling libtcl directly. For example:

import (
	"modernc.org/libc"
	"modernc.org/tcl"
	libtcl "modernc.org/tcl/lib"
)

in := tcl.MustNewInterp()
returnCode := libtcl.XTcl_Eval(in.TLS(), in.Handle(), "set a 42")
returnString := libc.GoString(libtcl.XTcl_GetStringResult(in.TLS(), in.Handle()))