path: root/Master/texmf-dist/source/latex/expl3/l3precom.dtx

% \iffalse
%% File: l3precom.dtx Copyright (C) 1990-2006,2009 Frank Mittelbach, LaTeX3 project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
%% license or (at your option) any later version.  The latest version
%% of this license is in the file
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% This file is part of the ``expl3 bundle'' (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
%%
%% -----------------------------------------------------------------------
%%
%% The development version of the bundle can be found at
%%
%%    http://www.latex-project.org/svnroot/experimental/trunk/
%%
%% for those people who are interested.
%%
%%%%%%%%%%%
%% NOTE: %%
%%%%%%%%%%%
%%
%%   Snapshots taken from the repository represent work in progress and may
%%   not work or may contain conflicting material!  We therefore ask
%%   people _not_ to put them into distributions, archives, etc. without
%%   prior consultation with the LaTeX Project Team.
%%
%% -----------------------------------------------------------------------
%
%<*driver|package>
\RequirePackage{l3names}
%</driver|package>
%\fi
\GetIdInfo$Id: l3precom.dtx 1453 2009-08-08 14:38:49Z joseph $
  {L3 Experimental precompilation module}
%\iffalse
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass[full]{l3doc}
\begin{document}
\DocInput{\filename.\filenameext}
\end{document}
%</driver>
% \fi
%
% \title{The \textsf{l3precom} package\thanks{This file
%         has version number \fileversion, last
%         revised \filedate.}\\
% Precompilation of complex data}
% \author{\Team}
% \date{\filedate}
% \maketitle
%
% \begin{documentation}
%
% \section{Introduction}
%
%    It is possible speed up the processing of documents when complex parts
%    of the document style file are `precompiled' and stored in a
%    separate file.
%
% \section{Control sequence functions extended \ldots}
%
% \begin{function}{\cs_gen_sym:N |
%                  \cs_ggen_sym:N}
% \begin{syntax}
%   "\cs_gen_sym:N" <tl var.>
% \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 <tl var.> 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|\cs_record_name:c}
% \begin{syntax}
%   "\cs_record_name:N" <cs>
% \end{syntax}
% Takes the <cs> and saves it in a special place 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_record_meaning:N}
% \begin{syntax}
%   "\cs_record_meaning:N" <cs>
% \end{syntax}
% Takes the <cs> and saves its meaning in a special place for pre-compiling
% purposes on a file later on. Used for tracing purposes.
% \end{function}
%
% \begin{function}{\register_record_name:N}
% \begin{syntax}
%   "\register_record_name:N" <register>
% \end{syntax}
% Takes the <register> 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:".
% \end{function}
%
% \begin{function}{\cs_load_dump:n}
% \begin{syntax}
%   "\cs_load_dump:n" \Arg{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}
%  "\cs_set_nopar:Npn" <cs> \Arg{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}
%
% \begin{function}{\dumpLaTeXstate}
% \begin{syntax}
% "\dumpLaTeXstate" \Arg{file}
% \end{syntax}
% This function is used to write control sequences
% and registers, together with their meaning or value in the <file>|.dmp|
% file.
% \end{function}
%
% \section{Internal variables}
%
% \begin{variable}{\g_gen_sym_num |
%                  \g_ggen_sym_num} 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 <tl var.>.
% \end{variable}
%
% \begin{variable}{\g_cs_dump_name_tl}
% Used to store the name of the file to dump to.
% \end{variable}
%
% \begin{variable}{\g_cs_trace_seq}
% Sequence which holds the control sequence names that are to
% be dumped with their corresponding meanings. Used for tracing purposes.
% \end{variable}
%
% \begin{variable}{\g_register_trace_seq}
% Sequence holding the register names to be dumped with their
% corresponding values. Used for tracing purposes.
% \end{variable}
%
% \end{documentation}
%
% \begin{implementation}
%
%  \section{\pkg{l3precom} implementation}
%
%    We start by ensuring that the required packages are loaded.
%    \begin{macrocode}
%<package>\ProvidesExplPackage
%<package>  {\filename}{\filedate}{\fileversion}{\filedescription}
%<package>\RequirePackage{l3num}
%<package>\RequirePackage{l3io}
%<package>\RequirePackage{l3seq}
%<package>\RequirePackage{l3int}
%    \end{macrocode}
%
%  \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}
%<*initex|package>
%<*precompile>
\iow_new:N\c_cs_dump_stream
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\g_cs_dump_name_tl}
%    This \m{tl var.}~is used to store the name of the file.
%
%    \begin{macrocode}
\tl_new:Nn\g_cs_dump_name_tl{}
%    \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,\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}
\cs_new_nopar: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}
\cs_generate_variant:Nn \cs_record_name:N {c}
%    \end{macrocode}
%  \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}
\cs_new_nopar:Npn\cs_dump:{
\iow_term:x{Precompiling~style~into~(\g_cs_dump_name_tl)}
\iow_open:Nn\c_cs_dump_stream{\g_cs_dump_name_tl}
%    \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_now:Nx\c_cs_dump_stream
{\group_begin:
\tex_catcode:D`\token_to_str:N\*=11\scan_stop:
\token_to_str:N\ExplSyntaxOn
}
\seq_map_inline:Nn
\g_cs_dump_seq
{\tex_message:D{.}
\iow_now:Nx\c_cs_dump_stream
%    \end{macrocode}
%    We use a direct |\cs_gset_nopar:Npn| to disable any type of local/global
%    check on the pointers.
%    \begin{macrocode}
     {\exp_not:n{\cs_gset_nopar:Npn ##1}
         {\tl_to_str:N##1}}
}
%    \end{macrocode}
%    We also need to remember the current values of the
%    |\g_gen_sym_num| and |\g_ggen_sym_num| counters to allow
%    further updates after a database was dumped.
%    \begin{macrocode}
\iow_now:Nx \c_cs_dump_stream {\exp_not:n{\num_gset:Nn
                \g_gen_sym_num}
                {\num_use:N\g_gen_sym_num}^^J
\exp_not:n{\num_gset:Nn \g_ggen_sym_num}
                {\num_use:N\g_ggen_sym_num}}
\iow_now:Nx
\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}
\cs_new_nopar:Npn \cs_load_dump:n #1 {
  \file_if_exist:nTF { #1 .cmp } {
    \file_input:n { #1 .cmp }
    \cs_set_eq:NN \cs_dump: \fi:
    \if_false:
  }{
%<*precompile>
    \tl_gset:Nn \g_cs_dump_name_tl { #1 .cmp }
%</precompile>
%<*!precompile>
    \tex_errmessage:D { Cannot~ dump~ with~ this~ format }
%</!precompile>
  }
}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\g_gen_sym_num}
% \begin{macro}{\g_ggen_sym_num}
%    Two counters to make up new local or global \textsl{short} names
%    in pointer structures like the \textsc{ldb}.
%    We use a fake counters since operations with them are seldom.
%    \begin{macrocode}
\num_new:N\g_gen_sym_num \num_gset:Nn\g_gen_sym_num{0}
\num_new:N\g_ggen_sym_num \num_gset:Nn\g_ggen_sym_num{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_num| (|\g_ggen_sym_num|)
%    in roman numeral representation. The generated control sequence
%    is locally stored in the token that was passed in |#1|.
%
%    \begin{macrocode}
\cs_new_nopar:Npn\cs_gen_sym:N#1{
\num_gincr:N\g_gen_sym_num
\tl_set:Nc#1{l*\tex_romannumeral:D\num_use:N\g_gen_sym_num}
%<*precompile>
\exp_after:wN\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:wN\tl_clear_new:N#1}
%    \end{macrocode}
%    The global variant
%    \begin{macrocode}
\cs_new_nopar:Npn\cs_ggen_sym:N#1{
\num_gincr:N\g_ggen_sym_num
\tl_set:Nc#1{g*\tex_romannumeral:D\num_use:N\g_ggen_sym_num}
%<*precompile>
\exp_after:wN\cs_record_name:N#1
%</precompile>
\exp_after:wN\tl_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}
\cs_set_nopar: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}
\cs_set_nopar: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}
\cs_new_nopar:Npn\dumpLaTeXstate#1{
  \iow_term:x{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_now:Nx\c_cs_dump_stream
             {\token_to_str:N##1~
              \token_to_meaning:N##1}
       }
  \tex_message:D{~registers}
  \seq_map_inline:Nn
       \g_register_trace_seq
       {\tex_message:D{.}
        \iow_now:Nx\c_cs_dump_stream
             {\token_to_str:N##1
              \toks_use:N##1}
       }
  \tex_message:D{~finished}
}
%</trace>
%</initex|package>
%    \end{macrocode}
%  \end{macro}
%
%
%    Show token usage:
%    \begin{macrocode}
%<*showmemory>
\showMemUsage
%</showmemory>
%    \end{macrocode}
%
% \end{implementation}
% \PrintIndex
%
% \endinput