home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 0 / 0998 / Interp.3 < prev    next >
Text File  |  1990-12-28  |  4KB  |  96 lines
  1. '\" Copyright 1989 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Interp.man,v 1.3 90/01/15 14:58:40 ouster Exp $ SPRITE (Berkeley)
  10. '\" 
  11. .so \*(]ltmac.sprite
  12. .HS Tcl_Interp tcl
  13. .BS
  14. .SH NAME
  15. Tcl_Interp \- client-visible fields of interpreter structures
  16. .SH SYNOPSIS
  17. .nf
  18. \fB#include <tcl.h>\fR
  19. .sp
  20. typedef struct {
  21.     char *\fIresult\fR;
  22.     int \fIdynamic\fR;
  23.     int \fIerrorLine\fR;
  24. } Tcl_Interp;
  25. .BE
  26.  
  27. .SH DESCRIPTION
  28. .PP
  29. The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
  30. structure.  This pointer is then passed into other Tcl procedures
  31. to process commands in the interpreter and perform other operations
  32. on the interpreter.  Interpreter structures contain many many fields
  33. that are used by Tcl, but only three that may be accessed by
  34. clients:  \fIresult\fR and \fIdynamic\fR.  These fields are used by
  35. Tcl command procedures to return strings that form part of the result
  36. of each command.  When Tcl_Eval returns, the string pointed to be
  37. the \fIresult\fR field will be used by Tcl_Eval's caller
  38. as a return value or error message.
  39. .PP
  40. The easiest way for command procedures to manipulate the \fIresult\fR
  41. and \fIdynamic\fR fields is to call Tcl_Return;  Tcl_Return
  42. will hide all the details of managing these fields.
  43. The description below is for those procedures that manipulate the
  44. fields directly.
  45. .PP
  46. Whenever a command procedure returns, it must ensure
  47. that the \fIresult\fR field of its interpreter points to the string
  48. being returned by the command.  Normally, these strings are assumed
  49. to be statically allocated;  in this case, the \fIdynamic\fR field
  50. must be zero.  As an alternative, a command procedure may dynamically
  51. allocate its return value and store a pointer to it in \fIinterp->result\fR.
  52. In this case, the command procedure must also set \fIinterp->dynamic\fR
  53. to non-zero.  If \fIinterp->dynamic\fR is non-zero, then Tcl will free
  54. the space pointed to by \fIinterp->result\fR before it invokes the next command.
  55. If a client procedure overwrites \fIinterp->result\fR field when
  56. \fIinterp->dynamic\fR is non-zero, then it is responsible for freeing the
  57. old \fIinterp->result\fR.  Once again, if clients use the
  58. \fBTcl_Result\fR procedure to manage these fields, they need not worry
  59. about these issues.
  60. .PP
  61. As part of processing each command, \fBTcl_Eval\fR initializes
  62. \fIinterp->result\fR
  63. and \fIinterp->dynamic\fR just before calling the command procedure for
  64. the command.  The \fIdynamic\fR field will be initialized to zero,
  65. and \fIinterp->result\fR will point to an empty string.  Commands that
  66. do not return any value can simply leave the fields alone.
  67. Furthermore, the empty string pointed to by \fIresult\fR is actually
  68. part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
  69. If a command wishes to return a short string, it can simply copy
  70. it to the area pointed to by \fIinterp->result\fR.  Or, it can use
  71. the sprintf procedure to generate a short result string at the location
  72. pointed to by \fIinterp->result\fR.
  73. .PP
  74. If a command procedure calls a lower-level procedure that sets
  75. \fIinterp->result\fR and \fIinterp->dynamic\fR (such as a recursive
  76. instance of \fBTcl_Eval\fR), then the command procedure must reset
  77. \fIinterp->result\fR if it wishes to return a value different
  78. than that returned by the lower-level procedure.  As part of
  79. resetting \fIinterp->result\fR, it must free the space if
  80. \fIinterp->dynamic\fR is set.  Once again, the easiest way to
  81. make sure this gets done right is to call \fBTcl_Result\fR.
  82. .PP
  83. The \fIerrorLine\fR
  84. .VS
  85. field is valid only after \fBTcl_Eval\fR returns
  86. a \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR
  87. field identifies the line number of the command being executed when
  88. the error occurred.  The line numbers are relative to the command
  89. being executed:  1 means the first line of the command passed to
  90. \fBTcl_Eval\fR, 2 means the second line, and so on.  \fIErrorLine\fR
  91. should not normally be modified except by \fBTcl_Eval\fR.
  92. .VE
  93.  
  94. .SH KEYWORDS
  95. dynamic, interpreter, result
  96.