home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tcl2-73c.zip / tcl7.3 / doc / Eval.3 < prev    next >
Text File  |  1993-04-03  |  5KB  |  120 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/Eval.3,v 1.13 93/04/03 16:40:04 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tcl_Eval tclc 7.0
  25. .BS
  26. .SH NAME
  27. Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tcl.h>\fR
  31. .sp
  32. int
  33. .VS
  34. \fBTcl_Eval\fR(\fIinterp, cmd\fR)
  35. .VE
  36. .sp
  37. int
  38. \fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
  39. .sp
  40. int
  41. \fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
  42. .sp
  43. int
  44. \fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
  45. .SH ARGUMENTS
  46. .AS Tcl_Interp **termPtr;
  47. .AP Tcl_Interp *interp in
  48. Interpreter in which to execute the command.  String result will be
  49. stored in \fIinterp->result\fR.
  50. .AP char *cmd in
  51. Command (or sequence of commands) to execute.  Must be in writable
  52. memory (\fBTcl_Eval\fR makes temporary modifications to the command).
  53. .AP char *string in
  54. String forming part of Tcl command.
  55. .AP char *fileName in
  56. Name of file containing Tcl command string.
  57. .BE
  58.  
  59. .SH DESCRIPTION
  60. .PP
  61. All four of these procedures execute Tcl commands.
  62. \fBTcl_Eval\fR is the core procedure:  it parses commands
  63. from \fIcmd\fR and executes them in
  64. .VS
  65. order until either an error occurs or it reaches the end of the string.
  66. .VE
  67. The return value from \fBTcl_Eval\fR is one
  68. of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
  69. \fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
  70. a string with additional information (result value or error message).
  71. This return information corresponds to the last command executed from
  72. \fIcmd\fR.
  73. .PP
  74. \fBTcl_VarEval\fR takes any number of string arguments
  75. of any length, concatenates
  76. them into a single string, then calls \fBTcl_Eval\fR to
  77. execute that string as a Tcl command.
  78. It returns the result of the command and also modifies
  79. \fIinterp->result\fR in the usual fashion for Tcl commands.  The
  80. last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
  81. of arguments.
  82. .PP
  83. \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
  84. its contents as a Tcl command by calling \fBTcl_Eval\fR.  It returns
  85. a standard Tcl result that reflects the result of evaluating the
  86. file.
  87. If the file couldn't be read then a Tcl error is returned to describe
  88. why the file couldn't be read.
  89. .PP
  90. \fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
  91. processes the command at global level.
  92. This means that the variable context for the command consists of
  93. global variables only (it ignores any Tcl procedure that is active).
  94. This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
  95. .PP
  96. During the processing of a Tcl command it is legal to make nested
  97. calls to evaluate other commands (this is how conditionals, loops,
  98. and procedures are implemented).
  99. If a code other than
  100. \fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
  101. caller should normally return immediately, passing that same
  102. return code back to its caller, and so on until the top-level application is
  103. reached.  A few commands, like \fBfor\fR, will check for certain
  104. return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
  105. specially without returning.
  106. .PP
  107. \fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
  108. in progress for \fIinterp\fR.
  109. If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
  110. about to be returned from the topmost \fBTcl_Eval\fR invocation for
  111. \fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
  112. and sets \fIinterp->result\fR to point to an error message indicating that
  113. the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
  114. invoked in an inappropriate place.  This means that top-level
  115. applications should never see a return code from \fBTcl_Eval\fR other then
  116. \fBTCL_OK\fR or \fBTCL_ERROR\fR.
  117.  
  118. .SH KEYWORDS
  119. command, execute, file, global, interpreter, variable
  120.