\documentclass[11pt,a4paper]{article}
% save as utf-8-emacs-unix

% 2006-07-07 EW Adventures-1.tex
% 2006-07-22 EW Adventures-2.tex
% 2006-08-14 EW Adventures-2a.tex
% 2007-01-10 EW Adventures-3.tex
% 2007-01-13 EW Adventures-4.tex
% 2008-11-14 EW Adventures-5.tex
% 2011-01-07 EW Adventures-6.tex: rs485+mpc
% 2011-02-14 EW Adventures-7.tex: list
% 2011-04-30 EW Adventures-8.tex: vocabulary
%
%
% language support
\usepackage[german]{babel}
%\usepackage{german}
\usepackage[utf8]{inputenc} % can use Umlauts now ü instead of "u
%\usepackage{lmodern} % better fonts
%\usepackage{pslatex} % use native PostScript fonts
%\usepackage{cm-super}

\usepackage{url} % \url{} \path{} with correct "hyphenation"
%\usepackage{fancyvrb} % for code examples

% \voffset-10mm
% \pagestyle{empty}
% \pagestyle{plain}
% \pagestyle{headings}
% \renewcommand{\baselinestretch}{1.08}
%\usepackage{xspace}
\parindent=0pt
\newcommand{\amforth}{\texttt{amforth}}
%\newcommand{\zB}{z.\,B.\ }
\begin{document}

\title{Adventures in amforth: Wortliste schließen}
\shorttitle{Adventures 8: Wortliste schließen}

\author{Erich Wälde}

\maketitle

%\begin{multicols}{2}

% --------------------------------------------------------------------
%\section{Intro}
%\label{sec:intro}

\begin{abstract}\itshape
  Beim Lesen in den bekannten Forth-Büchern ([\ref{brodie1}],
  [\ref{rather}], [\ref{vack}]) bekommt man vorgeführt, dass getrennte
  Wortlisten vom Programmierer eingesetzt werden können. Normalerweise ist
  nur eine Wortliste mit dem Namen \texttt{FORTH} vorhanden und aktiv.
  \amforth{} kann gemäß dem ANS94 Standard gleichzeitig acht aktive
  Wortlisten benutzen (seit Version 3.3).

  Der Programmierer kann eine spezielle Wortliste erstellen und diese
  \emph{schließen}. Der Anwender kann danach nur noch die Worte in dieser
  Liste benutzen, das Forthsystem ist für ihn nicht mehr benutzbar. Der
  gezeigte Quelltext wurde auf \amforth{} $4.2$ getestet.
\end{abstract}

\begin{multicols}{2}

% --------------------------------------------------------------------
\section{Vorarbeiten}
\label{sec:intro}

Ohne Änderung des \amforth-systems sind die Worte \texttt{get-current},
\texttt{get-order} und \texttt{order} verfügbar. Sie werden von \amforth{}
intern benutzt. Allerdings ist die Bedeutung der beispielsweise von
\texttt{get-order} auf den Stapel gelegten Zahlen nicht jedem sofort
ersichtlich.


Um mit Wortlisten sinnvoll arbeiten zu können, fügt man in der Datei
\path{dict_appl.inc} folgende Zeile hinzu:

{\small
\begin{verbatim}
.include "dict_wl.inc"
\end{verbatim}
}

Dadurch werden die Worte \texttt{set-current}, \texttt{set-order},
\texttt{only}, \texttt{forth-wordlist}, \texttt{also}, \texttt{previous},
\texttt{definitions}, \texttt{forth} und \texttt{wordlist} verfügbar.

Wortlisten werden durch eine Zahl, die \texttt{wid}, gekennzeichnet. Die
genannten Befehle verwenden diese Zahl und nicht den Namen der Wortliste.
Die \texttt{wid}s der aktiven Wortlisten werden in der Suchliste gespeichert. Die
Suchliste liegt bei \amforth{} im EEPROM und übersteht das Ausschalten des
Mikrokontrollers unbeschadet.


\begin{itemize}
% word list commands
  \item \texttt{forth-wordlist} ist eine Konstante (value), die die
    \texttt{wid} der Wortliste \texttt{FORTH} auf den Stapel legt.
  \item \texttt{wordlist ( -{}- wid)} erzeugt eine leere Wortliste und legt
    die neue \texttt{wid} auf den Stapel.
  \item \texttt{get-current ( -{}- wid )} legt die \texttt{wid} der Wortliste,
    in die derzeit neue Definitionen eingefügt werden, auf den Stapel.
  \item \texttt{set-current ( wid -{}- )} veranlasst, dass die nachfolgenden
    Definitionen in die Wortliste mit der angegebenen \texttt{wid} eingetragen werden.
  \item \texttt{definitions ( -{}- )} holt die oberste \texttt{wid} aus der
    Suchliste und ruft damit \texttt{set-current} auf. Nachfolgende
    Definitionen werden in diese oberste Wortliste eingetragen.
  \item \texttt{get-order ( -{}- wid0 .. widN n )} produziert die \texttt{wid}s aller
    aktiven Wortlisten und deren Anzahl.
  \item \texttt{set-order ( wid0 .. widN n -{}- )} speichert die angegebenen
    \texttt{wid}s in dieser Reihenfolge neu in der Suchliste.
  \item \texttt{order ( -{}- )} gibt die von \texttt{get-current} und
    \texttt{get-order} produzierten \texttt{wid}s aus.
% search list commands
  \item \texttt{also ( -{}- )} dupliziert den obersten Eintrag in der
    Suchliste und verschiebt die weiteren Einträge um einen Platz nach
    unten (wie dup).
  \item \texttt{previous ( -{}- )} löscht den obersten Eintrag in der
    Suchliste und verschiebt die weiteren Einträge um einen Platz noch oben
    (wie drop).
  \item \texttt{only ( -{}- )} ersetzt die Suchliste durch eine neue, in der
    lediglich die FORTH--Wortliste enthalten ist.
  \item \texttt{forth} ersetzt den obersten Eintrag der Suchliste durch die
    \texttt{wid} der Wortliste \texttt{FORTH}.
\end{itemize}


\section{Neue Wortliste anlegen}
\label{sec:wl.new}

Mit diesen Worten lässt sich das Wort \texttt{vocabulary} schreiben (siehe
\path{lib/vocabulary.frt}):

\listinginput[1]{1}{2011-02/vocabulary.frt}

\texttt{vocabulary} erzeugt eine Konstante, welche die \texttt{wid} einer
neu erzeugten, leeren Wortliste enthält. Ruft man das Wort auf, dann wird
der oberste Eintrag der Suchliste mit der genannten \texttt{wid}
überschrieben. Um eine neue Wortliste \texttt{<application>} mit neuen Worten zu
füllen, schreibt man also

{\small
\begin{verbatim}
vocabulary <application>
also <application> definitions
: neuesWort  ." Hallo aus Wortliste <application>" cr ;
...
\end{verbatim}
}

der Erfolg lässt sich mit \texttt{order} und \texttt{words} überprüfen

{\small
\begin{verbatim}
> order
40
2 40  14   ok
> words
neuesWort <application> vocabulary ...
\end{verbatim}
}

Die Liste \verb|<application>| lässt sich mit \texttt{previous} wieder aus
der Suchliste verbannen:

{\small
\begin{verbatim}
> previous
 ok
> order
40
1 14   ok
> words
<application> vocabulary ...
\end{verbatim}
}

Die Wortliste \verb|<application>| wird bei der Suche nicht mehr
berücksichtigt. Neue Worte werden allerdings immer noch in diese Liste
eingetragen. Erst ein Aufruf von \texttt{definitions} regelt das:

{\small
\begin{verbatim}
> definitions
 ok
> order
14
1 14   ok
>
\end{verbatim}
}



\section {Wortliste schließen}
\label {sec:wl.seal}

Um eine Wortliste zu schließen, muss man die Suchliste komplett
überschreiben. \texttt{sealed} lässt sich zunächst die Suchliste ausgeben,
sichert n und den obersten Eintrag, und ersetzt dann alle Einträge mit dem
Wert \texttt{-1}. Der oberste Wert wird dann wieder korrekt eingesetzt und
die Suchliste gespeichert.

{\small
\begin{verbatim}
: sealed ( -- )
  get-order               \ wl.0 .. wl.top  n
  over over swap >r >r    \ store n and top wid
     0 ?do drop loop      \ clear order entries
  r@ 0 ?do -1   loop drop \ replace with -1
  r> r> swap              \ restore top wid and n
  set-order               \ write search list
;
\end{verbatim}
}

%\textit{??? Wahrscheinlich würde es reichen, "wid 1 set-order" {} aufzurufen.
%  Aber dann stehen die wids immer noch in der Suchliste.}

Um den Erfolg von \texttt{sealed} besser zu sehen, fügen wir die Worte
\texttt{order} und \texttt{words} zur Wortliste \verb|<application>| hinzu.
Und damit wir zum Spielen nicht in dieser kurzen Liste für alle Ewigkeit
--- naja, bis zum nächsten flashen des Mikrokontrollers --- stranden, fügen
wir außerdem einen Notausgang in die Liste:

{\small
\begin{verbatim}
also <application> definitions
: order  order ;
: words  words ;
: escape only definitions ;
\end{verbatim}
}


{\small
\begin{verbatim}
also <application> sealed
 ok
> order
40 
1 40   ok
> words
escape words order neuesWort  ok
> neuesWort
Hallo aus der Wortliste <application>
 ok
> .s
 ?? -13 3 
> only
 ?? -13 5 
> 14 24 e!
 ?? -13 9 
> escape
 ok
> words
sealed <application> vocabulary ...
\end{verbatim}
}

\section {Überraschung}

Beim Testen stellte sich dann heraus, dass man das Wort \texttt{sealed} gar
nicht braucht. Steht in der aktuellen Suchliste nur ein Eintrag, dann
überschreibt \verb|<application>| diesen Eintrag, und man hat sich flugs
ausgesperrt. \amforth{} hat eben keine Sicherheitsnetze:

\textbf{Benutzung auf eigene Gefahr!}


% --------------------------------------------------------------------
\section{Referenzen}

\begin{enumerate}
%\item \label{Adv1} E. Wälde, Adventures in Forth,   Die 4. Dimension 3/2006, Jahrgang 22
%      gforth-ec r8c, i2c von Hand, Thermometer
%\item \label{Adv2} E. Wälde, Adventures in Forth 2, Die 4. Dimension 4/2006, Jahrgang 22
%      timeup Uhr und Kalender, twotask
%\item \label{Adv3} E. Wälde, Adventures in Forth 3, Die 4. Dimension 1/2007, Jahrgang 23
%      usart0, redirection
%\item \label{Adv4} E. Wälde, Adventures in Forth 4, Die 4. Dimension 1/2007, Jahrgang 23
%      dcf-77 Uhr
%\item \label{Adv5} E. Wälde, Adventures in Forth 5, Die 4. Dimension 4/2008, Jahrgang 24
%      Umstieg auf amforth, bit flags, sensor:, filter_mean:
%\item \label{Adv5} E. Wälde, Adventures in Forth 6, Die 4. Dimension 1/2011, Jahrgang 27
%      rs485, -emit, mpc

%\item \label{r8c-ds} Renesas R8C/13 datasheet auf \url{www.renesas.com}
%\item \label{Koenig} A.\ König und M.\ König, Das PICmicro Profi Buch, Franzis
%  Verlag 1999, ISBN 3-7723-4284-1
%\item \label{SPelc} Stephen Pelc, Programming Forth, \\ \url{http://www.mpeforth.com/arena/ProgramForth.pdf}
%\item \label{Deliano} \url{http://www.embeddedforth.de/emb3.pdf} S.\ 9
%\item \label{dcf} \url{http://de.wikipedia.org/wiki/DCF77} und Verweise darin
%\item \label{willem} ByteForth von Willem Ouwerkerk,\\  \url{http://www.forth.hccnet.nl/byteforth.htm}
\item \label{amforth} \url{http://amforth.sourceforge.net/}
%\item \label{ron} Ron Minke, Forth von der Pike auf  Die 4. Dimension 3+4/2005 \ldots 4/2006, sowie Sonderheft AVR und  3+4/2007
%\item \label{namedbits} M. Kalus, M. Trute, Named Bits, Die 4. Dimension 2/2007, Jahrgang 23
%\item \label{lubos} Lubo\v{s} P\v{e}kn\'{y}s Seite: \url{http://www.forth.cz}
%\item \label{RS485} Wikipedia (RS485) \url{de.wikipedia.org/wiki/RS485}
%\item \label{RS485a} \url{www.mikrocontroller.net/articles/RS-485}
%\item \label{g4.fs} Michael Kalus: g4.fs \url{www.forth-ev.de/repos/g4/g4.fs}
%\item \label{atmega32} atmega32 Datenblatt (doc2503.pdf) \url{www.atmel.com}
%
\item \label{brodie1} Leo Brodie --- Starting Forth,
  1987, Prentice Hall, S.\,219ff
%
\item \label{rather} Elizabeth D.\ Rather --- Forth Application Techniques,
  2006, Forth Inc., S.\,107ff
%
\item \label{vack} Gert--Ulrich Vack --- Programmieren mit FORTH, 1990,
  Verlag Technik Berlin, S.\,189ff
\end{enumerate}
\end{multicols}

\vfill
\begin{figure}
  \centering
  \includegraphics[width=\textwidth]{2011-03/amforthcluster}
  \caption{Verteilung des amforth auf der Welt}
\end{figure}
%\newpage
% --------------------------------------------------------------------
%%\section{Listings}
%%
%%
%%
%%\begin{quote}
%%\begin{small}
%%\begin{multicols}{2}
%%\listinginput[1]{1}{2011-02/list.fs}
%%
%%\end{multicols}
%%\end{small}
%%\end{quote}


\end{document}
