%%% ====================================================================
%%% @LaTeX-style-file{
%%% filename = "grabhedr.dtx",
%%% version = "1.99a",
%%% date = "2013/01/24",
%%% author = "Michael Downes",
%%% copyright = "This file is part of the dialogl package, released
%%% under the LPPL; see dialogl.ins for details."
%%% keywords = "TeX, file header,
%%% supported = "no",
%%% abstract = "This file defines a macro \inputfwh
%%% to be used instead of \input, to allow TeX to grab
%%% information from standardized file headers in the form
%%% proposed by Nelson Beebe during his term as president of the
%%% TeX Users Group. Of which all this here is an example.",
%%% }
%%% ====================================================================
%
% \iffalse
%<*driver>
\input{dia-driv.tex}
%</driver>
% \fi
%
% \section{Introduction}
% This file defines a function \cw{inputfwh} to be used instead of
% \cw{input}, to allow \tex/ to grab information from standardized
% file headers in the form proposed by Nelson Beebe during his term
% as president of the \tex/ Users Group. Usage:
%\begin{usage}
%\inputfwh{file.nam}
%\end{usage}
% Functions \cw{localcatcodes} and \cw{restorecatcodes} for
% managing catcode changes are also defined herein, as well as a
% handful of utility functions, many of them borrowed from
% \fn{latex.tex}: \cw{@empty}, \cw{@gobble}, \cw{@gobbletwo},
% \cw{@car}, \cw{@@input}, \cw{toks@}, \cw{afterfi},
% \cw{fileversiondate}, \cw{trap.input}.
%
% The use of \cw{inputfwh}, \cw{fileversiondate}, and
% \cw{trap.input} as illustrated in \fn{dialog.sty} is cumbersome
% klugery that in fact would better be handled by appropriate
% functionality built into the format file. But none of the major
% formats have anything along these lines yet. (It would also help
% if \tex/ made the current input file name accessible, like
% \cw{inputlineno}.)
%
% \StopEventually{}
%
% \section{Implementation}
% Standard package identification:
% \begin{macrocode}
%<*2e>
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{grabhedr}[1994/11/08 v0.9j]
%</2e>
% \end{macrocode}
%
% By enclosing this entire file in a group, saving and restoring
% catcodes `by hand' is rendered unnecessary. This is perhaps the
% best way to locally change catcodes, better than the
% \cw{localcatcodes} function defined below. But it tends to be
% inconvenient for the \tex/ programmer: every time you add
% something you have to remember to make it global; if you're like
% me, you end up making every change twice, with an abortive test
% run of \tex/ in between, in which you discover that a certain
% control sequence is undefined because you didn't assign it
% globally. (Using \cw{globaldefs} = 1 is dangerous in my experience;
% you have to take care not to accidentally change any variables that
% you don't want to be changed globally.)
% \begin{macrocode}
\begingroup
% \end{macrocode}
% Inside this group, enforce normal catcodes. All definitions must
% be global in order to persist beyond the \cw{endgroup}.
% \begin{macrocode}
\catcode96 12 % left quote
\catcode`\= 12
\catcode`\{=1 \catcode`\}=2 \catcode`\#=6
\catcode`\$=3 \catcode`\~=13 \catcode`\^=7
\catcode`\_=8 \catcode`\^^M=5 \catcode`\"=12
% \end{macrocode}
% Make \qc{\@} a letter for use in `private' control sequences.
% \begin{macrocode}
\catcode`\@=11
% \end{macrocode}
%
% \section{Preliminaries}
% For \cw{@empty}, \cw{@gobble}, \ldots{} we use the \latex/ names so
% that if \fn{grabhedr.sty} is used with \latex/ we won't waste hash
% table and string pool space.
%
% \begin{macro}{\@empty}
% Empty macro, for \cw{ifx} tests or initialization of variables.
% \begin{macrocode}
\gdef\@empty{}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@gobble}
% \begin{macro}{\@gobbletwo}
% \begin{macro}{\@gobblethree}
% Functions for gobbling unwanted tokens.
% \begin{macrocode}
\long\gdef\@gobble#1{}
\long\gdef\@gobbletwo#1#2{}
\long\gdef\@gobblethree#1#2#3{}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@car}
% The function \cw{@car}, though not really needed by
% \fn{grabhedr.sty}, is needed by the principal customers of
% \fn{grabhedr.sty} (e.g., \fn{dialog.sty}).
% \begin{macrocode}
\long\gdef\@car#1#2\@nil{#1}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@input}
% To define \cw{@@input} as in \latex/ we want to let it equal to
% the primitive \cw{input}. But if a \latex/ format is being used
% we don't want to execute that assignment because by now
% \cw{input} has changed its meaning. And if some other format is
% being used it behooves us to check, before defining \cw{@@input},
% whether \cw{input} still has its primitive meaning. Otherwise
% there's a good chance \cw{inputfwh} will fail to work properly.
% \begin{macrocode}
\ifx\UndEFiNed\@@input % LaTeX not loaded.
% \end{macrocode}
% This code shows a fairly easy way to check whether the meaning of a
% primitive control sequence is still the original meaning.
% \begin{macrocode}
\edef\0{\meaning\input}\edef\1{\string\input}%
\ifx\0\1%
\global\let\@@input\input
\else
\errhelp{%
Grabhedr.sty needs to know the name of the
\input primitive in order to define \inputfwh
properly. Consult a TeXnician for help.}
\errmessage{%
Non-primitive \noexpand\input detected}%
\fi
\fi
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\toks@}
% Scratch token register.
% \begin{macrocode}
\global\toksdef\toks@=0
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\afterfi}
% Sonja Maus's function for throwing code over the \cw{fi} (``An
% Expansion Power Lemma'', \TUB{} vol 12 no 2 June 1991). (Except
% that she called this function \cw{beforefi}.)
%
% \begin{macrocode}
\long\gdef\afterfi#1\fi{\fi#1}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\nx@}
% We will be using \cw{noexpand} a lot; this abbreviation improves
% the readability of the code.
% \begin{macrocode}
\global\let\nx@\noexpand
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\xp@}
% Another convenient abbreviation.
% \begin{macrocode}
\global\let\xp@\expandafter
% \end{macrocode}
% \end{macro}
%
% \section{Reading standard file headers}
% The function \cw{inputfwh} (`input file with header') inputs
% the given file, checking first to see if it starts with a
% standardized file header; if so, the filename, version and date
% are scanned for and stored in a control sequence.
%
% For maximum robustness, we strive to rely on the fewest possible
% assumptions about what the file that is about to be input might
% contain.
%
% Assumption 1: Percent character \qc{\%} has category 14. I.e., if
% the first line of the file to be input starts with \qc{\%}, it is
% OK to throw away that line.
%
% \begin{macro}{\@percentchar}
% \begin{macrocode}
\begingroup \lccode`\.=`\%%
\lowercase{\gdef\@percentchar{.}}%
\endgroup
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\fileversiondate}
% The function \cw{fileversiondate} is not only a useful support
% function for \cw{inputfwh}, it can also be used by itself at the
% beginning of a file to set file name, version, and date correctly
% even if the file is input by some means other than
% \cw{inputfwh}\Dash assuming that the arguments of the
% \cw{fileversiondate} command are kept properly up to date.
% \begin{macrocode}
\gdef\fileversiondate#1#2#3{%
\xp@\xdef\csname#1\endcsname{#2 (#3)}%
\def\filename{#1}\def\fileversion{#2}%
\def\filedate{#3}%
\message{#1 \csname#1\endcsname}%
}
% \end{macrocode}
% And now apply \cw{fileversiondate} to this file.
% \begin{macrocode}
%<*209>
\fileversiondate{grabhedr.sty}{0.9j}{1994/11/08}
%</209>
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@filehdrstart}
% \fn{filehdr.el} by default adds a string of equal signs (with an
% initial comment prefix) at the very top of a file header. This
% string must be scanned away first before we can start looking for
% the real information of the file header.
% \begin{macrocode}
\xdef\@filehdrstart{%
\@percentchar\@percentchar\@percentchar\space
==================================%
==================================}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@scanfileheader}
% The purpose of this function is just to scan up to the opening
% brace that marks the beginning of the file header body.
% Everything before that is ignored, not needed for our present
% purposes.
% \begin{macrocode}
\gdef\@scanfileheader#1@#2#{\@xscanfileheader}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@xscanfileheader}
% Throw in some dummy values of version and date at the end so that
% all we require from a file header is that the filename field must
% be present.
% \begin{macrocode}
\long\gdef\@xscanfileheader#1{%
\@yscanfileheader#1{} version = "??",
date = "??",\@yscanfileheader}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@yscanfileheader}
% This function assumes that filename, version, and date of a file
% are listed in that order (but not necessarily adjacent). It's
% possible for the version and date to be missing, or out of order,
% but the corresponding \tex/ variables \cw{fileversion} and
% \cw{filedate} will not get set properly unless the order is:
% filename, [\ldots,] version, [\ldots,] date. Trying to handle
% different orderings would be desirable but I haven't yet been
% struck by a suitable flash of insight on how to do it without
% grubby, time-consuming picking apart of the entire file header.
% \begin{macrocode}
\long\gdef\@yscanfileheader
#1 filename = "#2",#3 version = "#4",%
#5 date = "#6",#7\@yscanfileheader{%
\endgroup
\csname fileversiondate\endcsname{#2}{#4}{#6}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@readfirstheaderline}
% This function has to look at the first line of the file to see if
% it has the expected form for the first line of a file header.
% \begin{macrocode}
\begingroup
\lccode`\$=`\^^M
\lowercase{\gdef\@readfirstheaderline#1$}{%
\toks@{#1}%
\edef\@tempa{\@percentchar\the\toks@}%
\ifx\@tempa\@filehdrstart
\endgroup \begingroup
\catcode`\%=9 \catcode`\^^M=5 \catcode`\@=11
% \end{macrocode}
% Double quote and equals sign need to be category 12 in order for
% the parameter matching of \cw{@xscanfileheader} to work, and
% space needs its normal catcode of 10.
% \begin{macrocode}
\catcode`\ =10 \catcode`\==12 \catcode`\"=12
\xp@\@scanfileheader
\else
\message{(* Missing file header? *)}%
\afterfi\endgroup
\fi}
\endgroup
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@xinputfwh}
% An auxiliary function.
% \begin{macrocode}
\gdef\@xinputfwh{%
\ifx\next\@readfirstheaderline
% \end{macrocode}
% Sanitize a few characters. Otherwise an unmatched brace or other
% special character might cause a problem in the process of reading
% the first line as a macro argument.
% \begin{macrocode}
\catcode`\%=12 \catcode`\{=12 \catcode`\}=12
\catcode`\\=12 \catcode`\^^L=12
\catcode`\^=12
% Unique terminator token for the first line.
\catcode`\^^M=3\relax
\else \endgroup\fi
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@inputfwh}
% Auxiliary function, carries out the necessary \cw{futurelet}.
% \begin{macrocode}
\gdef\@inputfwh{\futurelet\next\@xinputfwh}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\inputfwh}
% Strategy for (almost) bulletproof reading of the first line of
% the input file is like this: Give the percent sign a special
% catcode, then use \cw{futurelet} to freeze the catcode of the
% first token in the input file. If the first token is {\em not\/}
% a percent character, then fine, just close the group wherein the
% percent character had its special catcode, and proceed with
% normal input; the first token will have its proper catcode
% because we did not change anything except the percent character.
% Otherwise, we still proceed with `normal' input execution, but by
% making \qc{\%} active and defining it suitably, we can carry out
% further tests to see if the first file line has the expected form
% (three percent signs plus lots of equal signs).
% \begin{macrocode}
\gdef\inputfwh#1{%
\begingroup\catcode`\%=\active
\endlinechar`\^^M\relax
\lccode`\~=`\%\relax
\lowercase{\let~}\@readfirstheaderline
\xp@\@inputfwh\@@input #1\relax
}
% \end{macrocode}
% \end{macro}
%
% \section{Managing catcode changes}
%
% A survey of other methods for saving and restoring catcodes would
% be more work than I have time for at the moment. The method
% given here is the best one I know (other methods use up one extra
% control sequence name per file, or don't robustly
% handle multiple levels of file nesting).
%
% \begin{macro}{\localcatcodes}
% The \cw{localcatcodes} function changes catcodes according to the
% character/catcode pairs given in its argument, saving the
% previous catcode values of those characters on a stack so that
% they can be retrieved later with \cw{restorecatcodes}. Example:
%\begin{usage}
%\localcatcodes{\@{11}\"\active}
%\end{usage}
% to change the catcode of \cs{\@} to 11 (letter) and the catcode
% of \qc{\"} to 13 (active). In \plaintex/ you'd better be careful
% to use \qc{\+} instead of \cs{\+} in the argument of
% \cw{localcatcodes} because of the outerness of \cs{\+}.
%
% This function works by using token registers 0 and 4
% to accumulate catcode assignment statements: in \cw{toks0} we put
% the statements necessary to restore catcodes to their previous
% values, while in \cw{toks 4} we put the statements necessary to
% set catcodes to their new values.
% \begin{macrocode}
\gdef\localcatcodes#1{%
\ifx\@empty\@catcodestack
\gdef\@catcodestack{{}}%
\fi
\def\do##1##2{%
\ifnum##2>\z@
\catcode\number`##1 \space
\number\catcode`##1\relax
\expandafter\do\fi}%
\xdef\@catcodestack{{\do#1\relax\m@ne}%
\@catcodestack}%
\def\do##1##2{\catcode`##1 ##2\relax\do}%
\do#1\ {\catcode32\let\do}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@catcodestack}
% Init the stack with an empty element; otherwise popping the
% next-to-last element would wrongly remove braces from the last
% element. But as a matter of fact we could just as well initialize
% \cw{@catcodestack} to empty because \cw{localcatcodes} is careful
% to add an empty final element if necessary.
% \begin{macrocode}
\gdef\@catcodestack{{}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\restorecatcodes}
% The function \cw{restorecatcodes} has to pop the stack and
% execute the popped code.
% \begin{macrocode}
\gdef\restorecatcodes{%
\begingroup
\ifx\@empty\@catcodestack
\errmessage{Can't pop catcodes;
\nx@\@catcodestack = empty}%
\endgroup
\else
\def\do##1##2\do{%
\gdef\@catcodestack{##2}%
% \end{macrocode}
% Notice the placement of \arg{1} after the \cw{endgroup}, so that
% the catcode assignments are local assignments.
% \begin{macrocode}
\endgroup##1}%
\xp@\do\@catcodestack\do
\fi
}
% \end{macrocode}
% \end{macro}
%
% \section{Trapping redundant input statements}
% The utility \fn{listout.tex} calls \fn{menus.sty}, which calls
% \fn{dialog.sty}, and all three of these files start by loading
% \fn{grabhedr.sty} in order to take advantage of its functions
% \cw{fileversiondate}, \cw{localcatcodes}, and \cw{inputfwh}. But
% consequently, when \fn{listout.tex} is used there will be two
% redundant attempts to load \fn{grabhedr.sty}. The straightforward
% way to avoid the redundant input attempts would be to surround
% them with an \cw{ifx} test:
%
%^^V \ifx\undefined\fileversiondate
%^^V \input grabhedr.sty \relax
%^^V \fileversiondate{foo.bar}{0.9e}{10-Jun-1993}
%^^V \fi
%
% This method has a few drawbacks, however: (1)~the conditional
% remains open throughout the processing of everything in
% \fn{grabhedr.sty} and the \cw{fileversiondate} statement, which
% makes any \cw{else} or \cw{fi} mismatch problems harder to debug;
% (2)~if \cw{undefined} becomes accidentally defined the \cw{ifx}
% test will fail; (3)~choosing the right control sequence to test
% against \cw{undefined} requires a little care.
%
% In a situation where we know that the file to be input has had
% \cw{fileversiondate} applied to it, if it was already input, then
% we have a failsafe control sequence that we can test to find out
% whether the file has already been input\Dash the name
% of the file. Assuming a standard form for the input statement
% (one that will work with either plain \tex/ or \latex/, and makes
% as few assumptions as possible), we can write a function that
% will trap input statements and execute them only if the given
% file has not yet been loaded:
%
%^^V \csname trap.input\endcsname
%^^V \input grabhedr.sty \relax
%^^V \fileversiondate{foo.bar}{1.2}{1993-Jun-07}
%
% \begin{macro}{\trap.input}
% The function \cw{trap.input} scans for an input statement in
% canonical form and executes it if and only if the file has not yet
% been input (more precisely, if the control sequence consisting of
% the file name is undefined, which means that it has not had
% \cw{fileversiondate} applied to it). The canonical form
% that I consider to be the best is \cw{input} \meta{full file
% name}{\tt\char32 }\cw{relax}. Having the \cw{relax} means that the
% input statement will not try to expand beyond the end of the line
% if \cw{endlinechar} is catcoded to 9 (ignore), as is done rather
% frequently now by progressive \tex/ programmers. The \cw{relax}
% would ordinarily render the space after the file name unnecessary,
% but I prefer leaving the space in to avoid interfering with
% redefinitions of \cw{input} to take a space-delimited argument
% that are occasionally done to achieve other special effects (see,
% for example, ``Organizing a large collection of stylefiles'', by
% Angelika Binding, {\sl Cahiers GUTenberg}, num\'ero 10--11,
% septembre 1991, p.~175.) \latex/'s argument form
% \cw{input}\verb"{...}" cannot, unfortunately, be the
% canonical form if \plaintex/ compatibility is required.
% \begin{macrocode}
\expandafter\gdef\csname trap.input\endcsname
\input#1 \relax{%
\expandafter\ifx\csname#1\endcsname\relax
\afterfi\inputfwh{#1}\relax
\fi}
% \end{macrocode}
% \end{macro}
%
% End the group that encloses this entire file, and then call
% \cw{endinput}.
% \begin{macrocode}
\endgroup
\endinput
% \end{macrocode}
%
% \CheckSum{294}
% \Finale