/ 
Tcl-0.7
River stage two • 3 direct dependents • 17 total dependents
/ Tcl

NAME

Tcl - Tcl extension module for Perl

SYNOPSIS

use Tcl;

$interp = new Tcl;
$interp->Eval('puts "Hello world"');

DESCRIPTION

The Tcl extension module gives access to the Tcl library with functionality and interface similar to the C functions of Tcl. In other words, you can

create Tcl interpreters

The Tcl interpreters so created are Perl objects whose destructors delete the interpreters cleanly when appropriate.

execute Tcl code in an interpreter

The code can come from strings, files or Perl filehandles.

bind in new Tcl procedures

The new procedures can be either C code (with addresses presumably obtained using dl_open and dl_find_symbol) or Perl subroutines (by name, reference or as anonymous subs). The (optional) deleteProc callback in the latter case is another perl subroutine which is called when the command is explicitly deleted by name or else when the destructor for the interpreter object is explicitly or implicitly called.

Manipulate the result field of a Tcl interpreter
Set and get values of variables in a Tcl interpreter
Tie perl variables to variables in a Tcl interpreter

The variables can be either scalars or hashes.

Methods in class Tcl

To create a new Tcl interpreter, use

$i = new Tcl;

The following methods and routines can then be used on the Perl object returned (the object argument omitted in each case).

Init ()

Invoke Tcl_Init on the interpeter.

Eval (STRING)

Evaluate script STRING in the interpreter. If the script returns successfully (TCL_OK) then the Perl return value corresponds to interp->result otherwise a die exception is raised with the $@ variable corresponding to interp->result. In each case, corresponds means that if the method is called in scalar context then the string interp->result is returned but if the method is called in list context then interp->result is split as a Tcl list and returned as a Perl list.

GlobalEval (STRING)

Evalulate script STRING at global level. Otherwise, the same as Eval() above.

EvalFile (FILENAME)

Evaluate the contents of the file with name FILENAME. Otherwise, the same as Eval() above.

EvalFileHandle (FILEHANDLE)

Evaluate the contents of the Perl filehandle FILEHANDLE. Otherwise, the same as Eval() above. Useful when using the filehandle DATA to tack on a Tcl script following an __END__ token.

call (PROC, ARG, ...)

Looks up procedure PROC in the interpreter and invokes it directly with arguments (ARG, ...) without passing through the Tcl parser. For example, spaces embedded in any ARG will not cause it to be split into two Tcl arguments before being passed to PROC.

Before invoking procedure PROC special processing is performed on ARG list:

1. All subroutine references within ARG will be substituted with Tcl name which is responsible to invoke this subroutine. This Tcl name will be created using CreateCommand subroutine (see below).

2. All references to scalars will be substituted with names of Tcl variables transformed appropriately.

These first two items allows to write and expect it to work properly such code as:

my $r = 'aaaa';
button(".d", -textvariable => \$r, -command=>sub {$r++});

3. As a special case, it is supported a mechanism to deal with Tk's special event variables (they are mentioned as '%x', '%y' and so on throughout Tcl). Before suborutine reference that uses such variables there must be placed a reference to reference to a string that enumerates all desired fields. After this is done, access to event fields is performed via Tcl::Ev subroutine. Example:

$widget->bind('text', '<2>', \\'xy', sub {textPaste ($c)} );
sub textPaste {
  my ($w,$x,$y) = (shift, Tcl::Ev('x'), Tcl::Ev('y'));
  widget($w)->insert('text', "\@$x,$y", $interp->Eval('selection get'));
}
Tcl::Ev (FEILD)

Returns Tcl/Tk special event field designated by argument FIELD. FIELD must be single character. Before invoking Tcl::Ev a subroutine that will call it must enlist appropriate fields in argument list before appropriate code reference in call to Tcl. See description of 'call' method for details.

result ()

Returns the current interp->result field. List v. scalar context is handled as in Eval() above.

CreateCommand (CMDNAME, CMDPROC, CLIENTDATA, DELETEPROC)

Binds a new procedure named CMDNAME into the interpreter. The CLIENTDATA and DELETEPROC arguments are optional. There are two cases:

(1) CMDPROC is the address of a C function

(presumably obtained using dl_open and dl_find_symbol. In this case CLIENTDATA and DELETEPROC are taken to be raw data of the ClientData and deleteProc field presumably obtained in a similar way.

(2) CMDPROC is a Perl subroutine

(either a sub name, a sub reference or an anonymous sub). In this case CLIENTDATA can be any perl scalar (e.g. a ref to some other data) and DELETEPROC must be a perl sub too. When CMDNAME is invoked in the Tcl interpeter, the arguments passed to the Perl sub CMDPROC are

(CLIENTDATA, INTERP, LIST)

where INTERP is a Perl object for the Tcl interpreter which called out and LIST is a Perl list of the arguments CMDNAME was called with. As usual in Tcl, the first element of the list is CMDNAME itself. When CMDNAME is deleted from the interpreter (either explicitly with DeleteCommand or because the destructor for the interpeter object is called), it is passed the single argument CLIENTDATA.

DeleteCommand (CMDNAME)

Deletes command CMDNAME from the interpreter. If the command was created with a DELETEPROC (see CreateCommand above), then it is invoked at this point. When a Tcl interpreter object is destroyed either explicitly or implicitly, an implicit DeleteCommand happens on all its currently registered commands.

SetResult (STRING)

Sets interp->result to STRING.

AppendResult (LIST)

Appends each element of LIST to interp->result.

AppendElement (STRING)

Appends STRING to interp->result as an extra Tcl list element.

ResetResult ()

Resets interp->result.

SplitList (STRING)

Splits STRING as a Tcl list. Returns a Perl list or the empty list if there was an error (i.e. STRING was not a properly formed Tcl list). In the latter case, the error message is left in interp->result.

SetVar (VARNAME, VALUE, FLAGS)

The FLAGS field is optional. Sets Tcl variable VARNAME in the interpreter to VALUE. The FLAGS argument is the usual Tcl one and can be a bitwise OR of the constants $Tcl::GLOBAL_ONLY, $Tcl::LEAVE_ERR_MSG, $Tcl::APPEND_VALUE, $Tcl::LIST_ELEMENT.

SetVar2 (VARNAME1, VARNAME2, VALUE, FLAGS)

Sets the element VARNAME1(VARNAME2) of a Tcl array to VALUE. The optional argument FLAGS behaves as in SetVar above.

GetVar (VARNAME, FLAGS)

Returns the value of Tcl variable VARNAME. The optional argument FLAGS behaves as in SetVar above.

GetVar2 (VARNAME1, VARNAME2, FLAGS)

Returns the value of the element VARNAME1(VARNAME2) of a Tcl array. The optional argument FLAGS behaves as in SetVar above.

UnsetVar (VARNAME, FLAGS)

Unsets Tcl variable VARNAME. The optional argument FLAGS behaves as in SetVar above.

UnsetVar2 (VARNAME1, VARNAME2, FLAGS)

Unsets the element VARNAME1(VARNAME2) of a Tcl array. The optional argument FLAGS behaves as in SetVar above.

Linking Perl and Tcl variables

You can tie a Perl variable (scalar or hash) into class Tcl::Var so that changes to a Tcl variable automatically "change" the value of the Perl variable. In fact, as usual with Perl tied variables, its current value is just fetched from the Tcl variable when needed and setting the Perl variable triggers the setting of the Tcl variable.

To tie a Perl scalar $scalar to the Tcl variable tclscalar in interpreter $interp with optional flags $flags (see SetVar above), use

tie $scalar, Tcl::Var, $interp, "tclscalar", $flags;

Omit the $flags argument if not wanted.

To tie a Perl hash %hash to the Tcl array variable array in interpreter $interp with optional flags $flags (see SetVar above), use

tie %hash, Tcl::Var, $interp, "array", $flags;

Omit the $flags argument if not wanted. Any alteration to Perl variable $hash{"key"} affects the Tcl variable array(key) and vice versa.

AUTHORS

Malcolm Beattie, mbeattie@sable.ox.ac.uk, 23 Oct 1994. Vadim Konovalov, vkonovalov@peterstar.ru, 19 May 2003.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html