%\iffalse
%
% File overword.dtx
% Copyright (C) 1996, 1997 by Frank Bennett.  All rights reserved.
%
% IMPORTANT NOTICE:
% 
% You are not allowed to change this file.  You may however copy
% this file to a file with a different name and then change the
% copy if (a) you do not charge for the modified code, (b) you
% acknowledge the author(s) in the new file, if it
% is distributed to others, and (c) you attach these same
% conditions to the new file.
% 
% You are not allowed to distribute this file alone.  You are not
% allowed to take money for the distribution or use of this file
% (or a changed version) except for a nominal charge for copying
% etc.
% 
% You are allowed to distribute this file under the condition that
% it is distributed with all of its contents, intact.
% 
% For error reports, or offers to help make this a more powerful,
% friendlier, and altogether more thrilling package, please contact me on
% fb@soas.ac.uk
% 
%<style>\NeedsTeXFormat{LaTeX2e}[1995/06/01]
%<style>\ProvidesPackage{overword}
%<style>          [1998/01/17 18:15:15 3.1.1.1 Overword parsing support (Frank Bennett)]
% \fi
%
% \def\fileversion{3.1.1.1}
% \def\filedate{1998/01/17 18:15:15}
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
%\CodelineIndex
%\EnableCrossrefs
\begin{document}
\OnlyDescription    % Comment out for implementation details
\DocInput{overword.dtx}
\end{document}
%</driver>
% \fi
%
% \changes{v1.0}{1996/11/10}{Initial version separated from calendar.dtx}
% \changes{v1.1}{1996/11/10}{Fixed error in the installation file.}
% \changes{v1.2}{1997/01/09}{Added @preoverwordspace, for use with Camel 1.0s.}
% \changes{v1.3}{1997/03/01}{Trivial change to documentation.}
% \changes{v1.4}{1997/03/04}{Put \texttt{iffalse} around installation
%  file section of \texttt{dtx} file.}
% \changes{v1.5}{1997/10/05}{Changed local use of \cs{let} re \cs{@overword}
%  tp global, to avoid cross-nested local and global assignments.}
% \changes{v1.6}{1997/10/18}{New public release of all styles
%  and modules incorporating global bug-fixes.}
%
%\iffalse
% Source tree moved under RCS
% ---------------------------
% overword.dtx,v
% Revision 3.1.1.1  1998/01/17 18:15:15  root
% Release code, checksum verified
%
% Revision 3.1  1998/01/17 17:14:24  root
% Release code
%
% Revision 2.3  1998/01/16 11:59:18  root
% *** empty log message ***
%
% Revision 2.2  1997/11/07 10:44:05  root
% Release code.
%
% Revision 2.1.1.1  1997/11/04 05:06:07  root
% Development branch
%
% Revision 2.1  1997/11/01 14:55:51  bennett
% Release code.
%
% Revision 1.5  1997/10/30 20:27:21  root
% Trivial changes to the demo file.
%
% Revision 1.4  1997/10/30 08:15:14  root
% Added a note in the documentation describing the \@ifnextnparchar
% macro.
%
% Revision 1.3  1997/10/29 21:20:29  root
% Eliminated what looked like a needless gdef of preoverwordspace
% in @ifoverword.
%
% Revision 1.2  1997/10/29 20:10:35  bennett
% *** empty log message ***
%
% Revision 1.1  1997/10/29 08:17:52  root
% Initial revision
%
%\fi
%
% \title{User's Guide to the Overword package\thanks{This file is version number
%    \fileversion{}.  It was last revised on
%    \filedate.}}
%
% \author{Frank G. Bennett, Jr.}
%
%  \maketitle
%
% \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
% \DoNotIndex{\@flushglue,\@gobble,\@input}
% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
% \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
% \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
% \DoNotIndex{\cal,\csname,\def,\documentstyle,\dospecials,\edef}
% \DoNotIndex{\egroup}
% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
% \DoNotIndex{\ifcase}
% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
% \DoNotIndex{\strutbox}
% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
% \DoNotIndex{\catcode,\end,\escapechar,\frenchspacing,\glossary}
% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
% \DoNotIndex{\nopagebreak}
% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
% \DoNotIndex{\[,\{,\},\]}
% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
% \DoNotIndex{\baselineskip,\begin,\tw@}
% \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
% \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
% \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
% \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
% \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
% \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
% \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
% \DoNotIndex{\bfdefault}
% \setcounter{StandardModuleDepth}{1}
% \DeleteShortVerb{\|}
% \MakeShortVerb{\"}
%
% \begin{abstract}
% \noindent This package provides two low-level macros for the parsing of text
%  using \LaTeXe{}.
% \end{abstract}
%
%
% \CheckSum{143}
%
% \section{Using the macros}
%
% This package provides two macros which can be used as
% building blocks for the parsing of text.  It forms
% part of the Calendar package, but is written as
% a discrete module that may be used in other packages
% as well.
%
% The "\@ifoverword" macro takes four arguments.  These
% are, in order: a token to match; a text to expand when
% a match is found; a text to expand if the match is
% not found; and a text to expand if the macro encounters
% "\end".  This last is required to allow macros to be
% built which will react gracefully when the end of an
% environment or a document is encountered.
%
% This macro hops over word units (delimited by a space or spaces,
% any number of return characters being treated as a space),
% and expands text according to what it finds on the other side.
% Within the text arguments, "\@overword" can be used to
% insert the word that has been gobbled.  The expanded
% text can contain the name of the macro that invokes
% "\@ifoverword".
% Note that "\@overword" is relaxed at each invocation of
% the macro.  This can be used to detect whether the macro
% has encountered an "\end" immediately after itself or
% beyond a word, and thereby exit cleanly in either case.
%
% The file "demo.tex" contains a sample of the use of this macro.
% This can be used as a model for building text-parsing loops.
%
% The \cs{@ifnextnparchar} macro serves the same purpose as
% \cs{@ifnextchar} except that, like \cs{@ifoverword}, it is
% indifferent to \cs{par} (if it encounters one, it will
% gobble it and look at the next token following it).
% And like \cs{@ifoverword}, it
% takes a text to expand when the next token is \cs{end}
% as its fourth argument, to help 
% protect against accidental attempts to read past the end
% of the file.
%
%\StopEventually{\PrintIndex}
%
% \begin{macro}{\@ifoverword}
%    \begin{macrocode}
%<*style>
\long\def\@ifoverword#1#2#3#4{%
  \let\reserved@a=#1%
  \def\reserved@d{#4}\def\reserved@b{#2}\def\reserved@c{#3}%
  \global\let\@overword\relax%
  \futurelet\@let@token\@ifowd}
\long\def\@ifowd{%
  \ifx\@let@token\@sptoken%
    \gdef\@preoverwordspace{ }%
    \let\reserved@e\@xifowd%
  \else%
    \ifx\@let@token\end%
      \let\reserved@e\reserved@d%
    \else%
      \ifx\@let@token\par%
        \let\reserved@e\@xifpargobble%
      \else%
        \long\def\reserved@e##1 {\long\gdef\@overword{##1}\@@ifowd}%
      \fi%
    \fi%
  \fi%
  \reserved@e}
\long\def\@xifpargobble#1{\futurelet\@let@token\@ifowd}
\def\:{\@xifowd} \expandafter\def\: {\futurelet\@let@token\@ifowd}
\def\@@ifowd{\futurelet\@let@token\@ifnparnch}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@ifnextnparchar}
%    \begin{macrocode}
\long\def\@ifnextnparchar#1#2#3#4{%
  \let\reserved@a=#1%
  \def\reserved@b{#2}\def\reserved@c{#3}\def\reserved@d{#4}%
  \futurelet\@let@token\@ifnparnch}
\long\def\@ifnparnch{%
  \ifx\@let@token\@sptoken%
    \let\reserved@e\@xifnparnch%
  \else%
    \ifx\@let@token\end%
      \let\reserved@e\reserved@d%
    \else%
      \ifx\@let@token\par%
        \let\reserved@e\@xifpargobblench%
      \else%
        \ifx\@let@token\reserved@a%
          \let\reserved@e\reserved@b%
        \else%
          \let\reserved@e\reserved@c%
        \fi%
      \fi%
    \fi%
  \fi%
  \reserved@e}
\long\def\@xifpargobblench#1{\futurelet\@let@token\@ifnparnch}
\def\:{\@xifnparnch}
\expandafter\def\: {\futurelet\@let@token\@ifnparnch}
%</style>
%    \end{macrocode}
% \end{macro}
%\iffalse
% \section{Demo file}
%
%    \begin{macrocode}
%<*demo>
\documentclass{minimal}
\usepackage{overword}

\begin{document}

\makeatletter

\newtoks\registerone
\newtoks\registertwo
\def\list{}

\def\stashonright{%
  \registerone=\expandafter{\@overword}
  \registertwo=\expandafter{\list}
  \edef\list{%
    \noexpand\\{\the\registerone}\the\registertwo}}

\def\showlist{%
  \def\\##1{\message{##1}}
  \message{\space\space -> }
  \list
  \message{^^J}}

\def\readlistagain{%
  \def\\##1{ ##1 }
  \edef\listtext{\list}
\message{\listtext}
  \expandafter\store\listtext\enditall}

\def\storeandshow{%
  \@ifoverword\enditall
   {\message{Ran into \string\enditall!^^J}
    \stashonright
    \expandafter\showlist\@gobble}
   {\stashonright
    \storeandshow}
   {\message{Ran into \string\end!^^J}
    \stashonright
    \showlist}}

\message{^^J----------------------------------------------------------------------}
\message{This file demonstrates the operation of the Overword package for LaTeX}
\message{Ordinarily, TeX reads and inteprets printable characters one by one.}
\message{With this package, it is possible to read input word by word.  This}
\message{capability makes it possible to design user interfaces which are more}
\message{intuitive to users.  The Calendar bundle is one example of such an}
\message{interface.  Below, a phrase is printed to the terminal twice, once in}
\message{reverse word order, and once in re-reversed (normal) word order.  Each}
\message{message is triggered by a control sequence found just beyond the last}
\message{word read --- \string\enditall in the first instance, \string\end\space in the second.}
\message{This file produces no printed output.}
\message{^^J----------------------------------------------------------------------}

\storeandshow This is a demonstration of the overword package \enditall

\let\listclone\list
\def\list{}
\def\\#1{ #1 }
\edef\listtext{\listclone}
\expandafter\storeandshow\listtext

\end{document}
%</demo>
%    \end{macrocode}
%\fi
% \Finale \PrintChanges