.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Tcl 3pm"
.TH Tcl 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Tcl \- Tcl extension module for Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Tcl;
\&
\&    $interp = Tcl\->new;
\&    $interp\->Eval(\*(Aqputs "Hello world"\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "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
.IP "\(bu" 4
create Tcl interpreters
.Sp
The Tcl interpreters so created are Perl objects whose destructors
delete the interpreters cleanly when appropriate.
.IP "\(bu" 4
execute Tcl code in an interpreter
.Sp
The code can come from strings, files or Perl filehandles.
.IP "\(bu" 4
bind in new Tcl procedures
.Sp
The new procedures can be either C code (with addresses presumably
obtained using \fIdl_open\fR and \fIdl_find_symbol\fR) 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.
.IP "\(bu" 4
Manipulate the result field of a Tcl interpreter
.IP "\(bu" 4
Set and get values of variables in a Tcl interpreter
.IP "\(bu" 4
Tie perl variables to variables in a Tcl interpreter
.Sp
The variables can be either scalars or hashes.
.SS "Methods in class Tcl"
.IX Subsection "Methods in class Tcl"
To create a new Tcl interpreter, use
.PP
.Vb 1
\&    $interp = Tcl\->new;
.Ve
.PP
The following methods and routines can then be used on the Perl object
returned (the object argument omitted in each case).
.ie n .IP "$interp\->Init ()" 4
.el .IP "\f(CW$interp\fR\->Init ()" 4
.IX Item "$interp->Init ()"
Invoke \fITcl_Init\fR on the interpreter.
.ie n .IP "$interp\->CreateSlave (\s-1NAME, SAFE\s0)" 4
.el .IP "\f(CW$interp\fR\->CreateSlave (\s-1NAME, SAFE\s0)" 4
.IX Item "$interp->CreateSlave (NAME, SAFE)"
Invoke \fITcl_CreateSlave\fR on the interpreter.  Name is arbitrary.
The safe variable, if true, creates a safe sandbox interpreter.
 See: http://www.tcl.tk/software/plugin/safetcl.html
      http://www.tcl.tk/man/tcl8.4/TclCmd/safe.htm
.Sp
This command returns a new interpreter.
.ie n .IP "$interp\->Eval (\s-1STRING, FLAGS\s0)" 4
.el .IP "\f(CW$interp\fR\->Eval (\s-1STRING, FLAGS\s0)" 4
.IX Item "$interp->Eval (STRING, FLAGS)"
Evaluate script \s-1STRING\s0 in the interpreter. If the script returns
successfully (\s-1TCL_OK\s0) then the Perl return value corresponds to Tcl
interpreter's result otherwise a \fIdie\fR exception is raised with the $@
variable corresponding to Tcl's interpreter result object. In each case,
\&\fIcorresponds\fR means that if the method is called in scalar context then
the string result is returned but if the method is called in list context
then the result is split as a Tcl list and returned as a Perl list.
The \s-1FLAGS\s0 field is optional and can be a bitwise \s-1OR\s0 of the constants
Tcl::EVAL_GLOBAL or Tcl::EVAL_DIRECT.
.ie n .IP "$interp\->GlobalEval (\s-1STRING\s0)" 4
.el .IP "\f(CW$interp\fR\->GlobalEval (\s-1STRING\s0)" 4
.IX Item "$interp->GlobalEval (STRING)"
\&\s-1REMOVED.\s0  Evalulate script \s-1STRING\s0 at global level.
Call \fIEval\fR(\s-1STRING,\s0 Tcl::EVAL_GLOBAL) instead.
.ie n .IP "$interp\->EvalFile (\s-1FILENAME\s0)" 4
.el .IP "\f(CW$interp\fR\->EvalFile (\s-1FILENAME\s0)" 4
.IX Item "$interp->EvalFile (FILENAME)"
Evaluate the contents of the file with name \s-1FILENAME.\s0 Otherwise, the
same as \fIEval\fR() above.
.ie n .IP "$interp\->EvalFileHandle (\s-1FILEHANDLE\s0)" 4
.el .IP "\f(CW$interp\fR\->EvalFileHandle (\s-1FILEHANDLE\s0)" 4
.IX Item "$interp->EvalFileHandle (FILEHANDLE)"
Evaluate the contents of the Perl filehandle \s-1FILEHANDLE.\s0 Otherwise, the
same as \fIEval\fR() above. Useful when using the filehandle \s-1DATA\s0 to tack
on a Tcl script following an _\|_END_\|_ token.
.ie n .IP "$interp\->call (\s-1PROC, ARG, ...\s0)" 4
.el .IP "\f(CW$interp\fR\->call (\s-1PROC, ARG, ...\s0)" 4
.IX Item "$interp->call (PROC, ARG, ...)"
Looks up procedure \s-1PROC\s0 in the interpreter and invokes it using Tcl's eval
semantics that does command tracing and will use the ::unknown (\s-1AUTOLOAD\s0)
mechanism.  The arguments (\s-1ARG, ...\s0) are not passed through the Tcl parser.
For example, spaces embedded in any \s-1ARG\s0 will not cause it to be split into
two Tcl arguments before being passed to \s-1PROC.\s0
.Sp
Before invoking procedure \s-1PROC\s0 special processing is performed on \s-1ARG\s0 list:
.Sp
1.  All subroutine references within \s-1ARG\s0 will be substituted with Tcl name
which is responsible to invoke this subroutine. This Tcl name will be
created using CreateCommand subroutine (see below).
.Sp
2.  All references to scalars will be substituted with names of Tcl variables
transformed appropriately.
.Sp
These first two items allow one to write and expect it to work properly such
code as:
.Sp
.Vb 2
\&  my $r = \*(Aqaaaa\*(Aq;
\&  button(".d", \-textvariable => \e$r, \-command=>sub {$r++});
.Ve
.Sp
3. All references to hashes will be substituted with names of Tcl array
variables transformed appropriately.
.Sp
4.  As a special case, there is a mechanism to deal with Tk's special event
variables (they are mentioned as '%x', '%y' and so on throughout Tcl).
When creating a subroutine reference that uses such variables, you must
declare the desired variables using Tcl::Ev as the first argument to the
subroutine.  Example:
.Sp
.Vb 5
\&  sub textPaste {
\&      my ($x,$y,$w) = @_;
\&      widget($w)\->insert("\e@$x,$y", $interp\->Eval(\*(Aqselection get\*(Aq));
\&  }
\&  $widget\->bind(\*(Aq<2>\*(Aq, [\e&textPaste, Tcl::Ev(\*(Aq%x\*(Aq, \*(Aq%y\*(Aq), $widget] );
.Ve
.ie n .IP "$interp\->return_ref (\s-1NAME\s0)" 4
.el .IP "\f(CW$interp\fR\->return_ref (\s-1NAME\s0)" 4
.IX Item "$interp->return_ref (NAME)"
returns a reference corresponding to \s-1NAME,\s0 which was associated during
previously called \f(CW\*(C`$interpnt\->call(...)\*(C'\fR preprocessing. As a typical
example this could be variable associated with a widget.
.ie n .IP "$interp\->delete_ref (\s-1NAME\s0)" 4
.el .IP "\f(CW$interp\fR\->delete_ref (\s-1NAME\s0)" 4
.IX Item "$interp->delete_ref (NAME)"
deletes and returns a reference corresponding to \s-1NAME,\s0 which was associated
during previously called \f(CW\*(C`$interpnt\->call(...)\*(C'\fR preprocessing.
this follows _code_dispose about if \s-1NAME\s0 is a TClNAME or a \s-1DESCNAME.\s0
if \s-1NAME\s0 is a \s-1VARNAME\s0 then it is just deleted and returned.
.ie n .IP "$interp\->icall (\s-1PROC, ARG, ...\s0)" 4
.el .IP "\f(CW$interp\fR\->icall (\s-1PROC, ARG, ...\s0)" 4
.IX Item "$interp->icall (PROC, ARG, ...)"
Looks up procedure \s-1PROC\s0 in the interpreter and invokes it using Tcl's eval
semantics that does command tracing and will use the ::unknown (\s-1AUTOLOAD\s0)
mechanism.  The arguments (\s-1ARG, ...\s0) are not passed through the Tcl parser.
For example, spaces embedded in any \s-1ARG\s0 will not cause it to be split into
two Tcl arguments before being passed to \s-1PROC.\s0
.Sp
This is the lower-level procedure that the 'call' method uses.  Arguments
are converted efficiently from Perl SVs to Tcl_Objs.  A Perl \s-1AV\s0 array
becomes a Tcl_ListObj, an SvIV becomes a Tcl_IntObj, etc.  The reverse
conversion is done to the result.
.ie n .IP "$interp\->invoke (\s-1PROC, ARG, ...\s0)" 4
.el .IP "\f(CW$interp\fR\->invoke (\s-1PROC, ARG, ...\s0)" 4
.IX Item "$interp->invoke (PROC, ARG, ...)"
Looks up procedure \s-1PROC\s0 in the interpreter and invokes it directly with
arguments (\s-1ARG, ...\s0) without passing through the Tcl parser. For example,
spaces embedded in any \s-1ARG\s0 will not cause it to be split into two Tcl
arguments before being passed to \s-1PROC.\s0  This differs from icall/call in
that it directly invokes the command name without allowing for command
tracing or making use of Tcl's unknown (\s-1AUTOLOAD\s0) mechanism.  If the
command does not already exist in the interpreter, and error will be
thrown.
.Sp
Arguments are converted efficiently from Perl SVs to Tcl_Objs.  A Perl \s-1AV\s0
array becomes a Tcl_ListObj, an SvIV becomes a Tcl_IntObj, etc.  The
reverse conversion is done to the result.
.IP "Tcl::Ev (\s-1FIELD, ...\s0)" 4
.IX Item "Tcl::Ev (FIELD, ...)"
Used to declare %\-substitution variables of interest to a subroutine
callback.  \s-1FIELD\s0 is expected to be of the form \*(L"%#\*(R" where # is a single
character, and multiple fields may be specified.  Returns a blessed object
that the 'call' method will recognize when it is passed as the first
argument to a subroutine in a callback.  See description of 'call' method
for details.
.ie n .IP "$interp\->result ()" 4
.el .IP "\f(CW$interp\fR\->result ()" 4
.IX Item "$interp->result ()"
Returns the current Tcl interpreter result. List v. scalar context is
handled as in \fIEval\fR() above.
.ie n .IP "$interp\->CreateCommand (\s-1CMDNAME, CMDPROC, CLIENTDATA, DELETEPROC, FLAGS\s0)" 4
.el .IP "\f(CW$interp\fR\->CreateCommand (\s-1CMDNAME, CMDPROC, CLIENTDATA, DELETEPROC, FLAGS\s0)" 4
.IX Item "$interp->CreateCommand (CMDNAME, CMDPROC, CLIENTDATA, DELETEPROC, FLAGS)"
Binds a new procedure named \s-1CMDNAME\s0 into the interpreter. The
\&\s-1CLIENTDATA\s0 and \s-1DELETEPROC\s0 arguments are optional. There are two cases:
.Sp
(1) \s-1CMDPROC\s0 is the address of a C function
.Sp
(presumably obtained using \fIdl_open\fR and \fIdl_find_symbol\fR. In this case
\&\s-1CLIENTDATA\s0 and \s-1DELETEPROC\s0 are taken to be raw data of the ClientData and
deleteProc field presumably obtained in a similar way.
.Sp
(2) \s-1CMDPROC\s0 is a Perl subroutine
.Sp
(either a sub name, a sub reference or an anonymous sub). In this case
\&\s-1CLIENTDATA\s0 can be any perl scalar (e.g. a ref to some other data) and
\&\s-1DELETEPROC\s0 must be a perl sub too. When \s-1CMDNAME\s0 is invoked in the Tcl
interpreter, the arguments passed to the Perl sub \s-1CMDPROC\s0 are
.Sp
.Vb 1
\&    (CLIENTDATA, INTERP, LIST)
.Ve
.Sp
where \s-1INTERP\s0 is a Perl object for the Tcl interpreter which called out
and \s-1LIST\s0 is a Perl list of the arguments \s-1CMDNAME\s0 was called with.
If the 1\-bit of \s-1FLAGS\s0 is set then the 3 first arguments on the call
to \s-1CMDPROC\s0 are suppressed.
As usual in Tcl, the first element of the list is \s-1CMDNAME\s0 itself.
When \s-1CMDNAME\s0 is deleted from the interpreter (either explicitly with
\&\fIDeleteCommand\fR or because the destructor for the interpreter object
is called), it is passed the single argument \s-1CLIENTDATA.\s0
.ie n .IP "$interp\->DeleteCommand (\s-1CMDNAME\s0)" 4
.el .IP "\f(CW$interp\fR\->DeleteCommand (\s-1CMDNAME\s0)" 4
.IX Item "$interp->DeleteCommand (CMDNAME)"
Deletes command \s-1CMDNAME\s0 from the interpreter. If the command was created
with a \s-1DELETEPROC\s0 (see \fICreateCommand\fR above), then it is invoked at
this point. When a Tcl interpreter object is destroyed either explicitly
or implicitly, an implicit \fIDeleteCommand\fR happens on all its currently
registered commands.
.ie n .IP "(\s-1TCLNAME,GENCODE\s0) = $interp\->create_tcl_sub(\s-1CODEREF, EVENTS, TCLNAME, DESCRNAME\s0)" 4
.el .IP "(\s-1TCLNAME,GENCODE\s0) = \f(CW$interp\fR\->create_tcl_sub(\s-1CODEREF, EVENTS, TCLNAME, DESCRNAME\s0)" 4
.IX Item "(TCLNAME,GENCODE) = $interp->create_tcl_sub(CODEREF, EVENTS, TCLNAME, DESCRNAME)"
Creates a \s-1COMMAND\s0 called \s-1TCLNAME\s0 calling \s-1CODEREF\s0 in the interpreter \f(CW$interp\fR,
and adds it to the internal tracking structure.
\&\s-1DESCRNAME\s0 and \s-1TCLNAME\s0 should not begin
with =
or @
or ::perl::
to avoid colisions
If \s-1TCLNAME IS\s0 blank or undef, it is constructed from the \s-1CODEREF\s0 address.
\&\s-1GENCODE\s0 starts as \s-1TCLNAME\s0 but gets @$EVENTS which can contain \f(CW%vars\fR joined to it.
.Sp
\&\s-1TCLNAME\s0 and \s-1DESCRNAME\s0 get stored in an internal structure,
and can be used to purge things fRom the command table via code_destroy or \f(CW$interp\fR\->delete_ref;
.Sp
Returns (\s-1TCLNAME,GENCODE\s0).
if you are creating code refs with this you can continue to use the same coderef and it will be converted on each call.
but if you save \s-1GENCODE,\s0 you can replace the anon-coderef call in the tcl command with \s-1GENCODE.\s0
.Sp
for instance
.Sp
.Vb 1
\&  $interp\->call(\*(AqFILEEVENT\*(Aq,$fileref,WRITABLE=>sub {...});
.Ve
.Sp
can be replaced by
.Sp
.Vb 2
\&  my ($tclcode,$gencode)=$interp\->create_tcl_sub(sub{...}, EVENTS, TCLNAME, DESCRNAME);
\&  $interp\->call(\*(AqFILEEVENT\*(Aq,$gencode,WRITABLE=>$gencode);
.Ve
.Sp
or
.Sp
.Vb 2
\&  my $sub=sub{....};
\&  $interp\->call(\*(AqFILEEVENT\*(Aq,$fileref,WRITABLE=>$sub);
.Ve
.Sp
can be replaced by
.Sp
.Vb 2
\&  my ($tclcode,$gencode)=$interp\->create_tcl_sub($sub, EVENTS, TCLNAME, DESCRNAME);
\&  $interp\->call(\*(AqFILEEVENT\*(Aq,$gencode,WRITABLE=>$gencode);
.Ve
.Sp
although
.Sp
.Vb 1
\&  $interp\->call(\*(AqFILEEVENT\*(Aq,$fileref,WRITABLE=>$sub);
.Ve
.Sp
will stil work fine too.
.Sp
Then you later call
.Sp
.Vb 1
\&  $interp\->delete_ref($tclname);
.Ve
.Sp
when you are finished with that sub to clean it from the internal tracking and command table.
This means no automatic cleanup will occur on the sub{...} or \f(CW$sub\fR
.Sp
And after the destroy inside Tcl any triggering writable on \f(CW$fileref\fR will fail as well.
so it should be replaced first via
  \f(CW$interp\fR\->call('\s-1FILEEVENT\s0',$fileref,WRITABLE=>'');
.IP "(\s-1CODEREF\s0) = Tcl::_code_dispose(\s-1NAME\s0)" 4
.IX Item "(CODEREF) = Tcl::_code_dispose(NAME)"
Purges the internal table of a \s-1NAME\s0
and may initiate destruction of something created thru call or create_tcl_sub
.Sp
\&\s-1TCLNAME\s0 and \s-1DESCRNAME\s0 get stored in an internal structure,
and can be used to purge things form the command table.
calling _code_dispose on a \s-1TCLNAME\s0 retruned from create_tcl_sub removes all use instances and purges the command table.
calling _code_dispose on a \s-1DESCRNAME\s0 passed to create_tcl_sub removes only that instace
Code used in a \s-1DESCRNAME\s0 may be used in other places as well,
only when the last usage is purged does the entry get purged from the command table
.Sp
While the internal tracking structure saves the \s-1INTERP\s0 the code was added to,
it itself does not keep things separated by \s-1INTERP,
A TCLNAME\s0 or DESCRNAMe can only exist in one \s-1INTERP\s0 at a time,
using a new \s-1INTERP\s0 just causes the one in the last \s-1INTERP\s0 to disappear,
and probably end up with the Tcl code getting deleted
.Sp
Returns (\s-1CODEREF\s0), this is the original coderef
.ie n .IP "$interp\->SetResult (\s-1STRING\s0)" 4
.el .IP "\f(CW$interp\fR\->SetResult (\s-1STRING\s0)" 4
.IX Item "$interp->SetResult (STRING)"
Sets Tcl interpreter result to \s-1STRING.\s0
.ie n .IP "$interp\->AppendResult (\s-1LIST\s0)" 4
.el .IP "\f(CW$interp\fR\->AppendResult (\s-1LIST\s0)" 4
.IX Item "$interp->AppendResult (LIST)"
Appends each element of \s-1LIST\s0 to Tcl's interpreter result object.
.ie n .IP "$interp\->AppendElement (\s-1STRING\s0)" 4
.el .IP "\f(CW$interp\fR\->AppendElement (\s-1STRING\s0)" 4
.IX Item "$interp->AppendElement (STRING)"
Appends \s-1STRING\s0 to Tcl interpreter result object as an extra Tcl list element.
.ie n .IP "$interp\->ResetResult ()" 4
.el .IP "\f(CW$interp\fR\->ResetResult ()" 4
.IX Item "$interp->ResetResult ()"
Resets Tcl interpreter result.
.ie n .IP "$interp\->SplitList (\s-1STRING\s0)" 4
.el .IP "\f(CW$interp\fR\->SplitList (\s-1STRING\s0)" 4
.IX Item "$interp->SplitList (STRING)"
Splits \s-1STRING\s0 as a Tcl list. Returns a Perl list or the empty list if
there was an error (i.e. \s-1STRING\s0 was not a properly formed Tcl list).
In the latter case, the error message is left in Tcl's interpreter
result object.
.ie n .IP "$interp\->SetVar (\s-1VARNAME, VALUE, FLAGS\s0)" 4
.el .IP "\f(CW$interp\fR\->SetVar (\s-1VARNAME, VALUE, FLAGS\s0)" 4
.IX Item "$interp->SetVar (VARNAME, VALUE, FLAGS)"
The \s-1FLAGS\s0 field is optional. Sets Tcl variable \s-1VARNAME\s0 in the
interpreter to \s-1VALUE.\s0 The \s-1FLAGS\s0 argument is the usual Tcl one and
can be a bitwise \s-1OR\s0 of the constants Tcl::GLOBAL_ONLY,
Tcl::LEAVE_ERR_MSG, Tcl::APPEND_VALUE, Tcl::LIST_ELEMENT.
.ie n .IP "$interp\->SetVar2 (\s-1VARNAME1, VARNAME2, VALUE, FLAGS\s0)" 4
.el .IP "\f(CW$interp\fR\->SetVar2 (\s-1VARNAME1, VARNAME2, VALUE, FLAGS\s0)" 4
.IX Item "$interp->SetVar2 (VARNAME1, VARNAME2, VALUE, FLAGS)"
Sets the element \s-1VARNAME1\s0(\s-1VARNAME2\s0) of a Tcl array to \s-1VALUE.\s0 The optional
argument \s-1FLAGS\s0 behaves as in \fISetVar\fR above.
.ie n .IP "$interp\->GetVar (\s-1VARNAME, FLAGS\s0)" 4
.el .IP "\f(CW$interp\fR\->GetVar (\s-1VARNAME, FLAGS\s0)" 4
.IX Item "$interp->GetVar (VARNAME, FLAGS)"
Returns the value of Tcl variable \s-1VARNAME.\s0 The optional argument \s-1FLAGS\s0
behaves as in \fISetVar\fR above.
.ie n .IP "$interp\->GetVar2 (\s-1VARNAME1, VARNAME2, FLAGS\s0)" 4
.el .IP "\f(CW$interp\fR\->GetVar2 (\s-1VARNAME1, VARNAME2, FLAGS\s0)" 4
.IX Item "$interp->GetVar2 (VARNAME1, VARNAME2, FLAGS)"
Returns the value of the element \s-1VARNAME1\s0(\s-1VARNAME2\s0) of a Tcl array.
The optional argument \s-1FLAGS\s0 behaves as in \fISetVar\fR above.
.ie n .IP "$interp\->UnsetVar (\s-1VARNAME, FLAGS\s0)" 4
.el .IP "\f(CW$interp\fR\->UnsetVar (\s-1VARNAME, FLAGS\s0)" 4
.IX Item "$interp->UnsetVar (VARNAME, FLAGS)"
Unsets Tcl variable \s-1VARNAME.\s0 The optional argument \s-1FLAGS\s0
behaves as in \fISetVar\fR above.
.ie n .IP "$interp\->UnsetVar2 (\s-1VARNAME1, VARNAME2, FLAGS\s0)" 4
.el .IP "\f(CW$interp\fR\->UnsetVar2 (\s-1VARNAME1, VARNAME2, FLAGS\s0)" 4
.IX Item "$interp->UnsetVar2 (VARNAME1, VARNAME2, FLAGS)"
Unsets the element \s-1VARNAME1\s0(\s-1VARNAME2\s0) of a Tcl array.
The optional argument \s-1FLAGS\s0 behaves as in \fISetVar\fR above.
.SS "Command table cleanup"
.IX Subsection "Command table cleanup"
In V1.03 command table cleanup was intoduced.
This tries to keep the internal structure and command table clean.
In V1.02 and prior heavy use of sub { .. } in Tcl commands could pollute these tables
as they were never cleared. Command table cleanup tries to alieviate this.
.PP
if you call create_tcl_sub the internal reference exists until
you delete_ref or _code_dispose it, or you call create_tcl_sub with the same \s-1DESCRNAME.\s0
.PP
if the internal reference was created internaly by call(...) there are two rules
.IP "1)" 4
.IX Item "1)"
If the command is an \*(L"after\*(R" the internal references is keept at least until 1 second after the delay.
If there are still other \*(L"users\*(R" of the \s-1TCLNAME\s0 then it is not deleted until the last one goes away.
If another call with the same \s-1CODEREF\s0 happens before this,
then it will get registered as a \*(L"user\*(R" without any need to delete/recreate the tcl command first.
.IP "2)" 4
.IX Item "2)"
otherwise a \s-1DESCRNAME\s0 is created with the text sections of the command, prefaced by \*(L"=\*(R".
Like
\&\*(L"=after 1000\*(R"
or \*(L"=:.m.m add command \-command \-label Exit\*(R"
or \*(L"=::button .f3.b8 \-text conn \-command\*(R"
or \*(L"=gets sock9ac2b50\*(R"
or \*(L"=fileevent sock9827430 writable\*(R"
.Sp
the \s-1TCLCODES\s0 created for that command will be kept at least until a command with
the same \s-1DESCRNAME\s0 and containing a subroutine reference is run again.
Since many \s-1DESCRNAMES\s0 can reference the same \s-1TCLNAME\s0 only when
the last \s-1DESCRNAME\s0 referencing a \s-1TCLNAME\s0 is released is the \s-1TCLNAME\s0 purged.
.Sp
\&\s-1NOTE:\s0
Since
  \f(CW$interp\fR\->call('fileevent','sock9827430','writable');
does not contain a subroutine reference, it will not release/free the \s-1TCLNAME/DESCRNAME\s0 created by
  \f(CW$interp\fR\->call('fileevent','sock9827430','writable',sub{...});
even though that is the way you deactivate a writable/readable callback in Tcl.
.PP
Prior to V1.06 there was also a problem with the coderef never getting cleared from sas,
a refcount was kept at the \s-1PVCV\s0 that prevented it from getting garbage collected,
but that \s-1SV\s0 itself got \*(L"lost\*(R" and could never be garbage collected,
thereby also keeping anything in that codes \s-1PAD.\s0
.PP
To assist in tracking chages to the internal table and the commands table 3 trace subs were added,
set them to non-blank or non-zero to add the tracking output to \s-1SYSOUT,\s0 like this in your code:
.PP
.Vb 1
\&    sub Tcl::TRACE_SHOWCODE(){1}
.Ve
.IP "Tcl::TRACE_SHOWCODE" 4
.IX Item "Tcl::TRACE_SHOWCODE"
Display all generated Tcl code by \fBcall()\fR.
Be aware: Tkx::MainLoop runs by issuing a lot of \*(L"winfo exists .\*(R" calls, a \s-1LOT.\s0
But this is a nice way to tell what your programs are doing to Tcl.
.IP "Tcl::TRACE_CREATECOMMAND" 4
.IX Item "Tcl::TRACE_CREATECOMMAND"
Display Tcl subroutine creation by call/create_tcl_sub
.IP "Tcl::TRACE_DELETECOMMAND" 4
.IX Item "Tcl::TRACE_DELETECOMMAND"
Display Tcl subroutine deletion by cleanup/delete_ref/_code_dispose
.SS "Linking Perl and Tcl variables"
.IX Subsection "Linking Perl and Tcl variables"
You can \fItie\fR a Perl variable (scalar or hash) into class Tcl::Var
so that changes to a Tcl variable automatically \*(L"change\*(R" 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.
.PP
To tie a Perl scalar \fI\f(CI$scalar\fI\fR to the Tcl variable \fItclscalar\fR in
interpreter \fI\f(CI$interp\fI\fR with optional flags \fI\f(CI$flags\fI\fR (see \fISetVar\fR
above), use
.PP
.Vb 1
\&        tie $scalar, "Tcl::Var", $interp, "tclscalar", $flags;
.Ve
.PP
Omit the \fI\f(CI$flags\fI\fR argument if not wanted.
.PP
To tie a Perl hash \fI\f(CI%hash\fI\fR to the Tcl array variable \fIarray\fR in
interpreter \fI\f(CI$interp\fI\fR with optional flags \fI\f(CI$flags\fI\fR
(see \fISetVar\fR above), use
.PP
.Vb 1
\&        tie %hash, "Tcl::Var", $interp, "array", $flags;
.Ve
.PP
Omit the \fI\f(CI$flags\fI\fR argument if not wanted. Any alteration to Perl
variable \fI\f(CI$hash\fI{\*(L"key\*(R"}\fR affects the Tcl variable \fIarray(key)\fR
and \fIvice versa\fR.
.SS "Accessing Perl from within Tcl"
.IX Subsection "Accessing Perl from within Tcl"
After creation of Tcl interpreter, in addition to evaluation of Tcl/Tk
commands within Perl, other way round also instantiated. Within a special
namespace \f(CW\*(C` ::perl \*(C'\fR following objects are created:
.PP
.Vb 1
\&   ::perl::Eval
.Ve
.PP
So it is possible to use Perl objects from within Tcl.
.SS "Moving Tcl/Tk around with Tcl.pm"
.IX Subsection "Moving Tcl/Tk around with Tcl.pm"
\&\s-1NOTE:\s0 explanations below is for developers managing Tcl/Tk installations
itself, users should skip this section.
.PP
In order to create Tcl/Tk application with this module, you need to make
sure that Tcl/Tk is available within visibility of this module. There are
many ways to achieve this, varying on ease of starting things up and
providing flexible moveable archived files.
.PP
Following list enumerates them, in order of increased possibility to change
location.
.IP "\(bu" 4
First method
.Sp
Install Tcl/Tk first, then install Perl module Tcl, so installed Tcl/Tk will
be used. This is most normal approach, and no care of Tcl/Tk distribution is
taken on Perl side (this is done on Tcl/Tk side)
.IP "\(bu" 4
Second method
.Sp
Copy installed Tcl/Tk binaries to some location, then install Perl module Tcl
with a special action to make Tcl.pm know of this location. This approach
makes sure that only chosen Tcl installation is used.
.IP "\(bu" 4
Third method
.Sp
During compiling Tcl Perl module, Tcl/Tk could be statically linked into
module's shared library and all other files zipped into a single archive, so
each file extracted when needed.
.Sp
To link Tcl/Tk binaries, prepare their libraries and then instruct Makefile.PL
to use these libraries in a link stage.
(\s-1TODO\s0 provide better detailed description)
.SH "Other Tcl interpreter methods"
.IX Header "Other Tcl interpreter methods"
.IP "export_to_tcl method" 2
.IX Item "export_to_tcl method"
An interpreter method, export_to_tcl, is used to expose a number of perl
subroutines and variables all at once into tcl/tk.
.Sp
\&\fBexport_to_tcl\fR takes a hash as arguments, which represents named parameters,
with following allowed values:
.RS 2
.IP "\fBnamespace\fR => '...'" 4
.IX Item "namespace => '...'"
tcl namespace, where commands and variables are to
be created, defaults to 'perl'. If '' is specified \- then global
namespace is used. A possible '::' at end is stripped.
.IP "\fBsubs\fR => { ... }" 4
.IX Item "subs => { ... }"
anonymous hash of subs to be created in Tcl, in the form /tcl name/ => /code ref/
.IP "\fBvars\fR => { ... }" 4
.IX Item "vars => { ... }"
anonymous hash of vars to be created in Tcl, in the form /tcl name/ => /code ref/
.IP "\fBsubs_from\fR => '...'" 4
.IX Item "subs_from => '...'"
a name of Perl namespace, from where all existing subroutines will be searched
and Tcl command will be created for each of them.
.IP "\fBvars_from\fR => '...'" 4
.IX Item "vars_from => '...'"
a name of Perl namespace, from where all existing variables will be searched,
and each such variable will be tied to Tcl.
.RE
.RS 2
.Sp
An example:
.Sp
.Vb 2
\&  use strict;
\&  use Tcl;
\&
\&  my $int = Tcl\->new;
\&
\&  $tcl::foo = \*(Aqqwerty\*(Aq;
\&  $int\->export_to_tcl(subs_from=>\*(Aqtcl\*(Aq,vars_from=>\*(Aqtcl\*(Aq);
\&
\&  $int\->Eval(<<\*(AqEOS\*(Aq);
\&  package require Tk
\&
\&  button .b1 \-text {a fluffy button} \-command perl::fluffy_sub
\&  button .b2 \-text {a foo button} \-command perl::foo
\&  entry .e \-textvariable perl::foo
\&  pack .b1 .b2 .e
\&  focus .b2
\&
\&  tkwait window .
\&  EOS
\&
\&  sub tcl::fluffy_sub {
\&      print "Hi, I am a fluffy sub\en";
\&  }
\&  sub tcl::foo {
\&      print "Hi, I am foo\en";
\&      $tcl::foo++;
\&  }
.Ve
.RE
.IP "\fBexport_tcl_namespace\fR" 2
.IX Item "export_tcl_namespace"
extra convenience sub, binds to tcl all subs and vars from perl \fBtcl::\fR namespace
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 4
\& Malcolm Beattie, 23 Oct 1994
\& Vadim Konovalov, 19 May 2003
\& Jeff Hobbs, jeff (a) activestate . com, 22 Mar 2004
\& Gisle Aas, gisle (a) activestate . com, 14 Apr 2004
.Ve
.PP
Special thanks for contributions to Jan Dubois, Slaven Rezic, Paul Cochrane,
Huck Finn, Christopher Chavez, \s-1SJ\s0 Luo.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.PP
See http://www.perl.com/perl/misc/Artistic.html