\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#320: Improved Variable Handling in the Core Object System}
\date{June 13, 2008}
\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 \#320}&\textbf{Improved Variable Handling in the Core Object System}\\\hline
Author&

Donal K. Fellows \tipmail{dkf}{users.sf.net}
\\
Created&Friday, \(\text{13}^{\text{th}}\) June 2008\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Keywords&TclOO\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP specifies new configuration commands that allow variables to be used in methods of the core object system without explicit declaration in each method.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

During the discussions leading up to the vote on \cite{tip257}, it became apparent that being able to access at least some variables of an object without explicit declaration in each method was desirable. Doing this would make working with the core object system much easier in many common cases, and would also allow for potentially more efficient implementation.

However, there is a balance to be drawn. If every variable of the object was made available in the method by default (the simplest case) there would frequently be problems with interactions between the formal arguments of a superclass's methods and the instance variables of a subclass! That would be highly undesirable, as it completely breaks the principle of isolation of class implementations.

There are two ways of dealing with this issue.
\begin{enumerate}
\item{}
Make the variables understood by a particular class be distinct from those understood by subclasses of the class.
\setcounter{enumi}{1}
\item{}
Only bring those variables into scope that are actually declared by a particular class.
\end{enumerate}

Studying the first alternative, there are two ways to actually achieve this: not putting the variables in a namespace but actually using a separate structure (poor, because then we would lose the ability to easily use the variable with many of Tcl's general variable facilities), or modifying the namespace-visible name of each variable to include some unique string coupled to the class declaring it. Though I think that the second option is better than the first (actual implementations would be able to use the \textbf{oo::object} class's \textbf{variable} and \textbf{varname} methods to hide many of the details where they are currently exposed at all) I still do not particularly like it since it would mean that the cases where a class and a subclass \textit{want} to refer to the same variable are very awkward.

Hence I think that there should be a mechanism for declaring what variables a class has, that those names should be the namespace-visible names of the variables, and that only those variables that are declared by a particular class should be \textit{automatically} visible in the class's methods (including the constructor and destructor, of course). As a matter of basic symmetry, object-level declarations of variables and methods should also be possible.

\section{Proposed Change}

Every object and every class will have associated with it a list of variable names. This list will be configurable via a subcommand of \textbf{oo::define} and introspectable. Methods (strictly, only procedure-like methods, constructors and destructors) will then make those variables that were declared at the same declaration level (i.e. in the same class, or in the object itself for methods defined on the object) available in the method body without further declaration or qualification. At declaration time, the type of the variable (i.e. whether it is an array or a simple variable) will not be defined; that may be done in the constructor. As there is no (public) C API for declaring a procedure-like method, there will not be a public C API for declaring the variables either.

Note that the order in which the declaration of some methods and some variables for a class or object will not matter.

\subsection{Declaration}

The \textbf{oo::define} and \textbf{oo::objdefine} (and also the \textbf{self} subcommand of \textbf{oo::define}) will gain a new subcommand: \textbf{variable}. This will take zero or more arguments, and those arguments will form the list of variables that are made available by default. Each argument will need to be a valid variable local name without parentheses.

Syntax (other uses analogous according to normal behaviour of the class and object definition commands):

\begin{quote}
\textbf{oo::define} \textit{class} \textbf{variable} ?\textit{varName ...}?
\end{quote}

\subsection{Introspection}

The list of variables declared by a particular class, \textit{class}, may be retrieved by:

\begin{quote}
\textbf{info class variables} \textit{class}
\end{quote}

The list of variables declared by a particular object, \textit{object}, may be retrieved by:

\begin{quote}
\textbf{info object variables} \textit{object}
\end{quote}

Note that the full list of \textit{all} variables (matching an optional pattern) in an object's namespace will be retrievable using \textbf{info object vars}; this mechanism is disjoint (though \textbf{info object variables} will return variables that can be returned by \textbf{info object vars}).

\section{Implementation}

\url{https://sourceforge.net/support/tracker.php?aid=2005460}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#257]{tip257}
Donal K. Fellows,
Will Duquette,
Steve Landers,
Jeff Hobbs,
Kevin Kenny,
Miguel Sofer,
Richard Suchenwirth,
Larry W. Virden,
\emph{Object Orientation for Tcl},
on-line at \url{http://purl.org/tcl/tip/257.html}
\end{thebibliography}
\end{document}
