Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tcl_Interp(3)                              Tcl Library Procedures                              Tcl_Interp(3)



____________________________________________________________________________________________________________

NAME
       Tcl_Interp - client-visible fields of interpreter structures

SYNOPSIS
       #include <tcl.h>

       typedef struct {
               char *result;
               Tcl_FreeProc *freeProc;
               int errorLine;
       } Tcl_Interp;

       typedef void Tcl_FreeProc(char *blockPtr);
____________________________________________________________________________________________________________


DESCRIPTION
       The  Tcl_CreateInterp  procedure  returns  a pointer to a Tcl_Interp structure.  This pointer is then
       passed into other Tcl procedures to process commands in the interpreter and perform other  operations
       on  the interpreter.  Interpreter structures contain many fields that are used by Tcl, but only three
       that may be accessed by clients:  result, freeProc, and errorLine.

       Note that access to all three fields, result, freeProc and errorLine is deprecated.   Use  Tcl_SetRe- |
       sult, Tcl_GetResult, and Tcl_GetReturnOptions instead.

       The  result  and  freeProc  fields  are used to return results or error messages from commands.  This
       information is returned by command procedures back to Tcl_Eval, and by Tcl_Eval back to its  callers.
       The  result  field points to the string that represents the result or error message, and the freeProc
       field tells how to dispose of the storage for the string when it is not needed anymore.  The  easiest
       way  for  command  procedures  to manipulate these fields is to call procedures like Tcl_SetResult or
       Tcl_AppendResult;  they will hide all the details of managing the fields.  The description  below  is
       for those procedures that manipulate the fields directly.

       Whenever  a command procedure returns, it must ensure that the result field of its interpreter points
       to the string being returned by the command.  The result field must always point to a  valid  string.
       If  a  command  wishes to return no result then interp->result should point to an empty string.  Nor-mally, Normally,
       mally, results are assumed to be statically allocated, which means that the contents will not  change
       before  the  next  time Tcl_Eval is called or some other command procedure is invoked.  In this case,
       the freeProc field must be zero.  Alternatively, a command procedure  may  dynamically  allocate  its
       return  value  (e.g. using Tcl_Alloc) and store a pointer to it in interp->result.  In this case, the
       command procedure must also set interp->freeProc to the address of a  procedure  that  can  free  the
       value,  or  TCL_DYNAMIC  if  the storage was allocated directly by Tcl or by a call to Tcl_Alloc.  If
       interp->freeProc is non-zero,  then  Tcl  will  call  freeProc  to  free  the  space  pointed  to  by
       interp->result  before  it invokes the next command.  If a client procedure overwrites interp->result
       when interp->freeProc is non-zero, then it is responsible  for  calling  freeProc  to  free  the  old
       interp->result (the Tcl_FreeResult macro should be used for this purpose).

       FreeProc should have arguments and result that match the Tcl_FreeProc declaration above:  it receives
       a single argument which is a pointer to the result value to free.  In most  applications  TCL_DYNAMIC
       is  the  only  non-zero  value ever used for freeProc.  However, an application may store a different
       procedure address in freeProc in order to use an alternate memory allocator or in order to  do  other
       cleanup when the result memory is freed.

       As  part  of  processing  each command, Tcl_Eval initializes interp->result and interp->freeProc just
       before calling the command procedure for the command.  The freeProc  field  will  be  initialized  to
       zero,  and  interp->result  will point to an empty string.  Commands that do not return any value can
       simply leave the fields alone.  Furthermore, the empty string pointed to by result is  actually  part
       of an array of TCL_RESULT_SIZE characters (approximately 200).  If a command wishes to return a short
       string, it can simply copy it to the area pointed to by interp->result.  Or, it can use  the  sprintf
       procedure to generate a short result string at the location pointed to by interp->result.

       It is a general convention in Tcl-based applications that the result of an interpreter is normally in
       the initialized state described in the previous paragraph.   Procedures  that  manipulate  an  inter-preter's interpreter's
       preter's  result (e.g. by returning an error) will generally assume that the result has been initial-ized initialized
       ized when the procedure is called.  If such a procedure is to be called after  the  result  has  been
       changed,  then  Tcl_ResetResult  should be called first to reset the result to its initialized state.
       The direct use of interp->result is strongly deprecated (see Tcl_SetResult).

       The errorLine field is valid only after Tcl_Eval returns a TCL_ERROR return code.  In this  situation
       the errorLine field identifies the line number of the command being executed when the error occurred.
       The line numbers are relative to the command being executed:  1 means the first line of  the  command
       passed  to  Tcl_Eval,  2  means the second line, and so on.  The errorLine field is typically used in
       conjunction with Tcl_AddErrorInfo to report information about where  an  error  occurred.   ErrorLine
       should not normally be modified except by Tcl_Eval.


KEYWORDS
       free, initialized, interpreter, malloc, result



Tcl                                                  7.5                                       Tcl_Interp(3)