\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#65: Enhanced [info args]}
\date{September 18, 2001}
\author{Glenn Jackman, Don Porter, Glenn Jackman}
\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 \#65}&\textbf{Enhanced [info args]}\\\hline
Author&

Glenn Jackman \tipmail{glennj}{nortelnetworks.com}
\par
Don Porter \tipmail{dgp}{users.sf.net}
\par
Glenn Jackman \tipmail{glennj}{ncf.ca}
\\
Created&Tuesday, \(\text{18}^{\text{th}}\) September 2001\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Rejected\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a new subcommand to the [info] command be added that would return the list of arguments, together with any default values in the same format as the \textit{args} parameter to the [proc] command.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Introduction}

The [proc] man page defines \textit{args} as:

\begin{quote}
... the formal arguments to the procedure. It consists of a list, possibly empty, each of whose elements specifies one argument. Each argument specifier is also a list with either one or two fields. If there is only a single field in the specifier then it is the name of the argument; if there are two fields, then the first is the argument name and the second is its default value.
\end{quote}

Suppose we define a procedure like this:
\begingroup\small\begin{verbatim}
       proc test {one {two 2} {three {3 4 5}} args} {return}
\end{verbatim}
\endgroup

We want to determine the formal arguments for this procedure. We want some method to return the list:
\begingroup\small\begin{verbatim}
       one {two 2} {three {3 4 5}} args
\end{verbatim}
\endgroup

[info args] fails us because it does not return default values, only the list of argument names \{one two three args\}.

The [info default] command exists, and does partially what we want. However [info default] only operates on a single argument. To determine the complete list of arguments with default values, we must iterate over the arguments returned by [info args]. We would define a procedure like:
\begingroup\small\begin{verbatim}
       proc info_args_with_defaults {procname} {
           set argspec [list]
           # [info args] throws an error if $procname is not a procedure.
           foreach arg [info args $procname] {
               if {[info default $procname $arg value]} {
                   lappend argspec [list $arg $value]
               } else {
                   lappend argspec $arg
               }
           }
           return $argspec
       }
       info_args_with_defaults test  ;# ==> returns {one {two 2} {three {3 4 5}} args}
\end{verbatim}
\endgroup

A more sophisticated scripted solution is to overload the [info] command itself, as described in the Wiki at \url{http://wiki.tcl.tk/wrappingCommands}

It would be much more convenient to be able to rely on the [info] command itself to return the desired information, particularly since it \textit{almost} does what we want already.

\textit{This topic was originally raised in the \url{news:comp.lang.tcl} newsgroup in the thread \url{http://groups.google.com/groups?th=4b0d5dba85d2c160}}

\section{Specification}

Add [info formalargs] to the set of subcommands for Tcl's built-in [info] command, with syntax:
\begingroup\small\begin{verbatim}
 info formalargs $procName
\end{verbatim}
\endgroup

This command will raise an error if \textit{\$procName} is not the name of a proc. Otherwise, it will return a list of formal arguments of the named proc, along with their default values, if any, in a format suitable for passing to the [proc] command as a second argument.

\section{Rationale}

With the goal of maintaining backwards compatibility in mind, two possibilities arise: adding a new switch to the existing [info args] command, and adding a completely new subcommand to [info].

Adding a switch to [info args] may break backwards compatibility. If we use the syntax [info args \textit{?-withdefaults? procname}], there may be trouble with existing scripts containing a procedure named ``-withdefaults''. The syntax [info args \textit{procname ?-withdefaults?}] is completely backwards compatible. However, among Tcl commands that take subcommands, there is currently some inconsistency as to where switches should appear. [clock] subcommands place these options after required parameters. [namespace] and [package] subcommands place these options before required parameters. Some [file] subcommands put them before, some after. Currently, no [info] subcommands take switches.

Rather than compound to this inconsistency, creating a new [info] subcommand feels cleaner. Possible names include:
\begin{description}
\item[argspec, arglist, args\_with\_defaults]
These all collide with the ``arg'', ``ar'', ``a'' shorthands for [info args \textit{procname}]. And \textit{args\_with\_defaults} is just *way* too ugly.
\item[formalargs, fullargs]
Either of these could be used. This collides with the ``f'' shorthand for [info functions]
\item[parameters]
This collides with the ``pa'' shorthand for [info patchlevel]
\item[prototype]
This collides with the ``pro'' and ``pr'' shorthands for [info procs \textit{?pattern?}]
\item[signature]
This could be used, as it does not collide with any shorthand for either [info script] or [info sharedlibextension].
\end{description}

The term ``signature'' has meaning in the Java and C++ worlds: the function name and its arguments together comprise the signature. The purpose of this TIP is to return only the arguments with any defaults, so to avoid any potential confusion I will rule out ``signature''.

Of the remaining possibilities, my choice would be ``formalargs''. The term ``formal arguments'' is used in the [proc] man page. ``formalargs'' also incorporates the word ``args'', indicating a relationship to [info args].

\section{Reference Implementation}

Refer to the submitted patch, which implements an subcommand named [info fullargs], at: \url{http://sourceforge.net/tracker/index.php?func=detail&aid=461635&group_id=10894&atid=310894}

\section{Reasons for Rejection}

Those voting against this proposal believed that since the desired functionality is already possible with a short script of just a few Tcl commands, it would be unnecessary bloat to add another subcommand. Some also pointed to \cite{tip112} as another approach to letting people extend Tcl built-in commands with their own custom subcommands.

\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 \#112]{tip112}
Donal K. Fellows,
\emph{Ensembles are Namespaces are Commands},
on-line at \url{http://purl.org/tcl/tip/112.html}
\end{thebibliography}
\end{document}
