%-*-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
%
% mclass reference portion of Onyx Manual.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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

The \classname{mclass} class uses the singleton pattern to provide an
application-wide interface for loading modules.  Additionally, the
\htmlref{\method{mclass:modules}}{mclass:modules} method makes it possible to
find out what modules are currently loaded.

\begin{longtable}{\optableformat{4.10}}
\caption{mclass 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}{mclass:new}}}
	{instance}
	{Constructor.}
\hline
\optableent
	{--}
	{{\bf \htmlref{singleton}{mclass:singleton}}}
	{instance}
	{Get an mclass singleton instance.}
\hline \hline
\multicolumn{2}{|l|}{Instance-context methods} \\
\hline \hline
\optableent
	{modname}
	{{\bf \htmlref{load}{mclass:load}}}
	{--}
	{Load a module.}
\hline
\optableent
	{modname}
	{{\bf \htmlref{unload\_notify}{mclass:unload_notify}}}
	{--}
	{Notify the mclass singleton of a module unload.}
\hline
\optableent
	{--}
	{{\bf \htmlref{modules}{mclass:modules}}}
	{modules}
	{Get loaded modules.}
\end{longtable}

\begin{description}
\label{mclass:load}
\index{load@\onyxop{}{load}{}}
\item[{\onyxop{modname}{load}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[modname: ]
			The name of a module.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{invalidfileaccess}{invalidfileaccess}.]
		\item[\htmlref{ioerror}{ioerror}.]
		\item[\htmlref{limitcheck}{limitcheck}.]
		\item[\htmlref{rangecheck}{rangecheck}.]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\item[\htmlref{undefinedfilename}{undefinedfilename}.]
		\end{description}
	\item[Description: ]
		Load the module named \oparg{modname}, and define the module
		name as the module in currentdict.
	\item[Example(s): ]\begin{verbatim}

onyx:0> $modclopt mclass:singleton:load
onyx:0> 
		\end{verbatim}
	\end{description}
\label{mclass:modules}
\index{modules@\onyxop{}{modules}{}}
o\item[{\onyxop{--}{modules}{modules}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[modules: ]
			A dictionary of module names associated with
			\htmlref{\classname{module}}{sec:module} instances.
		\end{description}
	\item[Error(s): ] None.
	\item[Description: ]
		Get a dictionary of loaded modules.
	\item[Example(s): ]\begin{verbatim}

onyx:0> mclass:singleton:modules 1 sprint
<$modprompt -instance=$module- $modclopt -instance=$module->
onyx:0> 
		\end{verbatim}
	\end{description}
\label{mclass: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: ]
		Constructor.
	\item[Example(s): ]\begin{verbatim}

onyx:0> mclass:new 1 sprint
-instance-
onyx:0>
		\end{verbatim}
	\end{description}
\label{mclass:singleton}
\index{singleton@\onyxop{}{singleton}{}}
\item[{\onyxop{--}{singleton}{instance}}: ]
	\begin{description}\item[]
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[instance: ]
			An \classname{mclass} singleton instance.
		\end{description}
	\item[Error(s): ] None.
	\item[Description: ]
		Get an \classname{mclass} singleton instance.
	\item[Example(s): ]\begin{verbatim}

onyx:0> mclass:singleton 1 sprint
-instance=$mclass-
onyx:0> 
		\end{verbatim}
	\end{description}
\label{mclass:unload_notify}
\index{unload_notify@\onyxop{}{unload\_notify}{}}
\item[{\onyxop{modname}{unload\_notify}{--}}: ]
	\begin{description}\item[]
	\item[Input(s): ]
		\begin{description}\item[]
		\item[modname: ]
			The name of a module.
		\end{description}
	\item[Output(s): ] None.
	\item[Error(s): ]
		\begin{description}\item[]
		\item[\htmlref{stackunderflow}{stackunderflow}.]
		\item[\htmlref{typecheck}{typecheck}.]
		\end{description}
	\item[Description: ]
		Notify the mclass singleton of a module unload.  This method is
		called by the \htmlref{\method{module:unload}}{module:unload}
		method, and isn't normally called directly by application code.
	\item[Example(s): ] Following is the implementation of
		\htmlref{\method{module:unload}}{module:unload}:
		\begin{verbatim}
# Unload the module.
#
#instance#
#- unload -
$unload {
    # Evaluate the pre-unload hook.
    ,pre_unload_hook eval

    # Iteratively undefine the module definitions, as recorded in the mdefs
    # dict.
    ,mdefs {
        exch 0 get
        #defdict #defname
        undef
    } foreach

    # Evaluate the post-unload hook.
    ,post_unload_hook eval

    # Notify mclass_singleton of the unload.
    ,name ,mclass_singleton:unload_notify
} bind
    		\end{verbatim}
	\end{description}
\end{description}
