\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#92: Move Package Load Decisions to Application Developer}
\date{May 13, 2002}
\author{Clif Flynt}
\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 \#92}&\textbf{Move Package Load Decisions to Application Developer}\\\hline
Author&

Clif Flynt \tipmail{clif}{cflynt.com}
\\
Created&Monday, \(\text{13}^{\text{th}}\) May 2002\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Withdrawn\\
Vote&Pending\\
Version&\tipversion$Revision: 1.3 $\\
Keywords&package require, namespace, pkg\_mkIndex\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP makes the loading of packages far more flexible, so as to better support their use by application authors in situations above and beyond those foreseen by the developer of the package.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Overview}

I believe that we've been misdirecting our efforts in solutions to the Package issue.
\begin{itemize}
\item{}
The modifications to \textit{pkg\_mkIndex} give the library author (or package builder) the ability to define when a package will be loaded (immediate or deferred), which restricts an application developer to the decisions made by the library author.
\item{}
If a package is built to be loaded immediately, it is loaded into the top-level namespace. This breaks previous tricks to force a package to load inside an existing namespace.
\end{itemize}

These techniques limit the application writer to the behavior (and uses) envisioned by the package author and is counter to the concept that application developer best understands how they need a tool to perform for their application. The Tcl community, in particular, has grown largely because the tools have had applications far beyond those imagined by their initial developers.

Moving the decisions about when and how to load a package from \textit{pkg\_mkIndex} to the \textit{package require} command allows the application writer the freedom to find new styles of use that the package author may not have conceived.

Being able to force an immediate load into the current namespace rather than always loading packages into the global scope provides support for lightweight object style data structures without the need for extensions like Incr Tcl, OOTcl, etc.

Loading a package/namespace into the current namespace provides mechanisms for lightweight inheritance, and since namespaces can contain both code and data, loading a namespace multiple times (in separate namespaces) is a lightweight aggregation model.

I do not propose that this power removes the need for full object oriented programming models within the Tcl community. However, I believe that putting the power to develop these lightweight models into the application developer provides the developer with a more versatile tool kit than they currently have. (One that I've been using for several years, with workarounds.)

This proposal is to add new flags to the package require command, allowing an application developer to determine when and how to load a package.
\begin{description}
\item[-current]
Load the package into the current namespace rather than the global space. Implies immediate.
\item[-multiple]
Allow loading multiple copies of this package, for use with \textit{-current} when the application programmer wishes to create multiple nested copies of a package.
\item[-immediate]
Load immediately, rather than defer loading the package until needed. This is the default behavior with Tcl 8.3 and later.
\item[-defer]
Load package when required. The default with Tcl 8.2 and earlier, or when \textit{pkg\_mkIndex -lazy} used with Tcl 8.3.
\item[-exact]
No change to this option. Requires an exact Major/Minor revision match to be an acceptable package.
\end{description}

\section{Script Example}

The code below implements a simple stack object that can be merged into other namespaces to create objects that contain individual stacks.
\begingroup\small\begin{verbatim}
 package provide stack 1.0
 namespace eval stack {
     namespace export push pop peek size
     variable stack ""
     
     proc push {val} {
         variable stack;
         lappend stack $val
     }
      
     proc pop {} {
         variable stack;
         set rtn [lindex $stack end]
         set stack [lrange $stack 0 end-1]
         return $rtn
         }
 
     proc peek {{pos end}} {
         variable stack;
         return [lindex $stack $pos]
     }
      
     proc size {} {
         variable stack;
         return [llength $stack]
     }
      
 }
  
\end{verbatim}
\endgroup

With this data structure available, the guts of a Tower of Hanoi puzzle becomes simple:
\begingroup\small\begin{verbatim}
 namespace eval left {
         package require -current -multiple  stack 1.0
         namespace import [namespace current]::stack::*
     }   
 namespace eval center {
         package require -current -multiple  stack 1.0
         namespace import [namespace current]::stack::*
     }
 namespace eval right {
         package require -current -multiple  stack 1.0
         namespace import [namespace current]::stack::*
     }
      
 proc move {from to} {
         ${to}::push [${from}::pop]
     }
\end{verbatim}
\endgroup

This creates 3 'objects' each of which contains a private stack with the stack methods.

\section{Reference Implementation}

A reference implementation of the \textit{-current} and \textit{-multiple} flags has been created for Tcl 8.4a4 and is available at \url{http://noucorp.com/PkgPatch8.4.zip}

The implementation required these modifications to \textit{generic/tclPkg.c}:
\begin{itemize}
\item{}
\textit{Tcl\_PackageObjCmd} needs to be able to parse the new options and set the bitmapped flag.
\item{}
\textit{Tcl\_PkgRequireEx} is modified to accept a bitmapped flag instead of the \textit{exact} option.
\item{}
The 0x0001 bitmap position is used to map for \textit{exact} preserving the existing behavior of the \textit{Tcl\_PackageObjCmd} and \textit{Tcl\_PkgRequireEx} functions.
\item{}
These bitmapped flags are defined exact, current, and multiple:
\begingroup\small\begin{verbatim}
#define PKG_EXACT    0x01   /* Use the exact version - as used for exact */
#define PKG_CURRENT  0x02   /* Load into current namespace, not GLOBAL */
#define PKG_MULTIPLE 0x04   /* Allow loading multiple copies of a package */
\end{verbatim}
\endgroup
\item{}
\textit{Tcl\_PkgRequireEx} is modified to process the MULTIPLE and CURRENT flags.
\item{}
The Tcl tests have been reworked to understand the new error returns, etc. Running ``make tests'' will accept the new code.
\end{itemize}

Minimal testing has been done using pure Tcl packages. 

\section{Colophon}

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