home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / vtcl / doc / Eval.3 < prev    next >
Encoding:
Text File  |  1995-07-10  |  5.1 KB  |  128 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. /*-----------------------------------------------------------------------------
  24.  *    @(#) Eval.3 26.1 93/10/22 SCOINC
  25.  *
  26.  *    Copyright (C) The Santa Cruz Operation, 1992-1993.
  27.  *    This Module contains Proprietary Information of
  28.  *    The Santa Cruz Operation, and should be treated as Confidential.
  29.  *-----------------------------------------------------------------------------
  30.  */
  31. .so ../man.macros
  32. .HS Tcl_Eval tclc 7.0
  33. .BS
  34. .SH NAME
  35. Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
  36. .SH SYNOPSIS
  37. .nf
  38. \fB#include <tcl.h>\fR
  39. .sp
  40. int
  41. .VS
  42. \fBTcl_Eval\fR(\fIinterp, cmd\fR)
  43. .VE
  44. .sp
  45. int
  46. \fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
  47. .sp
  48. int
  49. \fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
  50. .sp
  51. int
  52. \fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
  53. .SH ARGUMENTS
  54. .AS Tcl_Interp **termPtr;
  55. .AP Tcl_Interp *interp in
  56. Interpreter in which to execute the command.  String result will be
  57. stored in \fIinterp->result\fR.
  58. .AP char *cmd in
  59. Command (or sequence of commands) to execute.  Must be in writable
  60. memory (\fBTcl_Eval\fR makes temporary modifications to the command).
  61. .AP char *string in
  62. String forming part of Tcl command.
  63. .AP char *fileName in
  64. Name of file containing Tcl command string.
  65. .BE
  66.  
  67. .SH DESCRIPTION
  68. .PP
  69. All four of these procedures execute Tcl commands.
  70. \fBTcl_Eval\fR is the core procedure:  it parses commands
  71. from \fIcmd\fR and executes them in
  72. .VS
  73. order until either an error occurs or it reaches the end of the string.
  74. .VE
  75. The return value from \fBTcl_Eval\fR is one
  76. of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
  77. \fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
  78. a string with additional information (result value or error message).
  79. This return information corresponds to the last command executed from
  80. \fIcmd\fR.
  81. .PP
  82. \fBTcl_VarEval\fR takes any number of string arguments
  83. of any length, concatenates
  84. them into a single string, then calls \fBTcl_Eval\fR to
  85. execute that string as a Tcl command.
  86. It returns the result of the command and also modifies
  87. \fIinterp->result\fR in the usual fashion for Tcl commands.  The
  88. last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
  89. of arguments.
  90. .PP
  91. \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
  92. its contents as a Tcl command by calling \fBTcl_Eval\fR.  It returns
  93. a standard Tcl result that reflects the result of evaluating the
  94. file.
  95. If the file couldn't be read then a Tcl error is returned to describe
  96. why the file couldn't be read.
  97. .PP
  98. \fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
  99. processes the command at global level.
  100. This means that the variable context for the command consists of
  101. global variables only (it ignores any Tcl procedure that is active).
  102. This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
  103. .PP
  104. During the processing of a Tcl command it is legal to make nested
  105. calls to evaluate other commands (this is how conditionals, loops,
  106. and procedures are implemented).
  107. If a code other than
  108. \fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
  109. caller should normally return immediately, passing that same
  110. return code back to its caller, and so on until the top-level application is
  111. reached.  A few commands, like \fBfor\fR, will check for certain
  112. return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
  113. specially without returning.
  114. .PP
  115. \fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
  116. in progress for \fIinterp\fR.
  117. If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
  118. about to be returned from the topmost \fBTcl_Eval\fR invocation for
  119. \fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
  120. and sets \fIinterp->result\fR to point to an error message indicating that
  121. the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
  122. invoked in an inappropriate place.  This means that top-level
  123. applications should never see a return code from \fBTcl_Eval\fR other then
  124. \fBTCL_OK\fR or \fBTCL_ERROR\fR.
  125.  
  126. .SH KEYWORDS
  127. command, execute, file, global, interpreter, variable
  128.