% \iffalse %% File: l3precom.dtx Copyright (C) 1990-2006 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/cgi-bin/cvsweb.cgi/ %% %% 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} % %\fi \GetIdInfo$Id: l3precom.dtx 621 2007-09-01 20:14:19Z morten $ {L3 Experimental precompilation module} %\iffalse %<*driver> %\fi \ProvidesFile{\filename.\filenameext} [\filedate\space v\fileversion\space\filedescription] %\iffalse \documentclass{l3doc} \begin{document} \DocInput{\filename.\filenameext} \end{document} % % \fi % % \section{Control sequence functions extended \ldots} % % \begin{function}{\cs_gen_sym:N | % \cs_ggen_sym:N} % \begin{syntax} % "\cs_gen_sym:N" % \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 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" % \end{syntax} % Takes the 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" "{" "}" % \end{syntax} % Loads and executes the file if found. Then scans % further ignoring everything until finding "\cs_dump:" where normal % execution continues. If 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 . % \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 % recorded by "\cs_record_name:N" a line % \begin{quote} % "\def:Npn" "{" "}" % \end{quote} % is written to this file. This means that when loading the file the % definitions of all these 's are directly available. % \end{function} % % % \subsection{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 . % \end{variable} % % \StopEventually{} % % \subsection{The Implementation} % % We start by ensuring that the required packages are loaded. % \begin{macrocode} %\ProvidesExplPackage % {\filename}{\filedate}{\fileversion}{\filedescription} %\RequirePackage{l3num} %\RequirePackage{l3io} %\RequirePackage{l3seq} %\RequirePackage{l3int} % \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} %<*initex|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 % \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} {\exp_not:n{\gdef:Npn ##1} {\tlp_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_expanded:Nn \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_expanded:Nn \c_cs_dump_stream {\group_end:} \iow_close:N\c_cs_dump_stream \tex_message:D{~finished} } % % \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> {\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_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} \def_new:Npn\cs_gen_sym:N#1{ \num_gincr:N\g_gen_sym_num \tlp_set:Nc#1{l*\tex_romannumeral:D\num_use:N\g_gen_sym_num} %<*precompile> \exp_after:NN\cs_record_name:N#1 % % \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{ \num_gincr:N\g_ggen_sym_num \tlp_set:Nc#1{g*\tex_romannumeral:D\num_use:N\g_ggen_sym_num} %<*precompile> \exp_after:NN\cs_record_name:N#1 % \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} } % % % \end{macrocode} % \end{macro} % % % Show token usage: % \begin{macrocode} %<*showmemory> \showMemUsage % % \end{macrocode} % % \endinput % % $Log$ % Revision 1.7 2006/03/20 18:26:37 braams % Updated the copyright notice (2006) and demoted all implementation % sections to subsections and so on to clean up the toc for source3.tex % % Revision 1.6 2005/12/27 16:03:21 morten % Changed RCS information retrieval plus a few name changes % % Revision 1.5 2005/04/12 12:06:30 morten % Fixed the use of fake integers (now known as "num") % % Revision 1.4 2005/03/16 22:36:14 braams % Added the tweaks necessary to be able to load with initex % % Revision 1.3 2005/03/11 21:51:50 braams % Just another small mistake to be corrected % % Revision 1.2 2005/03/11 21:21:01 braams % Added the header for CVS public read access and fixed the % use of RCS data %