util/src/TclTk/tcl8.6.12/doc/copy.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 copy n 0.1 TclOO "TclOO Commands"
   8 .so man.macros
   9 .BS
  10 '\" Note:  do not modify the .SH NAME line immediately below!
  11 .SH NAME
  12 oo::copy \- create copies of objects and classes
  13 .SH SYNOPSIS
  14 .nf
  15 package require TclOO
  16
  17 \fBoo::copy\fI sourceObject \fR?\fItargetObject\fR? ?\fItargetNamespace\fR?
  18 .fi
  19 .BE
  20 .SH DESCRIPTION
  21 .PP
  22 The \fBoo::copy\fR command creates a copy of an object or class. It takes the
  23 name of the object or class to be copied, \fIsourceObject\fR, and optionally
  24 the name of the object or class to create, \fItargetObject\fR, which will be
  25 resolved relative to the current namespace if not an absolute qualified name
  26 and
  27 .VS TIP473
  28 \fItargetNamespace\fR which is the name of the namespace that will hold the
  29 internal state of the object (\fBmy\fR command, etc.); it \fImust not\fR
  30 refer to an existing namespace.
  31 If either \fItargetObject\fR or \fItargetNamespace\fR is omitted or is given
  32 as the empty string, a new name is chosen. Names, unless specified, are
  33 chosen with the same algorithm used by the \fBnew\fR method of
  34 \fBoo::class\fR.
  35 .VE TIP473
  36 The copied object will be of the same class as the source object, and will have
  37 all its per-object methods copied. If it is a class, it will also have all the
  38 class methods in the class copied, but it will not have any of its instances
  39 copied.
  40 .PP
  41 .VS
  42 After the \fItargetObject\fR has been created and all definitions of its
  43 configuration (e.g., methods, filters, mixins) copied, the \fB<cloned>\fR
  44 method of \fItargetObject\fR will be invoked, to allow for customization of
  45 the created object such as installing related variable traces. The only
  46 argument given will be \fIsourceObject\fR. The default implementation of this
  47 method (in \fBoo::object\fR) just copies the procedures and variables in the
  48 namespace of \fIsourceObject\fR to the namespace of \fItargetObject\fR. If
  49 this method call does not return a result that is successful (i.e., an error
  50 or other kind of exception) then the \fItargetObject\fR will be deleted and an
  51 error returned.
  52 .VE
  53 .PP
  54 The result of the \fBoo::copy\fR command will be the fully-qualified name of
  55 the new object or class.
  56 .SH EXAMPLES
  57 .PP
  58 This example creates an object, copies it, modifies the source object, and
  59 then demonstrates that the copied object is indeed a copy.
  60 .PP
  61 .CS
  62 oo::object create src
  63 oo::objdefine src method msg {} {puts foo}
  64 \fBoo::copy\fR src dst
  65 oo::objdefine src method msg {} {puts bar}
  66 src msg              \fI\(-> prints "bar"\fR
  67 dst msg              \fI\(-> prints "foo"\fR
  68 .CE
  69 .SH "SEE ALSO"
  70 oo::class(n), oo::define(n), oo::object(n)
  71 .SH KEYWORDS
  72 clone, copy, duplication, object
  73 .\" Local variables:
  74 .\" mode: nroff
  75 .\" fill-column: 78
  76 .\" End: