home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 0 / 0998 / Eval.3 < prev    next >
Text File  |  1990-12-28  |  4KB  |  87 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_Eval.man,v 1.3 90/01/07 16:02:10 ouster Exp $ SPRITE (Berkeley)
  10. '\" 
  11. .so \*(]ltmac.sprite
  12. .HS Tcl_Eval tcl
  13. .BS
  14. .SH NAME
  15. Tcl_Eval \- execute a Tcl command string
  16. .SH SYNOPSIS
  17. .nf
  18. \fB#include <tcl.h>\fR
  19. .sp
  20. int
  21. \fBTcl_Eval\fR(\fIinterp, cmd, flags, termPtr\fR)
  22. .SH ARGUMENTS
  23. .AS Tcl_Interp **termPtr;
  24. .AP Tcl_Interp *interp in
  25. Interpreter in which to execute the command.  String result will be
  26. stored in \fIinterp->result\fR.
  27. .AP char *cmd in
  28. Command (or sequence of commands) to execute.
  29. .AP char flags in
  30. Either \fBTCL_BRACKET_TERM\fR or 0.
  31. .VS
  32. If 0, then \fBTcl_Eval\fR will process commands from \fIcmd\fR until
  33. it reaches the null character at the end of the string;  newlines
  34. will be treated as command separators.  If \fBTCL_BRACKET_TERM\fR,
  35. then \fBTcl_Eval\fR will process comands from \fIcmd\fR until either it
  36. reaches a null character or it encounters a close bracket that isn't
  37. backslashed or enclosed in braces, at which
  38. point it will return;  newlines will treated as white space, not as
  39. command separators.  Under normal conditions, \fIflags\fR should be 0.
  40. .VE
  41. .AP char **termPtr out
  42. If 
  43. .VS
  44. \fItermPtr\fR is non-NULL, \fBTcl_Eval\fR fills in *\fItermPtr\fR with
  45. the address of the character just after the last one in the last command
  46. successfully executed (normally the null character at the end of \fIcmd\fR).
  47. If an error occurs in the first command in \fIcmd\fR, then \fI*termPtr\fR
  48. will be set to \fIcmd\fR.
  49. .VE
  50. .BE
  51.  
  52. .SH DESCRIPTION
  53. .PP
  54. \fBTcl_Eval\fR parses commands from \fIcmd\fR and executes them in
  55. order until either an error occurs or \fBTcl_Eval\fR reaches a terminating
  56. character (']' or '\0', depending on the value of \fIflags\fR).
  57. The return value from \fBTcl_Eval\fR is one
  58. of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
  59. \fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
  60. a string with additional information (result value or error message).
  61. This return information corresponds to the last command executed from
  62. \fIcmd\fR.
  63. .PP
  64. During the processing of a command it is legal to make nested
  65. calls to \fBTcl_Eval\fR (this is how conditionals, loops, and procedures
  66. are implemented).  If a code other than
  67. \fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
  68. caller should normally return immediately, passing that same
  69. return code back to its caller, and so on until the top-level application is
  70. reached.  A few commands, like \fBfor\fR, will check for certain
  71. return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
  72. specially without returning.
  73. .PP
  74. \fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
  75. in progress for \fIinterp\fR.
  76. If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
  77. about to be returned from the topmost \fBTcl_Eval\fR invocation for
  78. \fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
  79. and sets \fIinterp->result\fR to point to an error message indicating that
  80. the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
  81. invoked in an inappropriate place.  This means that top-level
  82. applications should never see a return code from \fBTcl_Eval\fR other then
  83. \fBTCL_OK\fR or \fBTCL_ERROR\fR.
  84.  
  85. .SH KEYWORDS
  86. command, execute, interpreter
  87.