summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3precom.dtx
blob: 786181d93b55023804d97fcf5327d41ce8cfb48b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
% \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}
%</driver|package>
%\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}
%</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_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 <tlp>.
% \end{variable}
%
% \StopEventually{}
%
%  \subsection{The 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}
%
%    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
%</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}
     {\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}
}
%</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_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
%</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{
\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
%</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>
%</initex|package>
%    \end{macrocode}
%  \end{macro}
%
%
%    Show token usage:
%    \begin{macrocode}
%<*showmemory>
\showMemUsage
%</showmemory>
%    \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
%