util/X86LINUX64/man/mann/oo_define.n

   1 '\"
   2 '\" Copyright (c) 2007 Donal K. Fellows
   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 define n 0.3 TclOO "TclOO Commands"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 '\" Note:  do not modify the .SH NAME line immediately below!
 277 .SH NAME
 278 oo::define, oo::objdefine \- define and configure classes and objects
 279 .SH SYNOPSIS
 280 .nf
 281 package require TclOO
 282
 283 \fBoo::define\fI class defScript\fR
 284 \fBoo::define\fI class subcommand arg\fR ?\fIarg ...\fR?
 285 \fBoo::objdefine\fI object defScript\fR
 286 \fBoo::objdefine\fI object subcommand arg\fR ?\fIarg ...\fR?
 287 .fi
 288 .BE
 289
 290 .SH DESCRIPTION
 291 The \fBoo::define\fR command is used to control the configuration of classes,
 292 and the \fBoo::objdefine\fR command is used to control the configuration of
 293 objects (including classes as instance objects), with the configuration being
 294 applied to the entity named in the \fIclass\fR or the \fIobject\fR argument.
 295 Configuring a class also updates the
 296 configuration of all subclasses of the class and all objects that are
 297 instances of that class or which mix it in (as modified by any per-instance
 298 configuration). The way in which the configuration is done is controlled by
 299 either the \fIdefScript\fR argument or by the \fIsubcommand\fR and following
 300 \fIarg\fR arguments; when the second is present, it is exactly as if all the
 301 arguments from \fIsubcommand\fR onwards are made into a list and that list is
 302 used as the \fIdefScript\fR argument.
 303 .SS "CONFIGURING CLASSES"
 304 .PP
 305 The following commands are supported in the \fIdefScript\fR for
 306 \fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form:
 307 .TP
 308 \fBconstructor\fI argList bodyScript\fR
 309 .
 310 This creates or updates the constructor for a class. The formal arguments to
 311 the constructor (defined using the same format as for the Tcl \fBproc\fR
 312 command) will be \fIargList\fR, and the body of the constructor will be
 313 \fIbodyScript\fR. When the body of the constructor is evaluated, the current
 314 namespace of the constructor will be a namespace that is unique to the object
 315 being constructed. Within the constructor, the \fBnext\fR command should be
 316 used to call the superclasses' constructors. If \fIbodyScript\fR is the empty
 317 string, the constructor will be deleted.
 318 .TP
 319 \fBdeletemethod\fI name\fR ?\fIname ...\fR
 320 .
 321 This deletes each of the methods called \fIname\fR from a class. The methods
 322 must have previously existed in that class. Does not affect the superclasses
 323 of the class, nor does it affect the subclasses or instances of the class
 324 (except when they have a call chain through the class being modified).
 325 .TP
 326 \fBdestructor\fI bodyScript\fR
 327 .
 328 This creates or updates the destructor for a class. Destructors take no
 329 arguments, and the body of the destructor will be \fIbodyScript\fR. The
 330 destructor is called when objects of the class are deleted, and when called
 331 will have the object's unique namespace as the current namespace. Destructors
 332 should use the \fBnext\fR command to call the superclasses' destructors. Note
 333 that destructors are not called in all situations (e.g. if the interpreter is
 334 destroyed). If \fIbodyScript\fR is the empty string, the destructor will be
 335 deleted.
 336 .RS
 337 Note that errors during the evaluation of a destructor \fIare not returned\fR
 338 to the code that causes the destruction of an object. Instead, they are passed
 339 to the currently-defined \fBbgerror\fR handler.
 340 .RE
 341 .TP
 342 \fBexport\fI name \fR?\fIname ...\fR?
 343 .
 344 This arranges for each of the named methods, \fIname\fR, to be exported
 345 (i.e. usable outside an instance through the instance object's command) by the
 346 class being defined. Note that the methods themselves may be actually defined
 347 by a superclass; subclass exports override superclass visibility, and may in
 348 turn be overridden by instances.
 349 .TP
 350 \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
 351 .VS
 352 This slot (see \fBSLOTTED DEFINITIONS\fR below)
 353 .VE
 354 sets or updates the list of method names that are used to guard whether
 355 method call to instances of the class may be called and what the method's
 356 results are. Each \fImethodName\fR names a single filtering method (which may
 357 be exposed or not exposed); it is not an error for a non-existent method to be
 358 named since they may be defined by subclasses.
 359 .VS
 360 By default, this slot works by appending.
 361 .VE
 362 .TP
 363 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 364 .
 365 This creates or updates a forwarded method called \fIname\fR. The method is
 366 defined be forwarded to the command called \fIcmdName\fR, with additional
 367 arguments, \fIarg\fR etc., added before those arguments specified by the
 368 caller of the method. The \fIcmdName\fR will always be resolved using the
 369 rules of the invoking objects' namespaces, i.e., when \fIcmdName\fR is not
 370 fully-qualified, the command will be searched for in each object's namespace,
 371 using the instances' namespace's path, or by looking in the global namespace.
 372 The method will be exported if \fIname\fR starts with a lower-case letter, and
 373 non-exported otherwise.
 374 .TP
 375 \fBmethod\fI name argList bodyScript\fR
 376 .
 377 This creates or updates a method that is implemented as a procedure-like
 378 script. The name of the method is \fIname\fR, the formal arguments to the
 379 method (defined using the same format as for the Tcl \fBproc\fR command) will
 380 be \fIargList\fR, and the body of the method will be \fIbodyScript\fR. When
 381 the body of the method is evaluated, the current namespace of the method will
 382 be a namespace that is unique to the current object. The method will be
 383 exported if \fIname\fR starts with a lower-case letter, and non-exported
 384 otherwise; this behavior can be overridden via \fBexport\fR and
 385 \fBunexport\fR.
 386 .TP
 387 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
 388 .VS
 389 This slot (see \fBSLOTTED DEFINITIONS\fR below)
 390 .VE
 391 sets or updates the list of additional classes that are to be mixed into
 392 all the instances of the class being defined. Each \fIclassName\fR argument
 393 names a single class that is to be mixed in.
 394 .VS
 395 By default, this slot works by replacement.
 396 .VE
 397 .TP
 398 \fBrenamemethod\fI fromName toName\fR
 399 .
 400 This renames the method called \fIfromName\fR in a class to \fItoName\fR. The
 401 method must have previously existed in the class, and \fItoName\fR must not
 402 previously refer to a method in that class. Does not affect the superclasses
 403 of the class, nor does it affect the subclasses or instances of the class
 404 (except when they have a call chain through the class being modified). Does
 405 not change the export status of the method; if it was exported before, it will
 406 be afterwards.
 407 .TP
 408 \fBself\fI subcommand arg ...\fR
 409 .TP
 410 \fBself\fI script\fR
 411 .
 412 This command is equivalent to calling \fBoo::objdefine\fR on the class being
 413 defined (see \fBCONFIGURING OBJECTS\fR below for a description of the
 414 supported values of \fIsubcommand\fR). It follows the same general pattern of
 415 argument handling as the \fBoo::define\fR and \fBoo::objdefine\fR commands,
 416 and
 417 .QW "\fBoo::define \fIcls \fBself \fIsubcommand ...\fR"
 418 operates identically to
 419 .QW "\fBoo::objdefine \fIcls subcommand ...\fR" .
 420 .TP
 421 \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
 422 .VS
 423 This slot (see \fBSLOTTED DEFINITIONS\fR below)
 424 .VE
 425 allows the alteration of the superclasses of the class being defined.
 426 Each \fIclassName\fR argument names one class that is to be a superclass of
 427 the defined class. Note that objects must not be changed from being classes to
 428 being non-classes or vice-versa, that an empty parent class is equivalent to
 429 \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and
 430 \fBoo::class\fR may not be modified.
 431 .VS
 432 By default, this slot works by replacement.
 433 .VE
 434 .TP
 435 \fBunexport\fI name \fR?\fIname ...\fR?
 436 .
 437 This arranges for each of the named methods, \fIname\fR, to be not exported
 438 (i.e. not usable outside the instance through the instance object's command,
 439 but instead just through the \fBmy\fR command visible in each object's
 440 context) by the class being defined. Note that the methods themselves may be
 441 actually defined by a superclass; subclass unexports override superclass
 442 visibility, and may be overridden by instance unexports.
 443 .TP
 444 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
 445 .VS
 446 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 447 variables to be automatically made
 448 available in the methods, constructor and destructor declared by the class
 449 being defined. Each variable name must not have any namespace
 450 separators and must not look like an array access. All variables will be
 451 actually present in the instance object on which the method is executed. Note
 452 that the variable lists declared by a superclass or subclass are completely
 453 disjoint, as are variable lists declared by instances; the list of variable
 454 names is just for methods (and constructors and destructors) declared by this
 455 class. By default, this slot works by appending.
 456 .VE
 457 .SS "CONFIGURING OBJECTS"
 458 .PP
 459 The following commands are supported in the \fIdefScript\fR for
 460 \fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR
 461 form:
 462 .TP
 463 \fBclass\fI className\fR
 464 .
 465 This allows the class of an object to be changed after creation. Note that the
 466 class's constructors are not called when this is done, and so the object may
 467 well be in an inconsistent state unless additional configuration work is done.
 468 .TP
 469 \fBdeletemethod\fI name\fR ?\fIname ...\fR
 470 .
 471 This deletes each of the methods called \fIname\fR from an object. The methods
 472 must have previously existed in that object. Does not affect the classes that
 473 the object is an instance of.
 474 .TP
 475 \fBexport\fI name \fR?\fIname ...\fR?
 476 .
 477 This arranges for each of the named methods, \fIname\fR, to be exported
 478 (i.e. usable outside the object through the object's command) by the object
 479 being defined. Note that the methods themselves may be actually defined by a
 480 class or superclass; object exports override class visibility.
 481 .TP
 482 \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
 483 .VS
 484 This slot (see \fBSLOTTED DEFINITIONS\fR below)
 485 .VE
 486 sets or updates the list of method names that are used to guard whether a
 487 method call to the object may be called and what the method's results are.
 488 Each \fImethodName\fR names a single filtering method (which may be exposed or
 489 not exposed); it is not an error for a non-existent method to be named. Note
 490 that the actual list of filters also depends on the filters set upon any
 491 classes that the object is an instance of.
 492 .VS
 493 By default, this slot works by appending.
 494 .VE
 495 .TP
 496 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 497 .
 498 This creates or updates a forwarded object method called \fIname\fR. The
 499 method is defined be forwarded to the command called \fIcmdName\fR, with
 500 additional arguments, \fIarg\fR etc., added before those arguments specified
 501 by the caller of the method. Forwarded methods should be deleted using the
 502 \fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with
 503 a lower-case letter, and non-exported otherwise.
 504 .TP
 505 \fBmethod\fI name argList bodyScript\fR
 506 .
 507 This creates, updates or deletes an object method. The name of the method is
 508 \fIname\fR, the formal arguments to the method (defined using the same format
 509 as for the Tcl \fBproc\fR command) will be \fIargList\fR, and the body of the
 510 method will be \fIbodyScript\fR. When the body of the method is evaluated, the
 511 current namespace of the method will be a namespace that is unique to the
 512 object. The method will be exported if \fIname\fR starts with a lower-case
 513 letter, and non-exported otherwise.
 514 .TP
 515 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
 516 .VS
 517 This slot (see \fBSLOTTED DEFINITIONS\fR below)
 518 .VE
 519 sets or updates a per-object list of additional classes that are to be
 520 mixed into the object. Each argument, \fIclassName\fR, names a single class
 521 that is to be mixed in.
 522 .VS
 523 By default, this slot works by replacement.
 524 .VE
 525 .TP
 526 \fBrenamemethod\fI fromName toName\fR
 527 .
 528 This renames the method called \fIfromName\fR in an object to \fItoName\fR.
 529 The method must have previously existed in the object, and \fItoName\fR must
 530 not previously refer to a method in that object. Does not affect the classes
 531 that the object is an instance of. Does not change the export status of the
 532 method; if it was exported before, it will be afterwards.
 533 .TP
 534 \fBunexport\fI name \fR?\fIname ...\fR?
 535 .
 536 This arranges for each of the named methods, \fIname\fR, to be not exported
 537 (i.e. not usable outside the object through the object's command, but instead
 538 just through the \fBmy\fR command visible in the object's context) by the
 539 object being defined. Note that the methods themselves may be actually defined
 540 by a class; instance unexports override class visibility.
 541 .TP
 542 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
 543 .VS
 544 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 545 variables to be automatically made available in the methods declared by the
 546 object being defined.  Each variable name must not have any namespace
 547 separators and must not look like an array access. All variables will be
 548 actually present in the object on which the method is executed. Note that the
 549 variable lists declared by the classes and mixins of which the object is an
 550 instance are completely disjoint; the list of variable names is just for
 551 methods declared by this object. By default, this slot works by appending.
 552 .SH "SLOTTED DEFINITIONS"
 553 Some of the configurable definitions of a class or object are \fIslotted
 554 definitions\fR. This means that the configuration is implemented by a slot
 555 object, that is an instance of the class \fBoo::Slot\fR, which manages a list
 556 of values (class names, variable names, etc.) that comprises the contents of
 557 the slot. The class defines three operations (as methods) that may be done on
 558 the slot:
 559 .VE
 560 .TP
 561 \fIslot\fR \fB\-append\fR ?\fImember ...\fR?
 562 .VS
 563 This appends the given \fImember\fR elements to the slot definition.
 564 .VE
 565 .TP
 566 \fIslot\fR \fB\-clear\fR
 567 .VS
 568 This sets the slot definition to the empty list.
 569 .VE
 570 .TP
 571 \fIslot\fR \fB\-set\fR ?\fImember ...\fR?
 572 .VS
 573 This replaces the slot definition with the given \fImember\fR elements.
 574 .PP
 575 A consequence of this is that any use of a slot's default operation where the
 576 first member argument begins with a hyphen will be an error. One of the above
 577 operations should be used explicitly in those circumstances.
 578 .SS "SLOT IMPLEMENTATION"
 579 Internally, slot objects also define a method \fB\-\-default\-operation\fR
 580 which is forwarded to the default operation of the slot (thus, for the class
 581 .QW \fBvariable\fR
 582 slot, this is forwarded to
 583 .QW "\fBmy \-append\fR" ),
 584 and these methods which provide the implementation interface:
 585 .VE
 586 .TP
 587 \fIslot\fR \fBGet\fR
 588 .VS
 589 Returns a list that is the current contents of the slot. This method must
 590 always be called from a stack frame created by a call to \fBoo::define\fR or
 591 \fBoo::objdefine\fR.
 592 .VE
 593 .TP
 594 \fIslot\fR \fBSet \fIelementList\fR
 595 .VS
 596 Sets the contents of the slot to the list \fIelementList\fR and returns the
 597 empty string. This method must always be called from a stack frame created by
 598 a call to \fBoo::define\fR or \fBoo::objdefine\fR.
 599 .PP
 600 The implementation of these methods is slot-dependent (and responsible for
 601 accessing the correct part of the class or object definition). Slots also have
 602 an unknown method handler to tie all these pieces together, and they hide
 603 their \fBdestroy\fR method so that it is not invoked inadvertently. It is
 604 \fIrecommended\fR that any user changes to the slot mechanism be restricted to
 605 defining new operations whose names start with a hyphen.
 606 .VE
 607 .SH EXAMPLES
 608 This example demonstrates how to use both forms of the \fBoo::define\fR and
 609 \fBoo::objdefine\fR commands (they work in the same way), as well as
 610 illustrating four of the subcommands of them.
 611 .PP
 612 .CS
 613 oo::class create c
 614 c create o
 615 \fBoo::define\fR c \fBmethod\fR foo {} {
 616     puts "world"
 617 }
 618 \fBoo::objdefine\fR o {
 619     \fBmethod\fR bar {} {
 620         my Foo "hello "
 621         my foo
 622     }
 623     \fBforward\fR Foo ::puts -nonewline
 624     \fBunexport\fR foo
 625 }
 626 o bar                \fI\(-> prints "hello world"\fR
 627 o foo                \fI\(-> error "unknown method foo"\fR
 628 o Foo Bar            \fI\(-> error "unknown method Foo"\fR
 629 \fBoo::objdefine\fR o \fBrenamemethod\fR bar lollipop
 630 o lollipop           \fI\(-> prints "hello world"\fR
 631 .CE
 632 .PP
 633 This example shows how additional classes can be mixed into an object. It also
 634 shows how \fBmixin\fR is a slot that supports appending:
 635 .PP
 636 .CS
 637 oo::object create inst
 638 inst m1              \fI\(-> error "unknown method m1"\fR
 639 inst m2              \fI\(-> error "unknown method m2"\fR
 640
 641 oo::class create A {
 642     \fBmethod\fR m1 {} {
 643         puts "red brick"
 644     }
 645 }
 646 \fBoo::objdefine\fR inst {
 647     \fBmixin\fR A
 648 }
 649 inst m1              \fI\(-> prints "red brick"\fR
 650 inst m2              \fI\(-> error "unknown method m2"\fR
 651
 652 oo::class create B {
 653     \fBmethod\fR m2 {} {
 654         puts "blue brick"
 655     }
 656 }
 657 \fBoo::objdefine\fR inst {
 658     \fBmixin -append\fR B
 659 }
 660 inst m1              \fI\(-> prints "red brick"\fR
 661 inst m2              \fI\(-> prints "blue brick"\fR
 662 .CE
 663 .SH "SEE ALSO"
 664 next(n), oo::class(n), oo::object(n)
 665 .SH KEYWORDS
 666 class, definition, method, object, slot
 667 .\" Local variables:
 668 .\" mode: nroff
 669 .\" fill-column: 78
 670 .\" End: