% \iffalse
%% File: l3precom.dtx Copyright (C) 1990-1998 LaTeX3 project
%
%<*dtx>
          \ProvidesFile{l3precom.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{l3precom}
%<driver> \ProvidesFile{l3precom.drv}
% \fi
%         \ProvidesFile{l3precom.dtx}
          [1998/04/20 v1.0b L3 Experimental precompilation module]
%
% \iffalse
%<*driver>
\documentclass{l3doc}

\begin{document}
\DocInput{l3precom.dtx}
\end{document}
%</driver>
% \fi
%
% \section{Control sequence functions extended \ldots}
%
% \begin{function}{\cs_gen_sym:N |
%                  \cs_ggen_sym:N}
% \begin{syntax}
%   "\cs_gen_sym:N" <tlp>
% \end{syntax}
% These functions will generate a new control sequence name for use as a
% pointer, e.g.\ some tree structure like the LDB. The new unique name
% is returned locally in <tlp> for further use. The names are generated
% using the roman numeral representation of some special counters
% together with a prefix of "\l*" (local) or "\g*"( global).
% \end{function}
% 
% \begin{function}{\cs_record_name:N}
% \begin{syntax}
%   "\cs_record_name:N" <cs>
% \end{syntax}
% Takes the <cs> and saves it in a special places for pre-compiling
% purposes on a file later on. All control sequences that are recorded
% with this function will be dumped by "\cs_dump:".  This function is
% internally automatically used to record all symbols generated by
% "\cs_gen_sym:N" and "\cs_ggen_sym:N".
% \end{function}
% 
% \begin{function}{\cs_load_dump:n}
% \begin{syntax}
%   "\cs_load_dump:n" "{" <file name> "}"
% \end{syntax}
% Loads and executes the file <file name> if found. Then scans
% further ignoring everything until finding "\cs_dump:" where normal
% execution continues. If <file name> is not found, the name is saved
% and normal execution of all following code is done until "\cs_dump:" is
% scanned. Then all symbols marked for dumping are dumped into <file
% name>.
% \end{function}
% 
% \begin{function}{\cs_dump:}
% Dumps the symbols  recorded by "\cs_record_name:N" in the file given
% by the argument in "\cs_load_dump:n". Dumping means that for every
% <cs> recorded by "\cs_record_name:N" a line
% \begin{quote}
%  "\def:Npn" <cs> "{" <current meaning of cs> "}"
% \end{quote}
% is written to this file. This means that when loading the file the
% definitions of all these <cs>'s are directly available.
% \end{function}
%
%
% \subsection{Internal variables}
% 
% \begin{variable}{\g_gen_sym_fint |
%                  \g_ggen_sym_fint} Holds the number of the last
% generated symbol by "\cs_gen_sym:N" or "\cs_ggen_sym:N".
% \end{variable}
% 
% \begin{variable}{\g_cs_dump_seq}
% Sequence in which the symbols to be dumped are stored.
% \end{variable}
% 
% \begin{variable}{\c_cs_dump_stream}
% Output stream used for writing out the definitions of the
% recorded <tlp>.
% \end{variable}
% 
% 
% 
%  \section{Precompiling some functions}
%
%    We start by ensuring that the required packages are loaded.
%    \begin{macrocode}
%<package>\RequirePackage{l3int}
%<package>\RequirePackage{l3io}
%<package>\RequirePackage{l3seq}
%    \end{macrocode}
%
%    It might speed up the processing of documents when certain parts
%    of the document style file are `precompiled' and stored in a
%    separate file.
%
%  \begin{macro}{\c_cs_dump_stream}
%    We need to allocate an output stream in order to be able to write
%    the precompiled code out.
%    Stream number for the dump.
%
%    \begin{macrocode}
%<*package>
%<*precompile>
\iow_new:N\c_cs_dump_stream
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\g_cs_dump_name_tlp}
%    This \m{tlp} is used to store the name of the file.
%
%    \begin{macrocode}
\tlp_new:Nn\g_cs_dump_name_tlp{}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\g_cs_dump_seq}
%    While processing the documentstyle we build up a list of
%    control sequence names to be dumped. For this purpose
%    we use the |\g_cs_dump_seq| sequence.
%
%    \begin{macrocode}
\seq_new:N\g_cs_dump_seq
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\cs_record_name:N}
%  \begin{macro}{\cs_record_name:c}
%    These functions mark a control sequence for dumping into a
%    precompiled style. 
%
%    When the {\sf trace} `module' is included in the code we also write
%    information about the control sequence into a |.dmp| file.
%    \begin{macrocode}
\def_new:Npn\cs_record_name:N#1{
%<*trace>
      \seq_gput_left:Nn
          \g_cs_trace_seq#1
%</trace>
      \seq_gput_left:Nn
          \g_cs_dump_seq#1}
\def_new:Npn\cs_record_name:c{\exp_args:Nc\cs_record_name:N}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%
% \begin{macro}{\cs_dump:}
%    When a document style\marginpar{\small As you can see from the
%    wording this pre-dates \LaTeXe{} \quad \emph{Frank}}
%    calls |\cs_dump:| it triggers this code
%    to write all the precompilation information out to a file.
%
%    Before dumping, we write a message to the terminal informing the
%    `user' of this fact.
%    \begin{macrocode}
\def_new:Npn\cs_dump:{
  \iow_expanded_term:n{Precompiling~style~into~(\g_cs_dump_name_tlp)}
  \iow_open:Nn\c_cs_dump_stream{\g_cs_dump_name_tlp}
%    \end{macrocode}
%    The first thing we write on a `dump' file is a command that
%    allows us to use |*| in control sequences. We also need to be 
%    able to write to (and read from) the file internal control
%    sequences, containing |_| and |:|.
%    \begin{macrocode}
  \iow_expanded:Nn\c_cs_dump_stream
    {\group_begin:
     \tex_catcode:D`\token_to_string:N\*=11\scan_stop:
     \token_to_string:N\CodeStart
    }
  \seq_map_inline:Nn
       \g_cs_dump_seq
       {\tex_message:D{.}
        \iow_expanded:Nn\c_cs_dump_stream
%    \end{macrocode}
%    We use a direct |\gdef:Npn| to disable any type of local/global
%    check on the pointers.
%    \begin{macrocode}
             {\token_to_string:N\gdef:Npn
                 \token_to_string:N##1
                 {\tlp_to_str:N##1}}
       }
%    \end{macrocode}
%    We also need to remember the current values of the
%    |\g_gen_sym_fint| and |\g_ggen_sym_fint| counters to allow
%    further updates after a database was dumped.
%    \begin{macrocode}
  \iow_expanded:Nn
     \c_cs_dump_stream
     {\token_to_string:N\fint_gset:Nn
                        \g_gen_sym_fint
                        {\fint_use:N\g_gen_sym_fint}^^J
      \token_to_string:N\fint_gset:Nn
                        \g_ggen_sym_fint
                        {\fint_use:N\g_ggen_sym_fint}}
  \iow_expanded:Nn
     \c_cs_dump_stream
     {\group_end:}
  \iow_close:N\c_cs_dump_stream
  \tex_message:D{~finished}
}
%</precompile>
%    \end{macrocode}
% \end{macro}
%
%  \begin{macro}{\cs_load_dump:n}
%    A function to read a precompiled file into memory and skip until a
%    |\cs_dump:| command is found. If no such file is found, processing
%    continues and a subsequent |\cs_dump:| command will then create the
%    dump file.
%    \begin{macrocode}
\def_new:Npn\cs_load_dump:n#1{
  \file_not_found:nTF{#1.cmp}
%<*precompile>
      {\tlp_gset:Nn\g_cs_dump_name_tlp{#1.cmp}}
%</precompile>
%<-precompile> {\tex_errmessage:D{Cannot~ dump~ with~ this~ format}}
      {\input{#1.cmp}
       \let:NN\cs_dump:\fi:
       \if_false:}}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\g_gen_sym_fint}
% \begin{macro}{\g_ggen_sym_fint}
%    Two counters to make up new local or global {\sl short\/} names
%    in pointer structures like the {\sc ldb}.
%    We use a fake counters since operations with them are seldom.
%    \begin{macrocode}
\fint_new:N\g_gen_sym_fint
\fint_gset:Nn\g_gen_sym_fint{0}
\fint_new:N\g_ggen_sym_fint
\fint_gset:Nn\g_ggen_sym_fint{0}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\cs_gen_sym:N}
% \begin{macro}{\cs_ggen_sym:N}
%    We need to be able to generate control sequences on the fly.
%    They will exist of a prefix, either |l*| or |g*|, followed
%    by the value of the counter |\g_gen_sym_fint| (|\g_ggen_sym_fint|)
%    in roman numeral representation. The generated control sequence
%    is locally stored in the token that was passed in |#1|.
%
%    \begin{macrocode}
\def_new:Npn\cs_gen_sym:N#1{
  \fint_gincr:N\g_gen_sym_fint
  \tlp_set:Nc#1{l*\tex_romannumeral:D\fint_use:N\g_gen_sym_fint}
%<*precompile>
  \exp_after:NN\cs_record_name:N#1
%</precompile>
%    \end{macrocode}
%    We still want to define the initial value for the new symbol
%    globally to make sure that during compilation something is
%    written to the output file.
%    \begin{macrocode}
  \exp_after:NN\tlp_clear_new:N#1}
%    \end{macrocode}
%    The global variant
%    \begin{macrocode}
\def_new:Npn\cs_ggen_sym:N#1{
  \fint_gincr:N\g_ggen_sym_fint
  \tlp_set:Nc#1{g*\tex_romannumeral:D\fint_use:N\g_ggen_sym_fint}
%<*precompile>
  \exp_after:NN\cs_record_name:N#1
%</precompile>
  \exp_after:NN\tlp_clear_new:N#1}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%  \begin{macro}{\g_cs_trace_seq}
%    A sequence which holds the control sequence names that are to 
%    be dumped. They are stored together with their meaning.
%
%    ATTENTION: as we currently don't distribute allocation routines
%    for primitive registers this code will have no effect!
%    \begin{macrocode}
%<*trace>
\seq_new:N\g_cs_trace_seq
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\g_register_trace_seq}
%    Sequence holding the register names to be dumped with their
%    corresponding values.
%
%    ATTENTION: as we currently don't distribute allocation routines
%    for primitive registers this code will have no effect!
%    \begin{macrocode}
\seq_new:N\g_register_trace_seq
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\cs_record_meaning:N}
%    Function marking a control sequence for dumping with meaning.
%    \begin{macrocode}
\def:Npn\cs_record_meaning:N#1{
      \seq_gput_left:Nn
          \g_cs_trace_seq#1}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\register_record_name:N}
%    Function marking a register for dumping with value.
%    \begin{macrocode}
\def:Npn\register_record_name:N#1{
      \seq_gput_left:Nn
          \g_register_trace_seq#1}
%    \end{macrocode}
%  \end{macro}
%
%
% \begin{macro}{\dumpLaTeXstate}
%    The function |\dumpLaTeXstate| is used to write control sequences
%    and registers, together with their meaning or value in the |.dmp|
%    file. We write informational messages to the terminal during the 
%    dump.
%
%    ATTENTION: as we currently don't distribute allocation routines
%    for primitive registers this part of the code will dump nothing
%    unless |\register_record_name:N| is explicitly used.
%    \begin{macrocode}
\def_new:Npn\dumpLaTeXstate#1{
  \iow_expanded_term:n{Dumping~commands~into~(#1.dmp)}
  \iow_open:Nn\c_cs_dump_stream{#1.dmp}
  \seq_map_inline:Nn
       \g_cs_trace_seq
       {\tex_message:D{.}
        \iow_expanded:Nn\c_cs_dump_stream
             {\token_to_string:N##1~
              \token_to_meaning:N##1}
       }
  \tex_message:D{~registers}
  \seq_map_inline:Nn
       \g_register_trace_seq
       {\tex_message:D{.}
        \iow_expanded:Nn\c_cs_dump_stream
             {\token_to_string:N##1
              \the_internal:D##1}
       }
  \tex_message:D{~finished}
}
%</trace>
%</package>
%    \end{macrocode}
%  \end{macro}
%
%
%    Show token usage:
%    \begin{macrocode}
%<*showmemory>
\showMemUsage
%</showmemory>
%    \end{macrocode}
%
%