%-*-mode:latex-*-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (C) 1996-2004 Jason Evans <jasone@canonware.com>.
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions
% are met:
% 1. Redistributions of source code must retain the above copyright
%    notice(s), this list of conditions and the following disclaimer
%    unmodified other than the allowable addition of one or more
%    copyright notices.
% 2. Redistributions in binary form must reproduce the above copyright
%    notice(s), this list of conditions and the following disclaimer in
%    the documentation and/or other materials provided with the
%    distribution.
% 
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
% EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
% PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
% BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
% WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
% OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
% EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Version: Onyx 5.1.1
%
% vclass reference portion of Onyx Manual.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{vclass}
\label{sec:vclass}
\index{systemdict@\onyxop{}{vclass}{}}

The \classname{vclass} class serves as a base class from which a class hierarchy
can be built.  Although there are no mechanisms that force the use of
\classname{vclass} when constructing a class hierarchy, it usually makes sense
to do so, since the operators that implement object-oriented programming support
provide mechanisms, but almost no policy.  \classname{vclass} provides what
little policy is needed, such as the naming and invocation of constructors.

\begin{longtable}{\optableformat{4.10}}
\caption{vclass summary}
\\
\hline
\optableent
	{Input(s)}
	{Method}
	{Output(s)}
	{Description}
\hline \hline
%begin{latexonly}
\endfirsthead
\caption[]{\emph{continued}} \\
\hline
\optableent
	{Input(s)}
	{Method}
	{Output(s)}
	{Description}
\hline \hline \endhead
\multicolumn{2}{r}{\emph{Continued on next page...}} \endfoot
\hline \endlastfoot
%end{latexonly}
\multicolumn{2}{|l|}{Class-context methods} \\
\hline \hline
\optableent
	{--}
	{{\bf \htmlref{new}{vclass:new}}}
	{instance}
	{Constructor.}
\hline
\optableent
	{--}
	{{\bf \htmlref{rnew}{vclass:rnew}}}
	{instance}
	{Construction helper.}
\hline
\optableent
	{name}
	{{\bf \htmlref{implementor}{vclass:implementor}}}
	{class/null}
	{Get class that implements name.}
\hline
\optableent
	{name}
	{{\bf \htmlref{implements}{vclass:implements}}}
	{boolean}
	{Does class implement name?}
\hline
\optableent
	{name}
	{{\bf \htmlref{method}{vclass:method}}}
	{method}
	{Get class method by name.}
\hline
\optableent
	{--}
	{{\bf \htmlref{classname}{vclass:classname}}}
	{name/null}
	{Get class's name.}
\hline
\optableent
	{name/null}
	{{\bf \htmlref{setclassname}{vclass:setclassname}}}
	{--}
	{Set class's name.}
\hline
\optableent
	{--}
	{{\bf \htmlref{super}{vclass:super}}}
	{super/null}
	{Get class's superclass.}
\hline
\optableent
	{super/null}
	{{\bf \htmlref{setsuper}{vclass:setsuper}}}
	{--}
	{Set class's superclass.}
\hline
\optableent
	{--}
	{{\bf \htmlref{methods}{vclass:methods}}}
	{dict/null}
	{Get methods dict for class.}
\hline
\optableent
	{dict/null}
	{{\bf \htmlref{setmethods}{vclass:setmethods}}}
	{--}
	{Set methods dict for class.}
\hline \hline
\multicolumn{2}{|l|}{Class/instance-context methods} \\
\hline \hline
\optableent
	{--}
	{{\bf \htmlref{data}{vclass:data}}}
	{dict/null}
	{Get data for class/instance.}
\hline
\optableent
	{dict/null}
	{{\bf \htmlref{setdata}{vclass:setdata}}}
	{--}
	{Set data for class/instance.}
\hline
\optableent
	{key val}
	{{\bf \htmlref{def}{vclass:def}}}
	{--}
	{Define key as val in class/instance data dict.}
\hline
\optableent
	{key}
	{{\bf \htmlref{undef}{vclass:undef}}}
	{--}
	{Undefine key in class/instance data dict.}
\hline \hline
\multicolumn{2}{|l|}{Instance-context methods} \\
\hline \hline
\optableent
	{--}
	{{\bf \htmlref{isa}{vclass:isa}}}
	{class/null}
	{Get class for instance.}
\hline
\optableent
	{class/null}
	{{\bf \htmlref{setisa}{vclass:setisa}}}
	{--}
	{Set class for instance}
\hline
\optableent
	{class}
	{{\bf \htmlref{kind}{vclass:kind}}}
	{boolean}
	{Is class in instance's inheritance hierarchy?}
\end{longtable}

\begin{description}
\label{vclass:classname}
\index{classname@\onyxop{}{classname}{}}
\item[{\onyxop{--}{classname}{name/null}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[name/null: ]
			A name or null object.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the \htmlref{\onyxop{}{classname}{}}{systemdict:classname}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> vclass:classname 1 sprint
$vclass
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:data}
\index{data@\onyxop{}{data}{}}
\item[{\onyxop{--}{data}{dict/null}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[dict/null: ]
			A dict or null object.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class/instance-context method.

		Call the \htmlref{\onyxop{}{data}{}}{systemdict:data} operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> vclass:data 1 sprint
<>
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:def}
\index{def@\onyxop{}{def}{}}
\item[{\onyxop{key val}{def}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[key: ]
			An object.
		\item[val: ]
			An object.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\end{description}
	\item[Description: ]
		Class/instance-context method.

		Define \oparg{key} as \oparg{val} in the data dictionary of the
		current class or instance.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass vclass <><$foo_get {,foo}> cdef
onyx:0> $foo `foo' fooclass:def
onyx:0> fooclass:foo_get
onyx:1> 1 sprint
`foo'
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:implementor}
\index{implementor@\onyxop{}{implementor}{}}
\item[{\onyxop{name}{implementor}{class/null}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[name: ]
			An object of any type, usually a name object.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[class/null: ]
			A class or null object.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the
		\htmlref{\onyxop{}{implementor}{}}{systemdict:implementor}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> class dup vclass setsuper
onyx:1> $new exch :implementor:classname 1 sprint
$vclass
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:implements}
\index{implements@\onyxop{}{implements}{}}
\item[{\onyxop{name}{implements}{boolean}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[name: ]
			An object of any type, usually a name object.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[boolean: ]
			True if \oparg{name} is implemented by \oparg{class},
			false otherwise.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the
		\htmlref{\onyxop{}{implements}{}}{systemdict:implements}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $new vclass:implements 1 sprint
true
onyx:0> $foo vclass:implements 1 sprint
false
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:isa}
\index{isa@\onyxop{}{isa}{}}
\item[{\onyxop{--}{isa}{class}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[class/null: ]
			A class or null object.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Instance-context method.

		Call the \htmlref{\onyxop{}{isa}{}}{systemdict:isa} operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> instance isa 1 sprint
null
onyx:0> vclass:new:isa:classname 1 sprint
$vclass
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:kind}
\index{kind@\onyxop{}{kind}{}}
\item[{\onyxop{class}{kind}{boolean}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[class: ]
			A class object.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[boolean: ]
			True if \oparg{class} is in \oparg{instance}'s
			inheritance hierarchy, false otherwise.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Instance-context method.

		Call the \htmlref{\onyxop{}{kind}{}}{systemdict:kind} operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass class dup vclass setsuper def
onyx:1> fooclass over:kind 1 sprint
true
onyx:1> vclass exch:kind 1 sprint
true
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:method}
\index{method@\onyxop{}{method}{}}
\item[{\onyxop{name}{method}{method}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[name: ]
			An object of any type, usually a name object.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[method: ]
			The bottommost method associated with \oparg{name} in
			\oparg{class}'s inheritance hierarchy.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\item[\htmlref{undefined}{undefined}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the \htmlref{\onyxop{}{method}{}}{systemdict:method}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass class dup vclass setsuper def
onyx:0> $new fooclass:method 1 sprint
{--instance-- --dup-- --dn-- --setisa-- --dup-- --dict-- --setdata--}
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:methods}
\index{methods@\onyxop{}{methods}{}}
\item[{\onyxop{--}{methods}{dict/null}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[dict/null: ]
			A dict or null object.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the \htmlref{\onyxop{}{methods}{}}{systemdict:methods}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> vclass:methods 0 sprint
-dict-
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:new}
\index{new@\onyxop{}{new}{}}
\item[{\onyxop{--}{new}{instance}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[instance: ]
			An instance of \oparg{class}.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Constructor.
	\item[Example(s): ]\begin{verbatim}

onyx:0> vclass:new 1 sprint
-instance-
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:rnew}
\index{rnew@\onyxop{}{rnew}{}}
\item[{\onyxop{--}{rnew}{instance}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[instance: ]
			An instance of \oparg{class} for which the superclass's
			constructor has been called.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Recursively call superclass's constructor (\onyxop{}{new}{}).
		This method is typically only used internally by constructors.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass vclass <><$new {:rnew}> cdef
onyx:0> fooclass:new:isa:classname 1 sprint
$fooclass
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:setclassname}
\index{setclassname@\onyxop{}{setclassname}{}}
\item[{\onyxop{name/null}{setclassname}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[name/null: ]
			A name or null object.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the
		\htmlref{\onyxop{}{setclassname}{}}{systemdict:setclassname}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass class dup vclass setsuper def
onyx:0> $fooclass fooclass:setclassname
onyx:0> fooclass:classname 1 sprint
$fooclass
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:setdata}
\index{setdata@\onyxop{}{setdata}{}}
\item[{\onyxop{dict/null}{setdata}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[dict/null: ]
			A dict or null object.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class/instance-context method.

		Call the \htmlref{\onyxop{}{setdata}{}}{systemdict:setdata}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass class dup vclass setsuper def
onyx:0> <$foo `foo'> fooclass:setdata
onyx:0> fooclass:data 1 sprint
<$foo `foo'>
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:setisa}
\index{setisa@\onyxop{}{setisa}{}}
\item[{\onyxop{class/null}{setisa}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[class/null: ]
			A class or null object.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Instance-context method.

		Call the \htmlref{\onyxop{}{setisa}{}}{systemdict:setisa}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass class dup vclass setsuper def
onyx:0> fooclass:new
onyx:1> vclass over:setisa
onyx:1> :isa:classname 1 sprint
$vclass
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:setmethods}
\index{setmethods@\onyxop{}{setmethods}{}}
\item[{\onyxop{dict/null}{setmethods}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[dict/null: ]
			A dict or null object.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the
		\htmlref{\onyxop{}{setmethods}{}}{systemdict:setmethods}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass class dup vclass setsuper def
onyx:0> <$foo `foo'> fooclass:setmethods
onyx:0> fooclass:methods 1 sprint
<$foo `foo'>
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:setsuper}
\index{setsuper@\onyxop{}{setsuper}{}}
\item[{\onyxop{super/null}{setsuper}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[super/null: ]
			A class or null object.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the \htmlref{\onyxop{}{setsuper}{}}{systemdict:setsuper}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass class dup vclass setsuper def
onyx:0> fooclass:super:classname 1 sprint
$vclass
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:super}
\index{super@\onyxop{}{super}{}}
\item[{\onyxop{--}{super}{super/null}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[super/null: ]
			A class or null object.
		\end{description}
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Class-context method.

		Call the \htmlref{\onyxop{}{super}{}}{systemdict:super}
		operator.
	\item[Example(s): ]\begin{verbatim}

onyx:0> vclass:super 1 sprint
null
onyx:0> $fooclass class dup vclass setsuper def
onyx:0> fooclass:super:classname 1 sprint
$vclass
onyx:0>
		\end{verbatim}
	\end{description}
\label{vclass:undef}
\index{undef@\onyxop{}{undef}{}}
\item[{\onyxop{key}{undef}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[key: ]
			An object.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\end{description}
	\item[Description: ]
		Class/instance-context method.

		Undefine \oparg{key} in the data dictionary of the current class
		or instance.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $fooclass vclass <><$foo_get {,foo}> cdef
onyx:0> $foo `foo' fooclass:def
onyx:0> fooclass:foo_get
onyx:1> 1 sprint
`foo'
onyx:0> $foo fooclass:undef
onyx:0> fooclass:foo_get
Error $undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
cstack: (-class-)
estack/istack trace (0..3):
0:      ,foo
1:      :foo_get
2:      -file-
3:      --start--
onyx:1>
		\end{verbatim}
	\end{description}
\end{description}
