\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#397: Extensible Object Copying}
\date{February 13, 2012}
\author{Donal K. Fellows}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#397}&\textbf{Extensible Object Copying}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{manchester.ac.uk}
\\
Created&Monday, \(\text{13}^{\text{th}}\) February 2012\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Keywords&Tcl, TclOO, copy, clone\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a mechanism whereby an object or class can provide additional control over how it gets copied to a new one by the \textbf{oo::copy} command.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

I always knew that TclOO's \textbf{oo::copy} command was not particularly complete, in that only the C-level state was copied. The vast majority of state associated with an object (notably including its variables) was not copied on the grounds that the caller of \textbf{oo::copy} could do that for themselves. However, this has not proved particularly workable in practice once someone actually started to use the mechanism. It turns out that the callers of \textbf{oo::copy} expect a full copy of the object to be created.

This is quite challenging because some things associated with an object are tricky to copy correctly. For example, if an object has a number of Tk widgets under its control, or has timer callbacks set up, these are very challenging for a generic object copying scheme to detect (and generic copying of Tcl commands is difficult anyway). Fortunately, we already have a mechanism for handling such per-object variation: methods.

\section{Proposed Change}

I propose that the \textbf{oo::copy} command will internally call the newly created object's \textbf{\tiplangle{}cloned\tiprangle{}} method (passing in the name of the source object as the only argument) to allow for the customization of the copy. If the method fails (throws an exception), the copy will be destroyed and the error propagated.

\begin{quote}
\textit{copiedObject} \textbf{\tiplangle{}cloned\tiprangle{}} \textit{sourceObject}
\end{quote}

Furthermore, a default implementation of the \textbf{\tiplangle{}cloned\tiprangle{}} method will be created in \textbf{oo::object} which will duplicate the variables and procedures (note, not other commands) of the source to the copy. This method will not be exported by default (nor should it be; the method is not intended to be called directly).

\section{Reference Implementation}

See the ``development-rfe3485060'' branch of the tcloo repository: \url{https://core.tcl.tk/tcloo/timeline?r=development-rfe3485060}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
