Debian Codegraph @

texmf-dist/source/latex/checklistings/checklistings.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2015 by Timothy Bourke <[email protected]>
4 % and Marc Pouzet <[email protected]>
5 % -------------------------------------------------------
6 %
7 % This file may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.2
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in:
11 %
12 % http://www.latex-project.org/lppl.txt
13 %
14 % and version 1.2 or later is part of all distributions of LaTeX version
15 % 1999/12/01 or later.
16 %
17 % CTAN Topic: callback, listing
18 % \fi
19 %
20 % \iffalse
21 %<*driver>
22 \ProvidesFile{checklistings.dtx}
23 %</driver>
24 %<package>\NeedsTeXFormat{LaTeX2e}
25 %<package>\ProvidesPackage{checklistings}
26 %<package> [2015/09/01 v1.0 compile code samples and insert the results]
27 %<package>\RequirePackage{keyval}
28 %<package>\RequirePackage{kvoptions}
29 %<package>\RequirePackage{fancyvrb}
30 %<package>\RequirePackage{color}
31 %<package>\RequirePackage{listings}
32 %<package>\makeatletter
33 %<package>\lst@RequireAspects{writefile}
34 %<package>\SetupKeyvalOptions{family=CHKL,prefix=CHKL@}
35 %<package>\makeatother
36 %
37 %<*driver>
38 \documentclass{ltxdoc}
39
40 \usepackage{checklistings}
41 \usepackage{url}
42 \usepackage{hypdoc}
43 \usepackage{showexpl}
44 \usepackage{array}
45 \usepackage{longtable}
46
47 \lstset{
48 basicstyle=\small\ttfamily,
49 numbers=none,
50 keywordstyle=\color{blue}\bfseries,
51 pos=l,
52 }
53
54 \checklistings{
55 msgstyle={formatcom=\footnotesize},
56 errstyle={formatcom=\footnotesize}}
57
58 \EnableCrossrefs \CodelineIndex
59 \RecordChanges
60
61 \newcommand{\refsec}[1]{Section~\ref{sec:#1}}
62
63 \begin{document}
64 \DocInput{checklistings.dtx}
65 \PrintChanges
66 \PrintIndex
67 \end{document}
68 %</driver>
69 % \fi
70 %
71 % \CheckSum{444}
72 %
73 % \CharacterTable
74 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
75 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
76 % Digits \0\1\2\3\4\5\6\7\8\9
77 % Exclamation \! Double quote \" Hash (number) \#
78 % Dollar \$ Percent \% Ampersand \&
79 % Acute accent \' Left paren \( Right paren \)
80 % Asterisk \* Plus \+ Comma \,
81 % Minus \- Point \. Solidus \/
82 % Colon \: Semicolon \; Less than \<
83 % Equals \= Greater than \> Question mark \?
84 % Commercial at \@ Left bracket \[ Backslash \\
85 % Right bracket \] Circumflex \^ Underscore \_
86 % Grave accent \` Left brace \{ Vertical bar \|
87 % Right brace \} Tilde \~}
88 %
89 %
90 % \changes{v1.0}{2015/09/01}{Initial version}
91 %
92 % \GetFileInfo{checklistings.sty}
93 %
94 % \DoNotIndex{\newcommand,\newenvironment}
95 % \DoNotIndex{\@file,\@ifundefined,\@tempboxa,\@undefined}
96 % \DoNotIndex{\arabic,\bgroup,\color,\dimexpr,\relax,\topsep,\vspace}
97 % \DoNotIndex{\CurrentOption,\DeclareBoolOption,\DeclareComplementaryOption}
98 % \DoNotIndex{\DeclareDefaultOption,\DeclareStringOption,\DeclareVoidOption}
99 % \DoNotIndex{\def,\define@key,\edef,\egroup,\else,\emph,\expandafter}
100 % \DoNotIndex{\fi,\global,\hbox,\ifnum,\InputIfFileExists,\langle,\let}
101 % \DoNotIndex{\newcounter,\newif,\PackageWarning,\ProcessKeyvalOptions}
102 % \DoNotIndex{\rangle,\setbox,\setkeys,\space,\stepcounter}
103 % \DoNotIndex{\value,\@currentlabel,\@firstoftwo,\AtEndDocument,\em}
104 % \DoNotIndex{\closeout,\csname,\endcsname,\DefineVerbatimEnvironment}
105 % \DoNotIndex{\jobname,\kvsetkeys,\label,\newwrite,\noexpand,\openout}
106 % \DoNotIndex{\partopsep,\setlength,\thepage,\write,\resetcounteronoverlays}
107 % \DoNotIndex{\@tempa,\fvset,\ifx,\inputlineno,\lstset,\the}
108 % \DoNotIndex{\DeclareRobustCommand,\empty,\ifdefined,\meta}
109 % \expandafter\DoNotIndex\expandafter{\string\$}
110 % \expandafter\DoNotIndex\expandafter{\string\#}
111 %
112 % \title{The \textsf{checklistings} package\thanks{This document
113 % corresponds to \textsf{checklistings}~\fileversion, dated \filedate.}}
114 % \author{Timothy Bourke and Marc Pouzet}
115 %
116 % \maketitle
117
118 % \section{Introduction}
119 %
120 % User manuals and papers about programming languages usually contain many
121 % code samples, often with accompanying compiler messages giving the types
122 % of declarations or error messages explaining why certain declarations are
123 % invalid.
124 % This package extends
125 % |fancyvrb|\footnote{\url{http://www.ctan.org/pkg/fancyvrb}} and
126 % |listings|\footnote{\url{http://www.ctan.org/pkg/listings}}, which are
127 % ideal for displaying code, with a way to pass code samples through a
128 % compiler and include the resulting messages in a \LaTeX{} document.
129 % The motivation is to check the code samples in a document for syntax and
130 % typing errors and to facilitate the inclusion of inferred types and
131 % compiler warnings or errors in a text.
132 % This package is intentionally very lightweight and unlike packages like
133 % |python|,\footnote{\url{http://www.ctan.org/pkg/python}} it is not
134 % intended for interacting with an interpretor or including the execution
135 % traces of code.
136 % While it does not focus on a specific programming language, it is designed
137 % to work well with ML-like languages.
138 %
139 % As an example, the text at left below is generated by the \LaTeX{} code at
140 % right:
141 %
142 % \iffalse
143 %<*example>
144 % \fi
145 \begin{LTXexample}
146 Code samples are included
147 verbatim and the results of
148 compilation can be included
149 automatically:
150 \begin{chklisting}[withresult]
151 let inc x = x + 1
152 let y = inc 3
153 \end{chklisting}
154 \end{LTXexample}
155 % \iffalse
156 %</example>
157 % \fi
158 %
159 % A first pass through |latex| generates both a |.chkl| file,
160 % with parameters for the compiler, and an |.ml| file containing the source
161 % code (i.e., the two lines in the example above).
162 % Running the |checklistings.sh| script processes these files to produce a
163 % |.tex| file with the results of compilation.
164 % A second pass through |latex| updates the compiler message.
165 %
166 % \noindent
167 % It is possible to continue examples and to label them (to be continued at
168 % some later point):
169 % \iffalse
170 %<*example>
171 % \fi
172 \begin{LTXexample}[pos=b]
173 These definitions follow on from the previous ones:
174 \begin{chklisting}[continue,withresult,label=early]
175 let z = y + inc y
176 \end{chklisting}
177 \end{LTXexample}
178 % \iffalse
179 %</example>
180 % \fi
181 %
182 % \bigskip\noindent
183 % Examples need not necessarily succeed:
184 % \iffalse
185 %<*example>
186 % \fi
187 \begin{LTXexample}[pos=b]
188 This code does not compile:
189 \begin{chklisting}[continue,fail,withresult,skipone]
190 let u = 3
191 let w = u + "four"
192 \end{chklisting}
193 \end{LTXexample}
194 % \iffalse
195 %</example>
196 % \fi
197 % Note that the line number in the error message is 1 even though the
198 % |continue| option added a line to include the previous definitions and the
199 % |skipone| option hid the |let u = 3| line.
200 % The |checklistings.sh| script performs this adjustment by looking for the
201 % regular expression `|line *[0-9][0-9]*|' and decrementing the number
202 % appropriately.
203 % This approach is simple and effective but obviously not foolproof.
204 % Some manual tuning of the script may be required for correct results.
205 %
206 % \section{Use}\label{sec:use}
207 %
208 % Using the package involves three elements:
209 % \begin{enumerate}
210 %
211 % \item
212 % The declaration \verb|\usepackage{checklistings}|.\\
213 % \refsec{rvpkg} describes the options for configuring package behaviour.
214 %
215 % \item
216 % The environment \verb|chklisting|.\\
217 % This environment is used like any other verbatim environment.
218 % \refsec{rvenv} describes options that may be given to control its
219 % behaviour.
220 %
221 % \item
222 % The script \verb|checklistings.sh|.\\
223 % Running this script passes the contents of each \verb|chklisting|
224 % environment through a compiler or interpreter and copies the resulting
225 % output into a file.
226 %
227 % \end{enumerate}
228 %
229 % Additionally, the file \verb|checklistings.hva| can be used to incorporate
230 % the output of |checklistings| in HTML documents generated by
231 % HeVeA.\footnote{\url{http://hevea.inria.fr}}
232 %
233 % \subsection{Package options}\label{sec:rvpkg}
234 %
235 % \DescribeMacro{\checklistings}
236 % Package options are either given as optional arguments to
237 % \verb|\usepackage| or via one or more calls to \verb|\checklistings|.
238 % The advantage of the latter is that macros are not expanded (for a
239 % detailed explanation see the documentation for
240 % |kvoptions|,\footnote{\url{http://www.ctan.org/pkg/kvoptions}} Section
241 % 4.1, \emph{Package kvoptions-patch}).
242 % Options are passed as a comma separated list of \meta{key}|=|\meta{value}
243 % pairs and single \meta{key}s.
244 %
245 % There are three classes of options: options controlling the default
246 % behaviour of \verb|chklisting|, options for configuring the
247 % \verb|checklistings.sh| script, and options controlling the display of
248 % code and results.
249 %
250 % \subsubsection{Behavioural options}
251 %
252 % These options control the default behaviour of the \verb|chklisting|
253 % environment.
254 %
255 % \begin{longtable}{@{}>{\ttfamily}lp{75mm}>{\ttfamily}l@{}}
256 % \parbox{15mm}{option} & description & \parbox{25mm}{default}\\\hline
257 % withresult
258 % & Automatically show compilation results.
259 % & false
260 % \\
261 % skipone
262 % & Do not display the first line of code (see the description under the
263 % |chklisting| environment).
264 % &
265 % false
266 % \\
267 % skiptwo
268 % & Do not display the first two lines of code (see the description under
269 % the |chklisting| environment).
270 % &
271 % false
272 % \\
273 % hideproblems
274 % & Globally disable the display of failure messages (within a red box) when
275 % compilation fails or succeeds unexpectedly.
276 % &
277 % false
278 % \\
279 % \end{longtable}
280 %
281 % \subsubsection{Configuring compilation}\label{sec:compileconfig}
282 %
283 % These options are used for naming and placing the files generated by
284 % \verb|chklisting| environments.
285 % They are passed to the \verb|checklistings.sh| script and thus control
286 % its behaviour.
287 %
288 % \makeatletter
289 % \begin{longtable}{@{}>{\ttfamily}lp{75mm}>{\ttfamily}l@{}}
290 % \parbox{15mm}{option} & description & \parbox{25mm}{default}\\\hline
291 % prefix
292 % & Prefix for naming source files.
293 % It must not contain underscores (\verb|_|).
294 % & \CHKL@prefix
295 % \\
296 % ext
297 % & Extension of source files.
298 % & \CHKL@ext
299 % \\
300 % subdir
301 % & If defined, source files are created in the given subdirectory, which
302 % must already exist.
303 % A final slash (\verb|/|) should not be given.
304 % The name must not contain underscores (\verb|_|).
305 % & \CHKL@subdir
306 % \\
307 % prompt
308 % & The prompt displayed by |\chklistingcmd|.
309 % & \CHKL@prompt
310 % \\
311 % compiler
312 % & Path of the compiler to execute.
313 % & \CHKL@compiler
314 % \\
315 % compilerflags
316 % & Flags passed to the compiler.
317 % These are not revealed by |\chklistingcmd|.
318 % & \CHKL@compilerflags
319 % \\
320 % lastflags
321 % & Flags passed to the compiler before the main source file, that is, the
322 % last one given.
323 % & \CHKL@lastflags
324 % \\
325 % includecmd
326 % & The source language command for importing the definitions of another
327 % file.
328 % & \CHKL@includecmd
329 % \\
330 % html
331 % & The path of a program that renders source code as html.
332 % This value can be useful when using HeVeA to produce web pages from
333 % \LaTeX{} documents.
334 % In any case, it is optional.
335 % & \CHKL@html
336 % \end{longtable}
337 % \makeatother
338 %
339 % Each \verb|chklisting| environment is assigned a number $n$, from zero,
340 % and its contents are written to the file:
341 % \meta{subdir}|/|\meta{prefix}\meta{n}|.|\meta{ext},
342 % where \meta{n} is zero-padded to four characters.
343 % For example, by default, the fourth environment is written to the file
344 % \verb|chklisting0003.ml| in the current directory.
345 %
346 % Source lines are added for each dependency, and those files are compiled
347 % using the \meta{compiler}, \meta{compilerflags}, and \meta{lastflags}
348 % options.
349 % For example, if the fourth environment depends on the first and the
350 % second, a line is added:
351 % \begin{center}
352 % \meta{includecmd} |Withopen0000| \meta{includecmd} |Withopen0001|,
353 % \end{center}
354 % where \verb|Withopen| is the prefix used for such augmented files, and the
355 % compiler is invoked with:\\
356 % \begin{center}
357 % \begin{tabular}{ll}
358 % \meta{compiler}
359 % & \meta{compilerflags}\ \ |Withopen0000|\ \ |Withopen0001| \\
360 % & \meta{lastflags}\ \ |Withopen0003|
361 % \end{tabular}
362 % \end{center}
363 %
364 % \subsubsection{Controlling the display}
365 %
366 % This package exploits the display options given by the |fancyvrb| package.
367 %
368 % \begin{longtable}{@{}>{\ttfamily}lp{75mm}>{\ttfamily}l@{}}
369 % \parbox{15mm}{option} & description & \parbox{25mm}{default}\\\hline
370 % codestyle
371 % & |fancyvrb| options for code
372 % & \\
373 % msgstyle
374 % & |fancyvrb| options for compiler messages
375 % & formatcom=\string\em
376 % \\
377 % errstyle
378 % & |fancyvrb| options for error messages
379 % & formatcom=\string\em
380 % \\
381 % codelst
382 % & |listings| options for source code, passed with |\lstset|. When this
383 % option is not empty, |fancyvrb=true| is included automatically.
384 % \\
385 % msglst
386 % & As for |codelst|, but applied to compiler messages.
387 % \\
388 % errlst
389 % & As for |codelst|, but applied to error messages.
390 % \\
391 % \end{longtable}
392 %
393 % Other options are passed directly through to the |fancyvrb| package and
394 % applied to all |chklisting| code blocks (but not to messages or errors).
395 % For example, \verb|frame=single|.
396 % These options must typically be set using |\checklistings|, since they
397 % will usually contain commands that should not be expanded immediately
398 % (like |\em| or |\bf|).
399 %
400 % \subsection{The \texttt{chklisting} environment}\label{sec:rvenv}
401 %
402 % \DescribeEnv{chklisting}
403 % As an optional argument, this environment takes a comma separated list of
404 % \meta{key}|=|\meta{value} and single \meta{key}s.
405 %
406 % \begin{longtable}{@{}>{\ttfamily}lp{100mm}}
407 % \parbox{15mm}{option} & description \\\hline
408 % fail
409 % & This code is expected to fail; an error is reported if it succeeds.
410 % \\
411 % continue
412 % & This code is continued from the previous |chklisting| environment; all
413 % of the definitions available there are imported.
414 % \\
415 % label
416 % & Label this code for later inclusion.
417 % \\
418 % include
419 % & All of the definitions available after the environment with the given
420 % label are imported.
421 % \\
422 % withresult
423 % & The result of compiling the code is displayed (see also
424 % |\chklistingmsg| and |\chklistingerr|).
425 % This is normally either the types of declared values or the results of
426 % evaluation.
427 % For environments marked |fail|, it will be an error message.
428 % \\
429 % withoutresult
430 % & The result of compiling code is not displayed automatically.
431 % This is the default behaviour, but it can be overridden by the package
432 % options.
433 % \\
434 % hide
435 % & The code is not displayed, but it is still compiled, compiler messages
436 % are still displayed (if |withresult| is active), and definitions are still
437 % available for continuation (|continue|), labelling (|label|), and later
438 % inclusion (|include|).
439 % \\
440 % skipone
441 % & Do not display the first line of the code.
442 % This line is still sent to the compiler and may thus be used to open
443 % other modules, or to pass execution options (via comments).
444 % \\
445 % skiptwo
446 % & As pre the previous option, but two lines are skipped.
447 % \\
448 % skipnone
449 % & Do not skip any lines; this option overrides any package-level skip
450 % setting.
451 % \\
452 % hideproblems
453 % & Do not display an error message within the document when compilation
454 % fails or succeeds unexpectedly.
455 % \\
456 % showproblems
457 % & Display an error message within the document when compilation fails or
458 % succeeds unexpectedly.
459 % This is the default behaviour unless the |hideproblems| package option was
460 % set.
461 % \\
462 % \end{longtable}
463 %
464 % The results of compiling the code of a |chklisting| environment are made
465 % available in the following macros until the next |chklisting| which will
466 % redefine them.
467 % \begin{description}
468 %
469 % \item[\texttt{\string\chklistingcmd}]
470 % \DescribeMacro{\chklistingcmd}
471 % contains an idealised version of the command line used to compile the code
472 % sample.
473 % It includes the |prompt|, the basename of |compiler|, and |lastflags|, but
474 % not |compilerflags| or the list of included files.
475 % Furthermore, the |subdir| and serial number are removed from the filename
476 % of the code sample, which becomes simply \meta{prefix}|.|\meta{ext}.
477 %
478 % \item[\texttt{\string\chklistingmsg\marg{label}}]
479 % \DescribeMacro{\chklistingmsg}: inserts the verbatim text emitted by the
480 % compiler, provided compilation succeeded, for the |chklisting|
481 % environment labelled \meta{label}.
482 % When \meta{label} is left empty, the message for the last environment is
483 % inserted.
484 % It should not be used after environments marked |fail|.
485 %
486 % \item[\texttt{\string\chklistingerr\marg{label}}]
487 % \DescribeMacro{\chklistingerr}: inserts the verbatim text emitted by the
488 % compiler, provided compilation failed, for the |chklisting| environment
489 % labelled \meta{label}.
490 % When \meta{label} is left empty, the message for the last environment is
491 % inserted.
492 % It should only be used after environments marked |fail|.
493 % \end{description}
494 %
495 % \subsection{The \texttt{checklistings.sh} script}\label{sec:rvsh}
496 %
497 % Processing a document that uses the |checklistings| package produces a
498 % |.chkl| file containing compiler options and a list of source files
499 % together with their interdependencies.
500 % The |checklistings.sh| script processes |.chkl| files by executing the
501 % specified compiler against each listed source file
502 % \meta{subdir}|/|\meta{prefix}\meta{n}|.|\meta{ext} and copying the
503 % results---the command-line used, whether it succeeded or failed, the
504 % messages on |stdout|, and the messages on |stderr|---into a corresponding
505 % file, \meta{subdir}|/|\meta{prefix}\meta{n}|.tex|, for inclusion in the
506 % original document.
507 %
508 % The \verb|checklistings.sh| script is written for the Bourne shell
509 % (\verb|sh|).
510 % It takes a list of |.chkl| files as arguments (with or without the
511 % exentions), but if none are given it processes all such files in the
512 % current working directory.
513 %
514 % The compilation options specified within a \LaTeX{} source file, see
515 % \refsec{compileconfig}, can be manually overridden by processing a |.chkl|
516 % file, before any others, containing a `|lock|' directive, for example:
517 % |lock compiler=/usr/local/bin/ocamlc|.
518 % This feature is useful when working with others to develop the compiler
519 % being documented.
520 %
521 % \StopEventually{}
522 \makeatletter
523 %
524 % \section{Remarks}
525 %
526 % \subsection{Known limitations}
527 %
528 % The package and script have some known limitations.
529 % \begin{itemize}
530 %
531 % \item
532 % Line numbers in error messages may not correspond correctly with the line
533 % numbers of sample files, due to either the |skip*| options, or because of
534 % lines added to import code.
535 %
536 % \item
537 % The system has been designed to work with ML-style compilers.
538 % It has not been tested with other compilers and interpreters.
539 % Please contact \url{[email protected]} if you would like to support other
540 % systems.
541 % Patches are most welcome, but the intent is to keep this package
542 % relatively simple rather than to try to do everything.
543 %
544 % \item
545 % Multiple languages in a single document are not supported.
546 %
547 % \item
548 % Care must be taken when using |checklistings| with the overlays of the
549 % Beamer package.
550 % In particular, |chklisting| environment commands are to be avoided within
551 % commands that completely omit material from slides, like |only|, |alt|, or
552 % |temporal|, or with `closed' overlay specifications, like |2| or |1-3|.
553 % As these commands do not execute the material, the environment sequence
554 % numbers do not increase monotonically, and the compilation results may not
555 % be properly synchronized with the verbatim text.
556 % Commands that only hide material, or that introduce it successively, like
557 % |uncover| or |visible|, or `open' overlay specifications, like |2-|,
558 % should function as expected.
559 %
560 % \end{itemize}
561 %
562 % \section{Implementation}
563 %
564 % All internal macros have names of the form |\CHKL@|\meta{name}.
565 %
566 % \begin{macro}{\chklisting}
567 % Generate the sequence of source code identifiers used in per-environment
568 % filenames and to manage dependencies.
569 % If |beamer| is being used, reset the counter on each overlay to avoid
570 % generating multiple output files for the same program.
571 % \begin{macrocode}
572 \newcounter{chklisting}
573 \ifdefined\resetcounteronoverlays
574 \resetcounteronoverlays{chklisting}
575 \fi
576 % \end{macrocode}
577 % \end{macro}
578 %
579 % \begin{macro}{\ifCHKL@fileexists}
580 % An internal boolean variable for remembering whether an input |.tex| file,
581 % corresponding to the compilation of source code, was found.
582 % \begin{macrocode}
583 \newif\ifCHKL@fileexists
584 % \end{macrocode}
585 % \end{macro}
586 %
587 % \subsection{Package Options}
588 %
589 % The package options are processed using the |kvoptions| package.
590 %
591 % \begin{macro}{\CHKL@pkg@verbopts}
592 % This list accumulates package-level options for the |verbatim|
593 % environments.
594 % \begin{macrocode}
595 \def\CHKL@pkg@verbopts{}
596 % \end{macrocode}
597 % \end{macro}
598 %
599 % \begin{macro}{\CHKL@pkg@globalskip}
600 % Defines the number of lines to be skipped when displaying a code sample as
601 % defined by the global options |skipone| and |skiptwo|.
602 % \begin{macrocode}
603 \def\CHKL@pkg@globalskip{0}
604 % \end{macrocode}
605 % \end{macro}
606 %
607 % \noindent
608 % Declare the package options and their default values:
609
610 % \begin{macrocode}
611 \DeclareBoolOption{withresult}
612 \DeclareComplementaryOption{withoutresult}{withresult}
613 \DeclareBoolOption[true]{showproblems}
614 \DeclareComplementaryOption{hideproblems}{showproblems}
615 \DeclareVoidOption{skipone}
616 {\edef\CHKL@pkg@globalskip{1}%
617 \edef\CHKL@pkg@verbopts{\CHKL@pkg@verbopts,firstline=2}}
618 \DeclareVoidOption{skiptwo}
619 {\edef\CHKL@pkg@globalskip{2}%
620 \edef\CHKL@pkg@verbopts{\CHKL@pkg@verbopts,firstline=3}}
621 \DeclareDefaultOption
622 {\edef\CHKL@pkg@verbopts{\CHKL@pkg@verbopts,\CurrentOption}}
623 \DeclareStringOption[]{codestyle}
624 \DeclareStringOption[formatcom=\em]{msgstyle}
625 \DeclareStringOption[formatcom=\em]{errstyle}
626 \DeclareStringOption{codelst}
627 \DeclareStringOption{msglst}
628 \DeclareStringOption{errlst}
629 \DeclareStringOption{emptyoption}
630 \DeclareStringOption[.]{subdir}
631 \DeclareStringOption[chklisting]{prefix}
632 \DeclareStringOption[.ml]{ext}
633 \DeclareStringOption[\#]{prompt}
634 \DeclareStringOption[ocamlc]{compiler}
635 \DeclareStringOption{compilerflags}
636 \DeclareStringOption[-i]{lastflags}
637 \DeclareStringOption[open]{includecmd}
638 \DeclareStringOption[]{html}
639 \ProcessKeyvalOptions*
640 % \end{macrocode}
641 %
642 % \begin{macro}{\checklistings}
643 % This macro offers another way of setting package options with the
644 % advantage that values are not expanded.
645 % \begin{macrocode}
646 \def\checklistings{\kvsetkeys{CHKL}}
647 % \end{macrocode}
648 % \end{macro}
649 %
650 % \subsection{Logging Files to be Processed}
651 %
652 % Several definitions and commands are used to create and write to the
653 % |.chkl| file.
654 %
655 % \begin{macro}{\CHKL@samplefile}
656 % The file generated when a \LaTeX{} document that uses the |checklistings|
657 % package is processed.
658 % \begin{macrocode}
659 \newwrite\CHKL@samplefile
660 \openout\CHKL@samplefile=\jobname.chkl
661 \AtEndDocument{\closeout\CHKL@samplefile}
662 % \end{macrocode}
663 % \end{macro}
664 %
665 % Package options are logged to the file.
666 % \begin{macrocode}
667 \write\CHKL@samplefile{subdir=\CHKL@subdir/}
668 \write\CHKL@samplefile{prefix=\CHKL@prefix}
669 \write\CHKL@samplefile{ext=\CHKL@ext}
670 \write\CHKL@samplefile{compiler=\CHKL@compiler}
671 \write\CHKL@samplefile{compilerflags=\CHKL@compilerflags}
672 \write\CHKL@samplefile{lastflags=\CHKL@lastflags}
673 \write\CHKL@samplefile{includecmd=\CHKL@includecmd}
674 \write\CHKL@samplefile{htmlfilter=\CHKL@html}
675 % \end{macrocode}
676 %
677 % \begin{macro}{\CHKL@logsample}
678 % An entry is logged for each |chklisting| environment.
679 % It contains the sequence number for the example, followed by a colon, an
680 % ordered list of other sample files to import, and the page and line
681 % numbers (to include in error messages).
682 % \begin{macrocode}
683 \DeclareRobustCommand{\CHKL@logsample}[2]{%
684 \edef\CHKL@tolog{#1:#2 [page=\noexpand\thepage] [line=\the\inputlineno]}%
685 \expandafter\write\expandafter\CHKL@samplefile\expandafter{\CHKL@tolog}%
686 }
687 % \end{macrocode}
688 % \end{macro}
689 %
690 % \subsection{Insertion of Compilation Results}
691 %
692 % Several macros are defined for use by the |checklistings.sh| script (and
693 % any similar program).
694 % These macros are called from within the |.tex| file generated for each
695 % |chklisting| environment.
696 %
697 % \begin{macro}{\ifchklisting}
698 % A successful compilation is signalled by |\chklistingtrue|, and a failed
699 % compilation by |\chklistingfalse|.
700 % \begin{macrocode}
701 \newif\ifchklisting
702 % \end{macrocode}
703 % \end{macro}
704 %
705 % \begin{macro}{\setchklistingcmd}
706 % The command used to compile a sample is recorded by |\setchklistingcmd|
707 % which (re)defines the internal |\CHKL@prompt| value.
708 % \begin{macrocode}
709 \DeclareRobustCommand{\setchklistingcmd}[1]{%
710 \global\def\chklistingcmd{\emph{\CHKL@prompt{#1}}}}
711 % \end{macrocode}
712 % \end{macro}
713
714 % \begin{environment}{ChkListingMsg}
715 % Normal compiler messages (written on |stdout|) should be communicated
716 % between |\begin{ChkListingMsg}| and |\end{ChkListingMsg}|.
717 % This verbatim text is saved using the |SaveVerbatim| feature of
718 % |fancyvrb|.
719 % \begin{macrocode}
720 \def\ChkListingMsg{\FV@Environment{}{ChkListingMsg}}
721 \def\FVB@ChkListingMsg{\FVB@SaveVerbatim{ChkListingMsg}}
722 \let\FVE@ChkListingMsg\FVE@SaveVerbatim
723 \DefineVerbatimEnvironment{ChkListingMsg}{ChkListingMsg}{}
724 % \end{macrocode}
725 % \end{environment}
726
727 % \begin{environment}{ChkListingErr}
728 % Compiler error messages (usually written on |stderr|) should be
729 % communicated between |\begin{ChkListingErr}| and |\end{ChkListingErr}|.
730 % This verbatim text is saved using the |SaveVerbatim| feature of
731 % |fancyvrb|.
732 % \begin{macrocode}
733 \def\ChkListingErr{\FV@Environment{}{ChkListingErr}}
734 \def\FVB@ChkListingErr{\FVB@SaveVerbatim{ChkListingErr}}
735 \let\FVE@ChkListingErr\FVE@SaveVerbatim
736 \DefineVerbatimEnvironment{ChkListingErr}{ChkListingErr}{}
737 % \end{macrocode}
738 % \end{environment}
739
740 % \begin{macro}{\chklistingfile}
741 % This is the filename used by |checklistings.sh| to refer to the file
742 % containing sample code when |\setchklistingcmd| is called.
743 % \begin{macrocode}
744 \DeclareRobustCommand{\chklistingfile}{\CHKL@prefix\CHKL@ext}
745 % \end{macrocode}
746 % \end{macro}
747 %
748 % \subsection{Main Environment}
749 %
750 % Several auxiliary definitions are needed to track per-environment
751 % configuration options.
752 %
753 % \begin{macro}{\ifCHKL@shouldfail}
754 % This boolean variable records whether sample code is expected to fail.
755 % \begin{macrocode}
756 \newif\ifCHKL@shouldfail
757 % \end{macrocode}
758 % \end{macro}
759 %
760 % \begin{macro}{\ifCHKL@showcode}
761 % This boolean variable records whether the compilation result should be
762 % shown.
763 % \begin{macrocode}
764 \newif\ifCHKL@showcode
765 % \end{macrocode}
766 % \end{macro}
767 %
768 % \begin{macro}{\CHKL@skip}
769 % Defines the number of lines to be skipped when displaying a code sample.
770 % It defaults to the value of |\CHKL@pkg@globalskip|, but may be altered by
771 % the environment options |skipone| and |skiptwo|.
772 % This value is only used to generate the |skip=| field in the |.chkl| file.
773 % The actual skipping is done by the |firstline| option of |verbopts|.
774 % \begin{macrocode}
775 \def\CHKL@skip{0}
776 % \end{macrocode}
777 % \end{macro}
778 %
779 % The |keyval| package\footnote{\url{http://www.ctan.org/pkg/keyval}} is
780 % used to parse environment options.
781 % The following macros setup parameters used by the |chklisting|
782 % environment.
783 %
784 % \begin{macro}{\CHKL@continue}
785 % \begin{macro}{\CHKL@precontinue}
786 % These two macros hold lists of source code identifiers:
787 % |\CHKL@precontinue| tracks the dependencies of the previous |chklisting|
788 % environment and |\CHKL@continue| tracks those of the current one.
789 % The |continue| option appends the previous dependencies onto the list of
790 % current ones.
791 % The dependencies used at each labelled environment are remembered in
792 % |\RBRB@deps|\meta{label}.
793 % The |include| option causes them to be added to the list of current
794 % dependencies.
795 %
796 % \begin{macrocode}
797 \edef\CHKL@precontinue{}
798 \define@key{CHKL@envkeys}{continue}[]{\edef\CHKL@continue{\CHKL@precontinue}}
799 \define@key{CHKL@envkeys}{include}{%
800 \edef\CHKL@continue{\CHKL@continue\space\@ifundefined{CHKL@deps@#1}%
801 {#1}{\csname CHKL@deps@#1\endcsname}}}
802 % \end{macrocode}
803 % \end{macro}
804 % \end{macro}
805 %
806 % \begin{macrocode}
807 \define@key{CHKL@envkeys}{fail}[]{\CHKL@shouldfailtrue}
808 \define@key{CHKL@envkeys}{label}{\edef\CHKL@label{#1}}
809 \define@key{CHKL@envkeys}{skipnone}[]{%
810 \edef\CHKL@skip{0}\edef\CHKL@verbopts{\CHKL@verbopts,firstline=1}}
811 \define@key{CHKL@envkeys}{skipone}[]{%
812 \edef\CHKL@skip{1}\edef\CHKL@verbopts{\CHKL@verbopts,firstline=2}}
813 \define@key{CHKL@envkeys}{skiptwo}[]{%
814 \edef\CHKL@skip{2}\edef\CHKL@verbopts{\CHKL@verbopts,firstline=3}}
815 \define@key{CHKL@envkeys}{hide}[]{\CHKL@showcodefalse}
816 \define@key{CHKL@envkeys}{withresult}[]{\CHKL@withresulttrue}
817 \define@key{CHKL@envkeys}{withoutresult}[]{\CHKL@withresultfalse}
818 \define@key{CHKL@envkeys}{showproblems}[]{\CHKL@showproblemstrue}
819 \define@key{CHKL@envkeys}{hideproblems}[]{\CHKL@showproblemsfalse}
820 % \end{macrocode}
821 %
822 % \begin{macro}{\chklistingmsg}
823 % This macro takes a single argument \meta{label}.
824 % It first configures the |listings| and |fancyvrb| packages with the
825 % current display options.
826 % It then checks the |fancyvrb| saved text namespace
827 % (`\texttt{FV@SV@\ldots}') for an entry named `\texttt{\ldots
828 % CHKL@MSG@\meta{label}}'.
829 % If found, the associated verbatim text is inserted via the |\UseVerbatim|
830 % feature of |fancyvrb|, otherwise an error message is inserted.
831 % In the latter case, we prefer not to fail outright, because the user may
832 % not yet have had the chance to run the compiler on the extracted code, in
833 % which case the log will already contain warnings from |chklisting|.
834 % By convention, the |chklisting| environment creates an entry for the
835 % empty label (`\texttt{FV@SV@CHKL@MSG@}') when compilation succeeds.
836 % \begin{macrocode}
837 \DeclareRobustCommand{\chklistingmsg}[1]{
838 \bgroup%
839 \ifx\CHKL@msglst\CHKL@emptyoption\else
840 \expandafter\lstset\expandafter{\CHKL@msglst,fancyvrb=true}\fi%
841 \@ifundefined{FV@SV@CHKL@MSG@#1}
842 {\def\@tempa{#1}
843 \ifx\@tempa\empty
844 \CHKL@none
845 \else
846 $\langle$No message found for the label `#1'!$\rangle$
847 \fi}
848 {\expandafter\UseVerbatim\expandafter[\CHKL@msgstyle]{CHKL@MSG@#1}}%
849 \egroup}
850 % \end{macrocode}
851 % \end{macro}
852 %
853 % \begin{macro}{\chklistingerr}
854 % This macro is essentially the same as the previous one---only that the
855 % substring `\texttt{ERR}' is used instead of `\texttt{MSG}'.
856 % \begin{macrocode}
857 \DeclareRobustCommand{\chklistingerr}[1]{
858 \bgroup%
859 \ifx\CHKL@errlst\CHKL@emptyoption\else
860 \expandafter\lstset\expandafter{\CHKL@errlst,fancyvrb=true}\fi%
861 \@ifundefined{FV@SV@CHKL@ERR@#1}
862 {\def\@tempa{#1}
863 \ifx\@tempa\empty
864 \CHKL@none
865 \else
866 $\langle$No message found for the label `#1'!$\rangle$
867 \fi}
868 {\expandafter\UseVerbatim\expandafter[\CHKL@errstyle]{CHKL@ERR@#1}}%
869 \egroup}
870 % \end{macrocode}
871 % \end{macro}
872 %
873 % \begin{environment}{chklisting}
874 % This is the main environment for including source code.
875 % This macro works in two parts:
876 % \begin{enumerate}
877 % \item
878 % It uses the listings package to write the code to a file,
879 % \item
880 % It either loads the corresponding |.tex| file or logs an error message.
881 % \end{enumerate}
882 %
883 % The |listings| package allows the definition of custom verbatim
884 % environments.
885 % This one has a single argument (a list of |keyval| options).
886 %
887 % \begin{macrocode}
888 \lstnewenvironment{chklisting}[1][]
889 {%
890 % \end{macrocode}
891 % Set default parameter values before invoking |\setkeys|:
892 % \begin{macrocode}
893 \CHKL@shouldfailfalse%
894 \CHKL@showcodetrue%
895 \let\CHKL@label\@undefined%
896 \edef\CHKL@continue{}%
897 \def\CHKL@skip{\CHKL@pkg@globalskip}%
898 \let\CHKL@verbopts\CHKL@pkg@verbopts%
899 \def\@currentlabel{\thechklisting}%
900 \setkeys{CHKL@envkeys}{#1}%
901 % \end{macrocode}
902 %
903 % Log an entry to the |.chkl| file:
904 %
905 % \begin{macrocode}
906 \CHKL@logsample{\arabic{chklisting}}{\CHKL@continue%
907 \space\ifnum\CHKL@skip>0[skip=\CHKL@skip]\fi%
908 \ifCHKL@shouldfail\space[fail]\fi}%
909 % \end{macrocode}
910 %
911 % Update |\CHKL@precontinue| for the next source code block, and, if a label
912 % was defined, add an |\CHKL@deps@|\meta{label} entry.
913 %
914 % \begin{macrocode}
915 \global\edef\CHKL@precontinue{\CHKL@continue\space\arabic{chklisting}}%
916 \@ifundefined{CHKL@label}{}{%
917 \global\expandafter\edef\csname CHKL@deps@\CHKL@label\endcsname{\CHKL@precontinue}}%
918 % \end{macrocode}
919 %
920 % A file will be created in the |\CHKL@subdir| subdirectory, with the name
921 % |\CHKL@prefix| followed by the value of the |chklisting| counter, padded
922 % out with zeroes to four digits, and the extension |\RBRB@ext|.
923 %
924 % \begin{macrocode}
925 \edef\CHKL@num{%
926 \ifnum\value{chklisting}<1000 0\fi
927 \ifnum\value{chklisting}<100 0\fi
928 \ifnum\value{chklisting}<10 0\fi
929 \arabic{chklisting}}%
930 \stepcounter{chklisting}%
931 \def\CHKL@file{\CHKL@subdir/\CHKL@prefix\CHKL@num}%
932 % \end{macrocode}
933 %
934 % Clear the definitions used to return information about the compilation
935 % run, and close the environment by opening a file, using the |listings|
936 % package, into which to write the ensuing contents.
937 %
938 % \begin{macrocode}
939 \global\let\chklistingcmd\@undefined%
940 \global\let\FV@SV@ChkListingMsg\@undefined%
941 \global\let\FV@SV@ChkListingErr\@undefined%
942 \chklistingtrue%
943 \setbox\@tempboxa\hbox\bgroup%
944 \lst@BeginWriteFile{\CHKL@file\CHKL@ext}%
945 }
946 % \end{macrocode}
947 %
948 % Start closing the environment by closing the previously opened file and
949 % group.
950 %
951 % \begin{macrocode}
952 {%
953 \lst@EndWriteFile%
954 \egroup%
955 % \end{macrocode}
956 %
957 % If |hide| is not active, apply |\CHKL@verbopts| and reload the newly
958 % created file.
959 %
960 % \begin{macrocode}
961 \ifCHKL@showcode%
962 \bgroup%
963 \ifx\CHKL@codelst\CHKL@emptyoption\else%
964 \expandafter\lstset\expandafter{\CHKL@codelst,fancyvrb=true}%
965 \fi%
966 \expandafter\fvset\expandafter{\CHKL@verbopts}%
967 \expandafter\VerbatimInput\expandafter[\CHKL@codestyle]{\CHKL@file\CHKL@ext}%
968 \egroup%
969 \fi%
970 % \end{macrocode}
971 %
972 % Check whether a corresponding |.tex| file was created:
973 %
974 % \begin{macrocode}
975 \global\edef\CHKL@none{$\langle$Cannot load \[email protected]!$\rangle$}%
976 \InputIfFileExists{\[email protected]}{\CHKL@fileexiststrue}{\CHKL@fileexistsfalse}%
977 % \end{macrocode}
978 %
979 % If the |.tex| file was loaded successfully, create `unlabelled' saved
980 % verbatim environments for the message and error texts.
981 % These are exploited, respectively, by the |\chklistingmsg| and
982 % |\chklistingerr| macros.
983 %
984 % \begin{macrocode}
985 \ifCHKL@fileexists%
986 \@ifundefined{FV@SV@ChkListingMsg}%
987 {}{\global\let\FV@SV@CHKL@MSG@=\FV@SV@ChkListingMsg}%
988 \@ifundefined{FV@SV@ChkListingErr}%
989 {}{\global\let\FV@SV@CHKL@ERR@=\FV@SV@ChkListingErr}%
990 % \end{macrocode}
991 %
992 % Then, if compilation failed and the |fail| option was not active, or if
993 % compilation succeeded and the |fail| option is active, log a warning
994 % message and, if errors are not being ignored, include details in the
995 % document.
996 % Otherwise, if |withresult| was given, expand either |\chklistingerr| or
997 % |\chklistingmsg|.
998 %
999 % \begin{macrocode}
1000 \ifCHKL@shouldfail%
1001 \ifchklisting%
1002 \PackageWarning{checklistings}%
1003 {Compilation of \CHKL@file\CHKL@ext\space should have failed}%
1004 \ifCHKL@showproblems%
1005 \UseVerbatim[frame=single,
1006 label=Unexpected success,
1007 rulecolor=\color{red}]{ChkListingMsg}%
1008 \fi%
1009 \else%
1010 \ifCHKL@withresult%
1011 {\setlength{\partopsep}{0em}\chklistingerr{}}%
1012 \fi%
1013 \fi%
1014 \else%
1015 \ifchklisting%
1016 \ifCHKL@withresult%
1017 {%\vspace{\dimexpr-2\topsep-2\partopsep+.5em\relax}%
1018 \setlength{\partopsep}{0em}\chklistingmsg{}}%
1019 \fi%
1020 \else%
1021 \PackageWarning{checklistings}%
1022 {Compilation of \CHKL@file\CHKL@ext\space should not have failed}%
1023 \ifCHKL@showproblems%
1024 \UseVerbatim[frame=single,
1025 label=Unexpected failure,
1026 rulecolor=\color{red}]{ChkListingErr}%
1027 \fi%
1028 \fi%
1029 \fi%
1030 \else%
1031 % \end{macrocode}
1032 %
1033 % If the |.tex| file was not loaded successfully, clear the
1034 % |\chklistingcmd| macros, and the `unlabelled' saved verbatim environments
1035 % for the message and error results.
1036 %
1037 % \begin{macrocode}
1038 \PackageWarning{checklistings}{Cannot load \[email protected]}%
1039 \global\let\chklistingcmd\CHKL@none%
1040 \global\let\FV@SV@CHKL@MSG@\@undefined%
1041 \global\let\FV@SV@CHKL@ERR@\@undefined%
1042 \fi%
1043 % If this environment is labelled, create persistent references to the saved
1044 % verbatim environments for the message and error results.
1045 % These are exploited, respectively, by the |\chklistingmsg| and
1046 % |\chklistingerr| macros when their \meta{label} argument is not empty.
1047 %
1048 \@ifundefined{CHKL@label}{}{%
1049 \global\expandafter\let%
1050 \csname FV@SV@CHKL@MSG@\CHKL@label\endcsname=\FV@SV@CHKL@MSG@%
1051 \global\expandafter\let%
1052 \csname FV@SV@CHKL@ERR@\CHKL@label\endcsname=\FV@SV@CHKL@ERR@%
1053 }%
1054 }%
1055 % \end{macrocode}
1056 % \end{environment}
1057 %
1058 \makeatother
1059 \clearpage
1060 % \Finale
1061 \endinput