util/src/TclTk/tcl8.6.12/pkgs/itcl4.2.2/doc/body.n

   1 '\"
   2 '\" Copyright (c) 1993-1998  Lucent Technologies, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH body n 3.0 itcl "[incr\ Tcl]"
   8 .so man.macros
   9 .BS
  10 '\" Note:  do not modify the .SH NAME line immediately below!
  11 .SH NAME
  12 itcl::body \- change the body for a class method/proc
  13 .SH SYNOPSIS
  14 \fBitcl::body \fIclassName\fB::\fIfunction args body\fR
  15 .BE
  16
  17 .SH DESCRIPTION
  18 .PP
  19 The \fBbody\fR command is used outside of an \fB[incr\ Tcl]\fR
  20 class definition to define or redefine the body of a class
  21 method or proc.  This facility allows a class definition
  22 to have separate "interface" and "implementation" parts.
  23 The "interface" part is a \fBclass\fR command with declarations
  24 for methods, procs, instance variables and common variables.
  25 The "implementation" part is a series of \fBbody\fR and
  26 \fBconfigbody\fR commands.  If the "implementation" part
  27 is kept in a separate file, it can be sourced again and
  28 again as bugs are fixed, to support interactive development.
  29 When using the "tcl" mode in the \fBemacs\fR editor, the
  30 "interface" and "implementation" parts can be kept in the
  31 same file; as bugs are fixed, individual bodies can be
  32 highlighted and sent to the test application.
  33 .PP
  34 The name "\fIclassName\fB::\fIfunction\fR"
  35 identifies the method/proc being changed.
  36 .PP
  37 If an \fIargs\fR list was specified when the \fIfunction\fR was
  38 defined in the class definition, the \fIargs\fR list for the
  39 \fBbody\fR command must match in meaning.  Variable names
  40 can change, but the argument lists must have the same required
  41 arguments and the same default values for optional arguments.
  42 The special \fBargs\fR argument acts as a wildcard when included
  43 in the \fIargs\fR list in the class definition; it will match
  44 zero or more arguments of any type when the body is redefined.
  45 .PP
  46 If the \fIbody\fR string starts with "\fB@\fR", it is treated
  47 as the symbolic name for a C procedure.  The \fIargs\fR list
  48 has little meaning for the C procedure, except to document
  49 the expected usage.  (The C procedure is not guaranteed to
  50 use arguments in this manner.)  If \fIbody\fR does not start
  51 with "\fB@\fR", it is treated as a Tcl command script.  When
  52 the function is invoked, command line arguments are matched
  53 against the \fIargs\fR list, and local variables are created
  54 to represent each argument.  This is the usual behavior for
  55 a Tcl-style proc.
  56 .PP
  57 Symbolic names for C procedures are established by registering
  58 procedures via \fBItcl_RegisterC()\fR.  This is usually done
  59 in the \fBTcl_AppInit()\fR procedure, which is automatically called
  60 when the interpreter starts up.  In the following example,
  61 the procedure \fCMy_FooCmd()\fR is registered with the
  62 symbolic name "foo".  This procedure can be referenced in
  63 the \fBbody\fR command as "\fC@foo\fR".
  64 .CS
  65 int
  66 Tcl_AppInit(interp)
  67     Tcl_Interp *interp;     /* Interpreter for application. */
  68 {
  69     if (Itcl_Init(interp) == TCL_ERROR) {
  70         return TCL_ERROR;
  71     }
  72
  73     if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
  74         return TCL_ERROR;
  75     }
  76 }
  77 .CE
  78
  79 .SH EXAMPLE
  80 In the following example, a "File" class is defined to represent
  81 open files.  The method bodies are included below the class
  82 definition via the \fBbody\fR command.  Note that the bodies
  83 of the constructor/destructor must be included in the class
  84 definition, but they can be redefined via the \fBbody\fR command
  85 as well.
  86 .CS
  87 itcl::class File {
  88     private variable fid ""
  89     constructor {name access} {
  90         set fid [open $name $access]
  91     }
  92     destructor {
  93         close $fid
  94     }
  95
  96     method get {}
  97     method put {line}
  98     method eof {}
  99 }
 100
 101 itcl::body File::get {} {
 102     return [gets $fid]
 103 }
 104 itcl::body File::put {line} {
 105     puts $fid $line
 106 }
 107 itcl::body File::eof {} {
 108     return [::eof $fid]
 109 }
 110
 111 #
 112 # See the File class in action:
 113 #
 114 File x /etc/passwd "r"
 115 while {![x eof]} {
 116     puts "=> [x get]"
 117 }
 118 itcl::delete object x
 119 .CE
 120
 121 .SH KEYWORDS
 122 class, object, procedure