% \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} % %\fi \GetIdInfo$Id: l3precom.dtx 1793 2010-02-09 20:36:19Z 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} % % \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" % \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|\cs_record_name:c} % \begin{syntax} % "\cs_record_name:N" % \end{syntax} % Takes the 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" % \end{syntax} % Takes the 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" % \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:". % \end{function} % % \begin{function}{\cs_load_dump:n} % \begin{syntax} % "\cs_load_dump:n" \Arg{file name} % \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} % "\cs_set_nopar:Npn" \Arg{current meaning of cs} % \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} % % \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 |.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}{\g_cs_dump_stream} % Output stream used for writing out the definitions of the % recorded . % \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 {\filename}{\filedate}{\fileversion}{\filedescription} \package_check_loaded_expl: % % \end{macrocode} % % \begin{macro}{\g_cs_dump_name_tl} % This \m{tl var.}~is used to store the name of the file. % % \begin{macrocode} %<*initex|package> %<*precompile> \tl_new:N \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 % \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\g_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\g_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\g_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_int| and |\g_ggen_sym_int| counters to allow % further updates after a database was dumped. % \begin{macrocode} \iow_now:Nx \g_cs_dump_stream {\exp_not:n{\int_gset:Nn \g_gen_sym_int} {\int_use:N\g_gen_sym_int}^^J \exp_not:n{\int_gset:Nn \g_ggen_sym_int} {\int_use:N\g_ggen_sym_int}} \iow_now:Nx \g_cs_dump_stream {\group_end:} \iow_close:N\g_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} \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> \tex_errmessage:D { Cannot~ dump~ with~ this~ format } % } } % \end{macrocode} % \end{macro} % % \begin{macro}{\g_gen_sym_int} % \begin{macro}{\g_ggen_sym_int} % Two counters to make up new local or global \textsl{short} names % in pointer structures like the \textsc{ldb}. % \begin{macrocode} \int_new:N\g_gen_sym_int \int_gset:Nn\g_gen_sym_int{0} \int_new:N\g_ggen_sym_int \int_gset:Nn\g_ggen_sym_int{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{ \int_gincr:N\g_gen_sym_num \tl_set:Nc#1{l*\tex_romannumeral:D\int_use:N\g_gen_sym_int} %<*precompile> \exp_after:wN\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:wN\tl_clear_new:N#1} % \end{macrocode} % The global variant % \begin{macrocode} \cs_new_nopar:Npn\cs_ggen_sym:N#1{ \int_gincr:N\g_ggen_sym_int \tl_set:Nc#1{g*\tex_romannumeral:D\int_use:N\g_ggen_sym_int} %<*precompile> \exp_after:wN\cs_record_name:N#1 % \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\g_cs_dump_stream{#1.dmp} \seq_map_inline:Nn \g_cs_trace_seq {\tex_message:D{.} \iow_now:Nx\g_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\g_cs_dump_stream {\token_to_str:N##1 \toks_use:N##1} } \iow_clos:Nn \g_cs_dump_stream \tex_message:D{~finished} } % % % \end{macrocode} % \end{macro} % % % Show token usage: % \begin{macrocode} %<*showmemory> \showMemUsage % % \end{macrocode} % % \end{implementation} % \PrintIndex % % \endinput