3
% Trademarks appear throughout this documentation without any trademark
4
% symbol, so you can't assume that a name is free. There is no intention
5
% of infringement; the usage is to the benefit of the trademark owner.
8
% S O F T W A R E L I C E N S E
9
% =================================
11
% The files listings.dtx and listings.ins and all files generated
12
% from only these two files are referred to as `the listings package'
13
% or simply `the package'. A `driver' is generated from lstdrvrs.dtx.
16
% The listings package is copyright 1996--2002 Carsten Heinz.
17
% The language drivers are copyright 1997/1998/1999/2000/2001/2002 any
18
% individual author listed in the driver files.
20
% Distribution and warranty.
21
% The listings package as well as lstdrvrs.dtx and all drivers are
22
% distributed under the terms of the LaTeX Project Public License
23
% from CTAN archives in directory macros/latex/base/lppl.txt.
24
% Either version 1.0 or, at your option, any later version.
27
% The listings package is free software. However, if you distribute the
28
% package as part of a commercial product or if you use the package to
29
% prepare a commercial document (books, journals, and so on), I'd like
30
% to encourage you to make a donation to the LaTeX3 fund. The size of
31
% this `license fee' should depend on the value of the package for your
32
% product. For more information about LaTeX see
33
% http://www.latex-project.org
35
% No matter whether you use the package for a commercial or non-commercial
36
% document, please send me a copy of the document (.dvi, .ps, .pdf,
37
% hardcopy, etc.) to support further development---it is easier to
38
% introduce new features or simplify things if I see how the package is
39
% used by other people.
41
% Modification advice.
42
% Permission is granted to modify the listings package as well as
43
% lstdrvrs.dtx. You are not allowed to distribute a modified version
44
% of the package or lstdrvrs.dtx unless you change the file names and
45
% provide the original files. In any case it is better to contact the
46
% address below; other users will welcome removed bugs, new features,
47
% and additional programming languages.
50
% Send comments and ideas on the package, error reports and additional
51
% programming languages to
62
% end of software license
66
\documentclass[a4paper]{ltxdoc}
74
\DocInput{listings.dtx}
80
%^^A Command/key to aspect relation
81
%^^A ================================
83
%\lstisaspect[strings]{string,morestring,deletestring,stringstyle,showstringspaces}
84
%\lstisaspect[comments]{comment,morecomment,deletecomment,commentstyle}
85
%\lstisaspect[pod]{printpod,podcomment}
86
%\lstisaspect[escape]{texcl,escapebegin,escapeend,escapechar,escapeinside,mathescape}
87
%\lstisaspect[keywords]{sensitive,classoffset,keywords,morekeywords,deletekeywords,keywordstyle,ndkeywords,morendkeywords,deletendkeywords,ndkeywordstyle,keywordsprefix,otherkeywords}
88
%\lstisaspect[emph]{emph,moreemph,deleteemph,emphstyle}
89
%\lstisaspect[tex]{texcs,moretexcs,deletetexcs,texcsstyle}
90
%\lstisaspect[directives]{directives,moredirectives,deletedirectives,directivestyle}
91
%\lstisaspect[html]{keywordsinside,usekeywordsinside}
92
%\lstisaspect[keywordcomments]{keywordcomment,morekeywordcomment,deletekeywordcomment,keywordcommentsemicolon}
93
%\lstisaspect[index]{index,moreindex,deleteindex,indexstyle,\string\lstindexmacro}
94
%\lstisaspect[procnames]{procnamestyle,indexprocnames,procnamekeys,moreprocnamekeys,deleteprocnamekeys}
95
%\lstisaspect[style]{style,\string\lstdefinestyle,\string\lst@definestyle,\string\lststylefiles}
96
%\lstisaspect[language]{language,alsolanguage,defaultdialect,\string\lstalias,\string\lstdefinelanguage,\string\lst@definelanguage,\string\lstloadlanguages,\string\lstlanguagefiles}
97
%\lstisaspect[formats]{format,fmtindent,\string\lstdefineformat,\string\lst@defineformat,\string\lstformatfiles}
98
%\lstisaspect[labels]{numbers,numberstyle,numbersep,stepnumber,numberblanklines,firstnumber,\string\thelstnumber}
99
%\lstisaspect[lineshape]{xleftmargin,xrightmargin,resetmargins,linewidth,lineskip,breaklines,breakindent,breakautoindent,prebreak,postbreak}
100
%\lstisaspect[frames]{framexleftmargin,framexrightmargin,framextopmargin,framexbottommargin,backgroundcolor,fillcolor,rulecolor,rulesepcolor,rulesep,framerule,framesep,frameshape,frameround,frame}
101
%\lstisaspect[make]{makemacrouse}
102
%\lstisaspect[fancyvrb]{fancyvrb}
103
%\lstisaspect[lgrind]{lgrindef,\string\lstlgrindeffile}
104
%\lstisaspect[hyper]{hyperref,morehyperref,deletehyperref,hyperanchor,hyperlink}
105
%\lstisaspect[kernel]{basewidth,fontadjust,columns,flexiblecolumns,identifierstyle,^^A
106
% tabsize,showtabs,tab,showspaces,keepspaces,formfeed,SelectCharTable,^^A
107
% MoreSelectCharTable,extendedchars,alsoletter,alsodigit,alsoother,excludedelims,^^A
108
% literate,basicstyle,print,firstline,lastline,nolol,captionpos,abovecaptionskip,^^A
109
% belowcaptionskip,label,title,caption,\string\lstlistingname,boxpos,float,^^A
110
% floatplacement,aboveskip,belowskip,everydisplay,showlines,emptylines,gobble,name,^^A
111
% \string\lstname,\string\lstlistlistingname,\string\lstlistoflistings,^^A
112
% \string\lstnewenvironment,\string\lstinline,\string\lstinputlisting,lstlisting,^^A
113
% \string\lstloadaspects,\string\lstset,\string\thelstlisting,\string\lstaspectfiles,^^A
114
% inputencoding,delim,moredelim,deletedelim}
115
%\lstisaspect[doc]{lstsample,lstxsample}^^A environment
118
%^^A The long awaited beginning of documentation
119
%^^A =============================================
122
%\setbox\abstractbox=\vbox{
124
% The \packagename{listings} package is a source code printer for \LaTeX.
125
% You can typeset stand alone files as well as listings with an environment
126
% similar to \texttt{verbatim} as well as you can print code snippets using
127
% a command similar to |\verb|.
128
% Many parameters control the output and if your preferred programming
129
% language isn't already supported, you can make your own definition.
132
% \title{\vspace*{-2\baselineskip}The \textsf{Listings} Package}
133
% \author{Copyright 1996--2002\\ Carsten Heinz \textless\lstemail\textgreater}
134
% \date{2002/04/01\footnote{Documentation revised 2002/10/13: table
135
% \ref{uPredefinedLanguages} of predefined languages and credits in
136
% section \ref{uClosingAndCredits} have been updated. Patch file 1.0\,i
137
% of same date includes several bug-fixes.}^^A
138
% \enspace\enspace Version 1.0\\ \box\abstractbox}
139
% \def\lstemail{\href{mailto:cheinz@gmx.de}{\texttt{cheinz@gmx.de}}}
141
% \hypersetup{pdfsubject=Package guide,pdfauthor=Carsten Heinz <cheinz@gmx.de>}
144
% \csname @twocolumntrue\endcsname
146
%^^A \enlargethispage{2\baselineskip}
147
% \csname @starttoc\endcsname{toc}
153
% \paragraph{Reading this manual}
154
% If you are experienced with the \packagename{listings} package, you should
155
% read the paragraph ``\emph{News and changes}'' below. Otherwise read section
156
% \lstref{uGettingStarted} step by step and then go on with
157
% section \ref{uTheNextSteps}.
159
% \paragraph{News and changes}
160
% This is the first release of the package with a major version number unequal
161
% to zero. And many changes have been made since version 0.21.
162
% One main task was to synchronize the keys of \packagename{listings} and
163
% \packagename{fancyvrb}. So user's of both packages can switch between them
164
% without learning new keys---as long as the same functionality is provided.
165
% The table lists (hopefully) all renamed keys and all removed keys.
169
% \begin{tabular}{rlrl}
170
% \emph{0.21}&\emph{now}&\emph{0.21}&\emph{now}\\[1ex]
171
% \texttt{first} & \texttt{firstline} & --- & \texttt{numbers}\\
172
% \texttt{last} & \texttt{lastline} & \texttt{labelstep} & \texttt{stepnumber}\\
173
% \texttt{stringspaces} & \texttt{showstringspaces} & \texttt{labelstyle} & \texttt{numberstyle}\\
174
% \texttt{visiblespaces} & \texttt{showspaces} & \cs{thelstlabel} & \cs{thelstnumber}\\
175
% \texttt{visibletabs} & \texttt{showtabs} & \texttt{labelsep} & \texttt{numbersep}\\
176
% \texttt{framerulewidth} & \texttt{framerule} & \texttt{firstlabel} & \texttt{firstnumber}\\
177
% \texttt{framerulesep} & \texttt{rulesep} & \texttt{advancelabel} & ---\\
178
% \texttt{frametextsep} & \texttt{framesep} & \texttt{spread} & ---\\
179
% \texttt{framespread} & superceded by & \texttt{indent} & \texttt{xleftmargin}$^3$\\
180
% & \texttt{framexleftmargin} & --- & \texttt{xrightmargin}\\
181
% & \texttt{framexrightmargin} & \texttt{wholeline} & \texttt{resetmargins}\\
182
% & \texttt{framextopmargin} & \texttt{defaultclass} & \texttt{classoffset}\\
183
% & \texttt{framexbottommargin} & \texttt{stringtest} & ---\\
184
% \texttt{framerulecolor} & \texttt{rulecolor}$^1$ & \texttt{outputpos} & ---\\
185
% --- & \texttt{columns}$^2$
188
% \parindent=20pt\relax
189
% \par\indent $^1$ \emph{All} color-keys require now an explicit \cs{color} command in the value.
190
% \par\indent $^2$ Please look at section \ref{uFixedAndFlexibleColumns}.
191
% \par\indent $^3$ Now frames are also moved!
193
% As stated in the footnote, some keys changed their behaviour, for example
194
% you will have to write \keyname{backgroundcolor}|=\color|\marg{color}
195
% instead of omitting the color command as in version 0.21. Another
196
% modification is that the name argument of \texttt{lstlisting} has been
197
% replaced by the key \keyname{name} and an addon to \keyname{firstnumber}.
198
% But don't panic, you don't need to remove all empty name arguments in your
199
% old sources, the argument is still allowed.
201
% The package documentation has also been revised. Please notice the new
202
% sections \ref{uLanguageDefinitions} and \ref{uDelimiters}.
204
% Eventually note that all experimental features and all \dag-marked keys might
205
% change in future. All others are fixed!
208
% There are many people I have to thank for fruitful communication, posting
209
% their ideas, giving error reports, adding programming languages to
210
% \texttt{lstdrvrs.dtx}, and so on. Their names are listed in section
211
% \ref{uClosingAndCredits}.
214
% \paragraph{Trademarks}
215
% Trademarks appear throughout this documentation without any trademark
216
% symbol; they are the property of their respective trademark owner.
217
% There is no intention of infringement; the usage is to the benefit of the
224
% \part{User's guide}
227
% \section{Getting started}\label{uGettingStarted}
230
% \subsection{A minimal file}\label{uAMinimalFile}
232
% Before using the \packagename{listings} package, you should be familiar with
233
% the \LaTeX\ typesetting system. You need not to be an expert.
234
% Here is a minimal file for \packagename{listings}.
236
% \documentclass{article}
237
% \usepackage{listings}
239
% \lstset{language=Pascal}
240
% % Insert Pascal examples here.
241
% \end{document}\end{verbatim}
242
% Now type in this first example and run it through \LaTeX.
244
% \item Must I do that really?
246
% Yes and no. Some books about programming say this is good.
247
% What a mistake! Typing takes time---wasted if the code is clear to
248
% you. And if you need that time to understand what is going on, the
249
% author of the book should reconsider the concept of presenting the
250
% crucial things---you might want to say that about this guide even---or
251
% you're simply unexperienced with programming. If only the latter case
252
% applies, you should spend more time on reading (good) books about
253
% programming, (good) documentations, and (good) source code from other
254
% people. Of course you should also make your own experiments.
255
% You will learn a lot. However, running the example through \LaTeX\
256
% shows whether the \packagename{listings} package is installed.
257
% \item The example doesn't work.
259
% Are the two packages \packagename{listings} and \packagename{keyval}
260
% installed on your system? Read section \ref{rInstallation} on the
261
% installation process. If this doesn't help, you should consult your
262
% system administrator, the local \TeX\ and \LaTeX\ guides, or a \TeX\
263
% FAQ. And after you checked \emph{all} these sources, you might want to
264
% write a post to a \TeX\ newsgroup like \texttt{comp.text.tex}.
265
% \item Should I read the software license before using this package?
267
% Yes, but read this \emph{Getting started} section first to decide
268
% whether you are willing to use the package.^^A ;-)
272
% \subsection{Typesetting listings}
274
% Three types of source codes are supported: code snippets, code segments, and
275
% listings of stand alone files; the first inside paragraphs and the others as
276
% separate paragraphs---the difference is the same as between text style and
277
% display style formulas.
279
% \item No matter what kind of source you have, if a listing contains national
280
% characters like \'e, \L, \"a, or whatever, you must tell it the
281
% package! Section \lstref{uSpecialCharacters} discusses this issue.
284
% \paragraph{Code snippets}
285
% The well-known \LaTeX\ command |\verb| typesets code snippets verbatim.
286
% The new command |\lstinline| pretty-prints the code, for example
287
%`\lstinline!var i:integer;!' is typeset by
288
%`{\rstyle|\lstinline|}|!var i:integer;!|'. The exclamation marks delimit
289
% the code and can be replaced by any character not in the code;
290
% |\lstinline$var i:integer;$| gives the same result.
292
% \paragraph{Displayed code}
293
% The \texttt{lstlisting} environment typesets the enclosed source code. Like
294
% most examples, the following one shows verbatim \LaTeX\ code on the right
295
% and the result on the left. You might take the right-hand side, put it into
296
% the minimal file, and run it through \LaTeX.
297
% \begin{lstsample}[lstlisting]{}{}
299
% for i:=maxint to 0 do
304
% Write('Case insensitive ');
305
% WritE('Pascal keywords.');
308
% It can't be easier.
310
% \item That's not true. The name `\texttt{listing}' is shorter.
312
% Indeed. But other packages already define environments with that name.
313
% To be compatible with such packages, all commands and environments of
314
% the \packagename{listings} package use the prefix `\texttt{lst}'.
316
% The environment provides an optional argument. It tells the package to
317
% perform special tasks, for example, to print only the lines 2--5:
318
% \begin{lstsample}{\lstset{frame=trbl,framesep=0pt}\label{gFirstKey=ValueList}}{}
319
% \begin{lstlisting}[firstline=2,
321
% for i:=maxint to 0 do
326
% Write('Case insensitive ');
327
% WritE('Pascal keywords.');
331
% \item Hold on! I've several questions.
332
% Where comes the frame from and what is it good for?
334
% You can put frames around all listings except code snippets.
335
% You will learn it later. The frame shows that empty lines at the end
336
% of listings aren't printed. This is line 5 in the example.
337
% \item Hey, you can't drop my empty lines!
339
% You can tell the package not to drop them:
340
% The key `\ikeyname{showlines}' controls these empty lines and is
341
% described in section \ref{rTypesettingListings}. Warning: First
342
% read ahead on how to use keys in general.
343
% \item I get obscure error messages when using `\ikeyname{firstline}'.
345
% That shouldn't happen. Make a bug report as described in section
346
% \lstref{uTroubleshooting}.
349
% \paragraph{Stand alone files}
350
% Finally we come to |\lstinputlisting|, the command to pretty-print stand
351
% alone files. It has one optional and one file name argument.
352
% Note that you possibly need to specify the relative path to the file.
353
% Here now the result is printed below the verbatim code since both together
354
% don't fit the text width.
355
% \begin{lstsample}{\lstset{comment=[l]\%,columns=fullflexible}}{\lstset{alsoletter=\\,emph=\\lstinputlisting,emphstyle=\rstyle}\lstaspectindex{\lstinputlisting}{}}
356
% \lstinputlisting[lastline=4]{listings.sty}
359
% \item The spacing is different in this example.
361
% Yes. The two previous examples have aligned columns, i.e.~columns with
362
% identical numbers have the same horizontal position---this package
363
% makes small adjustments only. The columns in the example here are not
364
% aligned. This is explained elsewhere (keyword: full flexible column
368
% Now you know all pretty-printing commands and environments. It remains
369
% to learn the parameters which control the work of the \packagename{listings}
370
% package. This is, however, the main task. Here are some of them.
373
% \subsection{Figure out the appearance}\label{gFigureOutTheAppearance}
375
% Keywords are typeset bold, comments in italic shape, and spaces in strings
376
% appear as \textvisiblespace. You don't like these settings? Look at this:
378
% \begin{lstxsample}[basicstyle,keywordstyle,identifierstyle,commentstyle,stringstyle,showstringspaces]
379
% \lstset{% general command to set parameter(s)
380
% basicstyle=\small, % print whole listing small
381
% keywordstyle=\color{black}\bfseries\underbar,
382
% % underlined bold black keywords
383
% identifierstyle=, % nothing happens
384
% commentstyle=\color{white}, % white comments
385
% stringstyle=\ttfamily, % typewriter type for strings
386
% showstringspaces=false} % no special string spaces
389
% \begin{lstxsample}[basicstyle,keywordstyle,identifierstyle,commentstyle,stringstyle,showstringspaces]
390
% \lstset{% general command to set parameter(s)
391
% basicstyle=\small, % print whole listing small
392
% keywordstyle=\bfseries\underbar,
393
% % underlined bold keywords
394
% identifierstyle=, % nothing happens
395
% commentstyle=\itshape, % default
396
% stringstyle=\ttfamily, % typewriter type for strings
397
% showstringspaces=false} % no special string spaces
400
% \begin{lstsample}{}{}
402
% for i:=maxint to 0 do
407
% Write('Case insensitive ');
408
% WritE('Pascal keywords.');
413
% \item You've requested white coloured comments, but I can see the comment
416
% There are a couple of possible reasons:
417
% (1) You've printed the documentation on nonwhite paper.
418
% (2) If you are viewing this documentation as a \texttt{.dvi}-file, your
419
% viewer seems to have problems with colour specials. Try to print
420
% the page on white paper.
421
% (3) If a printout on white paper shows the comment, the colour
422
% specials aren't suitable for your printer or printer driver.
423
% Recreate the documentation and try it again---and ensure that
424
% the \packagename{color} package is well-configured.
427
% The styles use two different kinds of commands. |\ttfamily| and |\bfseries|
428
% both take no arguments but |\underbar| does; it underlines the following
429
% argument. In general, the \emph{very last} command might read exactly one
430
% argument, namely some material the package typesets. There's one exception.
431
% The last command of \ikeyname{basicstyle} \emph{must not} read any
432
% tokens---or you will get deep in trouble.
434
% \item `|basicstyle=\small|' looks fine, but comments look really bad with
435
% `|commentstyle=\tiny|' and empty basic style, say.
437
% Don't change the font size inside listings.
438
% \item But I really want it!
440
% The package adjusts internal data after selecting the basic style at
441
% the beginning of each listing. This is a problem if you change the
442
% font size for comments or strings, for example.
443
% Section \ref{rColumnAlignment} shows how to overcome this.
444
% But once again: Don't change the font size inside listings unless you
445
% really know what you are doing.
448
% \paragraph{Warning}\label{wStrikingStyles}
449
% You should be very careful with striking styles; the last example is rather
450
% moderate---it can get horrible. \emph{Always use decent highlighting.}
451
% Unfortunately it is difficult to give more recommendations since they depend
452
% on the type of document you're creating. Slides or other presentations often
453
% require more striking styles than books, for example.
454
% In the end, it's \emph{you} who have to find the golden mean!
457
% \subsection{Seduce to use}\label{gSeduceToUse}
459
% You know all pretty-printing commands and some main parameters. Here now
460
% comes a small and incomplete overview of other features. The table of
461
% contents and the index also provide information.
463
% \paragraph{Line numbers}
464
% are available for all displayed listings, e.g.~tiny numbers on the left, each
465
% second line, with 5pt distance to the listing:
466
% \begin{lstxsample}[numbers,numberstyle,stepnumber,numbersep]
467
% \lstset{numbers=left, numberstyle=\tiny, stepnumber=2, numbersep=5pt}
469
% \begin{lstsample}{}{}
471
% for i:=maxint to 0 do
476
% Write('Case insensitive ');
477
% WritE('Pascal keywords.');
481
% \item I can't get rid of line numbers in subsequent listings.
483
% `|numbers=none|' turns them off.
484
% \item Can I use these parameters in the optional arguments?
486
% Of course. Note that optional arguments modify values for one
487
% particular listing only: you change the appearance, step or distance
488
% of line numbers for a single listing. The previous values are
489
% restored afterwards.
491
% The environment allows you to interrupt your listings: you can end a listing
492
% and continue it later with the correct line number even if there are other
493
% listings in between. Read section \ref{uLineNumbers} for a thorough
496
% \paragraph{Floating listings}
497
% Displayed listings may float:
498
% \begin{lstsample}{\lstset{frame=tb}}{}
499
% \begin{lstlisting}[float,caption=A floating example]
500
% for i:=maxint to 0 do
505
% Write('Case insensitive ');
506
% WritE('Pascal keywords.');
509
% Don't care about the parameter \ikeyname{caption} now. And if you put the
510
% example into the minimal file and run it through \LaTeX, please don't wonder:
511
% you'll miss the horizontal rules since they are described elsewhere.
513
% \item \LaTeX's float mechanism allows to determine the placement of floats.
516
% You can write `|float=tp|', for example.
519
% \paragraph{Other features}
520
% There are still features not mentioned so far: automatic breaking of long
521
% lines, the possibility to use \LaTeX\ code in listings, automated indexing,
522
% or personal language definitions.
523
% One more little teaser? Here you are. But note that the result is not
524
% produced by the \LaTeX\ code on the right alone. The main parameter is
526
% \begin{lstsample}{\lstset{literate={:=}{{$\gets$}}1 {<=}{{$\leq$}}1 {>=}{{$\geq$}}1 {<>}{{$\neq$}}1}}{}
528
% if (i<=0) then i := 1;
529
% if (i>=0) then i := 0;
530
% if (i<>0) then i := 0;
534
% You're not sure whether you should use \packagename{listings}?
535
% Read the next section!
538
% \subsection{Alternatives}
541
% \item Why do you list alternatives?
543
% Well, it's always good to know the competitors.^^A :-)
544
% \item I've read the descriptions below and the \packagename{listings} package
545
% seems to incorporate all the features. Why should I use one of the
548
% Firstly, the descriptions give a taste and not a complete overview,
549
% secondly, \packagename{listings} lacks some properties, and eventually,
550
% you should use the program matching your needs most precisely.
552
% This package is certainly not the final utility for typesetting source code.
553
% Other programs do their job very well---if you are not satisfied with
554
% \packagename{listings}. Some are independent of \LaTeX, other come as
555
% separate program plus \LaTeX\ package, and other more are packages which
556
% don't pretty-print the source code. The second type inlcudes converters,
557
% cross compilers, and preprocessors. Such programs create \LaTeX\ files
558
% you can use in your document or stand alone ready-to-run \LaTeX\ files.
560
% Note that I'm not dealing with any literate programming tool here, which
561
% could also be an alternative. However, you should have heard of the
562
% \texttt{WEB} system, the tool Prof.~Donald E.~Knuth developed and made use
563
% of to document and implement \TeX.
565
% \paragraph{\packagename{a2ps}}
566
% started as `ASCII to PostScript' converter, but today you can invoke the
567
% program with \texttt{--pretty-print=}\meta{language} option. If your
568
% favourite programming language is not already supported, you can write your
569
% own so-called style sheet. You can request line numbers, borders, headers,
570
% multiple pages per sheet, and many more. You can even print symbols like
571
% $\forall$ or $\alpha$ instead of their verbose forms. If you just want
572
% program listings and not a document with some listings, this is the best
575
% Visit the home page at
576
% \href{http://www.infres.enst.fr/~demaille/a2ps}^^A
577
% {http://www.infres.enst.fr/\textasciitilde demaille/a2ps}.
579
% \paragraph{\packagename{cvt2ltx}}
580
% is a family of `source code to \LaTeX' converters for C, Objective C, \Cpp,
581
% IDL and Perl. Different styles, line numbers and other qualifiers can be
582
% chosen by command-line option. Unfortunately it isn't documented how other
583
% programming languages can be added.
585
% Available via ftp from
586
% \href{ftp://axp3.sv.fh-mannheim.de/cvt2latex}^^A
587
% {ftp://axp3.sv.fh-mannheim.de/cvt2latex}.
589
% \paragraph{\packagename{\Cpp2\LaTeX}}
590
% is a C/\Cpp\ to \LaTeX\ converter. You can specify the fonts for comments,
591
% directives, keywords, and strings, or the size of a tabulator. But as far as
592
% I know you can't number lines.
594
% Available via ftp from
595
% \href{ftp://ftp.dante.de/tex-archive/support/C++2LaTeX-1_1pl1}^^A
596
% {\textrm{CTAN}/support/C++2LaTeX-1\textunderscore 1pl1}.
598
% \paragraph{\packagename{S\LaTeX}}
599
% is a pretty-printing Scheme program (invokes \LaTeX\ automatically)
600
% especially designed for Scheme and other Lisp dialects. It supports stand
601
% alone files, text and display listings, and you can even nest the
602
% commands/environments if you use \LaTeX\ code in comments, for example.
603
% Keywords, constants, variables, and symbols are definable and use of
604
% different styles is possible. No line numbers.
606
% Available via ftp from
607
% \href{ftp://ftp.dante.de/tex-archive/support/slatex}^^A
608
% {\textrm{CTAN}/support/slatex}.
610
% \paragraph{\packagename{tiny\textunderscore c2ltx}}
611
% is a C/\Cpp/Java to \LaTeX\ converter based on \packagename{cvt2ltx} (or the
612
% other way round?). It supports line numbers, block comments, \LaTeX\ code
613
% in/as comments, and smart line breaking. Font selection and tabulators are
614
% hard-coded, i.e.~you have to rebuild the program if you want to change the
617
% Available via ftp from
618
% \href{ftp://ftp.dante.de/tex-archive/support/tiny_c2l}^^A
619
% {\textrm{CTAN}/support/tiny\textunderscore c2l}.
621
% \paragraph{\packagename{listing}}
622
% ---note the missing \packagename{s}---is not a pretty-printer and the
623
% aphorism about documentation at the end of \texttt{listing.sty} is not
624
% true.\space ^^A :-)
625
% It defines |\listoflistings| and a nonfloating environment for listings.
626
% All font selection and indention must be done by hand. However, it's
627
% useful if you have another tool doing that work, e.g.~\packagename{LGrind}.
629
% Available via ftp from
630
% \href{ftp://ftp.dante.de/tex-archive/macros/latex/contrib/other/misc}^^A
631
% {\textrm{CTAN}/macros/latex/contrib/other/misc}.
634
% \item Why don't you list \packagename{LGrind}?
636
% \packagename{LGrind} contains nonfree code and became nonfree software.
637
% It is a cross compiler and comes with many predefined programming
638
% languages. It supports code snippets, displayed listings, line numbers
639
% to the left or right, arbitrary \LaTeX\ code in the source code,
640
% printing symbols instead of verbose names, font setup, and more.
641
% It is available via ftp from
642
% \href{ftp://ftp.dante.de/tex-archive/nonfree/support/lgrind}
643
% {\textrm{CTAN}/nonfree/support/lgrind}.
646
% \paragraph{\packagename{alg}}
647
% provides essentially the same functionality as \packagename{algorithms}.
648
% So read the next paragraph and note that the syntax will be different.
650
% Available via ftp from
651
% \href{ftp://ftp.dante.de/tex-archive/macros/latex/contrib/other/alg}^^A
652
% {\textrm{CTAN}/macros/latex/contrib/other/alg}.
654
% \paragraph{\packagename{algorithms}}
655
% goes a quite different way. You describe an algorithm and the package
656
% formats it, for example
658
% \begin{minipage}{0.45\linewidth}
660
% \begin{algorithmic}
663
% \ELSE\IF {$i\geq0$}
668
% \packagename{algorithms} not installed.
671
% \begin{minipage}{0.45\linewidth}
679
%\end{algorithmic}\end{verbatim}
682
% As this example shows, you get a good looking algorithm even from a bad
683
% looking input. The package provides a lot more constructs like |for|-loops,
684
% |while|-loops, or comments. You can request line numbers, `ruled', `boxed'
685
% and floating algorithms, a list of algorithms, and you can customize the
686
% terms \textbf{if}, \textbf{then}, and so on.
689
% \href{ftp://ftp.dante.de/tex-archive/macros/latex/contrib/supported/algorithms}^^A
690
% {\textrm{CTAN}/macros/latex/contrib/supported/algorithms}.
692
% \paragraph{\packagename{pretprin}}
693
% is a package for pretty-printing texts in formal languages---as the title
694
% in TUGboat, Volume 19 (1998), No.~3 states. It provides environments which
695
% pretty-print \emph{and} format the source code. Analyzers for Pascal and
696
% Prolog are defined; adding other languages is easy---if you are or get a bit
697
% familiar with automatons and formal languages.
700
% \href{http://www.mimuw.edu.pl/~wolinski/pretprin.html}^^A
701
% {http://www.mimuw.edu.pl/\textasciitilde wolinski/pretprin.html}.
703
% \paragraph{\packagename{alltt}}
704
% defines an environment similar to \texttt{verbatim} except that |\|, |{| and
705
% |}| have their usual meanings. This means that you can use commands in the
706
% verbatims, e.g.~select different fonts or enter math mode.
708
% This package is part of the \LaTeX\ base distribution.
710
% \paragraph{\packagename{moreverb}}
711
% requires \packagename{verbatim} and provides verbatim output to a file,
712
% `boxed' verbatims and line numbers.
714
% Available via ftp from
715
% \href{ftp://ftp.dante.de/tex-archive/macros/latex/contrib/supported/moreverb}^^A
716
% {\textrm{CTAN}/macros/latex/contrib/supported/moreverb}.
718
% \paragraph{\packagename{verbatim}}
719
% defines an improved version of the standard \texttt{verbatim} environment and
720
% a command to input files verbatim.
722
% Available via ftp from
723
% \href{ftp://ftp.dante.de/tex-archive/macros/latex/required/tools}^^A
724
% {\textrm{CTAN}/macros/latex/required/tools}.
726
% \paragraph{\packagename{fancyvrb}}
727
% is, roughly spoken, a super set of \packagename{alltt},
728
% \packagename{moreverb}, and \packagename{verbatim}, but many more parameters
729
% control the output. The package provides frames, line numbers on the left or
730
% on the right, automatic line breaking (difficult), and more. For example, an
731
% interface to \packagename{listings} exists, i.e.~you can pretty-print source
732
% code automatically.
733
% The package \packagename{fvrb-ex} builds above \packagename{fancyvrb} and
734
% defines environments to present examples similar to the ones in this guide.
736
% Available via ftp from
737
% \href{ftp://ftp.dante.de/tex-archive/macros/latex/contrib/supported/fancyvrb}^^A
738
% {\textrm{CTAN}/macros/latex/contrib/supported/fancyvrb}.
741
% \section{The next steps}\label{uTheNextSteps}
743
% Now, before actually using the \packagename{listings} package, you should
744
% \emph{really} read the software license. It does not cost much time and
745
% provides information you probably need to know.
748
% \subsection{Software license}\label{uSoftwareLicense}
750
% The files \texttt{listings.dtx} and \texttt{listings.ins} and all
751
% files generated from only these two files are referred to as `the
752
% \packagename{listings} package' or simply `the package'. A `driver'
753
% is generated from \texttt{lstdrvrs.dtx}.
755
% \paragraph{Copyright}
756
% The \packagename{listings} package is copyright 1996--2002 Carsten Heinz.
757
% The drivers are copyright 1997/1998/1999/2000/2001/2002 any individual
758
% author listed in the driver files.
760
% \paragraph{Distribution and warranty}
761
% The \packagename{listings} package as well as \texttt{lstdrvrs.dtx} and all
762
% drivers are distributed under the terms of the \LaTeX\ Project Public
763
% License from CTAN archives in directory |macros/latex/base/lppl.txt|,
764
% either version 1.0 or any later version.
766
% \paragraph{Use of the package}
767
% The \packagename{listings} package is \emph{free} software. However, if you
768
% distribute the package as part of a commercial product or if you use the
769
% package to prepare a commercial document (books, journals, and so on),
770
% I'd like to encourage you to make a donation to the \LaTeX3 fund.
771
% The size of this `license fee' should depend on the value of the package
772
% for your product. For more information about \LaTeX3 see
773
% \href{http://www.latex-project.org}^^A
774
% {http://www.latex-project.org}.
776
% No matter whether you use the package for a commercial or non-commercial
777
% document, please send me a copy of the document (\texttt{.dvi},
778
% \texttt{.ps}, \texttt{.pdf}, hardcopy, etc.) to support further
779
% development---it is easier to introduce new features or simplify things
780
% if I see how the package is used by other people.
782
% \paragraph{Modification advice}
783
% Permission is granted to modify the \packagename{listings} package as well
784
% as \texttt{lstdrvrs.dtx}. You are not allowed to distribute a modified
785
% version of the \packagename{listings} package or \texttt{lstdrvrs.dtx}
786
% unless you change the file names \emph{and} provide the original files.
787
% In any case it is better to contact the address below; other users will
788
% welcome removed bugs, new features, and additional programming languages.
790
% \paragraph{Contacts}
791
% Read section \lstref{uTroubleshooting} on how to submit a bug report.
792
% Send all other comments, ideas, and additional programming languages to
793
% \emph{Carsten Heinz, Tellweg 6, 42275 Wuppertal, Germany} or preferably to
794
% \lstemail\ using \texttt{listings} in the subject.
796
% \paragraph{Mailing list}
797
% This is mainly an announcement list regarding new versions, bugs, patches,
798
% and work-arounds. So I recommend it for system administrators, maintainers
799
% of \LaTeX\ installations, or people who absolutely need the latest bugs.
800
% To join the list, send an email to \lstemail\ with subject
801
% \texttt{subscribe listings}.
804
% \subsection{Package loading}\label{uPackageLoading}
806
% As usual in \LaTeX, the package is loaded by
807
% |\usepackage[|\meta{options}|]{listings}|,
808
% where |[|\meta{options}|]| is optional and gives a comma separated list of
809
% options. Each either loads an additional \packagename{listings} aspect, or
810
% changes default properties. Usually you don't have to take care of such
811
% options. But in some cases it could be necessary: if you want to compile
812
% documents created with an earlier version of this package or if you use
813
% special features. Here's an incomplete list of possible options.
815
% \item Where is a list of all options?
817
% In the developer's guide since they were introduced to debug the
818
% package more easily. Read section \ref{uHowTos} on how to get that
821
% \begin{description}
822
% \item[\normalfont\texttt{0.21}]\leavevmode
824
% compiles a document created with version 0.21.
826
% \item[\normalfont\texttt{draft}]\leavevmode
828
% The package prints no stand alone files, but shows the captions and
829
% defines the corresponding labels.
830
% Note that a global |\documentclass|-option \texttt{draft} is
831
% recognized, so you don't need to repeat it as a package option.
833
% \item[\normalfont\texttt{savemem}]\leavevmode
835
% tries to save some of \TeX's memory. If you switch between languages
836
% often, it could also reduce compile time. But all this depends on the
837
% particular document and its listings.
839
% Note that various experimental features also need explicit loading via
840
% options. Read the respective lines in section \ref{rExperimentalFeatures}.
843
% After package loading it is recommend to load all used dialects of programming
844
% languages with the following command. It is faster to load several languages
845
% with one command than loading each language on demand.
847
% \item {\rstyle\icmdname\lstloadlanguages}\marg{comma separated list of languages}
849
% Each language is of the form \oarg{dialect}\meta{language}. Without
850
% the optional \oarg{dialect} the package loads a default dialect. So
851
% write `|[Visual]C++|' if you want Visual \Cpp\ and `|[ISO]C++|' for
852
% ISO \Cpp. Both together can be loaded by the command
853
% |\lstloadlanguages{[Visual]C++,[ISO]C++}|.
855
% Table \ref{uPredefinedLanguages} on page \pageref{uPredefinedLanguages}
856
% shows all defined languages and their dialects.
858
%^^A After or even before language loading, you might want to define default
859
%^^A dialects---just to be independent of configuration files.
862
% \subsection{The key=value interface}\label{uTheKey=ValueInterface}
864
% This package uses the \packagename{keyval} package from the
865
% \packagename{graphics} bundle by David Carlisle. Each parameter is
866
% controlled by an associated key and a user supplied value. For example,
867
% \ikeyname{firstline} is a key and |2| a valid value for this key.
869
% The command {\rstyle\icmdname\lstset} gets a comma separated list of
870
% ``key|=|value'' pairs. The first list with more than a single entry is on
871
% page \pageref{gFirstKey=ValueList}: |firstline=2,lastline=5|.
873
% \item So I can write `|\lstset{firstline=2,lastline=5}|' once for all?
875
% No. `\ikeyname{firstline}' and `\ikeyname{lastline}' belong to a small
877
% keys which are used on individual listings. However, your command is
878
% not illegal---it has no effect. You have to use these keys inside the
879
% optional argument of the environment or input command.
880
% \item What's about a better example of a key|=|value list?
882
% There is one in section \ref{gFigureOutTheAppearance}.
883
% \item `|language=[77]Fortran|' does not work inside an optional argument.
885
% You must put braces around the value if a value with optional argument
886
% is used inside an optional argument. In the case here write
887
% `|language={[77]Fortran}|' to select Fortran 77.
888
% \item If I use the `\ikeyname{language}' key inside an optional argument, the
889
% language isn't active when I typeset the next listing.
891
% All parameters set via `|\lstset|' keep their values up to the end of
892
% the current environment or group. Afterwards the previous values are
893
% restored. The optional parameters of the two pretty-printing commands
894
% and the `\texttt{lstlisting}' environment take effect on the particular
895
% listing only, i.e.~values are restored immediately. For example, you
896
% can select a main language and change it for special listings.
897
% \item \icmdname\lstinline\ has an optional argument?
899
% Yes. And from this fact comes a limitation: you can't use the left
900
% bracket `|[|' as delimiter except you specify at least an empty
901
% optional argument as in `|\lstinline[][var i:integer;[|'.
902
% If you forget this, you will either get a ``runaway argument'' error
903
% from \TeX, or an error message from the \packagename{keyval} package.
907
% \subsection{Programming languages}\label{uProgrammingLanguages}
909
% You already know how to activate programming languages---at least Pascal.
910
% An optional parameter selects particular dialects of a language. For example,
911
% |language=[77]Fortran| selects Fortran 77 and |language=[XSC]Pascal| does the
912
% same for Pascal XSC. The general form is
913
% {\rstyle\ikeyname{language}}|=|\oarg{dialect}\meta{language}.
914
% If you want to get rid of keyword, comment, and string detection, use
915
% |language={}| as argument to |\lstset| or as optional argument.
917
% Table \ref{uPredefinedLanguages} shows all predefined languages and dialects.
918
% Use the listed names as \meta{language} and \meta{dialect}, respectively. If
919
% no dialect or `empty' is given in the table, just don't specify a dialect.
920
% Each underlined dialect is default; it is selected if you leave out
921
% the optional argument. The predefined defaults are the newest language
922
% versions or standard dialects.
924
%^^A Make table of predefined languages.
926
%\let\lstlanguages\empty
928
%\@for\lst@temp:={lstlang1.sty,lstlang2.sty,lstlang3.sty}\do
929
% {\IfFileExists\lst@temp{}{\let\lstlanguages\relax}}
931
%\ifx\lstlanguages\relax
932
% \PackageWarningNoLine{Listings}
933
% {Standard drivers not available.\MessageBreak
934
% Please check your installation.\MessageBreak
935
% Compilation aborted}
936
% \csname @@end\expandafter\endcsname
938
%\lstscanlanguages\lstlanguages{lstlang1.sty,lstlang2.sty,lstlang3.sty}{}^^A
939
%\def\topfigrule{\hrule\kern-0.4pt\relax}^^A
940
%\let\botfigrule\topfigrule
941
%\belowcaptionskip=\smallskipamount
944
% \caption{Predefined languages.
945
% Note that some definitions are preliminary, for example HTML and XML.
946
% Each underlined dialect is default dialect}\label{uPredefinedLanguages}^^A
948
% \setbox\@tempboxa\hbox{^^A
949
% \InputIfFileExists{listings.cfg}{\lst@InputCatcodes}{}}^^A
950
% \lstprintlanguages\lstlanguages
955
%\lstset{defaultdialect=[doc]Pascal}^^A restore
957
% \item How can I define default dialects?
959
% Check section \ref{rLanguagesAndStyles} for `\keyname{defaultdialect}'.
960
% \item I have C code mixed with assembler lines. Can \packagename{listings}
961
% pretty-print such source code, i.e.~highlight keywords and comments of
964
% `\ikeyname{alsolanguage}|=|\oarg{dialect}\meta{language}' selects a
965
% language additionally to the active one. So you only have to write a
966
% language definition for your assembler dialect, which doesn't interfere
967
% with the definition of C, say. Moreover you might want to use the key
968
% `\keyname{classoffset}' described in section \ref{rLanguagesAndStyles}.
969
% \item How can I define my own language?
971
% This is discussed in section \ref{rLanguageDefinitions}. And if you
972
% think that other people could benefit by your definition, you might
973
% want to send it to the address in section \ref{uSoftwareLicense}.
974
% Then it will be published under the \LaTeX\ Project Public License.
976
% Note that the arguments \meta{language} and \meta{dialect} are case
977
% insensitive and that spaces have no effect.
980
% \subsection{Special characters}\label{uSpecialCharacters}
983
% \paragraph{Tabulators}
984
% You might get unexpected output if your sources contain tabulators.
985
% The package assumes tabulator stops at columns 9, 17, 25, 33, and so on.
986
% This is predefined via |tabsize=8|. If you change the eight to the number
987
% $n$, you will get tabulator stops at columns $n+1,2n+1,3n+1,$ and so on.
988
% \begin{lstsample}[tabsize]{}{}
994
% 123 { 123 + two tabs }
997
% For better illustration, the left-hand side uses |tabsize=2| but the verbatim
998
% code |tabsize=4|. Note that |\lstset| modifies the values for all following
999
% listings in the same environment or group. This is no problem here since the
1000
% examples are typeset inside minipages. If you want to change settings for a
1001
% single listing, use the optional argument.
1004
% \paragraph{Visible tabulators and spaces}
1005
% One can make spaces and tabulators visible:
1006
% \begin{lstsample}[showspaces,showtabs,tab]{}{}
1007
% \lstset{showspaces=true,
1009
% tab=\rightarrowfill}
1010
% \begin{lstlisting}
1011
% for i:=maxint to 0 do
1017
% If you request \ikeyname{showspaces} but no \ikeyname{showtabs},
1018
% tabulators are converted to visible spaces.
1019
% The default definition of \ikeyname{tab} produces a `wide visible space'
1020
% \lstinline[showtabs]! !. So you might want to use |$\to$|, |$\dashv$|
1021
% or something else instead.
1023
% \item Some sort of advice: (1) You should really indent lines of source code
1024
% to make listings more readable. (2) Don't indent some lines with
1025
% spaces and others via tabulators. Changing the tabulator size (of your
1026
% editor or pretty-printing tool) completely disturbs the columns.
1027
% (3) As a consequence, never share your files with differently tab sized
1028
% people!^^A true only if you use tabulators, just :-)
1029
% \item To make the \LaTeX\ code more readable, I indent the environments'
1030
% program listings. How can I remove that indention in the output?
1032
% Read `How to gobble characters' in section \ref{uHowTos}.
1036
% \paragraph{Form feeds}
1037
% Another special character is a form feed causing an empty line by default.
1038
% {\rstyle\ikeyname{formfeed}}|=\newpage| would result in a new page every
1039
% form feed. Please note that such definitions (even the default) might get
1040
% in conflict with frames.
1043
% \paragraph{National characters}
1044
% If you type in such characters directly as characters of codes 128--255 and
1045
% use them also in listings, let the package know it---or you'll get really
1046
% funny results. {\rstyle\ikeyname{extendedchars}}|=true| allows and
1047
% |extendedchars=false| prohibits extended characters in listings. If you use
1048
% them, you should load \packagename{fontenc}, \packagename{inputenc} and/or
1049
% any other package which defines the characters.
1051
% \item I have problems using \packagename{inputenc} together with
1052
% \packagename{listings}.
1054
% This could be a compatibility problem. Make a bug report as described
1055
% in section \lstref{uTroubleshooting}.
1057
% The extended characters don't cover Arabic, Chinese, Hebrew, Japanese, and so
1058
% on. Read section \ref{uNationalCharacters} for details on work-arounds.
1061
% \subsection{Line numbers}\label{uLineNumbers}
1063
% You already know the keys \ikeyname{numbers}, \ikeyname{numberstyle},
1064
% \ikeyname{stepnumber}, and \ikeyname{numbersep} from section
1065
% \ref{gSeduceToUse}. Here now we deal with continued listings.
1066
% You have two options to get consistent line numbering across listings.
1068
% \begin{lstsample}[firstnumber]{\lstset{numbers=left,numberstyle=\tiny,stepnumber=2,numbersep=5pt}}{}
1069
% \begin{lstlisting}[firstnumber=100]
1070
% for i:=maxint to 0 do
1076
% And we continue the listing:
1077
% \begin{lstlisting}[firstnumber=last]
1078
% Write('Case insensitive ');
1079
% WritE('Pascal keywords.');
1082
% In the example, \ikeyname{firstnumber} is initially set to 100; some lines
1083
% later the value is \texttt{last}, which continues the numbering of the last
1084
% listing. Note that the empty line at the end of the first part is not printed
1085
% here, but it counts for line numbering. You should also notice that you can
1086
% write |\lstset{firstnumber=last}| once and get consecutively numbered code
1087
% lines---except you specify something different for a particular listing.
1089
% On the other hand you can use |firstnumber=auto| and name your listings.
1090
% Listings with identical names (case sensitive!) share a line counter.
1091
% \begin{lstsample}[name]{\lstset{numbers=left,numberstyle=\tiny,stepnumber=2,numbersep=5pt}}{}
1092
% \begin{lstlisting}[name=Test]
1093
% for i:=maxint to 0 do
1099
% And we continue the listing:
1100
% \begin{lstlisting}[name=Test]
1101
% Write('Case insensitive ');
1102
% WritE('Pascal keywords.');
1105
% The next |Test| listing goes on with line number {\makeatletter\lstno@Test},
1106
% no matter whether there are other listings in between.
1108
% \item Okay. And how can I get decreasing line numbers?
1112
% Decreasing line numbers as on page \pageref{rDecreasingLabels}.
1114
% May I suggest to demonstrate your individuality by other means?
1115
% If you differ, you should try a negative `\ikeyname{stepnumber}'
1116
% (together with `\ikeyname{firstnumber}').
1119
% Read section \ref{uHowTos} on how to reference line numbers.
1122
% \subsection{Layout elements}
1124
% It's always a good idea to structure the layout by vertical space,
1125
% horizontal lines, or different type sizes and typefaces. The best to stress
1126
% whole listings are---not all at once---colours, frames, vertical space, and
1127
% captions. The latter are also good to refer to listings, of course.
1129
% \paragraph{Vertical space}
1130
% The keys {\rstyle\ikeyname{aboveskip}} and {\rstyle\ikeyname{belowskip}}
1131
% control the vertical space above and below displayed listings. Both keys get
1132
% a dimension or skip as value and are initialized to |\medskipamount|.
1134
% \paragraph{Frames}
1135
% The key \ikeyname{frame} takes the verbose values \keyvalue{none},
1136
% \keyvalue{leftline}, \keyvalue{topline}, \keyvalue{bottomline},
1137
% \keyvalue{lines} (top and bottom), \keyvalue{single} for single frames, or
1138
% \keyvalue{shadowbox}.
1139
% \begin{lstsample}[frame]{}{}
1140
% \begin{lstlisting}[frame=single]
1141
% for i:=maxint to 0 do
1148
% \item The rules aren't aligned.
1150
% This could be a bug of this package or a problem with your
1151
% \texttt{.dvi} driver. \emph{Before} sending a bug report to the package
1152
% author, modify the parameters described in section \ref{rFrames}
1153
% heavily. And do this step by step!
1154
% For example, begin with `|framerule=10mm|'. If the rules are
1155
% misaligned by the same (small) amount as before, the problem does not
1156
% come from the rule width. So continue with the next parameter.
1158
% Alternatively you can control the rules at the \texttt{t}op, \texttt{r}ight,
1159
% \texttt{b}ottom, and \texttt{l}eft directly by using the four initial letters
1160
% for single rules and their upper case versions for double rules.
1161
% \begin{lstsample}[frame]{}{}
1162
% \begin{lstlisting}[frame=trBL]
1163
% for i:=maxint to 0 do
1169
% Note that a corner is drawn if and only if both adjacent rules are requested.
1170
% You might think that the lines should be drawn up to the edge, but what's
1171
% about round corners? The key \ikeyname{frameround} must get exactly four
1172
% characters as value. The first character is attached to the upper right
1173
% corner and it continues clockwise. `\texttt{t}' as character makes the
1174
% corresponding corner round.
1175
% \begin{lstsample}[frameround]{}{}
1176
% \lstset{frameround=fttt}
1177
% \begin{lstlisting}[frame=trBL]
1178
% for i:=maxint to 0 do
1184
% Note that \ikeyname{frameround} has been used together with |\lstset| and thus
1185
% the value affects all following listings in the same group or environment.
1186
% Since the listing is inside a \texttt{minipage} here, this is no problem.
1188
% \item Dont' use frames all the time, in particular not with short listings.
1189
% This would emphasize nothing. Use frames for $10\%$ or even less of
1190
% your listings, for your most important ones.
1191
% \item If you use frames on floating listings, do you really want frames?
1193
% No, I want to separate floats from text.
1195
% Then it is better to redefine \LaTeX's `|\topfigrule|' and
1196
% `|\botfigrule|'. For example, you could write
1197
% `|\renewcommand*\topfigrule{\hrule\kern-0.4pt\relax}|' and make the
1198
% same definition for |\botfigrule|.
1201
% \paragraph{Captions}
1202
% Now we come to \ikeyname{caption} and \ikeyname{label}. You might guess that
1203
% they can be used in the same manner as \LaTeX's |\caption| and |\label|
1205
% \begin{lstsample}[caption,label]{\lstset{xleftmargin=.05\linewidth}}{}
1206
% \begin{lstlisting}[caption={Useless code},label=useless]
1207
% for i:=maxint to 0 do
1213
% Afterwards you could refer to the listing via |\ref{useless}|. By default
1214
% such a listing gets an entry in the list of listings, which can be printed
1215
% with the command {\rstyle\icmdname\lstlistoflistings}. The key
1216
% {\rstyle\ikeyname{nolol}} suppresses an entry for both the environment or
1217
% the input command. Moreover, you can specify a short caption for the list
1219
% \keyname{caption}|={|\oarg{short}\meta{long}|}|.
1220
% Note that the whole value is enclosed in braces since an optional value is
1221
% used in an optional argument.
1223
% If you don't want the label \texttt{\lstlistingname} plus number, you should
1224
% use \ikeyname{title}:
1225
% \begin{lstsample}[title]{\lstset{xleftmargin=.05\linewidth}}{}
1226
% \begin{lstlisting}[title={`Caption' without label}]
1227
% for i:=maxint to 0 do
1234
% \item Something goes wrong with `\keyname{title}' in my document: in front of
1235
% the title is a delimiter.
1237
% The result depends on the document class; some are not compatible.
1238
% Contact the package author for a work-around.
1241
% \paragraph{Colours}
1242
% One more element. You need the \packagename{color} package and can then
1243
% request coloured background via
1244
% \ikeyname{backgroundcolor}|=|\meta{color command}.
1246
% \item Great! I love colours.
1248
% Fine, yes, really. And I like to remind you of the warning about
1249
% striking styles on page \pageref{wStrikingStyles}.
1252
% \begin{lstxsample}[backgroundcolor]
1253
% \lstset{backgroundcolor=\color{yellow}}
1257
% color package not installed\end{verbatim}
1259
% \begin{lstsample}{}{}
1260
% \begin{lstlisting}[frame=single,
1262
% for i:=maxint to 0 do
1264
% j:=square(root(i));
1268
% The example also shows how to get coloured space around the whole listing:
1269
% use a frame whose rules has no width.
1272
% \subsection{Emphasize identifiers}\label{uEmphasizeIdentifiers}
1274
% Recall the pretty-printing commands and environment. |\lstinline| prints
1275
% code snippets, |\lstinputlisting| whole files, and \texttt{lstlisting}
1276
% pieces of code which reside in the \LaTeX\ file. And what are these
1277
% different `types' of source code good for? Well, it just happens that a
1278
% sentence contains a code fragment. Whole files are typically included in or
1279
% as an appendix. Nevertheless some books about programming also include such
1280
% listings in normal text sections---to increase the number of pages.
1281
% Nowadays source code should be shipped on disk or CD-ROM and only the main
1282
% header or interface files should be typeset for reference. So, please, don't
1283
% misuse the \packagename{listings} package. But let's get back to the topic.
1285
% Obviously `\texttt{lstlisting} source code' isn't used to make an executable
1286
% program from. Such source code has some kind of educational purpose or even
1289
% \item What's the difference between educational and didactic?
1291
% Something educational can be good or bad, true or false.
1292
% Didactic is true by definition.^^A :-)
1294
% Usually \emph{keywords} are highlighted when the package typesets a piece of
1295
% source code. This isn't necessary for readers knowing the programming
1296
% language well. The main matter is the presentation of interface, library or
1297
% other functions or variables. If this is your concern, here come the right
1298
% keys. Let's say, you want to emphasize the functions |square| and |root|,
1299
% for example, by underlining them. Then you could do it like this:
1300
% \begin{lstxsample}[emph,emphstyle]
1301
% \lstset{emph={square,root},emphstyle=\underbar}
1303
% \begin{lstsample}{}{}
1304
% \begin{lstlisting}
1305
% for i:=maxint to 0 do
1307
% j:=square(root(i));
1312
% \item Note that the list of identifiers |{square,root}| is enclosed in
1313
% braces. Otherwise the \packagename{keyval} package would complain
1314
% about an undefined key \keyname{root} since the comma finishes the
1316
% Note also that you \emph{must} put braces around the value if you
1317
% use an optional argument of a key inside an optional argument of a
1318
% pretty-printing command. Though it is not necessary, the following
1319
% example uses these braces. They are typically forgotten when they
1323
% Both keys have an optional \meta{class number} argument for multiple
1326
% \begin{lstxsample}[emph,emphstyle]
1327
% \lstset{emph={square}, emphstyle=\color{red},
1328
% emph={[2]root,base},emphstyle={[2]\color{blue}}}
1331
% \begin{lstxsample}[emph,emphstyle]
1332
% \lstset{emph={square}, emphstyle=\underbar,
1333
% emph={[2]root,base},emphstyle={[2]\fbox}}
1336
% \begin{lstsample}{}{}
1337
% \begin{lstlisting}
1338
% for i:=maxint to 0 do
1340
% j:=square(root(i));
1345
% \item What is the maximal \meta{class number}?
1347
% $2^{31}-1=2\,147\,483\,647$. But \TeX's memory will exceed before you
1348
% can define so many different classes.
1351
% One final hint: Keep the lists of identifiers disjoint. Never use a keyword
1352
% in an `emphasize' list or one name in two different lists. Even if your
1353
% source code is highlighted as expected, there is no guarantee that it is
1354
% still the case if you change the order of your listings or if you use the
1355
% next release of this package.
1359
% \subsection{*Listing alignment}\label{uListingAlignment}
1361
% The examples are typeset with centered \texttt{minipage}s. That's the reason
1362
% why you can't see that line numbers are printed in the margin. Now we
1363
% separate the minipage margin and the minipage by a vertical rule:
1364
% \begin{lstsample}{\lstset{frame=l,framesep=0pt,numberstyle=\tiny,stepnumber=2,numbersep=5pt}}{}
1366
% \begin{lstlisting}
1367
% for i:=maxint to 0 do
1373
% The listing is lined up with the normal text. The parameter \ikeyname{xleftmargin}
1374
% moves the listing to the right (or left if the dimension is negative).
1375
% \begin{lstsample}{\lstset{frame=l,framesep=0pt,numberstyle=\tiny,stepnumber=2,numbersep=5pt}}{}
1377
% \begin{lstlisting}[xleftmargin=15pt]
1378
% for i:=maxint to 0 do
1384
% \begin{lstlisting}{ }
1385
% Write('Insensitive');
1386
% WritE('keywords.');
1389
% Note again that optional arguments change settings for single listings.
1391
% If you use environments like \texttt{itemize} or \texttt{enumerate}, there
1392
% is `natural' indention coming from these environments. By default the
1393
% \packagename{listings} package respects this. But you might use
1394
% |resetmargins=true| (or |false|) to make your own decision. You can use it
1395
% together with |xleftmargin|, of course.
1397
% \item I get heavy overfull |\hbox|es from some listings.
1399
% This comes from long lines in your listings. You have some options
1400
% to get rid of the overful |\hbox|es. Firstly I recommend to typeset
1401
% listings in smaller fonts than the surrounding text, for example
1402
% `|basicstyle=\small|'. Secondly you might want to use the flexible
1403
% column format. Thirdly you can increase the line width or set it
1404
% explicitly, refer section \ref{rMarginsAndLineShape}.
1405
% If all this doesn't help, you might want to change
1406
% `\ikeyname{basewidth}', but be careful! The two unknown items are
1407
% explained in the next section.
1410
% You might need to control the vertical position of listings with the
1411
% \ikeyname{boxpos} key, for example, if you use them in \texttt{minipage} or
1412
% \texttt{tabular} environments. Here `listings' means \texttt{lstlisting} or
1413
% |\lstinputlisting|. As the following example shows, you can even place such
1414
% listings inside paragraphs, but you must force the package to do this by
1415
% enclosing the listing in |\hbox{| and |}|.
1417
% \item Is it good form to use the \TeX-primitive `|\hbox|' in a \LaTeX\
1420
% No, it's not. But \LaTeX's `|\mbox|' does not work in this example:
1422
% \begin{lstsample}{}{}
1423
% Here are some multi-line listings inside a paragraph.
1424
% The `boxpos' key controls their vertical alignment:
1425
% \hbox{\begin{lstlisting}[boxpos=c]
1429
% \hbox{\begin{lstlisting}[boxpos=b]
1433
% \hbox{\begin{lstlisting}[boxpos=t]
1441
% \subsection{Indexing}\label{uIndexing}
1443
% is just like emphasizing identifiers---I mean the usage:
1444
% \begin{lstxsample}[index]
1445
% \lstset{index={square},index={[2]root}}
1447
% \begin{lstsample}{}{}
1448
% \begin{lstlisting}
1449
% for i:=maxint to 0 do
1451
% j:=square(root(i));
1455
% Of course, you can't see anything here. You will have to look at the index.
1457
% \item Why the `\ikeyname{index}' key is able to work with multiple identifier
1460
% This question is strongly related to the `{\rstyle\ikeyname{indexstyle}}'
1461
% key. Someone might want to create multiple indexes or want to insert
1462
% prefixes like `|constants|', `|functions|', `|keywords|', and so on.
1463
% The `\ikeyname{indexstyle}' key works like the other style keys except
1464
% that the last token \emph{must} take an argument, namely the
1465
% (printable form of the) current identifier.
1467
% You can define `|\newcommand\indexkeywords[1]{\index{keywords, #1}}|'
1468
% and make similar definitions for constant or function names. Then
1469
% `|indexstyle=[1]\indexkeywords|' might meet your purpose. This becomes
1470
% easier if you want to create multiple indexes with the
1471
% \packagename{index} package
1472
% (\href{ftp://ftp.dante.de/tex-archive/macros/latex/contrib/supported/camel}
1473
% {CTAN/macros/latex/contrib/supported/camel}).
1474
% If you have defined appropriate new indexes, it is possible to write
1475
% `|indexstyle=\index[keywords]|', for example.
1477
% \item Let's say, I want to index all keywords. It would be annoying to
1478
% type in all the keywords again, specifically if the used programming
1479
% language changes frequently.
1483
% The \ikeyname{index} key has in fact two optional arguments. The first is the
1484
% well-known \meta{class number}, the second is a comma separated list of other
1485
% keyword classes whose identifiers are indexed. The indexed identifiers then
1486
% change automatically with the defined keywords---not automagically, it's not
1487
% an illusion.^^A :-)
1489
% Eventually you need to know the names of the keyword classes. It's usually
1490
% the key name followed by a class number, for example, |emph2|, |emph3|,
1491
% \ldots, |keywords2| or |index5|. But there is no number for the first order
1492
% classes |keywords|, |emph|, |directives|, and so on.
1494
% \item `|index=[keywords]|' does not work.
1496
% The package can't guess which optional argument you mean. Hence you
1497
% must specify both if you want to use the second one. You should try
1498
% `|index=[1][keywords]|'.
1502
% \subsection{Fixed and flexible columns}\label{uFixedAndFlexibleColumns}
1504
% The first thing a reader notices---except different styles for keywords,
1505
% etc.---is the column alignment. Arne John Glenstrup invented the flexible
1506
% column format in 1997. Since then some efforts were made to develop this
1507
% branch farther. Currently three column formats are provided: fixed, flexible,
1508
% and full flexible. Take a close look at the following examples.
1510
% \lstset{style={},language={}}
1511
% \def\sample{\begin{lstlisting}^^J WOMEN\ \ are^^A
1512
% ^^J \ \ \ \ \ \ \ MEN^^A
1514
% ^^J better MEN^^J \end{lstlisting}}
1515
% \begin{tabular}{@{}c@{\qquad\quad}c@{\qquad\quad}c@{\qquad\quad}c@{}}
1516
% {\rstyle\ikeyname{columns}}|=| & \texttt{fixed} & \texttt{flexible} & \texttt{fullflexible}\\
1517
% & (at {\makeatletter\lst@widthfixed})
1518
% & (at {\makeatletter\lst@widthflexible})
1519
% & (at {\makeatletter\lst@widthflexible})\\
1520
% \noalign{\medskip}
1521
% \lstset{basicstyle=\ttfamily,basewidth=0.51em}\sample
1522
% & \lstset{columns=fixed}\sample
1523
% & \lstset{columns=flexible}\sample
1524
% & \lstset{columns=fullflexible}\sample
1528
% \item Why are women better men?
1530
% Do you want to philosophize? Well, have I ever said that the
1531
% statement ``women are better men'' is true? I can't even remember this
1532
% about ``women are men'' \ldots ^^A ;-))
1534
% In the abstract one can say: The fixed column format ruins the spacing
1535
% intended by the font designer, while the flexible formats ruin the column
1536
% alignment (possibly) intended by the programmer. Common to all is that the
1537
% input characters are translated into a sequence of basic output units like
1538
% \begingroup \lstset{gobble=6,xleftmargin=\leftmargini}
1540
%^^A Make \fbox around each output unit.
1542
% \def\lst@alloverstyle#1{\fbox{\kern-\fboxrule\strut#1}\kern-\fboxrule}
1543
% \begin{lstlisting}[basewidth=1em]
1544
% if x=y then write('align')
1545
% else print('align');
1547
% Now, the fixed format puts $n$ characters into a box of width $n\times{}
1548
% $`base width', where the base width is {\makeatletter\lst@widthfixed} in the
1549
% example. The format shrinks and stretches the space between the characters
1550
% to make them fit the box. As shown in the example, some character strings look
1551
% \hbox to 2em{b\hss a\hss d}
1553
% \hbox to 2em{w\hss o\hss r\hss s\hss e},
1554
% but the output is vertically aligned.
1557
% If you don't need or like this, you should use a flexible format. All
1558
% characters are typeset at their natural width. In particular, they never
1559
% overlap. If a word requires more space than reserved, the rest of the line
1560
% simply moves to the right. The difference between the two formats is that the
1561
% full flexible format cares about nothing else and the normal flexible format
1562
% tries to fix the column alignment if a character string needs less space
1563
% than `reserved'. In the flexible example above, the two MENs are vertically
1564
% aligned since some space has been inserted in the fourth line to fix the
1565
% alignment. In the full flexible format, the two MENs are not aligned.
1567
% Note that both flexible modes printed the two blanks in the first line as a
1568
% single blank, but for different reasons: the normal flexible format fixes
1569
% the column alignment and the full flexible format doesn't care about the
1573
% \section{Advanced techniques}\label{uAdvancedTechniques}
1576
% \subsection{Style definitions}
1578
% It is obvious that a pretty-printing tool like this requires some kind of
1579
% language selection and definition. The first has already been described and
1580
% the latter is convered by the next section. However, it is very convenient
1581
% to have the same for printing styles: at a central place of your document
1582
% they can be modified easily and the changes take effect on all listings.
1584
% Similar to languages,
1585
% {\rstyle\ikeyname{style}}|=|\meta{style name}
1586
% activates a previously defined style. A definition is as easy:
1587
% {\rstyle|\lstdefinestyle|}\marg{style name}\marg{key=value list}.
1588
% Keys not used in such a definition are untouched by the corresponding style
1589
% selection, of course. For example, you could write
1591
% \lstdefinestyle{numbers}
1592
% {numbers=left, stepnumber=1, numberstyle=\tiny, numbersep=10pt}
1593
% \lstdefinestyle{nonumbers}
1594
% {numbers=none}\end{verbatim}
1595
% and switch from listings with line numbers to listings without ones and vice
1596
% versa simply by |style=nonumbers| and |style=numbers|, respectively.
1598
% \item You could even write
1599
% `|\lstdefinestyle{C++}{language=C++,style=numbers}|'.
1600
% Style and language names are independent of each other and so might
1601
% coincide. Moreover it is possible to activate other styles.
1603
% \item It's easy to crash the package using styles. Write
1604
% '|\lstdefinestyle{crash}{style=crash}|' and '|\lstset{style=crash}|'.
1605
% \TeX's capacity will exceed, sorry [parameter stack size]. Only bad
1606
% boys use such recursive calls, but only good girls use this package.
1607
% Thus the problem is of minor interest.^^A :-)
1611
% \subsection{Language definitions}\label{uLanguageDefinitions}
1613
% This is like style definitions except for an optional dialect name and an
1614
% optional base language---and, of course, a different command name and
1615
% specialized keys. In the simple case it's
1616
% {\rstyle|\lstdefinelanguage|}\marg{language name}\marg{key=value list}.
1617
% For many programming languages it is sufficient to specify keywords and
1618
% standard function names, comments, and strings. Let's look at an example.
1619
% \begin{lstxsample}[morekeywords,sensitive,morecomment,morestring]
1620
% \lstdefinelanguage{rock}
1621
% {morekeywords={one,two,three,four,five,six,seven,eight,
1622
% nine,ten,eleven,twelve,o,clock,rock,around,the,tonight},
1624
% morecomment=[l]{//},
1625
% morecomment=[s]{/*}{*/},
1629
% \begingroup \csname lst@EndWriteFile\endcsname
1633
% There isn't much to say about keywords. They are defined like identifiers
1634
% you want to emphasize. Additionally you need to specify whether they are
1635
% case sensitive or not. And yes: you could insert |[2]| in front of the
1636
% keyword \texttt{one} to define the keywords as `second order' and print them
1637
% in |keywordstyle={[2]...}|.
1639
% \item I get a `\texttt{Missing = inserted for }|\ifnum|' error when I select
1642
% Did you forget the comma after `|keywords={...}|'? And if you encounter
1643
% unexpected characters after selecting a language (or style), you have
1644
% probably forgotten a different comma or you have given to many
1645
% arguments to a key, for example, |morecomment=[l]{--}{!}|.
1648
% So let's turn to comments and strings. Each value starts with a
1649
% \emph{mandatory} \oarg{type} argument followed by a changing number of
1650
% opening and closing delimiters. Note that each delimiter (pair) requires a
1651
% key=value on its own, even if types are equal. Hence, you'll need to insert
1652
% \texttt{morestring=[b]'} if single quotes open and close string or character
1653
% literals in the same way as double quotes do in the example.
1655
% Eventually you need to know the types and their numbers of delimiters. The
1656
% reference guide contains full lists, here we discuss only the most common.
1657
% For strings these are {\rstyle\texttt{b}} and {\rstyle\texttt{d}} with one
1658
% delimiter each. This delimiter opens and closes the string and inside a
1659
% string it is either escaped by a \texttt backslash or it is \texttt doubled.
1660
% The comment type {\rstyle\texttt{l}} requires exactly one delimiter, which
1661
% starts a comment on any column. This comment goes up to the end of line.
1662
% The other two most common comment types are {\rstyle\texttt{s}} and
1663
% {\rstyle\texttt{n}} with two delimiters each. The first delimiter opens a
1664
% comment which is terminated by the second delimiter. In contrast to the
1665
% \texttt s-type, \texttt n-type comments can be nested.
1666
% \begin{lstxsample}[b,d,l,s,n]
1667
% \lstset{morecomment=[l]{//},
1668
% morecomment=[s]{/*}{*/},
1669
% morecomment=[n]{(*}{*)},
1673
% \begin{lstsample}{}{}
1674
% \begin{lstlisting}
1675
% "str\"ing " not a string
1676
% 'str''ing ' not a string
1678
% /* comment/**/ not a comment
1679
% (* nested (**) still comment
1680
% comment *) not a comment
1684
% \item Is it \emph{that} easy?
1686
% Almost. There are some troubles you can run into. For example, if
1687
% `\texttt{-*}' starts a comment line and `\texttt{-*-}' a string
1688
% (unlikely but possible), then you must define the shorter delimiter
1690
% Another problem: by default some characters are not allowed inside
1691
% keywords, for example `\texttt{-}', `\texttt{:}', `\texttt{.}', and
1692
% so on. The reference guide covers this problem by introducing some
1693
% more keys, which let you adjust the standard character table
1694
% appropriately. But note that white space characters are prohibited
1697
% Finally remember that this section is only an introduction to language
1698
% definitions. There are more keys and possibilities.
1701
% \subsection{Delimiters}\label{uDelimiters}
1703
% You already know two special delimiter classes: comments and strings.
1704
% However, their full syntax hasn't been described so far. For example,
1705
% \ikeyname{commentstyle} applies to all comments---except you specify
1706
% something different. The \emph{optional} \oarg{style} argument follows the
1707
% \emph{mandatory} \oarg{type} argument.
1709
% \begin{lstxsample}
1710
% \lstset{morecomment=[l][keywordstyle]{//},
1711
% morecomment=[s][\color{white}]{/*}{*/}}
1714
% \begin{lstxsample}
1715
% \lstset{morecomment=[l][keywordstyle]{//},
1716
% morecomment=[s][\underbar]{/*}{*/}}
1719
% \begin{lstsample}{}{}
1720
% \begin{lstlisting}
1721
% // bold comment line
1722
% a single /* comment */
1725
% As you can see, you have the choice between specifying the style explicitly
1726
% by \LaTeX\ commands or implicitly by other style keys. But, you're right,
1727
% some implicitly defined styles have no seperate keys, for example the second
1728
% order keyword style. Here---and never with the number 1---you just append
1729
% the order to the base key: \texttt{keywordstyle2}.
1731
% You ask for an application? Here you are: one can define different printing
1732
% styles for `subtypes' of a comment, for example
1734
% \begin{lstxsample}
1735
% \lstset{morecomment=[s][\color{blue}]{/*+}{*/},
1736
% morecomment=[s][\color{red}]{/*-}{*/}}
1739
% \begin{lstxsample}
1740
% \lstset{morecomment=[s][\upshape]{/*+}{*/},
1741
% morecomment=[s][\bfseries]{/*-}{*/}}
1744
% \begin{lstsample}{\lstset{morecomment=[s]{/*}{*/}}}{}
1745
% \begin{lstlisting}
1746
% /* normal comment */
1751
% Here, the comment style is not applied to the second and third line.
1753
% \item Please remember that both `extra' comments must be defined \emph{after}
1754
% the normal comment, since the delimiter `\texttt{/*}' is a substring of
1755
% `\texttt{/*+}' and `\texttt{/*-}'.
1757
% \item I have another question. Is `\texttt{language=}\meta{different
1758
% language}' the only way to remove such additional delimiters?
1760
% Call {\rstyle\ikeyname{deletecomment}} and/or
1761
% {\rstyle\ikeyname{deletestring}} with the same arguments to remove
1762
% the delimiters (but you don't need to provide the optional style
1765
% Eventually, you might want to use the prefix \texttt{i} on any comment type.
1766
% Then the comment is not only invisible, it is completely discarded from the
1768
% \begin{lstxsample}[is]
1769
% \lstset{morecomment=[is]{/*}{*/}}
1771
% \begin{lstsample}{}{}
1772
% \begin{lstlisting}
1773
% begin /* comment */ end
1774
% begin/* comment */end
1778
% Okay, and now for the real challenges. More general delimiters can be defined
1779
% by the key {\rstyle\ikeyname{moredelim}}. Legal types are {\rstyle\texttt{l}}
1780
% and {\rstyle\texttt{s}}. These types can be preceded by an \texttt{i}, but
1781
% this time \emph{only the delimiters} are discarded from the output. This way
1782
% you can select styles by markers.
1783
% \begin{lstxsample}
1784
% \lstset{moredelim=[is][\ttfamily]{|}{|}}
1786
% \begin{lstsample}{}{}
1787
% \begin{lstlisting}
1788
% roman |typewriter|
1791
% You can even let the package detect keywords, comments, strings, and other
1792
% delimiters inside the contents.
1793
% \begin{lstxsample}
1794
% \lstset{moredelim=*[s][\itshape]{/*}{*/}}
1796
% \begin{lstsample}{}{}
1797
% \begin{lstlisting}
1803
% Moreover, you can force the styles being applied cumulative.
1804
% \begin{lstxsample}
1805
% \lstset{moredelim=**[is][\ttfamily]{|}{|}, % cumulative
1806
% moredelim=*[s][\itshape]{/*}{*/}} % not so
1808
% \begin{lstsample}{}{}
1809
% \begin{lstlisting}
1819
% Look carefully at the output and note the differences. The second
1820
% \texttt{begin} is not printed in bold typewriter type since standard
1821
% \LaTeX\ has no such font.
1823
% This suffices for an introduction. Now go and find some more applications.
1826
% \subsection{Closing and credits}\label{uClosingAndCredits}
1828
% You've seen a lot of keys but you are far away from knowing all of them.
1829
% The next step is the real use of the \packagename{listings} package.
1830
% Please take the following advices. Firstly, look up the known commands and
1831
% keys in the reference guide to get a notion of the notation there. Secondly,
1832
% poke about around these keys to learn some other parameters. Then, hopefully,
1833
% you'll be prepared if you encounter any problems or need some special things.
1837
% There is one question `you' haven't asked all the last pages: who is to
1838
% blame. The author has written the guides, coded the \packagename{listings}
1839
% package and some language drivers. Other people defined more languages or
1840
% contributed their ideas; many others made bug reports, but only the first
1841
% bug finder is listed.
1843
%^^A Thanks for error reports (first bug finder only), new programming
1844
%^^A languages, etc.
1845
%^^A Special thanks for communication which lead to kernel extensions.
1847
% Special thanks go to (alphabetical order)
1849
% \hyphenpenalty=10000\relax \rightskip=0pt plus \linewidth
1850
% \lstthanks{Andreas~Bartelt}{Andreas.Bartelt@Informatik.Uni-Oldenburg.DE},
1851
% \lstthanks{Jan~Braun}{Jan.Braun@tu-bs.de},
1852
% \lstthanks{Denis~Girou}{Denis.Girou@idris.fr},
1853
% \lstthanks{Arne~John~Glenstrup}{panic@diku.dk},
1854
% \lstthanks{Frank~Mittelbach}{frank.mittelbach@latex-project.org},
1855
% \lstthanks{Rolf~Niepraschk}{niepraschk@PTB.DE},
1856
% \lstthanks{Rui~Oliveira}{rco@di.uminho.pt},
1857
% \lstthanks{Jens~Schwarzer}{schwarzer@schwarzer.dk}, and
1858
% \lstthanks{Boris~Veytsman}{boris@plmsc.psu.edu}.
1860
% Moreover I wish to thank
1862
% \hyphenpenalty=10000\relax \rightskip=0pt plus \linewidth
1863
% \lstthanks{Bj{\o}rn~{\AA}dlandsvik}{bjorn@imr.no},
1864
% \lstthanks{Gaurav~Aggarwal}{gaurav@ics.uci.edu},
1865
% \lstthanks{Jason~Alexander}{jalex@ea.oac.uci.edu},
1866
% \lstthanks{Donald~Arseneau}{ASND@erich.triumf.ca},
1867
% \lstthanks{Claus~Atzenbeck}{Claus.Atzenbeck@stud.uni-regensburg.de},
1868
% \lstthanks{Peter~Bartke}{bartke@inf.fu-berlin.de} (big thankyou), ^^A beta tester
1869
% \lstthanks{Oliver~Baum}{oli.baum@web.de},
1870
% \lstthanks{Ralph~Becket}{rbeck@microsoft.com},
1871
% \lstthanks{Olaf~Trygve~Berglihn}{olafb@pvv.org}, ^^A {1999/11/29}{3-char comment delimiter don't work (Python)}
1872
% \lstthanks{Peter~Biechele}{peter.biechele@physik.uni-freiburg.de},
1873
% \lstthanks{Kai~Below}{below@tu-harburg.de},
1874
% \lstthanks{Beat~Birkhofer}{beat@birkhofer.ch},
1875
% \lstthanks{Fr\'ed\'eric~Boulanger}{Frederic.Boulanger@supelec.fr},
1876
% \lstthanks{Martin~Brodbeck}{Martin.Brodbeck@gmx.de},
1877
% \lstthanks{Walter~E.~Brown}{WB@fnal.gov},
1878
% \lstthanks{Achim~D.~Brucker}{brucker@informatik.uni-freiburg.de},
1879
% \lstthanks{David~Carlisle}{carlisle@cs.man.ac.uk},
1880
% \lstthanks{Bradford~Chamberlain}{brad@cs.washington.edu},
1881
% \lstthanks{Patrick~Cousot}{Patrick.Cousot@wanadoo.fr},
1882
% \lstthanks{Xavier~Cr\'egut}{cregut@enseeiht.fr},
1883
% \lstthanks{Holger~Danielsson}{dani@fbg.schwerte.de},
1884
% \lstthanks{Andreas~Deininger}{deininger@uni-kassel.de},
1885
% \lstthanks{Robert~Denham}{Robert.Denham@dnr.qld.gov.au},
1886
% \lstthanks{Detlev~Dr\"oge}{droege@informatik.uni-koblenz.de},
1887
% \lstthanks{Anders~Edenbrandt}{Anders.Edenbrandt@dna.lth.se},
1888
% \lstthanks{Chris~Edwards}{edwch00p@infoscience.otago.ac.nz},
1889
% \lstthanks{David~John~Evans}{Matrix.Software@dial.pipex.com},
1890
% \lstthanks{Daniel~Gerigk}{Daniel.Gerigk@ePost.de},
1891
% \lstthanks{KP~Gores}{kp.gores@web.de},
1892
% \lstthanks{Christian~Gudrian}{Christian.Gudrian@kawo1.rwth-aachen.de},
1893
% \lstthanks{Carsten~Hamm}{carsten.hamm@siemens.com},
1894
% \lstthanks{Harald~Harders}{h.harders@tu-bs.de},
1895
% \lstthanks{Christian~Haul}{haul@dvs1.informatik.tu-darmstadt.de},
1896
% \lstthanks{Aidan~Philip~Heerdegen}{Aidan.Heerdegen@anu.edu.au},
1897
% \lstthanks{Jim~Hefferon}{jhefferon@smcvt.edu},
1898
% \lstthanks{Heiko~Heil}{info@heiko-heil.de},
1899
% \lstthanks{J\"urgen~Heim}{heim@astro.uni-tuebingen.de},
1900
% \lstthanks{Dr.~Jobst~Hoffmann}{HOFFMANN@rz.rwth-aachen.de},
1901
% \lstthanks{Torben~Hoffmann}{toho@it.dtu.dk},
1902
% \lstthanks{Richard~Hoefter}{hoefter@gmx.de},
1903
% \lstthanks{Berthold~H\"ollmann}{bhoel@starship.python.net},
1904
% \lstthanks{Hermann~H\"uttler}{hermann.huettler@gmx.net},
1905
% \lstthanks{Ralf~Imh\"auser}{snoopy@tribal.line.org},
1906
% \lstthanks{R.~Isernhagen}{R.Isernhagen@FH-Wolfenbuettel.DE},
1907
% \lstthanks{Oldrich~Jedlicka}{ojedlick@students.zcu.cz},
1908
% \lstthanks{Marcin~Kasperski}{Marcin.Kasperski@softax.com.pl},
1909
% \lstthanks{Christian~Kindinger}{chkind@uni-wuppertal.de},
1910
% \lstthanks{Steffen~Klupsch}{steffen@vlsi.informatik.tu-darmstadt.de},
1911
% \lstthanks{Peter~K\"oller}{pkoeller@metaprojekt.de} (big thankyou), ^^A beta tester
1912
% \lstthanks{Stefan~Lagotzki}{info@lagotzki.de},
1913
% \lstthanks{Rene~H.~Larsen}{rhl@traceroute.dk},
1914
% \lstthanks{Olivier~Lecarme}{ol@i3s.unice.fr},
1915
% \lstthanks{Thomas~Leduc}{Thomas.Leduc@lsv.ens-cachan.fr},
1916
% \lstthanks{Dr.~Peter~Leibner}{Peter.Leibner@sta.siemens.de},
1917
% \lstthanks{Thomas~Leonhardt}{leonhardt@informatik.tu-darmstadt.de} (big thankyou), ^^A beta tester
1918
% \lstthanks{Magnus~Lewis-Smith}{Magnus.Lewis-Smith@pace.co.uk},
1919
% \lstthanks{Knut~Lickert}{knut.lickert@gmx.de},
1920
% \lstthanks{Kris~Luyten}{no email available},
1921
% \lstthanks{Jos\'e~Romildo~Malaquias}{romildo@urano.iceb.ufop.br},
1922
% \lstthanks{Andreas~Matthias}{amat@kabsi.at},
1923
% \lstthanks{Knut~M\"uller}{knut@physik3.gwdg.de},
1924
% \lstthanks{Svend~Tollak~Munkejord}{svendm@efisms.energy.sintef.no},
1925
% \lstthanks{Gerd~Neugebauer}{gerd.neugebauer@gmx.de},
1926
% \lstthanks{Torsten~Neuer}{tneuer@inwise.de},
1927
% \lstthanks{Michael~Niedermair}{m.g.n@gmx.de},
1928
% \lstthanks{Heiko~Oberdiek}{oberdiek@ruf.uni-freiburg.de},
1929
% \lstthanks{Markus~Pahlow}{pahlowm@mar.dfo-mpo.gc.ca},
1930
% \lstthanks{Zvezdan~V.~Petkovic}{zpetkovic@acm.org},
1931
% \lstthanks{Michael~Piefel}{piefel@informatik.hu-berlin.de},
1932
% \lstthanks{Michael~Piotrowski}{mxp@linguistik.uni-erlangen.de},
1933
% \lstthanks{Manfred~Piringer}{sz0490@rrze.uni-erlangen.de},
1934
% \lstthanks{Vincent~Poirriez}{Vincent.Poirriez@univ-valenciennes.fr},
1935
% \lstthanks{Adam~Prugel-Bennett}{apb@ecs.soton.ac.uk},
1936
% \lstthanks{Ralf~Quast}{rquast@hs.uni-hamburg.de},
1937
% \lstthanks{Aslak~Raanes}{araanes@ifi.ntnu.no},
1938
% \lstthanks{Venkatesh~Prasad~Ranganath}{vranganath@cox.net},
1939
% \lstthanks{Georg~Rehm}{Georg.Rehm@germanistik.uni-giessen.de},
1940
% \lstthanks{Fermin~Reig}{reig@ics.uci.edu},
1941
% \lstthanks{Detlef~Reimers}{dreimers@aol.com},
1942
% \lstthanks{Stephen~Reindl}{stephen.reindl@vodafone.com},
1943
% \lstthanks{Peter~Ruckdeschel}{Peter.Ruckdeschel@uni-bayreuth.de},
1944
% \lstthanks{Magne~Rudshaug}{magne@ife.no},
1945
% \lstthanks{Vespe~Savikko}{vespe@cs.tut.fi},
1946
% \lstthanks{Gunther~Schmidl}{gschmidl@gmx.at},
1947
% \lstthanks{Jochen~Schneider}{jschneider@ds3.etech.haw-hamburg.de},
1948
% \lstthanks{Martin~Steffen}{ms@informatik.uni-kiel.de},
1949
% \lstthanks{Andreas~Stephan}{Andreas.Stephan@victoria.de},
1950
% \lstthanks{Gabriel~Tauro}{gabriel@informatik.uni-jena.de},
1951
% \lstthanks{Winfried~Theis}{theis@statistik.uni-dortmund.de},
1952
% \lstthanks{Jens~T.~Berger~Thielemann}{jensthi@ifi.uio.no},
1953
% \lstthanks{Kalle~Tuulos}{kalle.tuulos@nic.fi},
1954
% \lstthanks{Gregory~Van~Vooren}{Gregory.VanVooren@rug.ac.be},
1955
% \lstthanks{Thorsten~Vitt}{vitt@informatik.hu-berlin.de},
1956
% \lstthanks{Herbert~Voss}{voss@perce.de} (big thankyou), ^^A beta tester
1957
% \lstthanks{Herfried~Karl~Wagner}{hirf@gmx.at},
1958
% \lstthanks{Dominique~de~Waleffe}{ddw@miscrit.be},
1959
% \lstthanks{Michael~Weber}{mweber@informatik.hu-berlin.de},
1960
% \lstthanks{Sonja~Weidmann}{Sonja.Weidmann@gmx.de},
1961
% \lstthanks{Herbert~Weinhandl}{weinhand@grz08u.unileoben.ac.at},
1962
% \lstthanks{Michael~Wiese}{wiese@itwm.uni-kl.de},
1963
% \lstthanks{J\"orn~Wilms}{wilms@rocinante.colorado.edu},
1964
% \lstthanks{Kai~Wollenweber}{kai@ece.WPI.EDU},
1965
% \lstthanks{Ulrich~G.~Wortmann}{uliw@erdw.ethz.ch}, and
1966
% \lstthanks{Timothy~Van~Zandt}{tvz@econ.insead.edu}.
1968
% There are probably other people who contributed to this package.
1969
% If I've missed your name, send an email.
1973
% \part{Reference guide}
1976
% \section{Main reference}\label{rMainReference}
1978
% Your first training is completed. Now that you've left the User's guide, the
1979
% friend telling you what to do has gone. Get more practice and become a
1980
% journeyman!^^A :-)
1982
% \item Actually, the friend hasn't gone. There are still some advices, but
1983
% only from time to time.
1987
% \subsection{How to read the reference}
1989
% Commands, keys and environments are presented as follows.
1991
% \item[1.0,default,hints] \texttt{command}, \texttt{environment} or
1992
% \keyname{key} with \meta{parameters}
1994
% This field contains the explanation; here we describe the other fields.
1996
% If present, the label in the left margin provides extra information:
1997
% `\textit{addon}' indicates additionally introduced functionality,
1998
% `\textit{changed}' a modified key, `\textit{data}' a command just
1999
% containing data (which is therefore adjustable via |\renewcommand|),
2000
% and so on. Some keys and functionality are `\emph{bug}'-marked or
2001
% with a \dag-sign. These features might change in future or could be
2002
% removed, so use them with care.
2004
% If there is verbatim text touching the right margin, it is the
2005
% predefined value. Note that some keys default to this value every
2006
% listing, namely the keys which can be used on individual listings only.
2008
% The label in the right margin is the current version number and marks
2009
% newly introduced features.
2011
% Regarding the parameters, please keep in mind the following:
2013
% \item A list always means a comma separated list. You must put braces around
2014
% such a list. Otherwise you'll get in trouble with the
2015
% \packagename{keyval} package; it complains about an undefined key.
2016
% \item You must put parameter braces around the whole value of a key if you
2017
% use an \oarg{optional argument} of a key inside an optional
2018
% \oarg{key=value list}:
2019
% |\begin{lstlisting}[caption=|{\rstyle|{|}|[one]two|{\rstyle|}|}|]|.
2020
% \item Brackets `|[ ]|' usually enclose optional arguments and must be typed
2021
% in verbatim. Normal brackets `[ ]' always indicate an optional argument
2022
% and must not be typed in. Thus |[*]| must be typed in exactly as is,
2023
% but [|*|] just gets |*| if you use this argument.
2024
% \item A vertical rule indicates an alternative, e.g.~^^A
2025
% \meta{\alternative{true,false}} allows either \texttt{true} or
2026
% \texttt{false} as arguments.
2027
% \item If you want to enter one of the special characters |{}#%\|, this
2028
% character must be escaped with a backslash. This means that you must
2029
% write |\}| for the single character `right brace'---but of course not
2030
% for the closing paramater character.
2034
% \subsection{Typesetting listings}\label{rTypesettingListings}
2037
% \item[0.19] \rcmdname\lstset\marg{key=value list}
2039
% sets the values of the specified keys, see also section
2040
% \ref{uTheKey=ValueInterface}.
2041
% The parameters keep their values up to the end of the current group.
2042
% In opposition, all optional \meta{key=value list}s below modify the
2043
% parameters for single listings only.
2045
% \item[0.18] \rcmdname\lstinline\oarg{key=value list}\meta{character}\meta{source code}\meta{same character}
2047
% works like |\verb| but respects the active language and style. These
2048
% listings use flexible columns except requested differently in the
2049
% optional argument. You can write `|\lstinline!var i:integer;!|' and
2050
% get `\lstinline!var i:integer;!'.
2052
% Since the command first looks ahead for an optional argument, you must
2053
% provide at least an empty one if you want to use |[| as
2056
% \dag\ An experimental implementation has been done to support the
2057
% syntax |\lstinline|\oarg{key=value list}\marg{source code}. Try it if
2058
% you want and report success and failure. A known limitation is that
2059
% inside another argument the last source code token must not be an
2060
% explicit space token---and, of course, using a listing inside another
2061
% argument is itself experimental, see section \ref{rListingsInsideArguments}.
2063
% \item[0.15,,changed] |\begin{|\texttt{\rstyle lstlisting}|}|\oarg{key=value list}
2065
% \leavevmode\hspace*{-\leftmargini}|\end{|\texttt{\rstyle lstlisting}|}|
2067
% typesets the code in between as a displayed listing.
2069
% In contrast to the environment of the \packagename{verbatim} package,
2070
% \LaTeX\ code on the same line and after the end of environment is
2071
% typeset respectively executed.
2073
% \item[0.1] \rcmdname\lstinputlisting\oarg{key=value list}\marg{file name}
2075
% typesets the stand alone source code file as a displayed listing.
2079
% \subsection{Space and placement}
2082
% \item[0.20,floatplacement,addon] \rkeyname{float}|=|[|*|]\meta{subset of \textup{\texttt{tbph}}}\syntaxor\rkeyname{float}
2084
% makes sense on individual displayed listings only and lets them float.
2085
% The argument controls where \LaTeX\ is \emph{allowed} to put the float:
2086
% at the top or bottom of the current/next page, on a separate page, or
2087
% here where the listing is.
2089
% The optional star can be used to get a double-column float in a
2090
% two-column document.
2092
% \item[0.21,tbp] \rkeyname{floatplacement}|=|\meta{place specifiers}
2094
% is used as place specifier if \keyname{float} is used without value.
2096
% \item[0.21,\medskipamount] \rkeyname{aboveskip}|=|\meta{dimension}
2097
% \item[0.21,\medskipamount] \rkeyname{belowskip}|=|\meta{dimension}
2099
% define the space above and below displayed listings.
2101
% \item[0.17,0pt,\dag] \rkeyname{lineskip}|=|\meta{dimension}
2103
% specifies additional space between lines in listings.
2105
% \item[0.18,c,\dag] \rkeyname{boxpos}|=|\meta{\alternative{b,c,t}}
2107
% Sometimes the \packagename{listings} package puts a |\hbox| around a
2108
% listing---or it couldn't be printed or even processed correctly.
2109
% The key determines the vertical alignment to the surrounding material:
2110
% bottom baseline, centered or top baseline.
2114
% \subsection{The printed range}
2117
% \item[0.12,true,changed] \rkeyname{print}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{print}
2119
% controls whether an individual displayed listing is typeset. Even if
2120
% set false, the respective caption is printed and the label is defined.
2122
% Note: If the package is loaded without the \texttt{draft} option, you
2123
% can use this key together with |\lstset|. In the other case the key
2124
% can only be used to typeset particular listings despite of the
2125
% \texttt{draft} option.
2127
% \item[0.1,1,renamed] \rkeyname{firstline}|=|\meta{number}
2128
% \item[0.1,9999999,renamed] \rkeyname{lastline}|=|\meta{number}
2130
% can be used on individual listings only. They determine the physical
2131
% input lines used to print displayed listings.
2133
% \item[0.20,false] \rkeyname{showlines}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{showlines}
2135
% If true, the package prints empty lines at the end of listings.
2136
% Otherwise these lines are dropped (but they count for line numbering).
2138
% \item[1.0] \rkeyname{emptylines}|=|[|*|]\meta{number}
2140
% sets the maximum of empty lines allowed. If there is a block of more
2141
% than \meta{number} empty lines, only \meta{number} ones are printed.
2142
% Without the optional star, line numbers can be disturb when blank
2143
% lines are omitted; with the star, the lines keep their original
2146
% \item[0.19,0] \rkeyname{gobble}|=|\meta{number}
2148
% gobbles \meta{number} characters at the beginning of each
2149
% \emph{environment} code line. This key has no effect on \cs{lstinline}
2150
% or \cs{lstinputlisting}.
2152
% Tabulators expand to \ikeyname{tabsize} spaces before they are gobbled.
2153
% Code lines with less than \ikeyname{gobble} characters are considered
2154
% empty, but never indent the end of environment by more characters.
2158
% \subsection{Languages and styles}\label{rLanguagesAndStyles}
2160
% Please note that the arguments \meta{language}, \meta{dialect}, and
2161
% \meta{style name} are case insensitive and that spaces have no effect.
2163
% \item[0.18,{{}}] \rkeyname{style}|=|\meta{style name}
2165
% activates the key=value list stored with |\lstdefinestyle|.
2167
% \item[0.19] \rcmdname\lstdefinestyle\marg{style name}\marg{key=value list}
2169
% stores the key=value list.
2171
% \item[0.17,{{}}] \rkeyname{language}|=|\oarg{dialect}\meta{language}
2173
% activates a (dialect of a) programming language. The `empty' default
2174
% language detects no keywords, no comments, no strings, and so on.
2175
% Without specifying \meta{dialect}, the package chooses a default
2178
% Table \ref{uPredefinedLanguages} on page \pageref{uPredefinedLanguages}
2179
% lists all languages and dialects provided by \texttt{lstdrvrs.dtx}.
2180
% The predefined default dialects are underlined.
2182
% \item[0.21] \rkeyname{alsolanguage}|=|\oarg{dialect}\meta{language}
2184
% selects the (dialect of a) programming language additionally to the
2185
% current active one. Note that some language definitions interfere with
2186
% each other and are plainly incompatible.
2188
% Take a look at the \ikeyname{classoffset} key in section
2189
% \ref{rFigureOutTheAppearance} if you want to highlight the keywords
2190
% of the languages differently.
2192
% \item[0.19] \rkeyname{defaultdialect}|=|\oarg{dialect}\meta{language}
2194
% defines \meta{dialect} as default dialect for \meta{language}.
2195
% If you have defined a default dialect other than empty, for example
2196
% |defaultdialect=[iama]fool|, you can't select the empty dialect, even
2197
% not with |language=[]fool|.
2200
% Eventually here's a small list of language specific keys.
2202
% \item[0.19,false,optional] \rkeyname{printpod}|=|\meta{\alternative{true,false}}
2204
% prints or drops PODs in Perl.
2206
% \item[0.20,true,\dag optional] \rkeyname{usekeywordsinside}|=|\meta{\alternative{true,false}}
2208
% The package either use the first order keywords for HTML or prints all
2209
% identifiers inside |<>| in keyword style.
2211
% \item[0.20,true,optional] \rkeyname{makemacrouse}|=|\meta{\alternative{true,false}}
2213
% Make specific: Macro use of identifiers, which are defined as first
2214
% order keywords, also prints the surrounding |$(| and |)| in keyword
2215
% style. e.g.~you could get
2216
% \textbf{\textdollar(}\textbf{strip} \textdollar(BIBS)\textbf{)}.
2217
% If deactivated you get
2218
% \textdollar(\textbf{strip} \textdollar(BIBS)).
2222
% \subsection{Figure out the appearance}\label{rFigureOutTheAppearance}
2225
% \item[0.18,{{}}] \rkeyname{basicstyle}|=|\meta{basic style}
2227
% is selected at the beginning of each listing. You could use
2228
% |\footnotesize|, |\small|, |\itshape|, |\ttfamily|, or something like
2229
% that. The last token of \meta{basic style} must not read any following
2232
% \item[0.18,{{}}] \rkeyname{identifierstyle}|=|\meta{style}
2233
% \item[0.11,\itshape] \rkeyname{commentstyle}|=|\meta{style}
2234
% \item[0.12,{{}}] \rkeyname{stringstyle}|=|\meta{style}
2236
% determine the style for non-keywords, comments, and strings. The
2237
% \emph{last} token might be an one-parameter command like |\textbf| or
2240
% \item[0.11,\bfseries] \rkeyname{keywordstyle}|=|\oarg{number}\meta{style}
2241
% \item[0.19,keywordstyle] \rkeyname{ndkeywordstyle}|=|\meta{style}
2243
% are used to print keywords and second order keywords (if defined).
2244
% The optional \meta{number} argument is the class number to which the
2245
% style should be applied.
2246
% |ndkeywordstyle=...| is equivalent to |keywordstyle=[2]...|.
2248
% \item[1.0,0] \rkeyname{classoffset}|=|\meta{number}
2250
% is added to all class numbers before the styles, keywords, identifiers,
2251
% etc.~are assigned. The example below defines the keywords directly;
2252
% you could do it indirectly by selection two different languages.
2255
% \begin{lstxsample}
2256
% \lstset{classoffset=0,
2257
% morekeywords={one,three,five},keywordstyle=\color{red},
2259
% morekeywords={two,four,six},keywordstyle=\color{blue},
2260
% classoffset=0}% restore default
2263
% \begin{lstxsample}
2264
% \lstset{classoffset=0,
2265
% morekeywords={one,three,five},keywordstyle=\itshape,
2267
% morekeywords={two,four,six},keywordstyle=\bfseries},
2268
% classoffset=0}% restore default
2271
% \begin{lstsample}{}{}
2272
% \begin{lstlisting}
2279
% \item[0.20,keywordstyle,optional] \rkeyname{texcsstyle}|=|\meta{style}
2280
% \item[0.20,keywordstyle,optional] \rkeyname{directivestyle}|=|\meta{style}
2282
% determine the style of \TeX\ control sequences and directives.
2283
% Note that these key are present only if you've chosen an appropriate
2286
% \item[0.21] \rkeyname{emph}|=|\oarg{number}\marg{identifier list}
2287
% \item[0.21] \rkeyname{moreemph}|=|\oarg{number}\marg{identifier list}
2288
% \item[0.21] \rkeyname{deleteemph}|=|\oarg{number}\marg{identifier list}
2289
% \item[0.21] \rkeyname{emphstyle}|=|\oarg{number}\marg{style}
2291
% define, add and remove the \meta{identifier list} from `emphasize
2292
% class \meta{number}' respectively define the style for that class.
2293
% If you don't give an optional argument, the package assumes
2294
% \meta{number}$\,=1$.
2296
% These keys are described more detailed in section
2297
% \ref{uEmphasizeIdentifiers}.
2299
% \item[1.0] \rkeyname{delim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt][\texttt[\meta{style}\texttt]]\meta{delimiter\textup(s\textup)}
2300
% \item[1.0] \rkeyname{moredelim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt][\texttt[\meta{style}\texttt]]\meta{delimiter\textup(s\textup)}
2301
% \item[1.0] \rkeyname{deletedelim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt]\meta{delimiter\textup(s\textup)}
2303
% deletes all previously defined delimiters (but neither strings nor
2304
% comments) and defines the user supplied delimiter, adds the specified
2305
% delimiter, or removes it.
2307
% In the first two cases \meta{style} is used to print the delimited
2308
% code (and the delimiters). Here, \meta{style} could be something like
2309
% |\bfseries| or |\itshape|, or it could refer to other styles via
2310
% \texttt{keywordstyle}, \texttt{keywordstyle2}, \texttt{emphstyle},
2313
% Supported types are \texttt{l} and \texttt{s}, see the comment keys in
2314
% section \ref{uLanguageDefinitions} for an explanation. If you use the
2315
% prefix \texttt i, i.e.~\texttt{il} or \texttt{is}, the delimiters are
2316
% not printed, which is some kind of invisibility.
2318
% If you use one optional star, the package will detect keywords,
2319
% comments, and strings inside the delimited code. With both optional
2320
% stars, aditionally the style is applied cumulative, see section
2321
% \ref{uDelimiters}.
2325
% \subsection{Getting all characters right}
2328
% \item[0.18,false] \rkeyname{extendedchars}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{extendedchars}
2330
% allows or prohibits extended characters in listings, that means
2331
% (national) characters of codes 128--255. If you use extended
2332
% characters, you should load \packagename{fontenc} and/or
2333
% \packagename{inputenc}, for example.
2335
% \item[1.0,{{}}] \rkeyname{inputencoding}|=|\meta{encoding}
2337
% determines the input encoding. The usage of this key requires the
2338
% \packagename{inputenc} package; nothing happens if it's not loaded.
2340
% \item[0.12,8] \rkeyname{tabsize}|=|\meta{number}
2342
% sets tabulator stops at columns $\meta{number}+1$, $2\cdot\meta{number}+1$, $3\cdot\meta{number}+1$, and so on.
2343
% Each tabulator in a listing moves the current column to the next
2346
% \item[0.20,false,renamed] \rkeyname{showtabs}|=|\meta{\alternative{true,false}}
2348
% make tabulators visible or invisible. A visible tabulator looks like
2349
% \lstinline[showtabs]! !, but that can be changed. If you choose
2350
% invisible tabulators but visible spaces, tabulators are converted to
2351
% an appropriate number of spaces.
2353
% \item[0.20] \rkeyname{tab}|=|\meta{tokens}
2355
% \meta{tokens} is used to print a visible tabulator. You might want to use |$\to$|, |$\mapsto$|, |$\dashv$| or something like that instead of the strange default definition.
2357
% \item[0.20,false,renamed] \rkeyname{showspaces}|=|\meta{\alternative{true,false}}
2359
% lets all blank spaces appear {\textvisiblespace} or as blank spaces.
2361
% \item[0.12,true,renamed] \rkeyname{showstringspaces}|=|\meta{\alternative{true,false}}
2363
% lets blank spaces in strings appear {\textvisiblespace} or as blank
2366
% \item[0.19,\bigbreak] \rkeyname{formfeed}|=|\meta{tokens}
2368
% Whenever a listing contains a form feed \meta{tokens} is executed.
2372
% \subsection{Line numbers}\label{rLineNumbers}
2375
% \item[1.0,none] \rkeyname{numbers}|=|\meta{\alternative{none,left,right}}
2377
% makes the package either print no line numbers, or put them on the
2378
% left or the right side of a listing.
2380
% \item[0.16,1,renamed] \rkeyname{stepnumber}|=|\meta{number}
2382
% All lines with ``line number $\equiv 0$ modulo \meta{number}'' get a
2384
% If you turn line numbers on and off with \keyname{numbers}, the
2385
% parameter \keyname{stepnumber} will keep its value. Alternatively you
2386
% can turn them off via |stepnumber=0| and on with a nonzero number and
2387
% keep the value of \keyname{numbers}.
2389
% \item[0.16,{{}},renamed] \rkeyname{numberstyle}|=|\meta{style}
2391
% determines the font and size of the numbers.
2393
% \item[0.19,10pt,renamed] \rkeyname{numbersep}|=|\meta{dimension}
2395
% is the distance between number and listing.
2397
% \item[1.0,true] \rkeyname{numberblanklines}|=|\meta{\alternative{true,false}}
2399
% If this is set to false, blank lines get no printed line number.
2401
% \item[0.20,auto,{renamed,addon}] \rkeyname{firstnumber}|=|\meta{\alternative{auto,last,\normalfont\meta{number}}}
2403
% \texttt{auto} lets the package choose the first number: a new listing
2404
% starts with number one, a named listing continues the most recent
2405
% same-named listing (see below), and a stand alone file begins with
2406
% the number corresponding to the first input line.
2408
% \texttt{last} continues the numbering of the most recent listing and
2409
% \meta{number} sets it to the number.
2411
% \item[1.0] \rkeyname{name}|=|\meta{name}
2413
% names a listing. Displayed environment-listings with the same name
2414
% share a line counter.
2416
% \item[0.20,\arabic{lstnumber},{renamed,data}] \rcmdname\thelstnumber
2418
% prints the lines' numbers.
2420
% We show an example on how to redefine |\thelstnumber|. But if you test it,
2421
% you won't get the result shown on the left.
2422
% \begin{lstxsample}
2423
% \renewcommand*\thelstnumber{\oldstylenums{\the\value{lstnumber}}}
2425
% \begin{lstsample}{\lstset{stepnumber=-1}\label{rDecreasingLabels}}{}
2426
% \begin{lstlisting}[numbers=left,
2428
% begin { empty lines }
2435
% end; { empty lines }
2441
% The example shows a sequence $n,n+1,\ldots,n+7$ of 8 three-digit figures such that the sequence contains each digit $0,1,\ldots,9$.
2442
% But 8 is not minimal with that property.
2443
% Find the minimal number and prove that it is minimal.
2444
% How many minimal sequences do exist?
2446
% Now look at the generalized problem:
2447
% Let $k\in\{1,\ldots,10\}$ be given.
2448
% Find the minimal number $m\in\{1,\ldots,10\}$ such that there is a sequence $n,{n+1},\ldots,\allowbreak{n+m-1}$ of $m$ $k$-digit figures which contains each digit $\{0,\ldots,9\}$.
2449
% Prove that the number is minimal.
2450
% How many minimal sequences do exist?
2452
% If you solve this problem with a computer, write a \TeX\ program!
2456
% \subsection{Captions}
2458
% In despite of \LaTeX\ standard behaviour, captions and floats are independent
2459
% from each other here; you can use captions with non-floating listings.
2461
% \item[0.21] \rkeyname{title}|=|\meta{title text}
2463
% is used for a title without any numbering or label.
2465
% \item[0.20] \rkeyname{caption}|={|\oarg{short}\meta{caption text}|}|
2467
% The caption is made of \cs{lstlistingname} followed by a running
2468
% number, a seperator, and \meta{caption text}. Either the caption text
2469
% or, if present, \meta{short} will be used for the list of listings.
2471
% \item[0.21] \rkeyname{label}|=|\meta{name}
2473
% makes a listing referable via |\ref|\marg{name}.
2475
% \item[0.16] \rcmdname\lstlistoflistings
2477
% prints a list of listings. Each entry is with descending priority
2478
% either the short caption, the caption, the file name or the name of the
2479
% listing, see also the key \keyname{name} in section \ref{rLineNumbers}.
2481
% \item[1.0] \rkeyname{nolol}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{nolol}
2483
% If true, the listing does not make it into the list of listings.
2485
% \item[0.16,Listings,data] \rcmdname\lstlistlistingname
2487
% The header name for the list of listings.
2489
% \item[0.20,Listing,data] \rcmdname\lstlistingname
2491
% The caption label for listings.
2493
% \item[0.20,\arabic{lstlisting},data] \rcmdname\thelstlisting
2495
% prints the running number of the caption.
2497
% \item[0.19,,re-introduced] \rcmdname\lstname
2499
% prints the name of the current listing which is either the file name or
2500
% the name defined by the \keyname{name} key. This command can be used to
2501
% define a caption or title template, for example by
2502
% |\lstset{caption=\lstname}|.
2504
% \item[0.20,t] \rkeyname{captionpos}|=|\meta{subset of \textup{\texttt{tb}}}
2506
% specifies the positions of the caption: top and/or bottom of the
2509
% \item[0.20,\smallskipamount] \rkeyname{abovecaptionskip}|=|\meta{dimension}
2510
% \item[0.20,\smallskipamount] \rkeyname{belowcaptionskip}|=|\meta{dimension}
2512
% is the vertical space above respectively below each caption.
2516
% \subsection{Margins and line shape}\label{rMarginsAndLineShape}
2519
% \item[0.21,\linewidth] \rkeyname{linewidth}|=|\meta{dimension}
2521
% defines the base line width for listings. The following three keys are
2522
% taken into account additionally.
2524
% \item[0.19,0pt,renamed] \rkeyname{xleftmargin}|=|\meta{dimension}
2525
% \item[1.0,0pt] \rkeyname{xrightmargin}|=|\meta{dimension}
2527
% The dimensions are used as extra margins on the left and right. Line
2528
% numbers and frames both move respectively shrink or grow accordingly.
2530
% \item[0.19,false,renamed] \rkeyname{resetmargins}|=|\meta{\alternative{true,false}}
2532
% If true indention from list environments like \texttt{enumerate} or
2533
% \texttt{itemize} is reset, i.e.~not used.
2535
% \item[0.20,false] \rkeyname{breaklines}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{breaklines}
2537
% activates or deactivates automatic line breaking of long lines.
2539
% \item[0.20,{{}}] \rkeyname{prebreak}|=|\meta{tokens}
2540
% \item[0.20,{{}}] \rkeyname{postbreak}|=|\meta{tokens}
2542
% \meta{tokens} appear at the end of the current line respectively at the beginning of the next (broken part of the) line.
2544
% You must not use dynamic space (in particular spaces) since internally we use |\discretionary|.
2545
% However |\space| is redefined to be used inside \meta{tokens}.
2547
% \item[0.20,20pt] \rkeyname{breakindent}|=|\meta{dimension}
2549
% is the indention of the second, third, \ldots\ line of broken lines.
2551
% \item[0.20,true] \rkeyname{breakautoindent}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{breakautoindent}
2553
% activates or deactivates automatic indention of broken lines. This
2554
% indention is used additionally to \ikeyname{breakindent}, see the
2556
% Visible spaces or visible tabulators might set this auto
2557
% indention to zero.
2559
% In the following example we use tabulators to create long lines, but the
2560
% verbatim part uses |tabsize=1|.
2561
% \begin{lstxsample}
2562
% \lstset{postbreak=\space, breakindent=5pt, breaklines}
2564
% \begin{lstsample}{\lstset{string=[d]",tabsize=6}}{\lstset{tabsize=1}\hfuzz=1in}
2565
% \begin{lstlisting}
2566
% "A long string is broken!"
2567
% "Another long line."
2570
% \begin{lstlisting}[breakautoindent
2572
% { Now auto indention is off. }
2577
% \subsection{Frames}\label{rFrames}
2580
% \item[1.0,none] \rkeyname{frame}|=|\meta{\alternative{none,leftline,topline,bottomline,lines,single,shadowbox}}
2582
% draws either no frame, a single line on the left, at the top, at the
2583
% bottom, at the top and bottom, a whole single frame, or a shadowbox.
2585
% Note that \packagename{fancyvrb} supports the same frame types except
2586
% \texttt{shadowbox}. The shadow color is \keyname{rulesepcolor}, see
2589
% \item[0.19,{{}},changed] \rkeyname{frame}|=|\meta{subset of \textup{\texttt{trblTRBL}}}
2591
% The characters \texttt{trblTRBL} are attached to lines at the top and
2592
% bottom of a listing and to lines on the right and left. Upper case
2593
% characters are used to draw double rules. So |frame=tlrb| draws a
2594
% single frame and |frame=TL| double lines at the top and on the left.
2596
% Note that frames usually reside outside the listing's space.
2598
% \item[0.20,ffff] \rkeyname{frameround}|=|\meta{\alternative{t,f}}\meta{\alternative{t,f}}\meta{\alternative{t,f}}\meta{\alternative{t,f}}
2600
% The four letters are attached to the top right, bottom right, bottom
2601
% left and top left corner. In this order. \texttt{t} makes the
2602
% according corner round. If you use round corners, the rule width is
2603
% controlled via |\thinlines| and |\thicklines|.
2605
% Note: The size of the quarter circles depends on \keyname{framesep}
2606
% and is independent of the extra margins of a frame. The size is
2607
% possibly adjusted to fit \LaTeX's circle sizes.
2609
% \item[0.19,3pt,renamed] \rkeyname{framesep}|=|\meta{dimension}
2610
% \item[0.19,2pt,renamed] \rkeyname{rulesep}|=|\meta{dimension}
2612
% control the space between frame and listing and between double rules.
2614
% \item[0.19,0.4pt,renamed] \rkeyname{framerule}|=|\meta{dimension}
2616
% controls the width of the rules.
2618
% \item[1.0,0pt] \rkeyname{framexleftmargin}|=|\meta{dimension}
2619
% \item[1.0,0pt] \rkeyname{framexrightmargin}|=|\meta{dimension}
2620
% \item[1.0,0pt] \rkeyname{framextopmargin}|=|\meta{dimension}
2621
% \item[1.0,0pt] \rkeyname{framexbottommargin}|=|\meta{dimension}
2623
% are the dimensions which are used additionally to \keyname{framesep}
2624
% to make up the margin of a frame.
2626
% \item[0.21,,changed] \rkeyname{backgroundcolor}|=|\meta{color command}
2627
% \item[0.21,,{renamed,changed}] \rkeyname{rulecolor}|=|\meta{color command}
2628
% \item[1.0] \rkeyname{fillcolor}|=|\meta{color command}
2629
% \item[1.0] \rkeyname{rulesepcolor}|=|\meta{color command}
2631
% specify the colour of the background, the rules, the space between
2632
% `text box' and first rule, and of the space between two rules,
2634
% Note that the value requires a |\color| command, for example
2635
% \keyname{rulecolor}|=\color{blue}|.
2637
% \ikeyname{frame} does not work with |fancyvrb=true| or when the package
2638
% internally makes a |\hbox| around the listing! And there are certainly more
2639
% problems with other commands. Take the time to make a (bug) report.
2641
% \begin{lstxsample}
2642
% \lstset{framexleftmargin=5mm, frame=shadowbox, rulesepcolor=\color{blue}}
2645
% \lstset{framexleftmargin=5mm, frame=shadowbox}
2647
% \begin{lstsample}{}{}
2648
% \begin{lstlisting}[numbers=left]
2649
% for i:=maxint to 0 do
2656
% Do you want exotic frames?
2657
% Try the following key if you want for example
2658
% \begin{lstsample}{\lstset{frameshape={RYRYNYYYY}{yny}{yny}{RYRYNYYYY}}}{}
2659
% \begin{lstlisting}
2660
% for i:=maxint to 0 do
2667
% \item[0.20,,\dag] \rkeyname{frameshape}|=|\marg{top shape}\marg{left shape}\marg{right shape}\marg{bottom shape}
2669
% gives you full control over the drawn frame parts.
2670
% The arguments are not case sensitive.
2672
% Both \meta{left shape} and \meta{right shape} are `left-to-right'
2673
% \alternative{y,n} character sequences (or empty). Each |y| lets the
2674
% package draw a rule, otherwise the rule is blank. These vertical rules
2675
% are drawn `left-to-right' according to the specified shapes.
2676
% The example above uses |yny|.
2678
% \meta{top shape} and \meta{bottom shape} are `left-rule-right'
2679
% sequences (or empty). The first `left-rule-right' sequence is attached
2680
% to the most inner rule, the second to the next, and so on.
2681
% Each sequence has three characters: `rule' is either |y| or |n|;
2682
% `left' and `right' are |y|, |n| or |r| (which makes a corner round).
2683
% The example uses |RYRYNYYYY| for both shapes:
2684
% |RYR| describes the most inner (top and bottom) frame shape, |YNY|
2685
% the middle, and |YYY| the most outer.
2687
% To summarize, the example above used
2689
% \lstset{frameshape={RYRYNYYYY}{yny}{yny}{RYRYNYYYY}}\end{verbatim}
2690
% Note that you are not resticted to two or three levels.
2691
% However you'll get in trouble if you use round corners when they are too big.
2694
% \subsection{Indexing}
2697
% \item[0.19] \rkeyname{index}|=|\oarg{number}\oarg{keyword classes}\marg{identifiers}
2698
% \item[0.21] \rkeyname{moreindex}|=|\oarg{number}\oarg{keyword classes}\marg{identifiers}
2699
% \item[0.21] \rkeyname{deleteindex}|=|\oarg{number}\oarg{keyword classes}\marg{identifiers}
2701
% define, add and remove \meta{identifiers} and \meta{keyword classes}
2702
% from the index class list \meta{number}. If you don't specify the
2703
% optional number, the package assumes \meta{number} $=1$.
2705
% Each appearance of the explicitly given identifiers and each appearance
2706
% of the identifiers of the specified \meta{keyword classes} is indexed.
2707
% For example, you could write |index=[1][keywords]| to index all
2708
% keywords. Note that |[1]| is required here---otherwise we couldn't use
2709
% the second optional argument.
2711
% \item[0.19,\lstindexmacro] \rkeyname{indexstyle}|=|\oarg{number}\meta{tokens \textup(one-parameter command\textup)}
2713
% \meta{tokens} actually indexes the identifiers for the list
2714
% \meta{number}. In contrast to the style keys, \meta{tokens}
2715
% \emph{must} read exactly one parameter, namely the identifier.
2716
% Default definition is\icmdname{\lstindexmacro}\vspace*{-\itemsep}
2718
% \newcommand\lstindexmacro[1]{\index{{\ttfamily#1}}}\end{verbatim}
2719
% \vspace*{-\itemsep}which you shouldn't modify.
2720
% Define your own indexing commands and use them as argument to this key.
2722
% Section \ref{uIndexing} describes this feature in detail.
2725
% \subsection{Column alignment}\label{rColumnAlignment}
2728
% \item[1.0,{[c]fixed}] \rkeyname{columns}|=|\oarg{\alternative{c,l,r}}\meta{\alternative{fixed,flexible,fullflexible}}
2730
% selects the respective column format, refer section
2731
% \ref{uFixedAndFlexibleColumns}.
2733
% The optional |c|, |l|, or |r| controls the horizontal orientation of
2734
% smallest output units (keywords, identifiers, etc.). The arguments work
2735
% as follows, where vertical bars visualize the effect:
2736
% $\vert$\lstinline[columns={[c]fixed}]!listing!$\vert$,
2737
% $\vert$\lstinline[columns={[l]fixed}]!listing!$\vert$, and
2738
% $\vert$\lstinline[columns={[r]fixed}]!listing!$\vert$
2739
% in fixed column mode,
2740
% $\vert$\lstinline[columns={[c]flexible}]!listing!$\vert$,
2741
% $\vert$\lstinline[columns={[l]flexible}]!listing!$\vert$, and
2742
% $\vert$\lstinline[columns={[r]flexible}]!listing!$\vert$
2743
% with flexible columns, and
2744
% $\vert$\lstinline[columns={[c]fullflexible}]!listing!$\vert$,
2745
% $\vert$\lstinline[columns={[l]fullflexible}]!listing!$\vert$, and
2746
% $\vert$\lstinline[columns={[r]fullflexible}]!listing!$\vert$
2747
% with full flexible columns.
2749
% \item[0.18,false] \rkeyname{flexiblecolumns}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{flexiblecolumns}
2751
% selects the most recently selected flexible or fixed column format,
2752
% refer to section \ref{uFixedAndFlexibleColumns}.
2754
% \item[0.21,false,\dag] \rkeyname{keepspaces}|=|\meta{\alternative{true,false}}
2756
% |keepspaces=true| tells the package not to drop spaces to fix column
2757
% alignment and always converts tabulators to spaces.
2759
% \item[0.16] \rkeyname{basewidth}|=|\meta{dimension}\syntaxor
2760
% \item[0.18,{{0.6em,0.45em}}] \rkeyname{basewidth}|={|\meta{fixed}|,|\meta{flexible mode}|}|
2762
% sets the width of a single character box for fixed and flexible column
2763
% mode (both to the same value or individually).
2765
% \item[0.20,false] \rkeyname{fontadjust}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{fontadjust}
2767
% If true the package adjusts the base width every font selection.
2768
% This makes sense only if \ikeyname{basewidth} is given in font specific
2769
% units like `em' or `ex'---otherwise this boolean has no effect.
2771
% After loading the package, it doesn't adjust the width every font
2772
% selection: it looks at \ikeyname{basewidth} each listing and uses the
2773
% value for the whole listing. This is possibly inadequate if the style
2774
% keys in section \ref{rFigureOutTheAppearance} make heavy font size
2775
% changes, see the example below.
2777
% Note that this key might disturb the column alignment and might have an
2778
% effect on the keywords' appearance!
2780
% \begin{lstsample}{\lstset{basicstyle=\normalsize}}{}
2781
% \lstset{commentstyle=\scriptsize}
2782
% \begin{lstlisting}
2784
% doesn't look good }
2785
% for i:=maxint to 0 do
2791
% \begin{lstsample}{\lstset{basicstyle=\normalsize,commentstyle=\scriptsize}}{}
2792
% \begin{lstlisting}[fontadjust]
2794
% looks better now }
2795
% for i:=maxint to 0 do
2803
% \subsection{Escaping to \LaTeX}\label{rEscapingToLaTeX}
2805
% \textbf{Note:} {\itshape Any escape to \LaTeX\ may disturb the column
2806
% alignment since the package can't control the spacing there.}
2808
% \item[0.18,false] \rkeyname{texcl}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{texcl}
2810
% activates or deactivates \LaTeX\ comment lines. If activated, comment
2811
% line delimiters are printed as usual, but the comment line text (up to
2812
% the end of line) is read as \LaTeX\ code and typeset in comment style.
2814
% The example uses \Cpp\ comment lines (but doesn't say how to define them).
2815
% Without |\upshape| we would get \textit{calculate} since the comment style
2817
% \begin{lstsample}{\lstset{morecomment=[l]//}}{}
2818
% \begin{lstlisting}[texcl]
2819
% // \upshape calculate $a_{ij}$
2820
% A[i][j] = A[j][j]/A[i][j];
2825
% \item[0.19,false] \rkeyname{mathescape}|=|\meta{\alternative{true,false}}
2827
% activates or deactivates special behaviour of the dollar sign.
2828
% If activated a dollar sign acts as \TeX's text math shift.
2830
% This key is useful if you want to typeset formulas in listings.
2832
% \item[0.19,{{}}] \rkeyname{escapechar}|=|\meta{character}\syntaxor\rkeyname{escapechar}|={}|
2834
% If not empty the given character escapes the user to \LaTeX: all code
2835
% between two such characters is interpreted as \LaTeX\ code. Note that
2836
% \TeX's special characters must be entered with a preceding backslash,
2837
% e.g.~|escapechar=\%|.
2839
% \item[0.20,{{}}] \rkeyname{escapeinside}|=|\meta{character}\meta{character}\syntaxor\rkeyname{escapeinside}|={}|
2841
% Is a generalization of \ikeyname{escapechar}. If the value is not
2842
% empty, the package escapes to \LaTeX\ between the first and second
2845
% \item[0.20,{{}}] \rkeyname{escapebegin}|=|\meta{tokens}
2846
% \item[0.20,{{}}] \rkeyname{escapeend}|=|\meta{tokens}
2848
% The tokens are executed at the beginning respectively at the end of
2849
% each escape, in particular for \ikeyname{texcl}.
2850
% See section \ref{uNationalCharacters} for an application.
2853
% \begin{lstsample}{\lstset{morecomment=[l]//}}{}
2854
% \begin{lstlisting}[mathescape]
2855
% // calculate $a_{ij}$
2856
% $a_{ij} = a_{jj}/a_{ij}$;
2860
% \begin{lstsample}{\lstset{morecomment=[l]//}}{}
2861
% \begin{lstlisting}[escapechar=\%]
2862
% // calc%ulate $a_{ij}$%
2863
% %$a_{ij} = a_{jj}/a_{ij}$%;
2867
% \begin{lstsample}{\lstset{morecomment=[l]//}}{}
2868
% \lstset{escapeinside=`'}
2869
% \begin{lstlisting}
2870
% // calc`ulate $a_{ij}$'
2871
% `$a_{ij} = a_{jj}/a_{ij}$';
2874
% In the first example the comment line up to $a_{ij}$ has been typeset by the
2875
% \packagename{listings} package in comment style. The $a_{ij}$ itself is
2876
% typeset in `\TeX\ math mode' without comment style. About the half
2877
% comment line of the second example has been typeset by this package.
2878
% The rest is in `\LaTeX\ mode'.
2880
% To avoid problems with the current and future version of this package:
2882
% \item Don't use any command of the \packagename{listings} package when you
2883
% have escaped to \LaTeX.
2884
% \item Any environment must start and end inside the same escape.
2885
% \item You might use |\def|, |\edef|, etc., but do not assume that the
2886
% definitions are present later---except they are |\global|.
2887
% \item |\if \else \fi|, groups, math shifts |$| and |$$|, \ldots\ must be
2888
% balanced each escape.
2891
% Expand that list yourself and mail me about new items.
2894
% \subsection{Interface to \textsf{fancyvrb}}
2896
% The \packagename{fancyvrb} package---fancy verbatims---from Timothy van Zandt
2897
% provides macros for reading, writing and typesetting verbatim code. It has
2898
% some remarkable features the \packagename{listings} package doesn't have.
2899
% (Some are possible, but you must find somebody who implements them ; -- ).
2901
% \item[0.19,,bug] \rkeyname{fancyvrb}|=|\meta{\alternative{true,false}}
2903
% activates or deactivates the interface. If active, verbatim code is
2904
% read by \packagename{fancyvrb} but typeset by \packagename{listings},
2905
% i.e.~with emphasized keywords, strings, comments, and so on.
2906
% Internally we use a very special definition of |\FancyVerbFormatLine|.
2908
% This interface works with |Verbatim|, |BVerbatim| and |LVerbatim|.
2909
% But you shouldn't use \packagename{fancyvrb}'s \keyname{defineactive}.
2910
% (As far as I can see it doesn't matter since it does nothing at all,
2911
% but for safety \ldots)
2912
% If \packagename{fancyvrb} and \packagename{listings} provide similar
2913
% functionality, you should use \packagename{fancyvrb}'s.
2915
% Bug (\keyname{commandchars}): If you use \packagename{fancyvrb}'s
2916
% \keyname{commandchars}, the used commands must not take arguments from
2917
% the verbatim code except the source code which is actually typeset.
2918
% For example, |\textcolor{red}{keyword}| is illegal since |red| is (used
2919
% to select the colour and) not typeset. There is an easy work-around:
2920
% write |\newcommand*\myred{\textcolor{red}}| and use |\myred{keyword}|
2921
% inside the verbatim code.
2925
% \begin{lstsample}{}{}
2926
% \lstset{morecomment=[l]\ }% :-)
2927
% \fvset{commandchars=\\\{\}}
2930
% First verbatim line.
2931
% \fbox{Second} verbatim line.
2934
% \par\vspace{72.27pt}
2938
% First verbatim line.
2939
% \fbox{Second} verbatim line.
2941
% \lstset{fancyvrb=false}
2943
% The lines typeset by the \packagename{listings} package are wider since the
2944
% default \ikeyname{basewidth} equals not the width of a single typewriter type
2945
% character. Moreover note that the first space begins a comment as defined at
2946
% the beginning of the example.
2949
% \packagename{fancyvrb} seems to be unavailable on your platform, thus the
2950
% example couldn't be printed here.
2955
% \subsection{Environments}\label{rEnvironments}
2957
% If you want to define your own pretty-printing environments, try the
2958
% following command. The syntax comes from \LaTeX's |\newenvironment|.
2960
% \item[0.19] \rcmdname\lstnewenvironment\\
2961
% \marg{name}\oarg{number}\oarg{opt.~default~arg.}\\
2962
% |{|\meta{starting code}|}|\\
2963
% |{|\meta{ending code}|}|
2965
% As a simple example we could just select a particular language.
2966
% \begin{lstxsample}
2967
% \lstnewenvironment{pascal}
2968
% {\lstset{language=pascal}}
2971
% \begin{lstsample}{}{}
2973
% for i:=maxint to 0 do
2979
% Doing other things is as easy, for example, using more keys and adding an
2980
% optional argument to adjust settings each listing:
2982
%\lstnewenvironment{pascalx}[1][]
2983
% {\lstset{language=pascal,numbers=left,numberstyle=\tiny,float,#1}}
2987
% \subsection{Language definitions}\label{rLanguageDefinitions}
2989
% You should first read section \ref{uLanguageDefinitions} for an introduction
2990
% to language definitions. Otherwise you're probably unprepared for the full
2991
% syntax of |\lstdefinelanguage|.
2993
% \item[0.19] \rcmdname\lstdefinelanguage\syntaxnewline[\oarg{dialect}]\marg{language}\syntaxnewline[\oarg{base dialect}\marg{and base language}]\syntaxnewline\marg{key=value list}\syntaxnewline[\oarg{list of required aspects \textup(keywordcomments,texcs,etc.\textup)}]
2995
% defines the (given dialect of the) programming language \meta{language}.
2996
% If the language definition is based on another definition, you must
2997
% specify the whole \oarg{base dialect}\marg{and base language}. Note
2998
% that an empty \meta{base dialect} uses the default dialect!
3000
% The last optional argument should specify all required aspects. This is
3001
% a delicate point since the aspects are described in the developer's
3002
% guide. You might use existing languages as templates. For example,
3003
% ANSI C uses \aspectname{keywords}, \aspectname{comments},
3004
% \aspectname{strings} and \aspectname{directives}.
3006
% \icmdname{\lst@definelanguage} has the same syntax and is used to
3007
% define languages in the driver files.
3010
% \item Where should I put my language definition?
3012
% If you need the language for one particular document, put it into
3013
% the preamble of that document. Otherwise create the local file
3014
% `\texttt{lstlang0.sty}' or add the definition to that file, but use
3015
% `|\lst@definelanguage|' instead of `|\lstdefinelanguage|'.
3016
% However, you might want to send the definition to the address in
3017
% section \ref{uSoftwareLicense}. Then it will be published under the
3018
% \LaTeX\ Project Public License.
3021
% \item[0.18] \rcmdname\lstalias\marg{alias}\marg{language}
3023
% defines an alias for a programming language. Each \meta{alias} is
3024
% redirected to the same dialect of \meta{language}.
3025
% It's also possible to define an alias for one particular dialect only:
3027
% \item[0.18] \rcmdname\lstalias\oarg{alias dialect}\marg{alias}\oarg{dialect}\marg{language}
3029
% Here all four parameters are \emph{nonoptional} and an alias with empty
3030
% \meta{dialect} will select the default dialect. Note that aliases
3031
% can't be nested: The two aliases `|\lstalias{foo1}{foo2}|' and
3032
% `|\lstalias{foo2}{foo3}|' redirect |foo1| \emph{not} to |foo3|.
3034
% All remaining keys in this section are intended to build language
3035
% definitions. \emph{No other key should be used in such a definition!}
3038
% \paragraph{Keywords}
3039
% We begin with keyword building keys. Note: {\itshape If you want to enter
3040
% {\upshape|\|, |{|, |}|, |%|, |#|} or {\upshape|&|} inside or as an argument
3041
% here or below, you must do it with a preceding backslash!}
3043
% \item[1.0,,{\dag bug}] \rkeyname{keywordsprefix}|=|\meta{prefix}
3045
% All identifiers starting with \meta{prefix} will be printed as first
3048
% Bugs: Currently there are several limitations.
3049
% (1) The prefix is always case sensitive.
3050
% (2) Only one prefix can be defined at the same time.
3051
% (3) If used `standalone', the key might work only after selecting a
3052
% nonempty language (and switching back to the empty language if
3054
% (4) The key does not respect the value of \keyname{classoffset} and
3055
% has no optional class \meta{number} argument.
3057
% \item[0.11] \rkeyname{keywords}|=|\oarg{number}\marg{list of keywords}
3058
% \item[0.11] \rkeyname{morekeywords}|=|\oarg{number}\marg{list of keywords}
3059
% \item[0.18] \rkeyname{deletekeywords}|=|\oarg{number}\marg{list of keywords}
3061
% define, add to or remove the keywords from keyword list \meta{number}.
3062
% The use of \keyname{keywords} is discouraged since it deletes all
3063
% previously defined keywords in the list and is thus incompatible with
3064
% the \keyname{alsolanguage} key.
3066
% Please note the keys \ikeyname{alsoletter} and \ikeyname{alsodigit}
3067
% below if you use unusual charaters in keywords.
3069
% \item[0.19] \rkeyname{ndkeywords}|=|\marg{list of keywords}
3070
% \item[0.19] \rkeyname{morendkeywords}|=|\marg{list of keywords}
3071
% \item[0.19] \rkeyname{deletendkeywords}|=|\marg{list of keywords}
3073
% define, add to or remove the keywords from keyword list 2.
3074
% The use of \keyname{ndkeywords} is discouraged.
3076
% \item[0.19,,optional] \rkeyname{texcs}|=|\marg{list of control sequences \textup(without backslashes\textup)}
3077
% \item[0.20,,optional] \rkeyname{moretexcs}|=|\marg{list of control sequences \textup(without backslashes\textup)}
3078
% \item[0.21,,optional] \rkeyname{deletetexcs}|=|\marg{list of control sequences \textup(without backslashes\textup)}
3080
% Ditto for control sequences in \TeX\ and \LaTeX.
3082
% \item[0.18,,optional] \rkeyname{directives}|=|\marg{list of compiler directives}
3083
% \item[0.21,,optional] \rkeyname{moredirectives}|=|\marg{list of compiler directives}
3084
% \item[0.21,,optional] \rkeyname{deletedirectives}|=|\marg{list of compiler directives}
3086
% defines compiler directives in C, \Cpp, Objective-C, and POV.
3088
% \item[0.14] \rkeyname{sensitive}|=|\meta{\alternative{true,false}}
3090
% makes the keywords, control sequences, and directives case sensitive
3091
% and insensitive, respectively. This key affects the keywords, control
3092
% sequences, and directives only when a listing is processed. In all
3093
% other situations they are case sensitive, for example,
3094
% |deletekeywords={save,Test}| removes `save' and `Test', but neither
3095
% `SavE' nor `test'.
3097
% \item[0.19] \rkeyname{alsoletter}|=|\marg{character sequence}
3098
% \item[0.19] \rkeyname{alsodigit}|=|\marg{character sequence}
3099
% \item[0.19] \rkeyname{alsoother}|=|\marg{character sequence}
3101
% All identifiers (keywords, directives, and such) begin with a letter
3102
% and goes on with alpha-numeric characters (letters and digits).
3103
% For example, if you write
3104
% |keywords={one-two,\#include}|,
3105
% the minus must become a digit and the sharp a letter since the
3106
% keywords can't be detected otherwise.
3108
% Table \ref{rStdCharTable} show the standard configuration of the
3109
% \packagename{listings} package. The three keys overwrite the default
3110
% behaviour. Each character of the sequence becomes a letter, digit
3111
% and other, respectively.
3113
% \item[0.20] \rkeyname{otherkeywords}|=|\marg{keywords}
3115
% Each given `keyword' is printed in keyword style, but without changing
3116
% the `letter', `digit' and `other' status of the characters. This key
3117
% is designed to define keywords like |=>|, |->|, |-->|, |--|, |::|, and
3118
% so on. If one keyword is a subsequence of another (like |--| and
3119
% |-->|), you must specify the shorter first.
3121
% \item[0.20,,{\dag optional}] \rkeyname{keywordsinside}|=|\meta{character}\meta{character}\syntaxor\rkeyname{keywordsinside}|={}|
3123
% The first order keywords are active only between the first and second
3124
% character. This key is used for HTML.
3128
% \caption{Standard character table}\label{rStdCharTable}
3129
% \begin{tabular}{ll}
3130
% class & characters\\
3131
% \noalign{\smallskip}
3132
% letter & \texttt{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}\\
3133
% & \texttt{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}\\
3134
% & \texttt{@ \textdollar\ } |_|\\
3135
% digit & \texttt{0 1 2 3 4 5 6 7 8 9}\\
3136
% other & \texttt{!\ " \#\ \%\ \&\ ' ( ) * + , - .\ / :\ ; < = > ?}\\
3137
% & {\catcode`\|=12\texttt{[ \char92\ ] \textasciicircum\ \char123\ | \char125\ \textasciitilde}}\\
3139
% tabulator & chr(9)\\
3140
% form feed & chr(12)\\
3141
% \noalign{\smallskip}
3144
% Note: Extended characters of codes 128--255 (if defined) are \emph{currently}
3149
% \paragraph{Strings}
3151
% \item[0.12] \rkeyname{string}|=|\oarg{\alternative{b,d,m,bd}}\marg{delimiter \textup(character\textup)}
3152
% \item[0.21] \rkeyname{morestring}|=|\oarg{\alternative{b,d,m,bd}}\marg{delimiter}
3153
% \item[0.21] \rkeyname{deletestring}|=|\oarg{\alternative{b,d,m,bd}}\marg{delimiter}
3155
% define, add to or delete the delimiter from the list of string
3156
% delimiters. Starting and ending delimiters are the same, i.e.~in the
3157
% source code the delimiters must match each other.
3159
% The optional argument is the type and controls how the delimiter itself
3160
% is represented in a string or character literal: it is escaped by a
3161
% |b|ackslash, |d|oubled (or both is allowed via |bd|) or it is
3163
% The latter one is a special type for Ada and Matlab and possibly more
3164
% languages where the string delimters are also used for other purposes.
3165
% In general the delimiter is also doubled, but a string does not start
3166
% after a letter, a right parenthesis, or a right bracket.
3170
% \paragraph{Comments}
3172
% \item[0.13] \rkeyname{comment}|=|\oarg{type}\meta{delimiter\textup(s\textup)}
3173
% \item[0.21] \rkeyname{morecomment}|=|\oarg{type}\meta{delimiter\textup(s\textup)}
3174
% \item[0.21] \rkeyname{deletecomment}|=|\oarg{type}\meta{delimiter\textup(s\textup)}
3176
% Ditto for comments, but some types require more than a single
3177
% delimiter. The following overview uses \keyname{morecomment} as the
3180
% \item[0.13] \keyname{morecomment}|=[l]|\meta{delimiter}
3182
% The delimiter starts a comment line, which in general starts with the
3183
% delimiter and ends at end of line. If the character sequence |//|
3184
% should start a comment line (like in \Cpp, Comal 80 or Java),
3185
% |morecomment=[l]=//| is the correct declaration. For Matlab it
3186
% would be |morecomment=[l]\%|---note the preceding backslash.
3188
% \item[0.13] \keyname{morecomment}|=[s]|\marg{delimiter}\marg{delimiter}
3190
% Here we have two delimiters. The second ends a comment starting with
3191
% the first delimiter. If you require two such comments you can use this
3192
% type twice. C, Java, PL/I, Prolog and SQL all define single comments
3193
% via |morecomment=[s]{/*}{*/}|, and Algol does it with
3194
% |morecomment=[s]{\#}{\#}|, which means that the sharp delimits both
3195
% beginning and end of a single comment.
3197
% \item[0.13] \keyname{morecomment}|=[n]|\marg{delimiter}\marg{delimiter}
3199
% is similar to type |s|, but comments can be nested. Identical arguments
3200
% are not allowed---think a while about it!
3201
% Modula-2 and Oberon-2 use |morecomment=[n]{(*}{*)}|.
3203
% \item[0.18,,changed] \keyname{morecomment}|=[f][]|\oarg{n=preceding columns}\meta{delimiter}
3205
% The delimiter starts a comment line if and only if it appears on a
3206
% fixed column-number, namely if it is in column $n$ (zero based).
3208
% \item[0.17,,optional] \rkeyname{keywordcomment}|=|\marg{keywords}
3209
% \item[0.21,,optional] \rkeyname{morekeywordcomment}|=|\marg{keywords}
3210
% \item[0.21,,optional] \rkeyname{deletekeywordcomment}|=|\marg{keywords}
3212
% A keyword comment begins with a keyword and ends with the same keyword.
3213
% Consider |keywordcomment={comment,co}|. Then
3214
% `\textbf{comment}\allowbreak\ldots\textbf{comment}' and
3215
% `\textbf{co}\ldots\textbf{co}' are comments.
3217
% \item[0.17,,optional] \rkeyname{keywordcommentsemicolon}|=|\marg{keywords}\marg{keywords}\marg{keywords}
3219
% The definition of a `keyword comment semicolon' requires three keyword
3220
% lists, e.g.~|{end}{else,end}{comment}|. A semicolon always ends such a
3221
% comment. Any keyword of the first argument begins a comment and any
3222
% keyword of the second argument ends it (and a semicolon also);
3223
% a comment starting with any keyword of the third argument is terminated
3224
% with the next semicolon only. In the example all possible comments are
3225
% `\textbf{end}\ldots\textbf{else}', `\textbf{end}\ldots\textbf{end}'
3226
% (does not start a comment again) and `\textbf{comment}\ldots;' and
3227
% `\textbf{end}\ldots;'.
3228
% Maybe a curious definition, but Algol and Simula use such comments.
3230
% Note: The keywords here need not to be a subset of the defined
3231
% keywords. They won't appear in keyword style if they aren't.
3233
% \item[0.17,,optional] \rkeyname{podcomment}|=|\meta{\alternative{true,false}}
3235
% activates or deactivates PODs---Perl specific.
3239
% \subsection{Installation}\label{rInstallation}
3241
% \paragraph{Software installation}
3243
% \item Following the \TeX\ directory structure (TDS), you should put the files
3244
% of the \packagename{listings} package into directories as follows:
3246
% \begin{tabular}{lcl}
3247
% \texttt{listings.dvi}&$\to$&\texttt{texmf/doc/latex/listings}\\
3248
% \texttt{listings.dtx}, \texttt{listings.ins},\\
3249
% \texttt{lstdrvrs.dtx},
3250
% \texttt{lstpatch.sty}&$\to$&\texttt{texmf/source/latex/listings}
3253
% Note that you possibly don't have a patch file \texttt{lstpatch.sty}.
3254
% If you don't use the TDS, simply adjust the directories below.
3255
% \item Create the directory \texttt{texmf/tex/latex/listings} or remove all
3256
% files except \texttt{lst}\meta{whatever}\texttt{0.sty} and
3257
% \texttt{lstlocal.cfg} from that directory.
3258
% \item Change the working directory to \texttt{texmf/source/latex/listings}
3259
% and run \texttt{listings.ins} through \TeX.
3260
% \item Move the generated files to \texttt{texmf/tex/latex/listings} if this
3261
% is not already done.
3263
% \begin{tabular}{lcl}
3264
% \texttt{listings.sty}, \texttt{lstmisc.sty},
3265
% &&\qquad(kernel and add-ons)\\
3266
% \texttt{listings.cfg},
3267
% &&\qquad(configuration file)\\
3268
% \texttt{lstlang}\meta{number}\texttt{.sty},
3269
% &&\qquad(language drivers)\\
3270
% \texttt{lstpatch.sty}&$\to$&\texttt{texmf/tex/latex/listings}
3273
% \item If your \TeX\ implementation uses a file name database, update it.
3274
% \item If you receive a patch file later on, put it where
3275
% \texttt{listings.sty} is (and update file name database).
3277
% Note that \packagename{listings} requires at least version 1.10 of the
3278
% \packagename{keyval} package included in the \packagename{graphics} bundle by
3279
% David Carlisle. This bundle is available via ftp from
3280
% \href{ftp://ftp.dante.de/tex-archive/macros/latex/required/graphics}
3281
% {CTAN/macros/latex/required/graphics}.
3284
% \paragraph{Software configuration}
3285
% Read this only if you encounter problems with the standard configuration or
3286
% if you want the package to suit foreign languages, for example.
3288
% Never modify a file from the \packagename{listings} package, in particular
3289
% not the configuration file. Each new installation or new version overwrites
3290
% it. The software license allows modification, but I can't recommend it.
3291
% It's better to create one or more of the files
3293
% \begin{tabular}{lcl}
3294
% \texttt{lstmisc0.sty} & for & local add-ons
3295
% (see developer's guide),\\
3296
% \texttt{lstlang0.sty} & for & local language definitions
3297
% (see \ref{rLanguageDefinitions}), and\\
3298
% \texttt{lstlocal.cfg} & as & local configuration file
3301
% and put it/them to the other \packagename{listings} files. These three files
3302
% are not touched by a new installation except you remove them.
3303
% If \texttt{lstlocal.cfg} exists, it is loaded after \texttt{listings.cfg}.
3304
% You might want to change one of the following parameters.
3306
% \item[,,data] \rcmdname\lstaspectfiles\quad contains~\rlap{\texttt{\lstaspectfiles}}
3307
% \item[,,data] \rcmdname\lstlanguagefiles\quad contains~\rlap{\texttt{\lstlanguagefiles}}
3309
% The package uses the specified files to find add-ons and language
3312
% Moreover you might want to adjust
3313
% \icmdname\lstlistlistingname,
3314
% \icmdname\lstlistingname,
3315
% \ikeyname{defaultdialect},
3316
% \icmdname\lstalias, or
3317
% \icmdname\lstalias
3318
% as described in earlier section.
3321
% \section{Experimental features}\label{rExperimentalFeatures}
3323
% This section describes the more or less unestablished parts of this package.
3324
% It's unlikely that they are all removed (except it is stated explicitly), but
3325
% they are liable to (heavy) changes and improvements. Such features have been
3326
% \dag-marked in the last sections. So, if you find anything \dag-marked here,
3327
% you should be very, very careful.
3330
% \subsection{Listings inside arguments}\label{rListingsInsideArguments}
3332
% There are some things to consider if you want to use |\lstinline| or the
3333
% listing environment inside arguments. Since \TeX\ reads the argument before
3334
% the `\lst-macro' is executed, this package can't do anything to preserve the
3335
% input: spaces shrink to one space, the tabulator and the end of line are
3336
% converted to spaces, \TeX's comment character is not printable, and so on.
3337
% Hence, \emph{you} must work a bit more. You have to put a backslash in front
3338
% of each of the following four characters: |\{}%|. Moreover you must protect
3339
% spaces in the same manner if: (i) there are two or more spaces following each
3340
% other or (ii) the space is the first character in the line.
3341
% That's not enough: Each line must be terminated with a `line feed' |^^J|.
3342
% And you can't escape to \LaTeX\ inside such listings!
3344
% The easiest examples are with |\lstinline| since we need no line feed.
3346
%\footnote{\lstinline{var i:integer;} and
3347
% \lstinline!protected\ \ spaces! and
3348
% \fbox{\lstinline!\\\{\}\%!}}\end{verbatim}
3349
% yields\lstset{language=Pascal}\footnote{\lstinline{var i:integer;} and
3350
% \lstinline!protected\ \ spaces! and
3351
% \fbox{\lstinline!\\\{\}\%!}}
3352
% if the current language is Pascal. Note that this example shows another
3353
% experimental feature: use of argument braces as delimiters. This is
3354
% described in section \ref{rTypesettingListings}.
3356
% And now an environment example:
3357
% \begin{lstsample}{\lstset{language={}}}{}
3359
% \begin{lstlisting}^^J
3360
% \ !"#$\%&'()*+,-./^^J
3361
% 0123456789:;<=>?^^J
3362
% @ABCDEFGHIJKLMNO^^J
3363
% PQRSTUVWXYZ[\\]^_^^J
3364
% `abcdefghijklmno^^J
3365
% pqrstuvwxyz\{|\}~^^J
3369
% \item You might wonder that this feature is still experimental. The reason:
3370
% You shouldn't use listings inside arguments; it's not always safe.
3374
% \subsection{\dag\ Export of identifiers}\label{rExportOfIdentifiers}
3376
% It would be nice to export function or procedure names. In general that's a
3377
% dream so far. The problem is that programming languages use various syntaxes
3378
% for function and procedure declaration or definition. A general interface is
3379
% completely out of the scope of this package---that's the work of a compiler
3380
% and not of a pretty-printing tool. However, it is possible for particular
3381
% languages: in Pascal each function or procedure definition and variable
3382
% declaration is preceded by a particular keyword.
3383
% Note that you must request the following keys with \texttt{procnames} option:
3384
% |\usepackage[procnames]{listings}|.
3386
% \item[0.19,{{}},{\dag renamed,optional}] \rkeyname{procnamekeys}|=|\marg{keywords}
3387
% \item[0.21,,\dag optional] \rkeyname{moreprocnamekeys}|=|\marg{keywords}
3388
% \item[0.21,,\dag optional] \rkeyname{deleteprocnamekeys}|=|\marg{keywords}
3390
% each specified keyword indicates a function or procedure definition.
3391
% Any identifier following such a keyword appears in `procname' style.
3392
% For Pascal you might use\vspace{-.5\baselineskip}
3394
% procnamekeys={program,procedure,function}\end{verbatim}
3396
% \item[0.19,keywordstyle,\dag optional] \rkeyname{procnamestyle}|=|\meta{style}
3398
% defines the style in which procedure and function names appear.
3400
% \item[0.19,false,\dag optional] \rkeyname{indexprocnames}|=|\meta{\alternative{true,false}}
3402
% If activated, procedure and function names are also indexed.
3405
% The \aspectname{procnames} aspect is unsatisfactory (since unchanged for more
3406
% than three years). It marks and indexes the function definitions so far, but
3407
% it would be possible to mark also the following function calls, for example.
3408
% A key could control whether function names are added to a special keyword
3409
% class, which then appears in `procname' style. But should these names be
3410
% added globally? There are good reasons for both. Of course, we would also
3411
% need a key to reset the name list.
3415
% \subsection{\dag\ Hyper references}\label{rHyperReferences}
3417
% This very small aspect must be requested via \texttt{hyper} option since it
3418
% is experimental. One perspective for the future is to combine this aspect
3419
% with \aspectname{procnames}. Then it should be possible to click on a
3420
% function name and jump to its definition, for example.
3422
% \item[0.21,,{\dag optional}] \rkeyname{hyperref}|=|\marg{identifiers}
3423
% \item[0.21,,{\dag optional}] \rkeyname{morehyperref}|=|\marg{identifiers}
3424
% \item[0.21,,{\dag optional}] \rkeyname{deletehyperref}|=|\marg{identifiers}
3426
% Hyper references the specified identifiers (via \packagename{hyperref}
3427
% package). A `click' on such an identifier jumps to the previous
3430
% \item[0.21,\hyper@@anchor,{\dag optional}] \rkeyname{hyperanchor}|=|\meta{two-parameter macro}
3431
% \item[0.21,\hyperlink,{\dag optional}] \rkeyname{hyperlink}|=|\meta{two-parameter macro}
3433
% The macros are used to set an hyper anchor and link, respectively.
3434
% The defaults are suited for the \packagename{hyperref} package.
3438
% \subsection{Literate programming}
3440
% We begin with an example and hide the crucial key=value list.
3441
% \begin{lstsample}{\lstset{literate={:=}{{$\gets$}}1 {<=}{{$\leq$}}1 {>=}{{$\geq$}}1 {<>}{{$\neq$}}1}}{}
3442
% \begin{lstlisting}
3450
% Funny, isn't it? We could write |i := 0| respectively i| |$\gets$| |0
3451
% instead, but that's not literate!^^A :-)
3452
% Now you might want to know how this has been done. Have a \emph{close}
3453
% look at the following key.
3455
% \item[0.20,,\dag] \rkeyname{literate}|=|\meta{replacement item}\ldots\meta{replacement item}
3457
% First note that there are no commas between the items. Each item
3458
% consists of three arguments:
3459
% \marg{replace}\marg{replacement text}\marg{length}.
3460
% \meta{replace} is the original character sequence.
3461
% Instead of printing these characters, we use \meta{replacement text},
3462
% which takes the width of \meta{length} characters in the output.
3464
% Each `printing unit' in \meta{replacement text} \emph{must} be braced
3465
% except it's a single character. For example, you must put braces
3467
% If you want to replace |<-1->| by |$\leftarrow1\rightarrow$|, the
3468
% replacement item would be |{<-1->}{{$\leftarrow$}1{$\rightarrow$}}3|.
3469
% Note the braces around the arrows.
3471
% If one \meta{replace} is a subsequence of another \meta{replace}, you
3472
% must use the shorter sequence first. For example, |{-}| must be used
3473
% before |{--}| and this before |{-->}|.
3475
% In the example above I've used
3477
% literate={:=}{{$\gets$}}1 {<=}{{$\leq$}}1 {>=}{{$\geq$}}1 {<>}{{$\neq$}}1\end{verbatim}
3479
% Of course, it's good to have keys for adding and removing single
3480
% \meta{replacement item}s. Maybe the key(s) should work in the same fashion
3481
% as the string and comment definitions, i.e.~one item per key=value.
3482
% This way it would be easier to provide better auto-detection in case of a
3487
% \subsection{\textsf{LGrind} definitions}\label{rLGrindDefinitions}
3489
% Yes, it's a nasty idea to steal language definitions from other programs.
3490
% Nevertheless, it's possible for the \packagename{LGrind} definition
3491
% file---at least partially. Please note that this file must be found by
3494
% \item[0.21,,{optional}] \rkeyname{lgrindef}|=|\meta{language}
3496
% scans the \texttt{lgrindef} language definition file for
3497
% \meta{language} and activates it if present. Note that not all
3498
% \packagename{LGrind} capabilities have a \packagename{listings}
3501
% Note that `Linda' language doesn't work properly since it defines
3502
% compiler directives with preceding `|#|' as keywords.
3504
% \item[0.21,lgrindef.,{data,optional}] \rcmdname\lstlgrindeffile
3506
% contains the (path and) name of the definition file.
3510
% \subsection{\dag\ Automatic formatting}
3512
% \lstloadaspects{formats}^^A
3513
% The automatic source code formatting is far away from being good. First of
3514
% all, there are no general rules on how source code should be formatted. So
3515
% `format definitions' must be flexible. This flexibility requires a complex
3516
% interface, a powerful `format definition' parser, and lots of code lines
3517
% behind the scenes. Currently, format definitions aren't flexible enough
3518
% (possibly not the definitions but the results). A single `format item' has
3520
% \begin{itemize}\item[]
3521
% \meta{input chars}|=|\oarg{exceptional chars}\meta{pre}\oarg{\texttt{\string\string}}\meta{post}
3523
% Whenever \meta{input chars} aren't followed by one of the \meta{exceptional
3524
% chars}, formatting is done according to the rest of the value. If |\string|
3525
% isn't specified, the input characters aren't printed (except it's an
3526
% identifier or keyword). Otherwise \meta{pre} is `executed' before printing
3527
% the original character string and \meta{post} afterwards. These two are
3530
% \item |\newline| ---ensuring a new line;
3531
% \item |\space| ---ensuring a whitespace;
3532
% \item |\indent| ---increasing indention;
3533
% \item |\noindent| ---descreasing indention.
3535
% Now we can give an example.\lstaspectindex{\lstdefineformat}{}\lstaspectindex{format}{}
3536
% \begin{lstxsample}
3537
% \lstdefineformat{C}{%
3538
% \{=\newline\string\newline\indent,%
3539
% \}=\newline\noindent\string\newline,%
3540
% ;=[\ ]\string\space}
3542
% \begin{lstsample}{\lstset{language={}}}{}
3543
% \begin{lstlisting}[format=C]
3544
% for (int i=0;i<10; i++){/* wait */};
3547
% Not good. But there is a (too?) simple work-around:
3548
% \begin{lstxsample}
3549
% \lstdefineformat{C}{%
3550
% \{=\newline\string\newline\indent,%
3551
% \}=[;]\newline\noindent\string\newline,%
3552
% \};=\newline\noindent\string\newline,%
3553
% ;=[\ ]\string\space}
3555
% \begin{lstsample}{\lstset{language={}}}{}
3556
% \begin{lstlisting}[format=C]
3557
% for (int i=0;i<10; i++){/* wait */};
3560
% Sometimes the problem is just to find a suitable format definition.
3561
% Further formatting is complicated.
3562
% Here are only three examples with increasing level of difficulty.
3564
% \item Insert horizontal space to separate function/procedure name and
3565
% following parenthesis or to separate arguments of a function,
3566
% e.g.~add the space after a comma (if inside function call).
3567
% \item Smart breaking of long lines. Consider long `and/or' expressions.
3568
% Formatting should follow the logical structure!
3569
% \item Context sensitive formatting rules. It can be annoying if empty
3570
% or small blocks take three or more lines in the output---think of
3571
% scrolling down all the time. So it would be nice if the block
3572
% formatting was context sensitive.
3574
% Note that this is a very first and clumsy attempt to provide automatic
3575
% formatting---clumsy since the problem isn't trivial. Any ideas are welcome.
3576
% Implementations also. Eventually you should know that you must request format
3577
% definitions at package loading, e.g.~via |\usepackage[formats]{listings}|.
3580
% \section{Forthcoming ?}
3582
% This section is rather rudimentary. It just lists some things I don't want
3585
% First of all, I'd like to support even more languages, for example Maple,
3586
% PostScript, Reduce, and so on. Fortunately my lifetime is limited, so other
3587
% people may do that work. Please (e-)mail me your language definitions.
3589
% Then, there are several ideas for the future. Some have already been stated
3590
% as `to do's; some came from other people and are stated below; some more are
3591
% far from being implemented,
3592
% e.g.~\keyname{linerange}|=|\oarg{inter}\marg{line range list}
3593
% which prints all lines in the range and executes \meta{inter} when omitting
3594
% some code lines. The main problem here are frames and background colours;
3595
% what should happen to them? In fact, the problem is how this can be coded.
3596
% Another idea is to change the background colour (or the basic style) for
3597
% particular code blocks. This, too, is not easy.
3599
%^^A Auto-detect whether surplus space (from spaces and tabs) isn't needed to fix
3600
%^^A alignment of wide character combinations like |==| or |<>|.
3602
%^^A Make package compatible to calc package.
3604
%^^A Rewrite \lst@LAS, \lst@DefDriver, \lst@Require to distinguish loading
3605
%^^A of languages (which don't need base languages at once) and aspects
3606
%^^A (which need required aspects to be loaded).
3608
% \lsthelper{Vincent~Poirriez}{1999/11/18}{code examples inside caml comments}:
3609
% Inside caml comments, |[| and |]| should print the code in
3610
% between in basicstyle (or another newly introduced style). Nesting of these
3611
% `code example delimiters' is allowed, e.g.~|(* [[x;y]] *)|.
3613
% \lsthelper{Claus~Atzenbeck}{1999/12/03}{`extendedchars=false' doesn't issue
3614
% warning when extended characters are used}: issue warning in final mode if
3615
% \ikeyname{extendedchars}|=false| but extended chars are used.
3617
% \lsthelper{Andreas~Matthias}{2000/01/04}{define header/footer to print
3618
% the listing name}: Make the header/footer print the listing name.
3621
% \part{Tips and tricks}
3623
% Note: This part of the documentation is under construction.
3624
% Section \ref{uHowTos} must be sorted by topic and ordered in some way.
3625
% Moreover a new section `Examples' is planned, but not written.
3628
% \section{Troubleshooting}\label{uTroubleshooting}
3630
% If you're faced with a \packagename{listings}' package problem, there are
3631
% some steps you should undergo before you make a bug report. First you should
3632
% consult the reference guide whether the problem is already known. If not,
3633
% create a \emph{minimal} file which reproduced the problem. Follow these
3636
% \item Start from the minimal file in section \ref{uAMinimalFile}.
3637
% \item Add the \LaTeX\ code which causes the problem, but keep it short.
3638
% In particular, keep the number of additional packages small.
3639
% \item Remove some code from the file (and the according packages) until the
3640
% problem disappears. Then you've found a crucial piece.
3641
% \item Add this piece of code again and start over with step 3 until all code
3642
% and all packages are substantial.
3643
% \item You now have a minimal file. Send a bug report to the address on the
3644
% first page of this documentation and include the minimal file together
3645
% with the created \texttt{.log}-file. If you use a very special package
3646
% (i.e.~not on CTAN), also include the package if its software license
3651
% \section{How tos}\label{uHowTos}
3654
% \subsubsection*{How to reference line numbers}
3655
% You want to put |\label{|\meta{whatever}|}| into a \LaTeX\ escape which is
3656
% inside a comment whose delimiters aren't printed? The compiler won't see the
3657
% \LaTeX\ code since inside a comment, and the \packagename{listings} package
3658
% won't print anything since the delimiters are dropped and |\label| doesn't
3659
% produce any printable output. Well, your wish is granted.
3661
% In Pascal, for example, you could make the package recognize the `special'
3662
% comment delimiters |(*@| and |@*)| as begin-escape and end-escape sequences.
3663
% Then you can use this special comment for |\label|s and other things.
3664
% \begin{lstsample}{\lstset{numberstyle=\tiny,stepnumber=2,numbersep=5pt}}{}
3665
% \lstset{escapeinside={(*@}{@*)}}
3667
% \begin{lstlisting}
3668
% for i:=maxint to 0 do
3670
% { comment }(*@\label{comment}@*)
3673
% Line \ref{comment} shows a comment.
3676
% \item Can I use `|(*@|' and `|*)|' instead?
3679
% \item Can I use `|(*|' and `|*)|' instead?
3681
% Sure. If you want this.
3682
% \item Can I use `|{@|' and `|@}|' instead?
3684
% No, never! The second delimiter is not allowed. The character `|@|' is
3685
% defined to check whether the escape is over. But reading the lonely
3686
% `end-argument' brace, \TeX\ encounters the error `\texttt{Argument of @
3687
% has an extra \char125}'. Sorry.
3688
% \item Can I use `|{|' and `|}|' instead?
3690
% No. Again the second delimiter is not allowed. Here now \TeX\ would
3691
% give you a `\texttt{Runaway argument}' error. Since `|}|' is defined to
3692
% check whether the escape is over, it won't work as `end-argument' brace.
3693
% \item And how can I use a comment line?
3695
% For example, write `|escapeinside={//*}{\^^M}|'. Here |\^^M| represents
3696
% the end of line character.
3700
% \subsubsection*{How to gobble characters}
3701
% To make your \LaTeX\ code more readable, you might want to indent your
3702
% \texttt{lstlisting} listings. This indention must be removed for
3703
% pretty-printing. If you indent each code line by three characters, you can
3704
% remove them via |gobble=3|:
3705
% \begin{lstsample}{}{\lstset{showspaces}}
3706
% \begin{lstlisting}[gobble=3]
3707
% 1 for i:=maxint to 0 do
3712
% Write('Case insensitive ');
3713
% WritE('Pascal keywords.');
3716
% Note that empty lines as well as the beginning and the end of the environment
3717
% need not to respect the indention. But never indent the end by more than
3718
% `\ikeyname{gobble}' characters. Moreover note that tabulators expand to
3719
% |tabsize| spaces before we gobble.
3721
% \item Could I use `\ikeyname{gobble}' together with `|\lstinputlisting|'?
3723
% Yes, but it has no effect.
3725
% \item Note that `\ikeyname{gobble}' can also be set via `|\lstset|'.
3729
% \subsubsection*{How to include graphics}
3730
% \lsthelper{Herbert~Weinhandl}{1999/09/06}{listings + eps} found a very easy
3731
% way to include graphics in listings. Thanks for contributing this idea---an
3732
% idea I never have had.
3734
% Some programming languages allow the dollar sign to be part of an identifier.
3735
% But except for intermediate function names or library functions, this
3736
% character is most often unused. The \packagename{listings} package defines
3737
% the \ikeyname{mathescape} key, which lets `|$|' escape to \TeX's math mode.
3738
% This makes the dollar character an excellent candidate for our purpose here:
3739
% use a package which can include a graphic, set \ikeyname{mathescape} true,
3740
% and include the graphic between two dollar signs, which are inside a comment.
3742
% The following example is originally from a header file I got from Herbert.
3743
% For the presentation here I use the \texttt{lstlisting} environment and an
3744
% excerpt from the header file. The |\includegraphics| command is from
3745
% David Carlisle's \packagename{graphics} bundle.
3747
% \begin{lstlisting}[mathescape=true]
3749
% $ \includegraphics[height=1cm]{defs-p1.eps} $
3752
% Atom_T *V_ptr; /* pointer to Vacancy in grid */
3753
% Atom_T *x_ptr; /* pointer to (A|B) Atom in grid */
3755
% \end{lstlisting}\end{verbatim}
3756
% The result looks pretty good. Unfortunately you can't see it.
3759
% \subsubsection*{How to get closed frames on each page}
3760
% The package supports closed frames only for listings which don't cross pages.
3761
% If a listing is split on two pages, there is neither a bottom rule at the
3762
% bottom of a page, nor a top rule on the following page. If you insist on
3763
% these rules, you might want to use \texttt{framed.sty} by Donald Arseneau.
3764
% Then you could write
3767
% \begin{lstlisting}
3768
% or \lstinputlisting{...}
3770
% \end{framed}\end{verbatim}
3771
% The package also provides a \texttt{shaded} environment. If you use it, you
3772
% shouldn't forget to define \texttt{shadecolor} with the \packagename{color}
3776
% \subsubsection*{How to print national characters with $\Lambda$ and \packagename{listings}}\label{uNationalCharacters}
3778
% Apart from typing in national characters directly, you can use the `escape'
3779
% feature described in section \ref{rEscapingToLaTeX}.
3780
% The keys \ikeyname{escapechar}, \ikeyname{escapeinside}, and \ikeyname{texcl}
3781
% allow partial usage of \LaTeX\ code.
3783
% Now, if you use $\Lambda$ (Lambda, the \LaTeX\ pendant to Omega) and want,
3784
% for example, Arabic comment lines, you need not to write |\begin{arab}|
3785
% \ldots\ |\end{arab}| each escaped comment line. This can be automated:
3787
% \lstset{escapebegin=\begin{arab},escapeend=\end{arab}}
3789
% \begin{lstlisting}[texcl]
3790
% // Replace text by Arabic comment.
3791
% for (int i=0; i<1; i++) { };
3792
% \end{lstlisting}\end{verbatim}
3793
% If your programming language doesn't have comment lines, you'll have to use
3794
% \ikeyname{escapechar} or \ikeyname{escapeinside}:
3796
% \lstset{escapebegin=\begin{greek},escapeend=\end{greek}}
3798
% \begin{lstlisting}[escapeinside=`']
3799
% /* `Replace text by Greek comment.' */
3800
% for (int i=0; i<1; i++) { };
3801
% \end{lstlisting}\end{verbatim}
3802
% Note that the delimiters |`| and |'| are essential here. The example doesn't
3803
% work without them. There is a more clever way if the comment delimiters of
3804
% the programming language are single characters like the braces in Pascal:
3806
% \lstset{escapebegin=\textbraceleft\begin{arab},
3807
% escapeend=\end{arab}\textbraceright}
3809
% \begin{lstlisting}[escapeinside=\{\}]
3810
% for i:=maxint to 0 do
3812
% { Replace text by Arabic comment. }
3814
% \end{lstlisting}\end{verbatim}
3815
% Please note that the `interface' to $\Lambda$ is completely untested.
3816
% Reports are welcome!
3819
% \subsubsection*{How to get bold typewriter type keywords}
3820
% Many people asked for bold typewriter fonts since they aren't included in
3821
% the \LaTeX\ standard distribution. Here now one answer on how to use them
3824
% \item Please note that I personally don't regard the following as a good
3825
% solution. Such a bold typewriter type is too heavy. It would be better
3826
% to use a light version of \texttt{cmtt} as basic font and \texttt{cmtt}
3827
% or a \emph{slightly} heavier type for keywords.
3829
% \item Why don't you tell us how to use the better solution?
3831
% A light version of \texttt{cmtt} doesn't exist. If it's once available,
3832
% you can do a similar job as described below.
3834
% First of all, you'll need Metafont source files for bold typewriter, e.g.~
3835
% \texttt{cmbtt8.mf}, \texttt{cmbtt9.mf} and \texttt{cmbtt10.mf} from
3836
% \href{ftp://ftp.dante.de/tex-archive/fonts/cm/mf-extra/bold}
3837
% {CTAN/fonts/cm/mf-extra/bold}.
3838
% Secondly you have to create \texttt{.tfm}-files, i.e.~run the Metafont
3839
% program on these sources. This is possibly done automatically when you use
3840
% the fonts in a document. Finally you must tell \LaTeX\ that you've installed
3841
% bold typewriter fonts. Just use
3843
% \DeclareFontShape{OT1}{cmtt}{bx}{n}
3844
% {<5><6><7><8>cmbtt8%
3846
% <10><10.95>cmbtt10%
3847
% <12><14.4><17.28><20.74><24.88>cmbtt10%
3849
% in the preamble of your document. If you use these fonts often, you might
3850
% want to make a local copy of \texttt{ot1cmtt.fd} and replace the declaration
3851
% there. But note that you're not allowed to distributed the modified file
3852
% under its original name!
3855
% \subsubsection*{How to get the developer's guide}
3856
% In the \emph{source directory} of the listings package, i.e.~where
3857
% \texttt{listings.dtx} is, create the file \texttt{ltxdoc.cfg} with the
3858
% following contents.
3860
% \AtBeginDocument{\AlsoImplementation}\end{verbatim}
3861
% Then run \texttt{listings.dtx} through \LaTeX\ twice, run Makeindex,
3862
% and one last time \LaTeX\ on \texttt{listings.dtx}. This creates the whole
3863
% documentation including User's guide, Reference guide, Developer's guide,
3864
% and Implementation.
3868
% \def\index@prologue{\section*{Index}\markboth{Index}{Index}}
3870
%^^A \StopEventually{\lstcheckreference\setcounter{IndexColumns}{2}\PrintIndex}
3871
% \StopEventually{\setcounter{IndexColumns}{2}\PrintIndex}
3874
% \part{Developer's guide}
3876
% First I must apologize for this developer's guide since some parts are not
3877
% explained as good as possible. But note that you are in a pretty good shape:
3878
% this developer's guide exists! ^^A :-)
3879
% You might want to peak into section \ref{dPackageExtensions} before reading
3880
% section \ref{dBasicConcepts}.
3883
% \section{Basic concepts}\label{dBasicConcepts}
3885
% The functionality of the \packagename{listings} package appears to be
3886
% divided into two parts: on the one hand commands which actually typeset
3887
% listings and on the other via |\lstset| adjustable parameters. Both could
3888
% be implemented in terms of \lst-aspects, which are simply collections of
3889
% public keys and commands and internal hooks and definitions. The package
3890
% defines a couple of aspects, in particular the kernel, the main engine.
3891
% Other aspects drive this engine, and language and style definitions tell
3892
% the aspects how to drive. The relations between car, driver and assistant
3893
% driver are exactly reproduced---and I'll be your driving instructor.
3896
% \subsection{Package loading}\label{dPackageLoading}
3898
% Each option in |\usepackage[|\meta{options}|]{listings}| loads an aspect or
3899
% \emph{prevents} the package from loading it if the aspect name is
3900
% \emph{preceded by an exclamation mark}. This mechanism was designed to clear
3901
% up the dependencies of different package parts and to debug the package. For
3902
% this reason there is another option:
3904
% \item[0.21,,option] \texttt{noaspects}\leavevmode
3906
% deletes the list of aspects to load. Note that, for example, the
3907
% option lists |0.21,!labels,noaspects| and |noaspects| are essentially
3908
% the same: the kernel is loaded and no other aspect.
3910
% This is especially useful for aspect-testing since we can load exactly the
3911
% required parts. Note, however, that an aspect is loaded later if a predefined
3912
% programming language requests it. One can load aspects also by hand:
3914
% \item[0.20] |\lstloadaspects|\marg{comma separated list of aspect names}
3916
% loads the specified aspects if they are not already loaded.
3918
% Here now is a list of all aspects and related keys and commands---in the hope
3919
% that this list is complete.
3920
% \begin{description}
3921
% \hyphenpenalty=10000\relax \rightskip=0pt plus \linewidth\relax
3922
% \item[\aspectname{strings}]\leavevmode
3924
% \lstprintaspectkeysandcmds{strings}
3926
% \item[\aspectname{comments}]\leavevmode
3928
% \lstprintaspectkeysandcmds{comments}
3930
% \item[\aspectname{pod}]\leavevmode
3932
% \lstprintaspectkeysandcmds{pod}
3934
% \item[\aspectname{escape}]\leavevmode
3936
% \lstprintaspectkeysandcmds{escape}
3938
% \item[\aspectname{writefile}] requires 1 |\toks|, 1 |\write|
3940
% |\lst@BeginWriteFile|, |\lst@BeginAlsoWriteFile|, |\lst@EndWriteFile|
3942
% \item[\aspectname{style}]\leavevmode
3944
% empty style, \lstprintaspectkeysandcmds{style}
3946
% \item[\aspectname{language}]\leavevmode
3948
% empty language, \lstprintaspectkeysandcmds{language}
3950
% \item[\aspectname{keywords}]\leavevmode
3952
% \lstprintaspectkeysandcmds{keywords}
3954
% \item[\aspectname{emph}] requires \aspectname{keywords}
3956
% \lstprintaspectkeysandcmds{emph}
3958
% \item[\aspectname{html}] requires \aspectname{keywords}
3960
% \lstprintaspectkeysandcmds{html}
3962
% \item[\aspectname{tex}] requires \aspectname{keywords}
3964
% \lstprintaspectkeysandcmds{tex}
3966
% \item[\aspectname{directives}] requires \aspectname{keywords}
3968
% \lstprintaspectkeysandcmds{directives}
3970
% \item[\aspectname{index}] requires \aspectname{keywords}
3972
% \lstprintaspectkeysandcmds{index}
3974
% \item[\aspectname{procnames}] requires \aspectname{keywords}
3976
% \lstprintaspectkeysandcmds{procnames}
3978
% \item[\aspectname{keywordcomments}]
3979
% requires \aspectname{keywords}, \aspectname{comments}
3981
% \lstprintaspectkeysandcmds{keywordcomments}
3983
% \item[\aspectname{labels}] requires 2 |\count|
3985
% \lstprintaspectkeysandcmds{labels}
3987
% \item[\aspectname{lineshape}] requires 2 |\dimen|
3989
% \lstprintaspectkeysandcmds{lineshape}
3991
% \item[\aspectname{frames}] requires \aspectname{lineshape}
3993
% \lstprintaspectkeysandcmds{frames}
3995
% \item[\aspectname{make}] requires \aspectname{keywords}
3997
% \lstprintaspectkeysandcmds{make}
3999
% \item[\aspectname{doc}] requires \aspectname{writefile} and 1 |\box|
4001
% \lstprintaspectkeysandcmds{doc}
4003
% \item[\aspectname{0.21}] defines old keys in terms of the new ones.
4004
% \item[\aspectname{fancyvrb}] requires 1 |\box|
4006
% \lstprintaspectkeysandcmds{fancyvrb}
4008
% \item[\aspectname{lgrind}]\leavevmode
4010
% \lstprintaspectkeysandcmds{lgrind}
4012
% \item[\aspectname{hyper}] requires \aspectname{keywords}
4014
% \lstprintaspectkeysandcmds{hyper}
4016
% The kernel allocates 6 |\count|, 4 |\dimen| and 1 |\toks|.
4017
% Moreover it defines the following keys, commands, and environments:
4018
% \begin{itemize}\item[]
4019
% \hyphenpenalty=10000\relax \rightskip=0pt plus \linewidth\relax
4020
% \lstprintaspectkeysandcmds{kernel}, \keyname{fancyvrb}
4024
% \subsection{How to define \lst-aspects}\label{dHowToDefineLstAspects}
4026
% There are at least three ways to add new functionality: (a) you write an
4027
% aspect of general interest, send it to me, and I'll just paste it into the
4028
% implementation; (b) you write a `local' aspect not of general interest; or
4029
% (c) you have an idea for an aspect and make me writing it. (a) and (b) are
4030
% good choices.^^A :-)
4032
% An aspect definition starts with |\lst@BeginAspect| plus arguments and ends
4033
% with the next |\lst@EndAspect|. In particular, aspect definitions can't be
4036
% \item[0.20] |\lst@BeginAspect|[\oarg{list of required aspects}]\marg{aspect name}
4037
% \item[0.20] |\lst@EndAspect|
4039
% The optional list is a comma separated list of required aspect names.
4040
% The complete aspect is not defined in each of the following cases:
4042
% \item \meta{aspect name} is empty.
4043
% \item The aspect is already defined.
4044
% \item A required aspect is neither defined nor loadable via
4045
% |\lstloadaspects|.
4047
% Consequently you can't define a part of an aspect and later on another part.
4048
% But it is possible to define aspect $A_1$ and later aspect $A_2$ which
4051
% \item Put local add-ons into `\texttt{lstmisc0.sty}'---this file is searched
4052
% first by default. If you want to make add-ons for one particular
4053
% document just replace the surrounding `|\lst@BeginAspect|' and
4054
% `|\lst@EndAspect|' by `|\makeatletter|' and `|\makeatother|' and use
4055
% the definitions in the preamble of your document. However, you have to
4056
% load required aspects on your own.
4058
% You can put any \TeX\ material in between the two commands, but note that
4059
% definitions must be |\global| if you need them later---\LaTeX's |\newcommand|
4060
% makes local definitions and can't be preceded by |\global|. So use the
4061
% following commands, |\gdef|, and commands described in later sections.
4063
% \item[0.20] |\lst@UserCommand|\meta{macro}\meta{parameter text}\marg{replacement text}
4065
% The macro is (mainly) equivalent to |\gdef|. The purpose is to
4066
% distinguish user commands and internal global definitions.
4068
% \item[0.19] |\lst@Key|\marg{key name}\marg{init value}[\oarg{default value}]\marg{definition}
4069
% \item[0.19] |\lst@Key|\marg{key name}|\relax|[\oarg{default value}]\marg{definition}
4071
% defines a key using the \packagename{keyval} package from David
4072
% Carlisle. \meta{definition} is the replacement text of a macro with
4073
% one parameter. The argument is either the value from `key=value' or
4074
% \meta{default value} if no `=value' is given. The helper macros
4075
% |\lstKV@...| below might simplify \meta{definition}.
4077
% The key is not initialized if the second argument is |\relax|.
4078
% Otherwise \meta{init value} is the initial value given to the key.
4079
% Note that we locally switch to |\globalsdefs=1| to ensure that
4080
% initialization is not effected by grouping.
4082
% \item[0.19] |\lst@AddToHook|\marg{name of hook}\marg{\TeX\ material}
4084
% adds \TeX\ material at predefined points. Section \ref{dHooks} lists
4085
% all hooks and where they are defined respectively executed.
4086
% |\lst@AddToHook{A}{\csa}| before |\lst@AddToHook{A}{\csb}|
4087
% \emph{does not} guarantee that |\csa| is executed before |\csb|.
4089
% \item[0.20] |\lst@AddToHookExe|\marg{name of hook}\marg{\TeX\ material}
4091
% also executes \meta{\TeX\ material} for initialization. You might use
4092
% local variables---local in the sense of \TeX\ and/or usual programming
4093
% languages---but when the code is executed for initialization all
4094
% assignments are global: we set |\globaldefs| locally to one.
4096
% \item[0.20] |\lst@UseHook|\marg{name of hook}
4098
% executes the hook.
4101
% \item Let's look at two examples. The first extends the package by adding
4102
% some hook-material. If you want status messages, you might write
4104
% \lst@AddToHook{Init}{\message{\MessageBreak Processing listing ...}}
4105
% \lst@AddToHook{DeInit}{\message{complete.\MessageBreak}}\end{verbatim}
4106
% The second example introduces two keys to let the user control the
4107
% messages. The macro |\lst@AddTo| is described in section
4108
% \ref{dGeneralPurposeMacros}.
4110
% \lst@BeginAspect{message}
4111
% \lst@Key{message}{Annoying message.}{\gdef\lst@message{#1}}
4112
% \lst@Key{moremessage}\relax{\lst@AddTo\lst@message{\MessageBreak#1}}
4113
% \lst@AddToHook{Init}{\typeout{\MessageBreak\lst@message}}
4114
% \lst@EndAspect\end{verbatim}
4115
% However, there are certainly aspects which are more useful.
4117
% The following macros can be used in the \meta{definition} argument of the
4118
% |\lst@Key| command to evaluate the argument. The additional prefix |KV|
4119
% refers to the \packagename{keyval} package.
4121
% \item[0.19] |\lstKV@SetIf|\marg{value}\meta{if macro}
4123
% \meta{if macro} becomes |\iftrue| if the first character of
4124
% \meta{value} equals |t| or |T|. Otherwise it becomes |\iffalse|.
4125
% Usually you will use |#1| as \meta{value}.
4127
% \item[1.0] \cs{lstKV@SwitchCases}\marg{value}\\
4128
% |{|\meta{string 1}|&|\meta{execute 1}|\\|\\
4129
% | |\meta{string 2}|&|\meta{execute 2}|\\|\\
4130
% \hbox to 3em{\hfill\vdots}\\
4131
% | |\meta{string $n$}|&|\meta{execute $n$}|}|\marg{else}
4133
% Either execute \meta{else} or the \meta{value} matching part.
4135
% \item[0.20] |\lstKV@TwoArg|\marg{value}\marg{subdefinition}
4136
% \item[0.20] |\lstKV@ThreeArg|\marg{value}\marg{subdefinition}
4137
% \item[0.20] |\lstKV@FourArg|\marg{value}\marg{subdefinition}
4139
% \meta{subdefinition} is the replacement text of a macro with two,
4140
% three, and four parameters. We call this macro with the arguments given
4141
% by \meta{value}. Empty arguments are added if necessary.
4143
% \item[0.19] |\lstKV@OptArg|\oarg{default arg.}\marg{value}\marg{subdefinition}
4145
% |[|\meta{default arg.}|]| is \emph{not} optional. \meta{subdefinition}
4146
% is the replacement text of a macro with parameter text |[##1]##2|.
4147
% Note that the macro parameter character |#| is doubled since used
4148
% within another macro. \meta{subdefinition} accesses these arguments
4149
% via |##1| and |##2|.
4151
% \meta{value} is usually the argument |#1| passed by the
4152
% \packagename{keyval} package. If \meta{value} has no optional argument,
4153
% \meta{default arg.} is inserted to provide the arguments to
4154
% \meta{subdefinition}.
4156
% \item[0.21] |\lstKV@XOptArg|\oarg{default arg.}\marg{value}\meta{submacro}
4158
% Same as |\lstKV@OptArg| but the third argument \meta{submacro} is
4159
% already a definition and not replacement text.
4161
% \item[0.20] |\lstKV@CSTwoArg|\marg{value}\marg{subdefinition}
4163
% \meta{value} is a \texttt comma \texttt separated list of one or two
4164
% arguments. These are given to the subdefinition which is the
4165
% replacement text of a macro with two parameters. An empty second
4166
% argument is added if necessary.
4169
% \item One more example. The key `\keyname{sensitive}' belongs to the aspect
4170
% \aspectname{keywords}. Therefore it is defined in between
4171
% `|\lst@BeginAspect{keywords}|' and `|\lst@EndAspect|', which is not shown
4174
% \lst@Key{sensitive}\relax[t]{\lstKV@SetIf{#1}\lst@ifsensitive}
4175
% \lst@AddToHookExe{SetLanguage}{\let\lst@ifsensitive\iftrue}\end{verbatim}
4176
% The last line is equivalent to
4178
% \lst@AddToHook{SetLanguage}{\let\lst@ifsensitive\iftrue}
4179
% \global\let\lst@ifsensitive\iftrue\end{verbatim}
4180
% We initialize the variable globally since the user might request an
4181
% aspect in a group. Afterwards the variable is used locally---there is
4182
% no |\global| in \meta{\TeX\ material}. Note that we could define and
4183
% init the key as follows:
4185
% \lst@Key{sensitive}t[t]{\lstKV@SetIf{#1}\lst@ifsensitive}
4186
% \lst@AddToHook{SetLanguage}{\let\lst@ifsensitive\iftrue}\end{verbatim}
4190
% \subsection{Internal modes}\label{dInternalModes}
4192
% You probably know \TeX's conditional commands |\ifhmode|, |\ifvmode|,
4193
% |\ifmmode|, and |\ifinner|. They tell you whether \TeX\ is in (restricted)
4194
% horizontal or (internal) vertical or in (nondisplay) mathematical mode. For
4195
% example, true |\ifhmode| and true |\ifinner| indicate restricted horizontal
4196
% mode, which means that you are in a |\hbox|. The typical user doesn't care
4197
% about such modes; \TeX/\LaTeX\ manages all this. But since you're reading the
4198
% developer's guide, we discuss the analogue for the \packagename{listings}
4199
% package now. It uses modes to distinguish comments from strings, `comment
4200
% lines' from `single comments', and so on.
4202
% The package is in `no mode' before reading the source code. In the phase of
4203
% initialization it goes to `processing mode'. Afterwards the mode depends on
4204
% the actual source code. For example, consider the line
4206
% "string" // comment\end{verbatim}
4207
% and assume \texttt{language=C++}. Reading the string delimiter, the package
4208
% enters `string mode' and processes the string. The matching closing delimiter
4209
% leaves the mode, i.e.\ switches back to the general `processing mode'. Coming
4210
% to the two slashes, the package detects a comment line; it therefore enters
4211
% `comment line mode' and outputs the slashes. Usually this mode lasts to the
4214
% But with \texttt{textcl=true} the \aspectname{escape} aspect immediately
4215
% leaves `comment line mode', interrupts the current mode sequence, and enters
4216
% `\TeX\ comment line mode'. At the end of line we reenter the previous mode
4217
% sequence `no mode' $\to$ 'processing mode'. This escape to \LaTeX\ works
4218
% since `no mode' implies that \TeX's characters and catcodes are present,
4219
% whereas `processing mode' means that \packagename{listings}' characters and
4220
% catcodes are active.
4222
% \begin{table}[htbp]
4223
% \caption{Internal modes}\label{dDefinedInternalModes}
4224
% \def\lsttabspace{\hspace*{1em}\hfill}
4225
% \begin{tabular}{@{}lp{0.56\linewidth}@{}}
4226
% aspect\lsttabspace\meta{mode name} & Usage/We are processing \ldots\\
4227
% \noalign{\smallskip}
4228
% kernel\lsttabspace |\lst@nomode| &
4229
% If this mode is active, \TeX's `character table' is present; the other
4230
% implication is not true. Any other mode \emph{may} imply that catcodes
4231
% and\nobreak/\allowbreak or definitions of characters are changed.
4233
% \lsttabspace |\lst@Pmode| &
4234
% is a general processing mode. If active we are processing a listing,
4235
% but haven't entered a more special mode.
4237
% \lsttabspace |\lst@GPmode| &
4238
% general purpose mode for language definitions.
4240
% \aspectname{pod}\lsttabspace |\lst@PODmode| &
4241
% \ldots~a POD---Perl specific.
4243
% \aspectname{escape}\lsttabspace |\lst@TeXLmode| &
4244
% \ldots~a comment line, but \TeX's character table is present---except
4245
% the EOL character, which is needed to terminate this mode.
4247
% \lsttabspace |\lst@TeXmode| &
4248
% indicates that \TeX's character table is present (except one user
4249
% specified character, which is needed to terminate this mode).
4251
% \aspectname{directives}\lsttabspace |\lst@CDmode| &
4252
% indicates that the current line began with a compiler directive.
4254
% \aspectname{keywordcomments}\lsttabspace |\lst@KCmode| &
4255
% \ldots~a keyword comment.
4257
% \lsttabspace |\lst@KCSmode| &
4258
% \ldots~a keyword comment which can be terminated by a semicolon only.
4260
% \aspectname{html}\lsttabspace |\lst@insidemode| &
4261
% Active if we are between \texttt{<} and \texttt{>}.
4263
% \aspectname{make}\lsttabspace |\lst@makemode| &
4264
% Used to indicate a keyword.
4267
% Table \ref{dDefinedInternalModes} lists all static modes and which aspects
4268
% they belong to. Most features use dynamically created mode numbers, for
4269
% example all strings and comments. Each aspect may define its own mode(s)
4270
% simply by allocating it/\allowbreak them inside the aspect definition.
4272
% \item[0.19] |\lst@NewMode|\meta{mode \textup(control sequence\textup)}
4274
% defines a new static mode, which is a nonnegative integer assigned to
4275
% \meta{mode}. \meta{mode} should have the prefix \texttt{lst@} and
4276
% suffix \texttt{mode}.
4278
% \item[0.21] |\lst@UseDynamicMode|\marg{token\textup(s\textup)}
4280
% inserts a dynamic mode number as argument to the token(s).
4282
% This macro cannot be used to get a mode number when an aspect is
4283
% loaded or defined. It can only be used every listing in the process
4284
% of initialization, e.g.~to define comments when the character table
4287
% \item[0.19,,changed] |\lst@EnterMode|\meta{mode}\marg{start tokens}
4289
% opens a group level, enters the mode, uses \meta{style} as the current
4290
% style, and executes \meta{start tokens}. Note that the style and start
4291
% tokens are read as one single argument and that there must be braces
4294
% Use |\lst@modetrue| in \meta{start tokens} to prohibit future mode
4295
% changes---except leaving the mode, of course. You must test yourself
4296
% whether you're allowed to enter, see below.
4298
% \item[0.19] |\lst@LeaveMode|
4300
% returns to the previous mode by closing a group level if and only if
4301
% the current mode isn't |\lst@nomode| already. You must test yourself
4302
% whether you're allowed to leave a mode, see below.
4305
% \item[0.19] |\lst@LeaveAllModes|
4307
% returns to |\lst@nomode|.
4308
% This is some kind of emergency macro, so don't use it!
4311
% \item[0.19] |\lst@InterruptModes|
4312
% \item[0.19] |\lst@ReenterModes|
4314
% The first command returns to |\lst@nomode|, but saves the current mode
4315
% sequence on a special stack. Afterwards the second macro returns to the
4316
% previous mode. In between these commands you may enter any mode you
4317
% want. In particular you can interrupt modes, enter some modes, and say
4318
% `interrupt modes' again. Then two re-enters will take you back in front
4319
% of the first `interrupt modes'.
4321
% Remember that |\lst@nomode| implies that \TeX's character table is
4324
% Some variables show the internal state of processing. You are allowed to read
4325
% them, but \emph{direct write access is prohibited}. Note: |\lst@ifmode| is
4326
% \emph{not} obsolete since there is no relation between the boolean and the
4327
% current mode. It will happen that we enter a mode without setting
4328
% |\lst@ifmode| true, and we'll set it true without assigning any mode!
4330
% \item[0.18,,counter] |\lst@mode|
4332
% keeps the current mode number. Use |\ifnum\lst@mode=|\meta{mode name}
4333
% to test against a mode. Don't modify the counter directly!
4335
% \item[0.18,,boolean] |\lst@ifmode|
4337
% No mode change is allowed if this boolean is true---except leaving the
4338
% current mode. Use |\lst@modetrue| to modify this variable, but do it
4339
% only in \meta{start tokens}.
4341
% \item[1.0,,boolean] |\lst@ifLmode|
4343
% Indicates whether the current mode ends at end of line.
4347
% \subsection{Hooks}\label{dHooks}
4349
% Several problems arise if you want to define an aspect.
4350
% You should and/or must
4351
% (a) find additional functionality (of general interest) and implement it,
4352
% (b) create the user interface, and
4353
% (c) interface with the \packagename{listings} package, i.e.~find correct
4354
% hooks and insert appropriate \TeX\ material.
4355
% (a) is out of the scope of this developer's guide. The commands |\lstKV@...|
4356
% in section \ref{dHowToDefineLstAspects} might help you with (b). Here now we
4357
% describe all hooks of the \packagename{listings} package.
4359
% All hooks are executed inside an overall group. This group starts somewhere
4360
% near the beginning and ends somewhere at the end of each listing. Don't make
4361
% any other assumptions on grouping. So define variables globally if it's
4362
% necessary---and be alert of side effects if you don't use your own groups.
4364
% \item \hookname{AfterBeginComment}
4366
% is executed after the package has entered comment mode.
4367
% The starting delimiter is usually typeset when the hook is called.
4369
% \item \hookname{BoxUnsafe}
4371
% Contains all material to deactivate all commands and registers which
4372
% are possibly unsafe inside |\hbox|. It is used whenever the package
4373
% makes a box around a listing and for \packagename{fancyvrb} support.
4375
% \item \hookname{DeInit}
4377
% Called at the very end of a listing but before closing the box from
4378
% \hookname{BoxUnsafe} or ending a float.
4380
% \item \hookname{DetectKeywords}
4382
% This \hookname{Output} subhook is executed if and only if mode changes
4383
% are allowed, i.e.~if and only if the package doesn't process a comment,
4384
% string, and so on---see section \ref{dInternalModes}.
4386
% \item \hookname{DisplayStyle}
4388
% deactivates/activates features for displaystyle listings.
4390
% \item \hookname{EmptyStyle}
4392
% Executed to select the `empty' style---except the user has redefined
4395
% \item \hookname{EndGroup}
4397
% Executed whenever the package closes a group, e.g.~at end of comment or
4400
% \item \hookname{EOL}
4402
% Called at each end of \emph{input} line, right before
4403
% \hookname{InitVarsEOL}.
4405
% \item \hookname{EveryLine}
4407
% Executed at the beginning of each \emph{output} line, i.e.~more than
4408
% once for broken lines. This hook must not change the horizontal or
4409
% vertical position.
4411
% \item \hookname{EveryPar}
4413
% Executed once for each input line when the output starts. This hook
4414
% must not change the horizontal or vertical position.
4416
%^^A \item \hookname{ExcludeDelims}
4418
%^^A Executed by the \keyname{excludedelims} key before the excluded
4419
%^^A delimiters are determined.
4421
% \item \hookname{ExitVars}
4423
% Executed right before \hookname{DeInit}.
4425
% \item \hookname{FontAdjust}
4427
% adjusts font specific internal values (currently |\lst@width| only).
4429
% \item \hookname{Init}
4431
% Executed once each listing to initialize things before the character
4432
% table is changed. It is called after \hookname{PreInit} and before
4433
% \hookname{InitVars}.
4435
% \item \hookname{InitVars}
4437
% Called to init variables each listing.
4439
% \item \hookname{InitVarsBOL}
4441
% initializes variables at the beginning of each input line.
4443
% \item \hookname{InitVarsEOL}
4445
% updates variables at the end of each input line.
4447
% \item \hookname{ModeTrue}
4449
% executed by the package when mode changes become illegal.
4450
% Here keyword detection is switched off for comments and strings.
4452
% \item \hookname{OnEmptyLine}
4454
% executed \emph{before} the package outputs an empty line.
4456
% \item \hookname{OnNewLine}
4458
% executed \emph{before} the package starts one or more new lines,
4459
% i.e.~before saying |\par\noindent\hbox{}| (roughly speaking).
4461
% \item \hookname{Output}
4463
% Called before an identifier is printed.
4464
% If you want a special printing style, modify |\lst@thestyle|.
4466
% \item \hookname{OutputBox}
4468
% used inside each output box. Currently it is only used to make the
4469
% package work together with Lambda---hopefully.
4471
% \item \hookname{OutputOther}
4473
% Called before other character strings are printed.
4474
% If you want a special printing style, modify |\lst@thestyle|.
4476
% \item \hookname{PostOutput}
4478
% Called after printing an identifier or any other output unit.
4480
% \item \hookname{PostTrackKeywords}
4482
% is a very special \hookname{Init} subhook to insert keyword tests and
4483
% define keywords on demand.
4484
% This hook is called after \hookname{TrackKeywords}.
4486
% \item \hookname{PreInit}
4488
% Called right before \hookname{Init} hook.
4490
% \item \hookname{PreSet}
4492
% Each typesetting command/environment calls this hook to initialize
4493
% internals before any user supplied key is set.
4495
% \item \hookname{SelectCharTable}
4497
% is executed after the package has selected the standard character
4498
% table. Aspects adjust the character table here and define string and
4499
% comment delimiters, and such.
4501
% \item \hookname{SetFormat}
4503
% Called before internal assignments for setting a format are made.
4504
% This hook determines which parameters are reset every format selection.
4506
% \item \hookname{SetStyle}
4508
% Called before internal assignments for setting a style are made.
4509
% This hook determines which parameters are reset every style selection.
4511
% \item \hookname{SetLanguage}
4513
% Called before internal assignments for setting a language are made.
4514
% This hook determines which parameters are reset every language
4517
% \item \hookname{TextStyle}
4519
% deactivates/activates features for textstyle listings.
4521
% \item \hookname{TrackKeywords}
4523
% is a very special \hookname{Init} subhook to insert keyword tests and
4524
% define keywords on demand.
4525
% This hook is called before \hookname{PostTrackKeywords}.
4529
% \subsection{Character tables}\label{dCharacterTables}
4531
% Now you know how a car looks like, and you can get a driving license if you
4532
% take some practice. But you will have difficulties if you want to make heavy
4533
% alterations to the car. So let's take a closer look and come to the most
4534
% difficult part: the engine. We'll have a look at the big picture and fill in
4535
% the details step by step. For our purpose it's good to override \TeX's
4536
% character table. First we define a standard character table which contains
4538
% \item letters: characters identifiers are out of,
4539
% \item digits: characters for identifiers or numerical constants,
4540
% \item spaces: characters treated as blank spaces,
4541
% \item tabulators: characters treated as tabulators,
4542
% \item form feeds: characters treated as form feed characters, and
4543
% \item others: all other characters.
4545
% This character table is altered depending on the current programming language.
4546
% We may define string and comment delimiters or other special characters.
4547
% Table \ref{rStdCharTable} on page \pageref{rStdCharTable} shows the standard
4548
% character table. It can be modified with the keys \keyname{alsoletter},
4549
% \keyname{alsodigit}, and \keyname{alsoother}.
4551
% How do these `classes' work together? Let's say that the current character
4552
% string is `|tr|'. Then letter `|y|' simply appends the letter and we get
4553
% `|try|'. The next nonletter (and nondigit) causes the output of the
4554
% characters. Then we collect all coming nonletters until reaching a letter
4555
% again. This causes the output of the nonletters, and so on. Internally each
4556
% character becomes active in the sense of \TeX\ and is defined to do the right
4557
% thing, e.g.~we say
4559
% \def A{\lst@ProcessLetter A}\end{verbatim}
4560
% where the first `|A|' is active and the second has letter catcode 11.
4561
% The macro |\lst@ProcessLetter| gets one token and treats it as a letter.
4562
% The following macros exist, where the last three get no explicit argument.
4564
% \item[0.18] |\lst@ProcessLetter| \meta{spec.\ token}
4565
% \item[0.18] |\lst@ProcessDigit| \meta{spec.\ token}
4566
% \item[0.18] |\lst@ProcessOther| \meta{spec.\ token}
4567
% \item[0.18] |\lst@ProcessTabulator|
4568
% \item[0.18] |\lst@ProcessSpace|
4569
% \item[0.20] |\lst@ProcessFormFeed|
4571
% \meta{spec.\ token} is supposed to do two things. Usually it expands to
4572
% a printable version of the character. But if |\lst@UM| is equivalent to
4573
% |\@empty|, \meta{spec.\ token} must expand to a \emph{character token}.
4574
% For example, the sharp usually expands to |\#|, which is defined via
4575
% |\chardef| and is not a character token. But if |\lst@UM| is equivalent to
4576
% |\@empty|, the sharp expands to the character `|#|' (catcode 12). Note:
4577
% \emph{Changes to} |\lst@UM| \emph{must be locally.} However, there should
4578
% be no need to do such basic things yourself. The \packagename{listings}
4579
% package provides advanced macros which use that feature,
4580
% e.g.~|\lst@InstallKeywords| in section \ref{dKeywordsAndWorkingIdentifiers}.
4583
% \item[0.18] |\lst@Def|\marg{character code}\meta{parameter text}\marg{definition}
4584
% \item[0.18] |\lst@Let|\marg{character code}\meta{token}
4586
% defines the specified character respectively assigns \meta{token}.
4587
% The catcode table if not affected. Be careful if your definition has
4588
% parameters: it is not safe to read more than one character ahead.
4589
% Moreover, the argument can be \emph{arbitrary}; somtimes it's the next
4590
% source code character, sometimes it's some code of the
4591
% \packagename{listings} package, e.g.~|\relax|, |\@empty|, |\else|,
4592
% |\fi|, and so on. Therefore don't use \TeX's ord-operator |`| on such
4593
% an argument, e.g.~don't write |\ifnum`#1=65| to test against `|A|'.
4595
% |\lst@Def| and |\lst@Let| are relatively slow. The real definition of
4596
% the standard character table differs from the following example, but it
4599
% \lst@Def{9}{\lst@ProcessTabulator}
4600
% \lst@Def{32}{\lst@ProcessSpace}
4601
% \lst@Def{48}{\lst@ProcessDigit 0}
4602
% \lst@Def{65}{\lst@ProcessLetter A}\end{verbatim}
4605
% \item[0.20] |\lst@activecharstrue|
4606
% \item[0.20] |\lst@activecharsfalse|
4608
% control whether selecting the character table also makes all characters
4609
% active (standard/extended). This is usually true and therefore default.
4610
% Only the \packagename{fancyvrb} interface sets it locally false.
4613
% That's enough for the moment. Section \ref{dUsefulInternalDefinitions}
4614
% presents advanced definitions to manipulate the character table, in
4615
% particular how to add new comment or string types.
4618
% \subsection{On the output}
4620
% The \packagename{listings} package uses some variables to keep the output
4621
% data. Write access is not recommended. Let's start with the easy ones.
4623
% \item[0.17,,data] |\lst@lastother|
4625
% equals \meta{spec.\ token} version of the last processed
4626
% nonidentifier-character. Since programming languages redefine the
4627
% standard character table, we use the original \meta{spec.\ token}.
4628
% For example, if a double quote was processed last, |\lst@lastother|
4629
% is not equivalent to the macro which enters and leaves string mode.
4630
% It's equivalent to |\lstum@"|, where |"| belongs to the control
4631
% sequence. Remember that \meta{spec.\ token} expands either to a
4632
% printable or to a token character.
4634
% |\lst@lastother| is equivalent to |\@empty| if such a character is not
4635
% available, e.g.~at the beginning of a line. Sometimes an indentifier
4636
% has already been printed after processing the last `other' character,
4637
% i.e.~the character is far, far away. In this case |\lst@lastother|
4640
% \item[0.17] |\lst@outputspace|
4642
% Use this predefined \meta{spec.\ token} (obviously for character code
4643
% 32) to test against |\lst@lastother|.
4645
% \item[0.20] |\lstum@backslash|
4647
% Use this predefined \meta{spec.\ token} (for character code 92) to test
4648
% against |\lst@lastother|. In the replacement text for |\lst@Def| one
4649
% could write |\ifx| |\lst@lastother| |\lstum@backslash| \ldots\ to test
4650
% whether the last character has been a backslash.
4652
% \item[0.20] |\lst@SaveOutputDef|\marg{character code}\meta{macro}
4654
% Stores the \meta{spec.\ token} corresponding to \meta{character code}
4655
% in \meta{macro}. This is the only safe way to get a correct meaning to
4656
% test against |\lst@lastother|, for example
4657
% |\lst@SaveOutputDef{"5C}\lstum@backslash|.
4659
% You'll get a ``runaway argument'' error if \meta{character code} is not
4660
% between 33 and 126 (inclusive).
4662
% Now let's turn to the macros dealing a bit more with the output data and
4665
% \item[1.0] |\lst@XPrintToken|
4667
% outputs the current character string and resets it. This macro keeps
4668
% track of all variables described here.
4670
% \item[0.18,,token] |\lst@token|
4672
% contains the current character string. Each `character' usually
4673
% expands to its printable version, but it must expand to a character
4674
% token if |\lst@UM| is equivalent to |\@empty|.
4676
% \item[0.12,,counter] |\lst@length|
4678
% is the length of the current character string.
4680
% \item[0.12,,dimension] |\lst@width|
4682
% is the width of a single character box.
4684
% \item[0.20,,global dimension] |\lst@currlwidth|
4686
% is the width of so far printed line.
4688
% \item[0.18,,global counter] |\lst@column|
4689
% \item[0.12,,global counter] |\lst@pos| (nonpositive)
4691
% |\lst@column|$-$|\lst@pos| is the length of the so far printed line.
4692
% We use two counters since this simplifies tabulator handling:
4693
% |\lst@pos| is a nonpositive representative of `length of so far
4694
% printed line' modulo \keyname{tabsize}.
4695
% It's usually not the biggest nonpositive representative.
4697
% \item[0.20] |\lst@CalcColumn|
4699
% |\@tempcnta| gets |\lst@column| $-$ |\lst@pos| $+$ |\lst@length|.
4700
% This is the current column number minus one, or the current column
4701
% number zero based.
4703
% \item[0.18,,global dimension] |\lst@lostspace|
4705
% equals `lost' space: desired current line width minus real line width.
4706
% Whenever this dimension is positive the flexible column format can use
4707
% this space to fix the column alignment.
4711
% \section{Package extensions}\label{dPackageExtensions}
4714
% \subsection{Keywords and working identifiers}\label{dKeywordsAndWorkingIdentifiers}
4716
% The \aspectname{keywords} aspect defines two main macros. Their respective
4717
% syntax is shown on the left. On the right you'll find examples how the
4718
% package actually defines some keys.
4721
% \cs{lst@InstallFamily}
4723
% \marg{prefix}\syntaxfill \texttt k\\
4724
% \marg{name}\syntaxfill |{keywords}|\\
4725
% \marg{style name}\syntaxfill |{keywordstyle}|\\
4726
% \marg{style init}\syntaxfill |\bfseries|\\
4727
% \marg{default style name}\syntaxfill |{keywordstyle}|\\
4728
% \marg{working procedure}\syntaxfill |{}|\\
4729
% \meta{\alternative{l,o}}\syntaxfill |l|\\
4730
% \meta{\alternative{d,o}}\syntaxfill |d|
4732
% installs either a keyword or `working' class of identifiers according
4733
% to whether \meta{working procedure} is empty.
4735
% The three keys \meta{name}, \keyname{more}\meta{name} and
4736
% \keyname{delete}\meta{name}, and if not empty \meta{style name} are
4737
% defined. The first order member of the latter one is initialized with
4738
% \meta{style init} if not equivalent to |\relax|. If the user leaves a
4739
% class style undefined, \meta{default style name} is used instead.
4740
% Thus, make sure that this style is always defined. In the example,
4741
% the first order keywordstyle is set to |\bfseries| and is the default
4742
% for all other classes.
4744
% If \meta{working procedure} is not empty, this code is executed when
4745
% reaching such an (user defined) identifier. \meta{working procedure}
4746
% takes exactly one argument, namely the class number to which the
4747
% actual identifier belongs to. If the code uses variables and requires
4748
% values from previous calls, you must define these variables
4749
% |\global|ly. It's not sure whether working procedures are executed
4750
% inside a (separate) group or not.
4752
% \texttt l indicates a language key, i.e.~the lists are reset every
4753
% language selection. \texttt o stands for `other' key.
4754
% The keyword respectively working test is either installed at the
4755
% \hookname{DetectKeyword} or \hookname{Output} hook according to
4756
% \meta{\alternative{d,o}}.
4759
% \cs{lst@InstallKeywords}
4761
% \marg{prefix}\syntaxfill \texttt{cs}\\
4762
% \marg{name}\syntaxfill |{texcs}|\\
4763
% \marg{style name}\syntaxfill |{texcsstyle}|\\
4764
% \marg{style init}\syntaxfill |\relax|\\
4765
% \marg{default style name}\syntaxfill |{keywordstyle}|\\
4766
% \marg{working procedure}\syntaxfill see below\\
4767
% \meta{\alternative{l,o}}\syntaxfill |l|\\
4768
% \meta{\alternative{d,o}}\syntaxfill |d|
4770
% Same parameters, same functionality with one execption. The macro
4771
% installs exactly one keyword class and not a whole family. Therefore
4772
% the argument to \meta{working procedure} is constant (currently empty).
4774
% The working procedure of the example reads as follows.\vspace*{-.5\baselineskip}
4776
% {\ifx\lst@lastother\lstum@backslash
4777
% \let\lst@thestyle\lst@texcsstyle
4778
% \fi}\end{verbatim}
4779
%\vspace*{-.5\baselineskip}
4780
% What does this procedure do? First of all it is called only if a
4781
% keyword from the user supplied list (or language definition) is found.
4782
% The procedure now checks for a preceding backslash and sets the output
4783
% style accordingly.
4786
% \item[0.20] |\lst@InstallTest|\marg{prefix}\syntaxbreak
4787
% |\lst@|\meta{name}|@list||\lst@|\meta{name}~|\lst@g|\meta{name}|@list||\lst@g|\meta{name}\syntaxbreak
4788
% |\lst@g|\meta{name}|@sty|~\meta{\alternative{w,s}}\meta{\alternative{d,o}}
4790
% installs a `working identifier' test or keyword style depending on
4791
% \meta{\alternative{w,s}}. |\lst@g|\meta{name}|@sty| contains the
4792
% working procedure or style macro. Note that the behaviour of the tests
4793
% depends on the \texttt{savemem} option.
4794
% The keyword respectively working test is either installed at the
4795
% \hookname{DetectKeyword} or \hookname{Output} hook according to
4796
% \meta{\alternative{d,o}}.
4798
%^^A Either each call of this macro or each different \meta{prefix} inserts
4799
%^^A another test (depending on the \texttt{savemem} option).
4801
% |\lst@|\meta{name} contains the current identifier list and
4802
% |\lst@|\meta{name}|@list| a `|\lst@|\meta{$n_i$}|\lst@g|\meta{$n_i$}'
4803
% sequence of currently used classes. If no other classes are used,
4804
% this equals |\lst@|\meta{name}|\lst@g|\meta{name}. The global versions
4805
% |\lst@g|\ldots\ are used to keep track of the keywords.
4806
% (This description needs improvement.)
4811
% \subsection{Delimiters}
4813
% We describe two stages: adding a new delimiter type to an existing class of
4814
% delimiters and writing a new class. Each class has its name; currently exist
4815
% \texttt{Comment}, \texttt{String}, and \texttt{Delim}. As you know, the
4816
% latter and the first both provide the type \texttt l, but there is no string
4817
% which starts with the given delimiter and ends at end of line. So we'll add
4820
% First of all we extend the list of string types by
4822
% \lst@AddTo\lst@stringtypes{,l}\end{verbatim}
4823
% Then we must provide the macro which takes the user supplied delimiter and
4824
% makes appropriate definitions. The command name consists of the prefix
4825
% |\lst@|, the delimiter name, |DM| for using dynamic modes, and |@| followed
4828
% \gdef\lst@StringDM@l#1#2\@empty#3#4#5{%
4829
% \lst@CArg #2\relax\lst@DefDelimB{}{}{}#3{#1}{#5\lst@Lmodetrue}}\end{verbatim}
4830
% You can put these three lines into a \texttt{.sty}-file or surround them by
4831
% |\makeatletter| and |\makeatother| in the preamble of a document.
4834
%\lst@AddTo\lst@stringtypes{,l}
4835
%\gdef\lst@StringDM@l#1#2\@empty#3#4#5{^^A
4836
% \lst@CArg #2\relax\lst@DefDelimB{}{}{}#3{#1}{#5\lst@Lmodetrue}}
4838
% \begin{lstsample}{}{}
4839
% \lstset{string=[l]//}
4840
% \begin{lstlisting}
4841
% // This is a string.
4842
% This isn't a string.
4845
% You want more details, of course. Let's begin with the arguments.
4847
% \item The first argument \emph{after} |\@empty| is used to start the
4848
% delimiter. It's provided by the delimiter class.
4849
% \item The second argument \emph{after} |\@empty| is used to end the
4850
% delimiter. It's also provided by the delimiter class. We didn't
4851
% need it in the example, see the explanation below.
4852
% \item The third argument \emph{after} |\@empty| is
4853
% \marg{style}\meta{start tokens}.
4854
% This with a preceding |\def\lst@currstyle| is used as argument to
4855
% |\lst@EnterMode|. The delimiter class also provides it. In the
4856
% example we `extended' |#5| by |\lst@Lmodetrue| (line mode true).
4857
% The mode automatically ends at end of line, so we didn't need the
4858
% end-delimiter argument.
4860
% And now for the other arguments. In case of dynamic modes, the first argument
4861
% is the mode number. Then follow the user supplied delimiter(s) whose number
4862
% must match the remaining arguments up to |\@empty|. For non-dynamic modes,
4863
% you must either allocate a static mode yourself or use a predefined mode
4864
% number. The delimiters then start with the first argument.
4866
% Eventually let's look at the replacement text of the macro. The sequence
4867
% |\lst@CArg #2\relax| puts two required arguments after |\lst@DefDelimB|.
4868
% The syntax of the latter macro is
4870
% \item[1.0] \cs{lst@DefDelimB}
4872
% |{|\meta{1st}\meta{2nd}\marg{rest}|}|\syntaxfill |{//{}}|\\
4873
% \meta{save 1st}\syntaxfill |\lst@c/0|\\
4874
% \marg{execute}\syntaxfill|{}|\\
4875
% \marg{delim~exe~modetrue}\syntaxfill|{}|\\
4876
% \marg{delim~exe~modefalse}\syntaxfill|{}|\\
4877
% \meta{start-delimiter macro}\syntaxfill|#3|\\
4878
% \meta{mode number}\syntaxfill |{#1}|\\
4879
% |{|\marg{style}\meta{start tokens}|}|\syntaxfill |{#5\lst@Lmodetrue}|
4881
% defines \meta{1st}\meta{2nd}\meta{rest} as starting-delimiter.
4882
% \meta{execute} is executed when the package comes to \meta{1st}.
4883
% \meta{delim~exe~modetrue} and \meta{delim~exe~modefalse} are
4884
% executed only if the whole delimiter \meta{1st}\meta{2nd}\meta{rest}
4885
% is found. Exactly one of them is called depending on |\lst@ifmode|.
4887
% By default the package enters the mode if the delimiter is found
4888
% \emph{and} |\lst@ifmode| is false. Internally we make an appropriate
4889
% definition of |\lst@bnext|, which can be gobbled by placing
4890
% |\@gobblethree| at the very end of \meta{delim exe modefalse}.
4891
% One can provide an own definition (and gobble the default).
4893
% \meta{save 1st} must be an undefined macro and is used internally to
4894
% store the previous meaning of \meta{1st}. The arguments \meta{2nd}
4895
% and/or \meta{rest} are empty if the delimiter has strictly less than
4896
% three characters. All characters of \meta{1st}\meta{2nd}\meta{rest}
4897
% must already be active (if not empty).
4898
% That's not a problem since the macro |\lst@CArgX| does this job.
4900
% \item[1.0] \cs{lst@DefDelimE}
4902
% |{|\meta{1st}\meta{2nd}\marg{rest}|}|\\
4905
% \marg{delim~exe~modetrue}\\
4906
% \marg{delim~exe~modefalse}\\
4907
% \meta{end-delimiter macro}\\
4908
% \meta{mode number}
4910
% Ditto for ending-delimiter with slight differences:
4911
% \meta{delim~exe~modetrue} and \meta{delim~exe~modefalse} are executed
4912
% depending on whether |\lst@mode| equals \meta{mode}.
4914
% The package ends the mode if the delimiter is found and |\lst@mode|
4915
% equals \meta{mode}. Internally we make an appropriate definition of
4916
% |\lst@enext| (not |\lst@bnext|), which can be gobbled by placing
4917
% |\@gobblethree| at the very end of \meta{delim exe modetrue}.
4919
% \item[1.0] \cs{lst@DefDelimBE}
4921
% followed by the same eight arguments as for |\lst@DefDelimB| and \ldots\\
4922
% \meta{end-delimiter macro}
4924
% This is a combination of |\lst@DefDelimB| and |\lst@DefDelimE| for the
4925
% case of starting and ending delimiter being the same.
4927
% We finish the first stage by examining two easy examples.
4928
% \texttt d-type strings are defined by
4930
% \gdef\lst@StringDM@d#1#2\@empty#3#4#5{%
4931
% \lst@CArg #2\relax\lst@DefDelimBE{}{}{}#3{#1}{#5}#4}\end{verbatim}
4932
% (and an entry in the list of string types).
4933
% Not a big deal. Ditto \texttt d-type comments:
4935
% \gdef\lst@CommentDM@s#1#2#3\@empty#4#5#6{%
4936
% \lst@CArg #2\relax\lst@DefDelimB{}{}{}#4{#1}{#6}%
4937
% \lst@CArg #3\relax\lst@DefDelimE{}{}{}#5{#1}}\end{verbatim}
4938
% Here we just need to use both |\lst@DefDelimB| and |\lst@DefDelimE|.
4941
% So let's get to the second stage. For illustration, here's the definition of
4942
% the \texttt{Delim} class. The respective first argument to the service macro
4943
% makes it delete all delimiters of the class, add the delimiter, or delete
4944
% the particular delimiter only.
4946
% \lst@Key{delim}\relax{\lst@DelimKey\@empty{#1}}
4947
% \lst@Key{moredelim}\relax{\lst@DelimKey\relax{#1}}
4948
% \lst@Key{deletedelim}\relax{\lst@DelimKey\@nil{#1}}\end{verbatim}
4949
% The service macro itself calls another macro with appropriate arguments.
4951
% \gdef\lst@DelimKey#1#2{%
4952
% \lst@Delim{}#2\relax{Delim}\lst@delimtypes #1%
4953
% {\lst@BeginDelim\lst@EndDelim}
4954
% i\@empty{\lst@BeginIDelim\lst@EndIDelim}}\end{verbatim}
4955
% We have to look at those arguments. Above you can see the actual arguments
4956
% for the \texttt{Delim} class, below are the \texttt{Comment} class ones.
4957
% Note that the user supplied value covers the second and third line of
4960
% \item[0.21,,changed]
4963
% \meta{default style macro}\syntaxfill \cs{lst@commentstyle}\\ \relax
4964
% [\texttt*[\texttt*]]\texttt[\meta{type}\texttt][\texttt[\meta{style}\texttt][\texttt[\meta{type option}\texttt]]]\\
4965
% \meta{delimiter\textup(s\textup)}\cs{relax}\syntaxfill|#2|\cs{relax}\\
4966
% \marg{delimiter name}\syntaxfill|{Comment}|\\
4967
% \meta{delimiter types macro}\syntaxfill\texttt{\cs{lst@commenttypes}}\\
4968
% \alternative{\cs{@empty},\cs{@nil},\cs{relax}}\syntaxfill|#1|\\
4969
% \marg{begin- and end-delim macro}\syntaxfill|{|\cs{lst@BeginComment}\cs{lst@EndComment}|}|\\
4970
% \meta{extra prefix}\syntaxfill |i|\\
4971
% \meta{extra conversion}\syntaxfill |\@empty|\\
4972
% \marg{begin- and end-delim macro}\syntaxfill|{|\cs{lst@BeginIComment}\cs{lst@EndIComment}|}|
4974
% Most arguments should be clear. We'll discuss the last four. Both
4975
% \marg{begin- and end-delim macro} must contain exactly two control
4976
% sequences, which are given to |\lst@|\meta{name}[|DM|]|@|\meta{type}
4977
% to begin and end a delimiter. These are the arguments |#3| and |#4| in our
4978
% first example of |\lst@StringDM@l|. Depending on whether the user chosen
4979
% type starts with \meta{extra prefix}, the first two or the last control
4980
% sequences are used.
4982
% By default the package takes the delimiter(s), makes the characters active,
4983
% and places them after |\lst@|\meta{name}[|DM|]|@|\meta{type}. If the user
4984
% type starts with \meta{extra prefix}, \meta{extra conversion} might change
4985
% the definition of |\lst@next| to choose a different conversion. The default
4986
% is equivalent to |\lst@XConvert| with |\lst@false|.
4988
% Note that \meta{type} never starts with \meta{extra prefix} since it is
4989
% discarded. The functionality must be fully implemented by choosing a
4990
% different \marg{begin- and end-delim macro} pair.
4992
% You might need to know the syntaxes of the \meta{begin- and end-delim macro}s.
4993
% They are called as follows.
4995
% \item[0.21] |\lst@Begin|\meta{whatever}
4998
% |{|\marg{style}\meta{start tokens}|}|
4999
% \meta{delimiter}|\@empty|
5001
% \item[0.21] |\lst@End|\meta{whatever}
5004
% \meta{delimiter}|\@empty|
5006
% The existing macros are internally defined in terms of |\lst@DelimOpen| and
5007
% |\lst@DelimClose|, see the implementation.
5010
% \subsection{Getting the kernel run}
5012
% If you want new pretty-printing environments, you should be happy with
5013
% section \ref{rEnvironments}. New commands like |\lstinline| or
5014
% |\lstinputlisting| are more difficult. Roughly speaking you must follow
5017
% \item Open a group to make all changes local.
5018
% \item \meta{Do whatever you want.}
5019
% \item Call |\lsthk@PreSet| in any case.
5020
% \item Now you \emph{might } want to (but need not) use |\lstset| to set some
5022
% \item \meta{Do whatever you want.}
5023
% \item Execute |\lst@Init\relax| to finish initialization.
5024
% \item \meta{Do whatever you want.}
5025
% \item Eventually comes the source code, which is processed by the kernel.
5026
% You must ensure that the characters are either not already read or all
5027
% active. Moreover \emph{you} must install a way to detect the end of the
5028
% source code. If you've reached the end, you must \ldots
5029
% \item \ldots\ call |\lst@DeInit| to shutdown the kernel safely.
5030
% \item \meta{Do whatever you want.}
5031
% \item Close the group from the beginning.
5033
% For example, consider the |\lstinline| command in case of being not inside an
5034
% argument. Then the steps are as follows.
5036
% \item |\leavevmode\bgroup| opens a group.
5037
% \item |\def\lst@boxpos{b}| `baseline' aligns the listing.
5038
% \item |\lsthk@PreSet|
5039
% \item |\lstset{flexiblecolumns,#1}| (|#1| is the user provided
5041
% \item |\lsthk@TextStyle| deactivates all features not safe here.
5042
% \item |\lst@Init\relax|
5043
% \item |\lst@Def{`#1}{\lst@DeInit\egroup}| installs the `end inline'
5044
% detection, where |#1| is the next character after |\lstinline|.
5045
% Moreover chr(13) is redefined to end the fragment in the same way but
5046
% also issues an error message.
5047
% \item Now comes the source code and \ldots
5048
% \item \ldots\ |\lst@DeInit| (from |\lst@Def| above) ends the code snippet
5051
% \item |\egroup| (also from |\lst@Def|) closes the group.
5053
% The real definition is different since we allow source code inside arguments.
5054
% Read also section \ref{iTheInputCommand} if you really want to write
5055
% pretty-printing commands.
5058
% \section{Useful internal definitions}\label{dUsefulInternalDefinitions}
5060
% This section requires an update.
5063
% \subsection{General purpose macros}\label{dGeneralPurposeMacros}
5066
% \item[0.19] |\lst@AddTo|\meta{macro}\marg{\TeX~material}
5068
% adds \meta{\TeX~material} globally to the contents of \meta{macro}.
5070
% \item[0.20] |\lst@Extend|\meta{macro}\marg{\TeX~material}
5072
% calls |\lst@AddTo| after the first token of \meta{\TeX~material} is
5073
% |\expand|ed|after|. For example, |\lst@Extend \a \b| merges the
5074
% contents of the two macros and stores it globally in |\a|.
5076
% \item[0.19] |\lst@lAddTo|\meta{macro}\marg{\TeX~material}
5077
% \item[0.20] |\lst@lExtend|\meta{macro}\marg{\TeX~material}
5079
% are local versions of |\lst@AddTo| and |\lst@Extend|.
5081
% \item[0.18] |\lst@DeleteKeysIn|\meta{macro}\meta{macro \textup(keys to remove\textup)}
5083
% Both macros contain a comma separated list of keys (or keywords). All
5084
% keys appearing in the second macro are removed (locally) from the first.
5086
% \item[0.19] |\lst@ReplaceIn|\meta{macro}\meta{macro \textup(containing replacement list\textup)}
5087
% \item[0.20] |\lst@ReplaceInArg|\meta{macro}\marg{replacement list}
5089
% The replacement list has the form $a_1b_1$\ldots$a_nb_n$, where each
5090
% $a_i$ and $b_i$ is a character sequence (enclosed in braces if
5091
% necessary) and may contain macros, but the first token of $b_i$ must
5092
% not be equivalent to |\@empty|. Each sequence $a_i$ inside the first
5093
% macro is (locally) replaced by $b_i$.
5094
% The suffix |Arg| refers to the \emph{braced} second argument instead of
5095
% a (nonbraced) macro. It's a hint that we get the `real' argument and
5096
% not a `pointer' to the argument.
5098
% \item[0.20] |\lst@IfSubstring|\marg{character sequence}\meta{macro}\marg{then}\marg{else}
5100
% \meta{then} is executed if \meta{character sequence} is a substring of
5101
% the contents of \meta{macro}. Otherwise \meta{else} is called.
5103
% \item[0.12] |\lst@IfOneOf|\meta{character sequence}|\relax|\meta{macro}\marg{then}\marg{else}
5105
% |\relax| terminates the first parameter here since it is faster than
5106
% enclosing it in braces. \meta{macro} contains a comma separated list
5107
% of identifiers. If the character sequence is one of these indentifiers,
5108
% \meta{then} is executed, and otherwise \meta{else}.
5110
% \item[0.21] |\lst@Swap|\marg{tok1}\marg{tok2}
5112
% changes places of the following two tokens or arguments \emph{without}
5113
% inserting braces. For example, |\lst@Swap{abc}{def}| expands to
5116
% \item[0.18] |\lst@IfNextChars|\meta{macro}\marg{then}\marg{else}
5117
% \item[0.19] |\lst@IfNextCharsArg|\marg{character sequence}\marg{then}\marg{else}
5119
% Both macros execute either \meta{then} or \meta{else} according to
5120
% whether the given character sequence respectively the contents of the
5121
% given macro is found (after the three arguments). Note an important
5122
% difference between these macros and \LaTeX's |\@ifnextchar|:
5123
% We remove the characters behind the arguments until it is possible to
5124
% decide which part must be executed. However, we save these characters
5125
% in the macro |\lst@eaten|, so they can be inserted using \meta{then} or
5128
% \item[0.19] |\lst@IfNextCharActive|\marg{then}\marg{else}
5130
% executes \meta{then} if next character is active, and \meta{else}
5133
% \item[0.20] |\lst@DefActive|\meta{macro}\marg{character sequence}
5135
% stores the character sequence in \meta{macro}, but all characters
5136
% become active. The string \emph{must not} contain a begin group, end
5137
% group or escape character (|{}\|); it may contain a left brace, right
5138
% brace or backslash with other meaning (= catcode). This command
5139
% would be quite surplus if \meta{character sequence} is not already read
5140
% by \TeX\ since such catcodes can be changed easily. It is explicitly
5141
% allowed that the charcaters have been read, e.g.~in
5142
% |\def\test{\lst@DefActive\temp{ABC}}|!
5144
% Note that this macro changes |\lccode|s 0--9 without restoring them.
5146
% \item[0.20] |\lst@DefOther|\meta{macro}\marg{character sequence}
5148
% stores \meta{character sequence} in \meta{macro}, but all characters
5149
% have catcode 12. Moreover all spaces are removed and control sequences
5150
% are converted to their name without preceding backslash. For example,
5151
% |\{ Chip \}| leads to |{Chip}| where all catcodes are 12---internally
5152
% the primitive |\meaning| is used.
5155
% \item[0.19] |\lst@MakeActive|\marg{character sequence}
5157
% stores the character sequence in |\lst@arg| and has the same
5158
% restrictions as |\lst@DefActive|. If fact, the latter definition uses
5164
% \subsection{Character tables manipulated}\label{dCharacterTablesManipulated}
5167
% \item[0.20] |\lst@SaveDef|\marg{character code}\meta{macro}
5169
% Saves the current definition of the specified character in
5170
% \meta{macro}. You should always save a character definition before you
5171
% redefine it! And use the saved version instead of writing directly
5172
% |\lst@Process|\ldots---the character could already be redefined and
5173
% thus not equivalent to its standard definition.
5175
% \item[0.20] |\lst@DefSaveDef|\marg{character code}\meta{macro}\meta{parameter text}\marg{definition}
5176
% \item[0.20] |\lst@LetSaveDef|\marg{character code}\meta{macro}\meta{token}
5178
% combine |\lst@SaveDef| and |\lst@Def| respectively |\lst@Let|.
5180
% Of course I shouldn't forget to mention \emph{where} to alter the character
5181
% table. Hook material at \hookname{SelectCharTable} makes permanent changes,
5182
% i.e.~it effects all languages. The following two keys can be used in any
5183
% language definition and effects the particular language only.
5185
% \item[0.20] |SelectCharTable=|\meta{\TeX\ code}
5186
% \item[0.20] |MoreSelectCharTable=|\meta{\TeX\ code}
5188
% uses \meta{\TeX\ code} (additionally) to select the character table.
5189
% The code is executed after the standard character table is selected,
5190
% but possibly before other aspects make more changes. Since previous
5191
% meanings are always saved and executed inside the new definition, this
5192
% should be harmless.
5194
% Here come two rather useless examples. Each point (full stop) will cause a
5195
% message `|.|' on the terminal and in the |.log| file if language |useless| is
5198
% \lstdefinelanguage{useless}
5199
% {SelectCharTable=\lst@DefSaveDef{46}% save chr(46) ...
5200
% \lsts@point % ... in \lsts@point and ...
5201
% {\message{.}\lsts@point}% ... use new definition
5203
% If you want to count points, you could write
5205
% \newcount\lst@points % \global
5206
% \lst@AddToHook{Init}{\global\lst@points\z@}
5207
% \lst@AddToHook{DeInit}{\message{Number of points: \the\lst@points}}
5208
% \lstdefinelanguage[2]{useless}
5209
% {SelectCharTable=\lst@DefSaveDef{46}\lsts@point
5210
% {\global\advance\lst@points\@ne \lsts@point}
5212
% |% \global| indicates that the allocated counter is used globally. We zero
5213
% the counter at the beginning of each listing, display a message about the
5214
% current value at the end of a listing, and each processed point advances the
5218
% \item[0.21] |\lst@CArg|\meta{active characters}|\relax|\meta{macro}
5220
% The string of active characters is split into \meta{1st}, \meta{2nd},
5221
% and \marg{rest}. If one doesn't exist, an empty argument is used. Then
5222
% \meta{macro} is called with |{|\meta{1st}\meta{2nd}\marg{rest}|}| plus
5223
% a yet undefined control sequence \meta{save 1st}. This macro is
5224
% intended to hold the current definition of \meta{1st}, so \meta{1st}
5225
% can be redefined without loosing information.
5227
% \item[0.19] |\lst@CArgX|\meta{characters}|\relax|\meta{macro}
5229
% makes \meta{characters} active before calling |\lst@CArg|.
5231
% \item[0.21] |\lst@CDef{|\meta{1st}\meta{2nd}\marg{rest}|}|\meta{save 1st}\marg{execute}\marg{pre}\marg{post}
5233
% should be used in connection with |\lst@CArg| or |\lst@CArgX|, i.e.~as
5234
% \meta{macro} there. \meta{1st}, \meta{2nd}, and \meta{rest} must be
5235
% active characters and \meta{save 1st} must be an undefined control
5238
% Whenever the package reaches the character \meta{1st} (in a listing),
5239
% \meta{execute} is executed. If the package detects the whole string
5240
% \meta{1st}\meta{2nd}\meta{rest}, we additionally execute \meta{pre},
5241
% then the string, and finally \meta{post}.
5243
% \item[0.21] |\lst@CDefX|\meta{1st}\meta{2nd}\marg{rest}\meta{save 1st}\marg{execute}\marg{pre}\marg{post}
5245
% Ditto except that we execute \meta{pre} and \meta{post} without the
5246
% original string if we reach \meta{1st}\meta{2nd}\meta{rest}.
5247
% This means that the string is replaced by \meta{pre}\meta{post} (with
5248
% preceding \meta{execute}).
5250
% As the final example, here's the definition of |\lst@DefDelimB|.
5252
% \gdef\lst@DefDelimB#1#2#3#4#5#6#7#8{%
5255
% {\let\lst@bnext\lst@CArgEmpty
5256
% \lst@ifmode #4\else
5258
% \def\lst@bnext{#6{#7}{#8}}%
5261
% \@empty}\end{verbatim}
5265
% \part{Implementation}
5270
%^^A Don't index TeX-primitives.
5272
% \DoNotIndex{\advance,\afterassignment,\aftergroup,\batchmode,\begingroup}
5273
% \DoNotIndex{\box,\catcode,\char,\chardef,\closeout,\copy,\count,\csname,\def}
5274
% \DoNotIndex{\dimen,\discretionary,\divide,\dp,\edef,\else,\end,\endcsname}
5275
% \DoNotIndex{\endgroup,\endinput,\endlinechar,\escapechar,\everypar}
5276
% \DoNotIndex{\expandafter,\fi,\gdef,\global,\globaldefs,\hbadness,\hbox}
5277
% \DoNotIndex{\hrulefill,\hss,\ht}
5278
% \DoNotIndex{\if,\ifdim,\iffalse,\ifhmode,\ifinner,\ifnum,\ifodd,\iftrue}
5279
% \DoNotIndex{\ifvoid,\ifx,\ignorespaces,\immediate,\input,\jobname,\kern}
5280
% \DoNotIndex{\lccode,\leftskip,\let,\long,\lower,\lowercase,\meaning,\message}
5281
% \DoNotIndex{\multiply,\muskip,\noexpand,\noindent,\openout,\par,\parfillskip}
5282
% \DoNotIndex{\parshape,\parskip,\raise,\read,\relax,\rightskip,\setbox,\skip}
5283
% \DoNotIndex{\string,\the,\toks,\uppercase,\vbox,\vcenter,\vrule,\vtop,\wd}
5284
% \DoNotIndex{\write,\xdef}
5287
%^^A Don't index LaTeX's private definitions.
5289
% \DoNotIndex{\@@end,\@@par,\@M,\@arabic,\@circlefnt,\@currentlabel}
5290
% \DoNotIndex{\@currenvir,\@depth,\@doendpe,\@dottedtocline,\@eha,\@ehc}
5291
% \DoNotIndex{\@empty,\@firstofone,\@firstoftwo,\@float,\@for,\@getcirc}
5292
% \DoNotIndex{\@gobble,\@gobbletwo,\@halfwidth,\@height,\@ifnextchar}
5293
% \DoNotIndex{\@ifundefined,\@ignoretrue,\@makecaption,\@makeother,\@namedef}
5294
% \DoNotIndex{\@ne,\@noligs,\@notprerr,\@onlypreamble,\@secondoftwo,\@spaces}
5295
% \DoNotIndex{\@starttoc,\@totalleftmargin,\@undefined,\@whilenum}
5296
% \DoNotIndex{\@wholewidth,\@width}
5297
% \DoNotIndex{\c@chapter,\c@figure,\c@page,\end@float,\f@family,\filename@area}
5298
% \DoNotIndex{\filename@base,\filename@ext,\filename@parse,\if@twoside}
5299
% \DoNotIndex{\l@ngrel@x,\m@ne,\new@command,\nfss@catcodes,\tw@,\thr@@}
5300
% \DoNotIndex{\z@,\zap@space}
5303
%^^A Don't index LaTeX's package definitions.
5305
% \DoNotIndex{\AtEndOfPackage}
5306
% \DoNotIndex{\CurrentOption,\DeclareOption,\IfFileExists,\InputIfFileExists}
5307
% \DoNotIndex{\MessageBreak,\NeedsTeXFormat,\PackageError,\PackageWarning}
5308
% \DoNotIndex{\ProcessOptions,\ProvidesFile,\ProvidesPackage,\RequirePackage}
5311
%^^A Don't index LaTeX's public definitions.
5313
% \DoNotIndex{\abovecaptionskip,\active,\addcontentsline,\addtocounter,\begin}
5314
% \DoNotIndex{\belowcaptionskip,\bfseries,\bgroup,\bigbreak,\chapter}
5315
% \DoNotIndex{\contentsname,\do,\egroup,\footnotesize,\index,\itshape}
5316
% \DoNotIndex{\linewidth,\llap,\makeatletter,\newbox,\newcommand,\newcount}
5317
% \DoNotIndex{\newcounter,\newdimen,\newtoks,\newwrite,\nointerlineskip}
5318
% \DoNotIndex{\normalbaselines,\normalfont,\numberline,\pretolerance,\protect}
5319
% \DoNotIndex{\qquad,\refstepcounter,\removelastskip,\renewcommand,\rlap}
5320
% \DoNotIndex{\small,\smallbreak,\smallskipamount,\smash,\space,\strut}
5321
% \DoNotIndex{\strutbox,\tableofcontents,\textasciicircum,\textasciitilde}
5322
% \DoNotIndex{\textasteriskcentered,\textbackslash,\textbar,\textbraceleft}
5323
% \DoNotIndex{\textbraceright,\textdollar,\textendash,\textgreater,\textless}
5324
% \DoNotIndex{\textunderscore,\textvisiblespace,\thechapter,\ttdefault}
5325
% \DoNotIndex{\ttfamily,\typeout,\value,\vphantom}
5328
%^^A Don't index definitions from other packages.
5330
% \DoNotIndex{\MakePercentComment,\MakePercentIgnore}
5333
%^^A Don't index 0.19 definitions.
5335
% \DoNotIndex{\listlistingsname,\listoflistings,\lstbox,\lstbox@}
5336
% \DoNotIndex{\lstlanguage@}
5339
%^^A Don't index 0.20 subdefinitions.
5341
% \DoNotIndex{\lst@ATH@,\lst@BOLGobble@,\lst@BOLGobble@@,\lst@CArg@,\lst@CArg@@}
5342
% \DoNotIndex{\lst@CBC@,\lst@CBC@@,\lst@CCECUse@,\lst@CCPutMacro@,\lst@DefLang@}
5343
% \DoNotIndex{\lst@DefLang@@,\lst@DefOther@,\lst@DeleteKeysIn@,\lst@Escape@}
5344
% \DoNotIndex{\lstframe@,\lst@frameH@,\lst@frameL@,\lst@frameR@}
5345
% \DoNotIndex{\lst@FillFixed@,\lst@FindAlias@,\lst@FVConvert@}
5346
% \DoNotIndex{\lst@IfNextChars@,\lst@IfNextChars@@,\lst@InsideConvert@}
5347
% \DoNotIndex{\lst@InstallKeywords@,\lst@Key@,\lst@KeywordTestI@}
5348
% \DoNotIndex{\lst@MakeActive@,\lst@MakeMoreKeywords@}
5349
% \DoNotIndex{\lst@RC@,\lst@RC@@,\lst@ReplaceIn@,\lst@ReplaceInput@}
5350
% \DoNotIndex{\lst@ReportAllocs@,\lst@SKS@,\lst@SKS@@,\lst@UBC@}
5351
% \DoNotIndex{\lst@WorkingTestI@,\lstalias@,\lstalias@@,\lstalso@}
5352
% \DoNotIndex{\lstdefinestyle@,\lstenv@BOLGobble@@}
5353
% \DoNotIndex{\lstenv@ProcessJ@,\lstinline@,\lstKV@OptArg@,\lstKV@SetIf@}
5354
% \DoNotIndex{\lstlang@,\lstnewenvironment@,\lst@outputpos,\lstset@}
5357
% \section{Overture}
5359
% \paragraph{Registers}
5360
% For each aspect, the required numbers of registers are listed in section
5361
% \lstref{dPackageLoading}. Furthermore, the \packagename{keyval} package
5362
% allocates one token register. The macros, boxes and counters
5363
% |\@temp|\ldots|a|/|b|, the dimensions |\@tempdim|\ldots, and the macro
5364
% |\@gtempa| are also used, see the index.
5366
% \paragraph{Naming conventions}
5367
% Let's begin with definitions for the user. All these public macros have
5368
% lower case letters and contain |lst|. Private macros and variables use the
5369
% following prefixes (not up-to-date?):
5371
% \item |\lst@| for a general macro or variable,
5372
% \item |\lstenv@| if it is defined for the listing environment,
5373
% \item |\lsts@| for |s|aved character meanings,
5374
% \item |\lsthk@|\meta{name of hook} holds hook material,
5375
% \item |\lst|\meta{prefix}|@| for various kinds of keywords and working
5377
% \item |\lstlang@|\meta{language}|@|\meta{dialect} contains a language and
5378
% \item |\lststy@|\meta{the style} contains style definition,
5379
% \item |\lstpatch@|\meta{aspect} to patch an aspect,
5381
% \item |\lsta@|\meta{language}|$|\meta{dialect} contains alias,
5382
% \item |\lsta@|\meta{language} contains alias for all dialects of a language,
5383
% \item |\lstdd@|\meta{language} contains default dialect of a language
5386
% To distinguish procedure-like macros from data-macros, the name of procedure
5387
% macros use upper case letters with each beginning word, e.g.~|\lst@AddTo|.
5388
% A macro with suffix |@| is the main working-procedure for another definition,
5389
% for example |\lstinputlisting@| does the main work for |\lstinputlisting|.
5391
% \paragraph{Preamble}
5392
% All files generated from this \texttt{listings.dtx} will get a header.
5394
%% Please read the software license in listings.dtx or listings.dvi.
5396
%% (w)(c) 1996 -- 2002 Carsten Heinz and/or any other author
5397
%% listed elsewhere in this file.
5399
%% This file is distributed under the terms of the LaTeX Project Public
5400
%% License from CTAN archives in directory macros/latex/base/lppl.txt.
5401
%% Either version 1.0 or, at your option, any later version.
5403
%% Permission is granted to modify the listings package as well as
5404
%% lstdrvrs.dtx. You are not allowed to distribute a modified version
5405
%% of the package or lstdrvrs.dtx unless you change the file names and
5406
%% provide the original files. In any case it is better to contact the
5407
%% address below; other users will welcome removed bugs, new features,
5408
%% and additional programming languages.
5410
%% The listings package is free software.
5412
%% However, if you distribute the package as part of a commercial
5413
%% product or if you use the package to prepare a commercial document
5414
%% (books, journals, and so on), I'd like to encourage you to make a
5415
%% donation to the LaTeX3 fund. The size of this `license fee' should
5416
%% depend on the value of the package for your product. For more
5417
%% information about LaTeX see http://www.latex-project.org
5419
%% No matter whether you use the package for a commercial or
5420
%% non-commercial document, please send me a copy of the document (.dvi,
5421
%% .ps, .pdf, hardcopy, etc.) to support further development---it is
5422
%% easier to introduce new features or simplify things if I see how the
5423
%% package is used by other people.
5425
%% Send comments and ideas on the package, error reports and additional
5426
%% programming languages to <cheinz@gmx.de>.
5430
% \paragraph{Identification}
5431
% All files will have same date and version.
5433
\def\filedate{2002/04/01}
5434
\def\fileversion{1.0}
5436
% What we need and who we are.
5439
\NeedsTeXFormat{LaTeX2e}
5440
\ProvidesPackage{listings}
5441
[\filedate\space\fileversion\space(Carsten Heinz)]
5443
% \begin{macro}{\lst@CheckVersion}
5444
% can be used by the various driver files to guarantee the correct version.
5446
\def\lst@CheckVersion#1{\edef\reserved@a{#1}%
5447
\ifx\lst@version\reserved@a \expandafter\@gobble
5448
\else \expandafter\@firstofone \fi}
5451
\let\lst@version\fileversion
5455
% For example by the miscellaneous file
5458
\ProvidesFile{lstmisc.sty}
5459
[\filedate\space\fileversion\space(Carsten Heinz)]
5460
\lst@CheckVersion\fileversion
5463
*** This file requires `listings.sty' version \fileversion.^^J%
5464
*** You have a serious problem, so I'm exiting ...^^J%
5469
% or by the dummy patch.
5472
\ProvidesFile{lstpatch.sty}
5473
[\filedate\space\fileversion\space(Carsten Heinz)]
5474
\lst@CheckVersion\lst@version{}
5479
\ProvidesPackage{lstdoc}
5480
[\filedate\space\fileversion\space(Carsten Heinz)]
5484
% \paragraph{Category codes}
5485
% We define two macros to ensure correct catcodes when we input other files of
5486
% the \packagename{listings} package.
5488
% \begin{macro}{\lst@InputCatcodes}
5489
% |@| and |"| become letters. Tabulators and EOLs are ignored; this avoids
5490
% unwanted spaces---in the case I've forgotten a comment character.
5493
\def\lst@InputCatcodes{%
5494
\makeatletter \catcode`\"12%
5495
\catcode`\^^@\active
5504
% \begin{macro}{\lst@RestoreCatcodes}
5505
% To load the kernel, we will change some catcodes and lccodes. We restore them
5506
% at the end of package loading. \lsthelper{Dr.~Jobst~Hoffmann}{2000/11/17}
5507
% {incompatibility with typehtml package} reported an incompatibility with the
5508
% \packagename{typehtml} package, which is resolved by |\lccode`\/`\/| below.
5510
\def\lst@RestoreCatcodes#1{%
5512
\noexpand\catcode`\noexpand#1\the\catcode`#1\relax
5513
\expandafter\lst@RestoreCatcodes
5515
\edef\lst@RestoreCatcodes{%
5516
\noexpand\lccode`\noexpand\/`\noexpand\/%
5517
\lst@RestoreCatcodes\"\^^I\^^M\~\^^@\relax}
5519
% Now we are ready for
5522
\AtEndOfPackage{\lst@RestoreCatcodes}
5527
% \paragraph{Statistics}
5528
% \begin{macro}{\lst@GetAllocs}
5529
% \begin{macro}{\lst@ReportAllocs}
5530
% are used to show the allocated registers.
5533
\def\lst@GetAllocs{%
5535
0\noexpand\count\the\count10,1\noexpand\dimen\the\count11,%
5536
2\noexpand\skip\the\count12,3\noexpand\muskip\the\count13,%
5537
4\noexpand\box\the\count14,5\noexpand\toks\the\count15,%
5538
6\noexpand\read\the\count16,7\noexpand\write\the\count17}}
5539
\def\lst@ReportAllocs{%
5540
\message{^^JAllocs:}\def\lst@temp{none}%
5541
\expandafter\lst@ReportAllocs@\lst@allocs,\z@\relax\z@,}
5542
\def\lst@ReportAllocs@#1#2#3,{%
5543
\ifx#2\relax \message{\lst@temp^^J}\else
5544
\@tempcnta\count1#1\relax \advance\@tempcnta -#3\relax
5545
\ifnum\@tempcnta=\z@\else
5546
\let\lst@temp\@empty
5547
\message{\the\@tempcnta \string#2,}%
5549
\expandafter\lst@ReportAllocs@
5553
% \end{macro}\end{macro}
5560
% \paragraph{Miscellaneous}
5561
% \begin{macro}{\@lst}
5562
% Just a definition to save memory space.
5571
% \section{General problems}
5573
% All definitions in this section belong to the kernel.
5579
%^^A \subsection{Quick `if parameter empty'}
5581
%^^A There are many situations where you have to look whether a macro parameter is empty.
5582
%^^A We have at least two possibilities to test |#1|, for example:
5584
%^^A \begin{minipage}{0.35\linewidth}
5585
%^^A \begin{verbatim}
5587
%^^A\ifx \test\empty
5590
%^^A % #1 is not empty
5591
%^^A\fi\end{verbatim}
5593
%^^A \hskip2em\vrule\hskip2em
5594
%^^A \begin{minipage}{0.35\linewidth}
5595
%^^A \begin{verbatim}
5596
%^^A\ifx \empty#1\empty
5599
%^^A % #1 is not empty
5600
%^^A\fi\end{verbatim}
5603
%^^A where |\empty| is defined by |\def\empty{}|, of course.
5604
%^^A The left variant should be clear and works in any case.
5605
%^^A The right-hand side works correct if and only if the first token of |#1| is
5606
%^^A not equivalent to |\empty|.
5607
%^^A This granted, the |\ifx| is true if and only if |#1| is empty (since |\empty|
5608
%^^A left from |#1| is (not) compared with |\empty| on the right).
5609
%^^A The two |\empty|s might be replaced by any other macro, which is not
5610
%^^A equivalent to the first token of the argument.
5611
%^^A But the definition of that macro shouldn't be too complex since this would
5612
%^^A slow down the |\ifx|.
5613
%^^A The right example needs about $45\%$ of the left's time.
5614
%^^A Note that this \TeX{}nique lost its importance from version 0.18 on and that
5615
%^^A other packages use |!| or |\relax| instead of |\empty|, for example.
5617
%^^A This \TeX nique is described in ``The \TeX book'' on page 376.
5620
% \subsection{Substring tests}\label{iSubstringTests}
5622
% \lstset{language=TeX,gobble=4,xleftmargin=20pt,columns=[l]fullflexible,mathescape,keywordstyle=\ttfamily,texcsstyle=\bfseries}
5623
% \let\texverb\lstinline
5624
% \lstnewenvironment{texcode}[1][]{\lstset{#1}}{}
5625
% \lstset{keywords={def,key}}
5627
% It's easy to decide whether a given character sequence is a substring of
5628
% another string. For example, for the substring \texverb|def| we could say
5630
% \def \lst@temp#1def#2\relax{%
5631
% \ifx \@empty#2\@empty
5632
% % "def" is not a substring
5634
% % "def" is a substring
5637
% \lst@temp $\meta{another\ string}$def\relax
5639
% When \TeX\ passes the arguments |#1| and |#2|, the second is empty if
5640
% and only if \texverb|def| is not a substring. Without the additional
5641
% \texverb|def\relax|, one would get a ``runaway argument'' error if
5642
% \meta{another string} doesn't contain \texverb|def|.
5644
% We use substring tests mainly in the special case of an identifier and a
5645
% comma separated list of keys or keywords:
5646
% \begin{texcode}[keywords=key]
5647
% \def \lst@temp#1,key,#2\relax{%
5648
% \ifx \@empty#2\@empty
5649
% % `key' is not a keyword
5651
% % `key' is a keyword
5654
% \lst@temp,$\meta{list\ of\ keywords}$,key,\relax
5656
% This works very well and is quite fast. But we can reduce run time in the
5657
% case that \texttt{key} is a keyword. Then |#2| takes the rest of the string,
5658
% namely all keywords after \texttt{key}.
5659
% Since \TeX\ inserts |#2| between the \texverb|\@empty|s, it must drop all of
5660
% |#2| except the first character---which is compared with \texverb|\@empty|.
5661
% We can redirect this rest to a third parameter:
5662
% \begin{texcode}[keywords=key]
5663
% \def \lst@temp#1,key,#2#3\relax{%
5665
% % "key" is not a keyword
5667
% % "key" is a keyword
5670
% \lst@temp,$\meta{list\ of\ keywords}$,key,\@empty\relax
5672
% That's a bit faster and an improvement for version 0.20.
5674
% \begin{macro}{\lst@IfSubstring}
5675
% The implementation should be clear from the discussion above.
5677
\def\lst@IfSubstring#1#2{%
5678
\def\lst@temp##1#1##2##3\relax{%
5679
\ifx \@empty##2\expandafter\@secondoftwo
5680
\else \expandafter\@firstoftwo \fi}%
5681
\expandafter\lst@temp#2#1\@empty\relax}
5685
% \begin{macro}{\lst@IfOneOf}
5688
\def\lst@IfOneOf#1\relax#2{%
5689
\def\lst@temp##1,#1,##2##3\relax{%
5690
\ifx \@empty##2\expandafter\@secondoftwo
5691
\else \expandafter\@firstoftwo \fi}%
5692
\expandafter\lst@temp\expandafter,#2,#1,\@empty\relax}
5696
% One day, if there is need for a case insensitive key(word) test again, we
5697
% can use two |\uppercase|s to normalize the first parameter:
5699
%\def\lst@IfOneOfInsensitive#1\relax#2{%
5700
% \uppercase{\def\lst@temp##1,#1},##2##3\relax{%
5701
% \ifx \@empty##2\expandafter\@secondoftwo
5702
% \else \expandafter\@firstoftwo \fi}%
5704
% \expandafter\lst@temp\expandafter,#2,#1},\@empty\relax}\end{verbatim}
5705
% Here we assume that macro |#2| already contains capital characters only, see
5706
% the definition of |\lst@MakeMacroUppercase| at the very end of section
5707
% \ref{iMakingTests}. If we \emph{must not} assume that, we could simply
5708
% insert an |\expandafter| between the second |\uppercase| and the following
5709
% brace. But this slows down the tests!
5712
% \begin{macro}{\lst@DeleteKeysIn}
5713
% The submacro does the main work; we only need to expand the second
5714
% macro---the list of keys to remove---and append the terminator |\relax|.
5716
\def\lst@DeleteKeysIn#1#2{%
5717
\expandafter\lst@DeleteKeysIn@\expandafter#1#2,\relax,}
5719
% `Replacing' the very last |\lst@DeleteKeysIn@| by |\lst@RemoveCommas|
5720
% terminates the loop here. Note: The |\@empty| after |#2| ensures that this
5721
% macro also works if |#2| is empty.
5723
\def\lst@DeleteKeysIn@#1#2,{%
5725
\expandafter\@firstoftwo\expandafter\lst@RemoveCommas
5727
\ifx\@empty#2\@empty\else
5729
% If we haven't reached the end of the list and if the key is not empty, we
5730
% define a temporary macro which removes all appearances.
5732
\def\lst@temp##1,#2,##2{%
5734
\ifx\@empty##2\@empty\else
5735
\expandafter\lst@temp\expandafter,%
5737
\edef#1{\expandafter\lst@temp\expandafter,#1,#2,\@empty}%
5740
\lst@DeleteKeysIn@#1}
5744
% The following modification needs about $50\%$ more run time.
5745
% It doesn't use |\edef| and thus also works with |\{| inside |#1|.
5746
% However, we don't need that at the moment.
5748
% \def\lst@temp##1,#2,##2{%
5750
% \lst@lAddTo#1{##1}%
5752
% \lst@lAddTo#1{,##1}%
5753
% \expandafter\lst@temp\expandafter,%
5755
% \let\@tempa#1\let#1\@empty
5756
% \expandafter\lst@temp\expandafter,\@tempa,#2,\@empty\end{verbatim}
5759
% \begin{macro}{\lst@RemoveCommas}
5760
% The macro drops commas at the beginning and assigns the new value to |#1|.
5762
\def\lst@RemoveCommas#1{\edef#1{\expandafter\lst@RC@#1\@empty}}
5763
\def\lst@RC@#1{\ifx,#1\expandafter\lst@RC@ \else #1\fi}
5767
% The following version works with |\{| inside the macro |#1|.
5769
%\def\lst@RemoveCommas#1{\expandafter\lst@RC@#1\@empty #1}
5771
% \ifx,#1\expandafter\lst@RC@
5772
% \else\expandafter\lst@RC@@\expandafter#1\fi}
5773
%\def\lst@RC@@#1\@empty#2{\def#2{#1}}\end{verbatim}
5776
% \begin{macro}{\lst@ReplaceIn}
5777
% \begin{macro}{\lst@ReplaceInArg}
5778
% These macros are similar to |\lst@DeleteKeysIn|, except that \ldots
5780
\def\lst@ReplaceIn#1#2{%
5781
\expandafter\lst@ReplaceIn@\expandafter#1#2\@empty\@empty}
5782
\def\lst@ReplaceInArg#1#2{\lst@ReplaceIn@#1#2\@empty\@empty}
5784
% \ldots\space we replace |#2| by |#3| instead of |,#2,| by a single comma
5785
% (which removed the key |#2| above).
5787
\def\lst@ReplaceIn@#1#2#3{%
5788
\ifx\@empty#3\relax\else
5789
\def\lst@temp##1#2##2{%
5793
\lst@lAddTo#1{##1#3}\expandafter\lst@temp
5795
\let\@tempa#1\let#1\@empty
5796
\expandafter\lst@temp\@tempa#2\@empty
5797
\expandafter\lst@ReplaceIn@\expandafter#1%
5804
% \subsection{Flow of control}
5806
% \begin{macro}{\@gobblethree}
5807
% is defined if and only if undefined.
5809
\providecommand*\@gobblethree[3]{}
5813
% \begin{macro}{\lst@GobbleNil}
5815
\def\lst@GobbleNil#1\@nil{}
5819
% \begin{macro}{\lst@Swap}
5822
\def\lst@Swap#1#2{#2#1}
5826
% \begin{macro}{\lst@if}
5827
% \begin{macro}{\lst@true}
5828
% \begin{macro}{\lst@false}
5829
% A general |\if| for temporary use.
5831
\def\lst@true{\let\lst@if\iftrue}
5832
\def\lst@false{\let\lst@if\iffalse}
5839
% \begin{macro}{\lst@IfNextCharsArg}
5840
% is quite easy: We define a macro and call |\lst@IfNextChars|.
5842
\def\lst@IfNextCharsArg#1{%
5843
\def\lst@tofind{#1}\lst@IfNextChars\lst@tofind}
5847
% \begin{macro}{\lst@IfNextChars}
5848
% We save the arguments and start a loop.
5850
\def\lst@IfNextChars#1#2#3{%
5851
\let\lst@tofind#1\def\@tempa{#2}\def\@tempb{#3}%
5852
\let\lst@eaten\@empty \lst@IfNextChars@}
5854
% Expand the characters we are looking for.
5856
\def\lst@IfNextChars@{\expandafter\lst@IfNextChars@@\lst@tofind\relax}
5858
% Now we can refine |\lst@tofind| and append the input character |#3| to
5861
\def\lst@IfNextChars@@#1#2\relax#3{%
5862
\def\lst@tofind{#2}\lst@lAddTo\lst@eaten{#3}%
5865
% If characters are the same, we either call |\@tempa| or continue the test.
5867
\ifx\lst@tofind\@empty
5868
\let\lst@next\@tempa
5870
\let\lst@next\lst@IfNextChars@
5872
\expandafter\lst@next
5875
% If the characters are different, we call |\@tempb|.
5882
% \begin{macro}{\lst@IfNextCharActive}
5883
% We compare the character |#3| with its active version |\lowercase{~}|.
5884
% Note that the right brace between |\ifx~| and |#3| ends the |\lowercase|.
5885
% The |\endgroup| restores the |\lccode|.
5887
\def\lst@IfNextCharActive#1#2#3{%
5888
\begingroup \lccode`\~=`#3\lowercase{\endgroup
5897
% \begin{macro}{\lst@for}
5898
% A for-loop with expansion of the loop-variable.
5900
\def\lst@for#1\do#2{%
5901
\def\lst@forbody##1{#2}%
5902
\@for\lst@forvar:=#1\do
5903
{\expandafter\lst@forbody\expandafter{\lst@forvar}}}
5908
% \subsection{Catcode changes}\label{iCatcodeChanges}
5910
% A character gets its catcode right after reading it and \TeX\ has no
5911
% primitive command to change attached catcodes. However, we can replace these
5912
% characters by characters with same ASCII codes and different catcodes.
5913
% It's not the same but suffices since the result is the same.
5914
% Here we treat the very special case that all characters become active.
5915
% If we want \texverb|\lst@arg| to contain an active version of the character
5916
% |#1|, a prototype macro could be
5918
% \def\lst@MakeActive#1{\lccode`\~=`#1\lowercase{\def\lst@arg{~}}}
5920
% The |\lowercase| changes the ASCII code of |~| to the one of |#1| since we
5921
% have said that |~| is the lower case version of |#1|.
5922
% Fortunately the |\lowercase| doesn't change the catcode, so we have an active
5924
% Note that |~| is usually active.
5926
% \begin{macro}{\lst@MakeActive}
5927
% We won't do this character by character.
5928
% To increase speed we change nine characters at the same time (if nine
5929
% characters are left).
5931
% This was introduced when the delimiters were converted each listings. Now
5932
% this conversion is done only each language selection. So we might want to
5933
% implement a character by character conversion again to decrease the memory
5936
% We get the argument, empty |\lst@arg| and begin a loop.
5938
\def\lst@MakeActive#1{%
5939
\let\lst@temp\@empty \lst@MakeActive@#1%
5940
\relax\relax\relax\relax\relax\relax\relax\relax\relax}
5942
% There are nine |\relax|es since |\lst@MakeActive@| has nine parameters and we
5943
% don't want any problems in the case that |#1| is empty.
5944
% We need nine active characters now instead of a single |~|.
5945
% We make these catcode changes local and define the coming macro |\global|.
5948
\catcode`\^^@=\active \catcode`\^^A=\active \catcode`\^^B=\active
5949
\catcode`\^^C=\active \catcode`\^^D=\active \catcode`\^^E=\active
5950
\catcode`\^^F=\active \catcode`\^^G=\active \catcode`\^^H=\active
5952
% First we |\let| the next operation be |\relax|.
5953
% This aborts our loop for processing all characters (default and possibly
5955
% Then we look if we have at least one character.
5956
% If this is not the case, the loop terminates and all is done.
5958
\gdef\lst@MakeActive@#1#2#3#4#5#6#7#8#9{\let\lst@next\relax
5960
\else \lccode`\^^@=`#1%
5962
% Otherwise we say that |^^@|=chr(0) is the lower case version of the first
5964
% Then we test the second character.
5965
% If there is none, we append the lower case |^^@| to |\lst@temp|.
5966
% Otherwise we say that |^^A|=chr(1) is the lower case version of the second
5967
% character and we test the next argument, and so on.
5970
\lowercase{\lst@lAddTo\lst@temp{^^@}}%
5971
\else \lccode`\^^A=`#2%
5973
\lowercase{\lst@lAddTo\lst@temp{^^@^^A}}%
5974
\else \lccode`\^^B=`#3%
5976
\lowercase{\lst@lAddTo\lst@temp{^^@^^A^^B}}%
5977
\else \lccode`\^^C=`#4%
5979
\lowercase{\lst@lAddTo\lst@temp{^^@^^A^^B^^C}}%
5980
\else \lccode`\^^D=`#5%
5982
\lowercase{\lst@lAddTo\lst@temp{^^@^^A^^B^^C^^D}}%
5983
\else \lccode`\^^E=`#6%
5985
\lowercase{\lst@lAddTo\lst@temp{^^@^^A^^B^^C^^D^^E}}%
5986
\else \lccode`\^^F=`#7%
5988
\lowercase{\lst@lAddTo\lst@temp{^^@^^A^^B^^C^^D^^E^^F}}%
5989
\else \lccode`\^^G=`#8%
5991
\lowercase{\lst@lAddTo\lst@temp{^^@^^A^^B^^C^^D^^E^^F^^G}}%
5993
% If nine characters are present, we append (lower case versions of) nine
5994
% active characters and call this macro again via redefining |\lst@next|.
5996
\else \lccode`\^^H=`#9%
5997
\lowercase{\lst@lAddTo\lst@temp{^^@^^A^^B^^C^^D^^E^^F^^G^^H}}%
5998
\let\lst@next\lst@MakeActive@
5999
\fi \fi \fi \fi \fi \fi \fi \fi \fi
6003
% This |\endgroup| restores the catcodes of chr(0)--chr(8), but not the
6004
% catcodes of the characters inside |\lst@MakeActive@| since they are already
6007
% Note: A conversion from an arbitrary `catcode--character code' table back to
6008
% \TeX's catcodes is possible if we test against the character codes (either
6009
% via |\ifnum| or |\ifcase|).
6010
% But control sequences and begin and end group characters definitely need
6011
% some special treatment.
6012
% However I haven't checked the details.
6013
% So just ignore this and don't bother me for this note. :\,--\,)
6016
% \begin{macro}{\lst@DefActive}
6017
% An easy application of |\lst@MakeActive|.
6019
\def\lst@DefActive#1#2{\lst@MakeActive{#2}\let#1\lst@temp}
6023
% \begin{macro}{\lst@DefOther}
6024
% We use the fact that |\meaning| produces catcode 12 characters except spaces
6025
% stay spaces. |\escapechar| is modified locally to suppress the output of an
6026
% escape character. Finally we remove spaces via \LaTeX's |\zap@space|, which
6027
% was proposed by \lsthelper{Rolf~Niepraschk}{1997/04/24}{use \zap@space}---not
6028
% in this context, but that doesn't matter.
6030
\def\lst@DefOther#1#2{%
6031
\begingroup \def#1{#2}\escapechar\m@ne \expandafter\endgroup
6032
\expandafter\lst@DefOther@\meaning#1\relax#1}
6033
\def\lst@DefOther@#1>#2\relax#3{\edef#3{\zap@space#2 \@empty}}
6039
% \subsection{Applications to \ref*{iCatcodeChanges}}\label{iApplicationsTo}
6041
% \subsection{Applications to \ref{iCatcodeChanges}}\label{iApplicationsTo}
6044
% If an environment is used inside an argument, the listing is already read and
6045
% we can do nothing to preserve the catcodes.
6046
% However, under certain circumstances the environment can be used inside an
6047
% argument---that's at least what I've said in the User's guide.
6048
% And now I have to work for it coming true.
6049
% Moreover we define an analogous conversion macro for the
6050
% \packagename{fancyvrb} mode.
6052
% \item[0.19] |\lst@InsideConvert{|\meta{\TeX\ material \textup(already read\textup)}|}|
6054
% \emph{appends} a verbatim version of the argument to |\lst@arg|, but all
6055
% appended characters are active. Since it's not a character to character
6056
% conversion, `verbatim' needs to be explained. All characters can be
6057
% typed in as they are except |\|, |{|, |}| and |%|. If you want one of
6058
% these, you must write |\\|, |\{|, |\}| and |\%| instead.
6059
% If two spaces should follow each other, the second (third, fourth,
6060
% \ldots) space must be entered with a preceding backslash.
6062
% \item[0.19] |\lst@XConvert{|\meta{\TeX\ material \textup(already read\textup)}|}|
6064
% \emph{appends} a `verbatim' version of the argument to |\lst@arg|.
6065
% Here \TeX\ material is allowed to be put inside argument braces like
6066
% |{(*}{*)}|. The contents of these arguments are converted, the braces
6067
% stay as curly braces.
6069
% If |\lst@if| is true, each second argument is treated differently.
6070
% Only the first character (of the delimiter) becomes active.
6073
% \begin{macro}{\lst@InsideConvert}
6074
% We call a submacro (similar to |\zap@space|) to preserve single spaces which
6075
% are replaced by active spaces.
6077
\def\lst@InsideConvert#1{\lst@InsideConvert@#1 \@empty}
6078
\begingroup \lccode`\~=`\ \relax \lowercase{%
6080
% We make |#1| active and append these characters (plus an active space) to
6082
% If we haven't found the end |\@empty| of the input, we continue the process.
6084
\gdef\lst@InsideConvert@#1 #2{%
6085
\lst@MakeActive{#1}%
6087
\lst@lExtend\lst@arg{\lst@temp}%
6089
\lst@lExtend\lst@arg{\lst@temp~}%
6090
\expandafter\lst@InsideConvert@
6093
% Finally we end the |\lowercase| and close a group.
6099
% \begin{macro}{\lst@XConvert}
6100
% Check for an argument \ldots
6102
\def\lst@XConvert{\@ifnextchar\bgroup \lst@XConvertArg\lst@XConvert@}
6104
% \ldots, convert the argument, add it together with group delimiters to
6105
% |\lst@arg|, and we continue the conversion.
6107
\def\lst@XConvertArg#1{%
6108
{\lst@false \let\lst@arg\@empty
6109
\lst@XConvert#1\@nil
6110
\global\let\@gtempa\lst@arg}%
6111
\lst@lExtend\lst@arg{\expandafter{\@gtempa}}%
6114
% Having no |\bgroup|, we look whether we've found the end of the input, and
6115
% convert one token ((non)active character or control sequence) and continue.
6117
\def\lst@XConvert@#1{%
6119
\begingroup\lccode`\~=`#1\lowercase{\endgroup
6120
\lst@lAddTo\lst@arg~}%
6121
\expandafter\lst@XConvertNext
6123
\def\lst@XConvertNext{%
6124
\lst@if \expandafter\lst@XConvertX
6125
\else \expandafter\lst@XConvert \fi}
6127
% Now we make only the first character active.
6129
\def\lst@XConvertX#1{%
6131
\lst@XConvertX@#1\relax
6132
\expandafter\lst@XConvert
6134
\def\lst@XConvertX@#1#2\relax{%
6135
\begingroup\lccode`\~=`#1\lowercase{\endgroup
6136
\lst@XCConvertX@@~}{#2}}
6137
\def\lst@XCConvertX@@#1#2{\lst@lAddTo\lst@arg{{#1#2}}}
6142
% \subsection{Driver file handling*}
6144
% The \packagename{listings} package is split into several driver files,
6145
% miscellaneous (= aspect) files, and one kernel file.
6146
% All these files can be loaded partially and on demand---except the kernel
6147
% which provides this functionality.
6149
% \item[0.21] |\lst@Require|\marg{name}\marg{prefix}\marg{feature list}\meta{alias}\meta{file list macro}
6151
% tries to load all items of \meta{feature list} from the files
6152
% listed in \meta{file list macro}.
6153
% Each item has the form [\oarg{sub}]\meta{feature}.
6154
% |\lst@if| equals |\iftrue| if and only if all items were loadable.
6156
% The macro \meta{alias} gets an item as argument and must define
6157
% appropriate versions of |\lst@oalias| and |\lst@malias|. In fact
6158
% the feature associated with these definitions is loaded. You can
6159
% use \meta{alias}=|\lst@NoAlias| for no substitution.
6161
% \meta{prefix} identifies the type internally and \meta{name} is used
6164
% For example, |\lstloadaspects| uses the following arguments where |#1|
6165
% is the list of aspects: |{aspects}|\allowbreak|a|\allowbreak
6166
% |{#1}|\allowbreak|\lst@NoAlias|\allowbreak|\lstaspectfiles|.
6168
% \item[0.20] |\lst@DefDriver|\marg{name}\marg{prefix}\meta{interface macro}|\if|\alternative{true,false}
6172
% \item[0.21] |\lst@IfRequired|\oarg{sub}\marg{feature}\marg{then}\marg{else}
6174
% is used inside a driver file by the aspect, language, or whatever
6175
% else defining commands. \meta{then} is executed if and only if
6176
% \oarg{sub}\marg{feature} has been requested via |\lst@Require|.
6177
% Otherwise \meta{else} is executed---which is also the case for
6178
% subsequent calls with the same \oarg{sub}\marg{feature}.
6180
% \meta{then} and \meta{else} may use |\lst@prefix| (read access only).
6182
% |\lst@BeginAspect| in section \ref{iAspectCommands} and |\lst@DefDriver|
6183
% serve as examples.
6186
% \begin{macro}{\lst@Require}
6187
% Initialize variables (if required items aren't empty), \ldots
6189
\def\lst@Require#1#2#3#4#5{%
6191
\aftergroup\lst@true
6192
\ifx\@empty#3\@empty\else
6193
\def\lst@prefix{#2}\let\lst@require\@empty
6195
% \ldots\space and for each nonempty item: determine alias and add it to
6196
% |\lst@require| if it isn't loaded.
6198
\edef\lst@temp{\expandafter\zap@space#3 \@empty}%
6199
\lst@for\lst@temp\do{%
6200
\ifx\@empty##1\@empty\else \lstKV@OptArg[]{##1}{%
6202
\@ifundefined{\@lst\lst@prefix @\lst@malias $\lst@oalias}%
6203
{\edef\lst@require{\lst@require,\lst@malias $\lst@oalias}}%
6207
% Init things and input files if and as long as it is necessary.
6209
\global\let\lst@loadaspects\@empty
6211
\ifx\lst@require\@empty\else
6213
\ifx\lst@require\@empty\else
6214
\InputIfFileExists{##1}{}{}%
6218
% Issue error and call |\lst@false| (after closing the local group) if some
6219
% items weren't loadable.
6221
\ifx\lst@require\@empty\else
6222
\PackageError{Listings}{Couldn't load requested #1}%
6223
{The following #1s weren't loadable:^^J\@spaces
6224
\lst@require^^JThis may cause errors in the sequel.}%
6225
\aftergroup\lst@false
6230
\ifx\lst@loadaspects\@empty\else
6231
\lst@RequireAspects\lst@loadaspects
6238
% \begin{macro}{\lst@IfRequired}
6239
% uses |\lst@IfOneOf| and adds some code to \meta{then} part:
6240
% delete the now loaded item from the list and define
6241
% |\lst|\meta{prefix}|@|\meta{feature}|$|\meta{sub}.
6243
\def\lst@IfRequired[#1]#2{%
6244
\lst@NormedDef\lst@temp{[#1]#2}%
6245
\expandafter\lst@IfRequired@\lst@temp\relax}
6246
\def\lst@IfRequired@[#1]#2\relax#3{%
6247
\lst@IfOneOf #2$#1\relax\lst@require
6248
{\lst@DeleteKeysIn@\lst@require#2$#1,\relax,%
6249
\global\expandafter\let
6250
\csname\@lst\lst@prefix @#2$#1\endcsname\@empty
6255
% \begin{macro}{\lst@require}
6257
\let\lst@require\@empty
6261
% \begin{macro}{\lst@NoAlias}
6262
% just defines |\lst@oalias| and |\lst@malias|.
6264
\def\lst@NoAlias[#1]#2{%
6265
\lst@NormedDef\lst@oalias{#1}\lst@NormedDef\lst@malias{#2}}
6269
% \begin{macro}{\lst@LAS}
6271
\gdef\lst@LAS#1#2#3#4#5#6#7{%
6272
\lst@Require{#1}{#2}{#3}#4#5%
6274
\@ifundefined{lst#2@\lst@malias$\lst@oalias}%
6275
{\PackageError{Listings}%
6276
{#1 \ifx\@empty\lst@oalias\else \lst@oalias\space of \fi
6277
\lst@malias\space undefined}%
6278
{The #1 is not loadable. \@ehc}}%
6279
{#6\csname\@lst#2@\lst@malias $\lst@oalias\endcsname #7}}
6283
% \begin{macro}{\lst@RequireAspects}
6284
% \begin{macro}{\lstloadaspects}
6285
% make use of the just developped definitions.
6287
\def\lst@RequireAspects#1{%
6288
\lst@Require{aspect}{asp}{#1}\lst@NoAlias\lstaspectfiles}
6289
\let\lstloadaspects\lst@RequireAspects
6294
% \begin{macro}{\lstaspectfiles}
6295
% This macro is defined if and only if it's undefined yet.
6297
\@ifundefined{lstaspectfiles}
6298
{\newcommand\lstaspectfiles{lstmisc0.sty,lstmisc.sty}}{}
6302
% \begin{macro}{\lst@DefDriver}
6303
% Test the next character and reinsert the arguments.
6305
\gdef\lst@DefDriver#1#2#3#4{%
6306
\@ifnextchar[{\lst@DefDriver@{#1}{#2}#3#4}%
6307
{\lst@DefDriver@{#1}{#2}#3#4[]}}
6309
% We set |\lst@if| locally true if the item has been requested.
6311
\gdef\lst@DefDriver@#1#2#3#4[#5]#6{%
6312
\def\lst@name{#1}\let\lst@if#4%
6313
\lst@NormedDef\lst@driver{\@lst#2@#6$#5}%
6314
\lst@IfRequired[#5]{#6}{\begingroup \lst@true}%
6317
\@ifnextchar[{\lst@XDefDriver{#1}#3}{\lst@DefDriver@@#3}}
6319
% Note that |\lst@XDefDriver| takes optional `base' arguments, but eventually
6320
% calls |\lst@DefDriver@@|. We define the item (in case of need), and
6321
% |\endgroup| resets some catcodes and |\lst@if|, i.e.~|\lst@XXDefDriver| knows
6322
% whether called by a public or internal command.
6324
\gdef\lst@DefDriver@@#1#2{%
6326
\global\@namedef{\lst@driver}{#1{#2}}%
6329
\@ifnextchar[\lst@XXDefDriver\@empty}
6331
% We get the aspect argument, and (if not empty) load the aspects immediately
6332
% if called by a public command or extend the list of required aspects or
6333
% simply ignore the argument if the item leaves undefined.
6335
\gdef\lst@XXDefDriver[#1]{%
6336
\ifx\@empty#1\@empty\else
6338
\lstloadaspects{#1}%
6340
\@ifundefined{\lst@driver}{}%
6341
{\xdef\lst@loadaspects{\lst@loadaspects,#1}}%
6345
% We insert an additional `also'key=value pair.
6347
\gdef\lst@XDefDriver#1#2[#3]#4#5{\lst@DefDriver@@#2{also#1=[#3]#4,#5}}
6352
% \subsection{Aspect commands}\label{iAspectCommands}
6354
% This section contains commands used in defining `\lst-aspects'.
6355
% \begin{macro}{\lst@UserCommand}
6356
% is mainly equivalent to |\gdef|.
6358
%<!info>\let\lst@UserCommand\gdef
6359
%<info>\def\lst@UserCommand#1{\message{\string#1,}\gdef#1}
6363
% \begin{macro}{\lst@BeginAspect}
6364
% A straight-forward implementation:
6366
\newcommand*\lst@BeginAspect[2][]{%
6367
\def\lst@curraspect{#2}%
6368
\ifx \lst@curraspect\@empty
6369
\expandafter\lst@GobbleAspect
6372
% If \meta{aspect name} is not empty, there are certain other conditions not to
6373
% define the aspect (as described in section \ref{dHowToDefineLstAspects}).
6375
%<!info> \let\lst@next\@empty
6376
%<info> \def\lst@next{%
6377
%<info> \message{^^JDefine lst-aspect `#2':}\lst@GetAllocs}%
6378
\lst@IfRequired[]{#2}%
6379
{\lst@RequireAspects{#1}%
6380
\lst@if\else \let\lst@next\lst@GobbleAspect \fi}%
6381
{\let\lst@next\lst@GobbleAspect}%
6382
\expandafter\lst@next
6387
% \begin{macro}{\lst@EndAspect}
6388
% finishes an aspect definition.
6390
\def\lst@EndAspect{%
6391
\csname\@lst patch@\lst@curraspect\endcsname
6392
%<info> \lst@ReportAllocs
6393
\let\lst@curraspect\@empty}
6397
% \begin{macro}{\lst@GobbleAspect}
6398
% drops all code up to the next |\lst@EndAspect|.
6400
\long\def\lst@GobbleAspect#1\lst@EndAspect{\let\lst@curraspect\@empty}
6404
% \begin{macro}{\lst@Key}
6405
% The command simply defines the key. But we must take care of an optional
6406
% parameter and the initialization argument |#2|.
6409
%<info> \message{#1,}%
6410
\@ifnextchar[{\lstKV@def{#1}{#2}}%
6411
{\def\lst@temp{\lst@Key@{#1}{#2}}
6412
\afterassignment\lst@temp
6413
\global\@namedef{KV@\@lst @#1}####1}}
6415
% Now comes a renamed and modified copy from a \packagename{keyval} macro:
6416
% We need global key definitions.
6418
\def\lstKV@def#1#2[#3]{%
6419
\global\@namedef{KV@\@lst @#1@default\expandafter}\expandafter
6420
{\csname KV@\@lst @#1\endcsname{#3}}%
6421
\def\lst@temp{\lst@Key@{#1}{#2}}\afterassignment\lst@temp
6422
\global\@namedef{KV@\@lst @#1}##1}
6424
% We initialize the key if the first token of |#2| is not |\relax|.
6427
\ifx\relax#2\@empty\else
6428
\begingroup \globaldefs\@ne
6429
\csname KV@\@lst @#1\endcsname{#2}%
6435
% \begin{macro}{\lst@UseHook}
6436
% is very, very, \ldots, very (hundreds of times) easy.
6438
\def\lst@UseHook#1{\csname\@lst hk@#1\endcsname}
6442
% \begin{macro}{\lst@AddToHook}
6443
% \begin{macro}{\lst@AddToHookExe}
6444
% \begin{macro}{\lst@AddToHookAtTop}
6445
% All use the same submacro.
6447
\def\lst@AddToHook{\lst@ATH@\iffalse\lst@AddTo}
6448
\def\lst@AddToHookExe{\lst@ATH@\iftrue\lst@AddTo}
6449
\def\lst@AddToHookAtTop{\lst@ATH@\iffalse\lst@AddToAtTop}
6451
% If and only if the boolean value is true, the hook material is executed
6454
\long\def\lst@ATH@#1#2#3#4{%
6455
\@ifundefined{\@lst hk@#3}{%
6456
%<info> \message{^^Jnew hook `#3',^^J}%
6457
\expandafter\gdef\csname\@lst hk@#3\endcsname{}}{}%
6458
\expandafter#2\csname\@lst hk@#3\endcsname{#4}%
6461
\begingroup \globaldefs\@ne \lst@temp \endgroup
6468
% \begin{macro}{\lst@AddTo}
6469
% Note that the definition is global!
6471
\long\def\lst@AddTo#1#2{%
6472
\expandafter\gdef\expandafter#1\expandafter{#1#2}}
6476
% \begin{macro}{\lst@AddToAtTop}
6477
% We need a couple of |\expandafter|s now. Simply note that we have\\
6478
% {\small\hspace*{2em}|\expandafter\gdef\expandafter#1\expandafter{\lst@temp|
6479
% $\langle$\textit{contents of }|#1|$\rangle$|}|}\\
6480
% after the `first phase' of expansion.
6482
\def\lst@AddToAtTop#1#2{\def\lst@temp{#2}%
6483
\expandafter\expandafter\expandafter\gdef
6484
\expandafter\expandafter\expandafter#1%
6485
\expandafter\expandafter\expandafter{\expandafter\lst@temp#1}}
6489
% \begin{macro}{\lst@lAddTo}
6490
% A local version of |\lst@AddTo| \ldots
6492
\def\lst@lAddTo#1#2{\expandafter\def\expandafter#1\expandafter{#1#2}}
6496
% \begin{macro}{\lst@Extend}
6497
% \begin{macro}{\lst@lExtend}
6498
% \ldots\space and here we expand the first token of the second argument first.
6500
\def\lst@Extend#1#2{%
6501
\expandafter\lst@AddTo\expandafter#1\expandafter{#2}}
6502
\def\lst@lExtend#1#2{%
6503
\expandafter\lst@lAddTo\expandafter#1\expandafter{#2}}
6506
% This should never be changed to
6508
% \def\lst@Extend#1{%
6509
% \expandafter\lst@AddTo\expandafter#1\expandafter}
6510
% \def\lst@lExtend#1{%
6511
% \expandafter\lst@lAddTo\expandafter#1}\end{verbatim}
6512
% The first is not equivalent in case that the second argument is a single
6513
% (= non-braced) control sequence, and the second isn't in case of a braced
6520
% \subsection{Interfacing with \textsf{keyval}}
6522
% The \packagename{keyval} package passes the value via the one and only
6523
% paramater |#1| to the definition part of the key macro. The following
6524
% commands may be used to analyse the value. Note that we need at least version
6525
% 1.10 of the \packagename{keyval} package. Note also that the package removes
6526
% a naming conflict with AMS classes---reported by \lsthelper{Ralf~Quast}
6527
% {1998/01/08}{\keywords conflicts with AMS classes}.
6530
\RequirePackage{keyval}[1997/11/10]
6534
% \begin{macro}{\lstKV@TwoArg}
6535
% \begin{macro}{\lstKV@ThreeArg}
6536
% \begin{macro}{\lstKV@FourArg}
6537
% Define temporary macros and call with given arguments |#1|. We add empty
6538
% arguments for the case that the user doesn't provide enough.
6540
\def\lstKV@TwoArg#1#2{\gdef\@gtempa##1##2{#2}\@gtempa#1{}{}}
6541
\def\lstKV@ThreeArg#1#2{\gdef\@gtempa##1##2##3{#2}\@gtempa#1{}{}{}}
6542
\def\lstKV@FourArg#1#2{\gdef\@gtempa##1##2##3##4{#2}\@gtempa#1{}{}{}{}}
6544
% There's one question: What are the global definitions good for? |\lst@Key|
6545
% might set |\globaldefs| to one and possibly calls this macro. That's the
6546
% reason why we use global definitions here and below.
6551
% \begin{macro}{\lstKV@OptArg}
6552
% We define the temporary macro |\@gtempa| and insert default argument if
6555
\def\lstKV@OptArg[#1]#2#3{%
6556
\gdef\@gtempa[##1]##2{#3}\lstKV@OptArg@{#1}#2\@}
6557
\def\lstKV@OptArg@#1{\@ifnextchar[\lstKV@OptArg@@{\lstKV@OptArg@@[#1]}}
6558
\def\lstKV@OptArg@@[#1]#2\@{\@gtempa[#1]{#2}}
6562
% \begin{macro}{\lstKV@XOptArg}
6563
% Here |#3| is already a definition with at least two parameters whose first
6564
% is enclosed in brackets.
6566
\def\lstKV@XOptArg[#1]#2#3{%
6567
\global\let\@gtempa#3\lstKV@OptArg@{#1}#2\@}
6571
% \begin{macro}{\lstKV@CSTwoArg}
6572
% Just define temporary macro and call it.
6574
\def\lstKV@CSTwoArg#1#2{%
6575
\gdef\@gtempa##1,##2,##3\relax{#2}%
6580
% \begin{macro}{\lstKV@SetIf}
6581
% We simply test the lower case first character of |#1|.
6583
\def\lstKV@SetIf#1{\lstKV@SetIf@#1\relax}
6584
\def\lstKV@SetIf@#1#2\relax#3{\lowercase{%
6585
\expandafter\let\expandafter#3%
6586
\csname if\ifx #1t}true\else false\fi\endcsname}
6590
% \begin{macro}{\lstKV@SwitchCases}
6591
% is implemented as a substring test.
6593
\def\lstKV@SwitchCases#1#2#3{%
6594
\def\lst@temp##1\\#1&##2\\##3##4\@nil{%
6601
\lst@temp\\#2\\#1&\\\@empty\@nil}
6605
% \begin{macro}{\lstset}
6606
% Finally this main user interface macro.
6607
% We change catcodes for reading the argument.
6609
\lst@UserCommand\lstset{\begingroup \lst@setcatcodes \lstset@}
6610
\def\lstset@#1{\endgroup \ifx\@empty#1\@empty\else\setkeys{lst}{#1}\fi}
6614
% \begin{macro}{\lst@setcatcodes}
6615
% contains all catcode changes for |\lstset|.
6617
\def\lst@setcatcodes{\makeatletter \catcode`\"=12\relax}
6620
% Change more catcodes?
6625
% \subsection{Internal modes}
6627
% \begin{macro}{\lst@NewMode}
6628
% We simply use |\chardef| for a mode definition. The counter |\lst@mode|
6629
% mainly keeps the current mode number. But it is also used to advance the
6630
% number in the macro |\lst@newmode|---we don't waste another counter.
6632
\def\lst@NewMode#1{%
6634
\lst@mode\lst@newmode\relax \advance\lst@mode\@ne
6635
\xdef\lst@newmode{\the\lst@mode}%
6636
\global\chardef#1=\lst@mode
6637
\lst@mode\lst@nomode
6642
% \begin{macro}{\lst@mode}
6643
% \begin{macro}{\lst@nomode}
6644
% We allocate the counter and the first mode.
6647
\def\lst@newmode{\m@ne}% init
6648
\lst@NewMode\lst@nomode % init (of \lst@mode :-)
6653
% \begin{macro}{\lst@UseDynamicMode}
6654
% For dynamic modes we must not use the counter |\lst@mode| (since possibly
6655
% already valued). |\lst@dynamicmode| substitutes |\lst@newmode| and is a local
6656
% definition here, \ldots
6658
\def\lst@UseDynamicMode{%
6659
\@tempcnta\lst@dynamicmode\relax \advance\@tempcnta\@ne
6660
\edef\lst@dynamicmode{\the\@tempcnta}%
6661
\expandafter\lst@Swap\expandafter{\expandafter{\lst@dynamicmode}}}
6663
% \ldots\ initialized each listing with the current `value' of |\lst@newmode|.
6665
\lst@AddToHook{InitVars}{\let\lst@dynamicmode\lst@newmode}
6669
% \begin{macro}{\lst@EnterMode}
6670
% Each mode opens a group level, stores the mode number and execute mode
6671
% specific tokens. Moreover we keep all these changes in mind (locally) and
6672
% adjust internal variables if the user wants it.
6674
\def\lst@EnterMode#1#2{%
6675
\bgroup \lst@mode=#1\relax #2%
6677
\lst@lAddTo\lst@entermodes{\lst@EnterMode{#1}{#2}}}
6680
\lst@AddToHook{InitVars}{\let\lst@entermodes\@empty}
6684
% \begin{macro}{\lst@LeaveMode}
6685
% We simply close the group and call |\lsthk@EndGroup| if and only if the
6686
% current mode is not |\lst@nomode|.
6688
\def\lst@LeaveMode{%
6689
\ifnum\lst@mode=\lst@nomode\else
6690
\egroup \expandafter\lsthk@EndGroup
6694
\lst@AddToHook{EndGroup}{}% init
6698
% \begin{macro}{\lst@InterruptModes}
6699
% We put the current mode sequence on a stack and leave all modes.
6701
\def\lst@InterruptModes{%
6702
\lst@Extend\lst@modestack{\expandafter{\lst@entermodes}}%
6706
\lst@AddToHook{InitVars}{\global\let\lst@modestack\@empty}
6710
% \begin{macro}{\lst@ReenterModes}
6711
% If the stack is not empty, we leave all modes and pop the topmost element
6712
% (which is the last element of |\lst@modestack|).
6714
\def\lst@ReenterModes{%
6715
\ifx\lst@modestack\@empty\else
6717
\global\let\@gtempa\lst@modestack
6718
\global\let\lst@modestack\@empty
6719
\expandafter\lst@ReenterModes@\@gtempa\relax
6721
\def\lst@ReenterModes@#1#2{%
6724
% If we've reached |\relax|, we've also found the last element: we execute |#1|
6725
% and gobble |{#2}|=|{\relax}| after |\fi|.
6727
\gdef\@gtempa##1{#1}%
6728
\expandafter\@gtempa
6731
% Otherwise we just add the element to |\lst@modestack| and continue the loop.
6733
\lst@AddTo\lst@modestack{{#1}}%
6734
\expandafter\lst@ReenterModes@
6740
% \begin{macro}{\lst@LeaveAllModes}
6741
% Leaving all modes means closing groups until the mode equals |\lst@nomode|.
6743
\def\lst@LeaveAllModes{%
6744
\ifnum\lst@mode=\lst@nomode
6745
\expandafter\lsthk@EndGroup
6747
\expandafter\egroup\expandafter\lst@LeaveAllModes
6750
% We need that macro to end a listing correctly.
6752
\lst@AddToHook{ExitVars}{\lst@LeaveAllModes}
6756
% \begin{macro}{\lst@Pmode}
6757
% \begin{macro}{\lst@GPmode}
6758
% The `processing' and the general purpose mode.
6760
\lst@NewMode\lst@Pmode
6761
\lst@NewMode\lst@GPmode
6766
% \begin{macro}{\lst@modetrue}
6767
% The usual macro to value a boolean except that we also execute a hook.
6769
\def\lst@modetrue{\let\lst@ifmode\iftrue \lsthk@ModeTrue}
6770
\let\lst@ifmode\iffalse % init
6771
\lst@AddToHook{ModeTrue}{}% init
6775
% \begin{macro}{\lst@ifLmode}
6776
% Comment lines use a static mode. It terminates at end of line.
6778
\def\lst@Lmodetrue{\let\lst@ifLmode\iftrue}
6779
\let\lst@ifLmode\iffalse % init
6780
\lst@AddToHook{EOL}{\@whilesw \lst@ifLmode\fi \lst@LeaveMode}
6785
% \subsection{Divers helpers}
6787
% \begin{macro}{\lst@NormedDef}
6788
% works like |\def| (without any parameters!) but normalizes the replacement
6789
% text by making all characters lower case and stripping off spaces.
6791
\def\lst@NormedDef#1#2{\lowercase{\edef#1{\zap@space#2 \@empty}}}
6795
% \begin{macro}{\lst@NormedNameDef}
6796
% works like |\global\@namedef| (again without any parameters!) but normalizes
6797
% both the macro name and the replacement text.
6799
\def\lst@NormedNameDef#1#2{%
6800
\lowercase{\edef\lst@temp{\zap@space#1 \@empty}%
6801
\expandafter\xdef\csname\lst@temp\endcsname{\zap@space#2 \@empty}}}
6805
% \begin{macro}{\lst@GetFreeMacro}
6806
% Initialize |\@tempcnta| and |\lst@freemacro|, \ldots
6808
\def\lst@GetFreeMacro#1{%
6809
\@tempcnta\z@ \def\lst@freemacro{#1\the\@tempcnta}%
6812
% \ldots\space and either build the control sequence or advance the counter and
6816
\expandafter\ifx \csname\lst@freemacro\endcsname \relax
6817
\edef\lst@freemacro{\csname\lst@freemacro\endcsname}%
6819
\advance\@tempcnta\@ne
6820
\expandafter\lst@GFM@
6825
% \begin{macro}{\lst@gtempboxa}
6827
\newbox\lst@gtempboxa
6835
% \section{Doing output}
6838
% \subsection{Basic registers and keys}
6844
% \paragraph{The current character string}
6845
% is kept in a token register and a counter holds its length.
6846
% Here we define the macros to put characters into the output queue.
6848
% \begin{macro}{\lst@token}
6849
% \begin{macro}{\lst@length}
6850
% are allocated here. Quite a useful comment, isn't it?
6852
\newtoks\lst@token \newcount\lst@length
6857
% \begin{macro}{\lst@ResetToken}
6858
% \begin{macro}{\lst@lastother}
6859
% The two registers get empty respectively zero at the beginning of each line.
6860
% After receiving a report from \lsthelper{Claus~Atzenbeck}{1999/11/24}{HTML:
6861
% output unit repeated after >}---I removed such a bug many times---I decided
6862
% to reset these registers in the \hookname{EndGroup} hook, too.
6864
\def\lst@ResetToken{\lst@token{}\lst@length\z@}
6867
\lst@AddToHook{InitVarsBOL}{\lst@ResetToken \let\lst@lastother\@empty}
6868
\lst@AddToHook{EndGroup}{\lst@ResetToken \let\lst@lastother\@empty}
6870
% The macro |\lst@lastother| will be equivalent to the last `other' character,
6871
% which leads us to |\lst@ifletter|.
6875
% \begin{macro}{\lst@ifletter}
6876
% indicates whether the token contains an identifier or other characters.
6878
\def\lst@lettertrue{\let\lst@ifletter\iftrue}
6879
\def\lst@letterfalse{\let\lst@ifletter\iffalse}
6880
\lst@AddToHook{InitVars}{\lst@letterfalse}
6884
% \begin{macro}{\lst@Append}
6885
% puts the argument into the output queue.
6887
\def\lst@Append#1{\advance\lst@length\@ne
6888
\lst@token=\expandafter{\the\lst@token#1}}
6892
% \begin{macro}{\lst@AppendOther}
6893
% Depending on the current state, we first output the character string as an
6894
% identifier. Then we save the `argument' via |\futurelet| and call the macro
6895
% |\lst@Append| to do the rest.
6897
\def\lst@AppendOther{%
6898
\lst@ifletter \lst@Output\lst@letterfalse \fi
6899
\futurelet\lst@lastother\lst@Append}
6903
% \begin{macro}{\lst@AppendLetter}
6904
% We output a non-identifier string if necessary and call |\lst@Append|.
6906
\def\lst@AppendLetter{%
6907
\lst@ifletter\else \lst@OutputOther\lst@lettertrue \fi
6912
% \begin{macro}{\lst@SaveToken}
6913
% \begin{macro}{\lst@RestoreToken}
6914
% If a group end appears and ruins the character string, we can use these
6915
% macros to save and restore the contents. |\lst@thestyle| is the current
6916
% printing style and must be saved and restored, too.
6918
\def\lst@SaveToken{%
6919
\global\let\lst@gthestyle\lst@thestyle
6920
\xdef\lst@RestoreToken{\noexpand\lst@token{\the\lst@token}%
6921
\noexpand\lst@length\the\lst@length\relax
6922
\noexpand\let\noexpand\lst@thestyle
6923
\noexpand\lst@gthestyle}}
6929
% \paragraph{The current position}
6930
% is either the dimension |\lst@currlwidth|, which is the horizontal position
6931
% without taking the current character string into account, or it's the current
6932
% column starting with number 0. This is |\lst@column| $-$ |\lst@pos| $+$
6933
% |\lst@length|. Moreover we have |\lst@lostspace| which is the difference
6934
% between the current and the desired line width. We define macros to insert
6937
% \begin{macro}{\lst@currlwidth}
6938
% \begin{macro}{\lst@column}
6939
% \begin{macro}{\lst@pos}
6940
% the current line width and two counters.
6942
\newdimen\lst@currlwidth % \global
6943
\newcount\lst@column \newcount\lst@pos % \global
6944
\lst@AddToHook{InitVarsBOL}
6945
{\global\lst@currlwidth\z@ \global\lst@pos\z@ \global\lst@column\z@}
6951
% \begin{macro}{\lst@CalcColumn}
6952
% sets |\@tempcnta| to the current column.
6953
% Note that |\lst@pos| will be nonpositive.
6955
\def\lst@CalcColumn{%
6956
\@tempcnta\lst@column
6957
\advance\@tempcnta\lst@length
6958
\advance\@tempcnta-\lst@pos}
6962
% \begin{macro}{\lst@lostspace}
6963
% Whenever this dimension is positive we can insert space. A negative `lost
6964
% space' means that the printed line is wider than expected.
6966
\newdimen\lst@lostspace % \global
6967
\lst@AddToHook{InitVarsBOL}{\global\lst@lostspace\z@}
6971
% \begin{macro}{\lst@UseLostSpace}
6972
% We insert space and reset it if and only if |\lst@lostspace| is positive.
6974
\def\lst@UseLostSpace{\ifdim\lst@lostspace>\z@ \lst@InsertLostSpace \fi}
6978
% \begin{macro}{\lst@InsertLostSpace}
6979
% \begin{macro}{\lst@InsertHalfLostSpace}
6980
% Ditto, but insert even if negative. |\lst@Kern| will be defined very soon.
6982
\def\lst@InsertLostSpace{%
6983
\lst@Kern\lst@lostspace \global\lst@lostspace\z@}
6984
\def\lst@InsertHalfLostSpace{%
6985
\global\lst@lostspace.5\lst@lostspace \lst@Kern\lst@lostspace}
6991
% \paragraph{Column widths}
6992
% Here we deal with the width of a single column, which equals the width of a
6993
% single character box. Keep in mind that there are fixed and flexible column
6996
% \begin{macro}{\lst@width}
6997
% \begin{lstkey}{basewidth}
6998
% \keyname{basewidth} assigns the values to macros and tests whether they are
7002
\lst@Key{basewidth}{0.6em,0.45em}{\lstKV@CSTwoArg{#1}%
7003
{\def\lst@widthfixed{##1}\def\lst@widthflexible{##2}%
7004
\ifx\lst@widthflexible\@empty
7005
\let\lst@widthflexible\lst@widthfixed
7007
\def\lst@temp{\PackageError{Listings}%
7008
{Negative value(s) treated as zero}%
7010
\let\lst@error\@empty
7011
\ifdim \lst@widthfixed<\z@
7012
\let\lst@error\lst@temp \let\lst@widthfixed\z@
7014
\ifdim \lst@widthflexible<\z@
7015
\let\lst@error\lst@temp \let\lst@widthflexible\z@
7019
% We set the dimension in a special hook.
7021
\lst@AddToHook{FontAdjust}
7022
{\lst@width=\lst@ifflexible\lst@widthflexible
7023
\else\lst@widthfixed\fi \relax}
7028
% \begin{lstkey}{fontadjust}
7029
% \begin{macro}{\lst@FontAdjust}
7030
% This hook is controlled by a switch and is always executed at
7031
% \hookname{InitVars}.
7033
\lst@Key{fontadjust}{false}[t]{\lstKV@SetIf{#1}\lst@iffontadjust}
7034
\def\lst@FontAdjust{\lst@iffontadjust \lsthk@FontAdjust \fi}
7037
\lst@AddToHook{InitVars}{\lsthk@FontAdjust}
7043
% \subsection{Low- and mid-level output}
7045
% \paragraph{Doing the output}
7046
% means putting the character string into a box register, updating all internal
7047
% data, and eventually giving the box to \TeX.
7049
% \begin{macro}{\lst@OutputBox}
7050
% \begin{macro}{\lst@alloverstyle}
7051
% The lowest level is the output of a box register.
7052
% Here we use |\box#1| as argument to |\lst@alloverstyle|.
7054
\def\lst@OutputBox#1{\lst@alloverstyle{\box#1}}
7056
% \begin{ALTERNATIVE}
7057
% Instead of |\global\advance\lst@currlwidth| |\wd|\meta{box number} in
7058
% both definitions |\lst@Kern| and |\lst@CalcLostSpaceAndOutput|, we could
7059
% also advance the dimension here. But I decided not to do so since it
7060
% simplifies possible redefinitions of |\lst@OutputBox|: we need not to care
7061
% about |\lst@currlwidth|.
7064
\def\lst@alloverstyle#1{#1}% init
7069
% \begin{macro}{\lst@Kern}
7070
% has been used to insert `lost space'.
7071
% It must not use |\@tempboxa| since that \ldots
7074
\setbox\z@\hbox{{\lst@currstyle{\kern#1}}}%
7075
\global\advance\lst@currlwidth \wd\z@
7080
% \begin{macro}{\lst@CalcLostSpaceAndOutput}
7081
% \ldots\space is used here.
7082
% We keep track of |\lst@lostspace|, |\lst@currlwidth| and |\lst@pos|.
7084
\def\lst@CalcLostSpaceAndOutput{%
7085
\global\advance\lst@lostspace \lst@length\lst@width
7086
\global\advance\lst@lostspace-\wd\@tempboxa
7087
\global\advance\lst@currlwidth \wd\@tempboxa
7088
\global\advance\lst@pos -\lst@length
7090
% Before |\@tempboxa| is output, we insert space if there is enough lost space.
7091
% This possibly invokes |\lst@Kern| via `insert half lost space', which is the
7092
% reason for why we mustn't use |\@tempboxa| above. By redefinition we prevent
7093
% |\lst@OutputBox| from using any special style in |\lst@Kern|.
7095
\setbox\@tempboxa\hbox{\let\lst@OutputBox\box
7096
\ifdim\lst@lostspace>\z@ \lst@leftinsert \fi
7098
\ifdim\lst@lostspace>\z@ \lst@rightinsert \fi}%
7100
% Finally we can output the new box.
7102
\lst@OutputBox\@tempboxa \lsthk@PostOutput}
7105
\lst@AddToHook{PostOutput}{}% init
7109
% \begin{macro}{\lst@OutputToken}
7110
% Now comes a mid-level definition.
7111
% Here we use |\lst@token| to set |\@tempboxa| and eventually output the box.
7112
% We take care of font adjustment and special output styles.
7113
% Yet unknown macros are defined in the following subsections.
7115
\def\lst@OutputToken{%
7116
\lst@TrackNewLines \lst@OutputLostSpace
7118
{\lst@thestyle{\lst@FontAdjust
7119
\setbox\@tempboxa\lst@hbox
7122
\expandafter\lst@FillOutputBox\the\lst@token\@empty
7124
\lst@CalcLostSpaceAndOutput}}%
7128
\lst@AddToHook{OutputBox}{}% init
7133
% \paragraph{Delaying the output}
7134
% means saving the character string somewhere and pushing it back when
7135
% neccessary. We may also attach the string to the next output box without
7136
% affecting style detection: both will be printed in the style of the upcoming
7137
% output. We will call this `merging'.
7139
% \begin{macro}{\lst@Delay}
7140
% \begin{macro}{\lst@Merge}
7141
% To delay or merge |#1|, we process it as usual and simply save the state
7142
% in macros. For delayed characters we also need the currently `active'
7143
% output routine. Both definitions first check whether there are already
7144
% delayed or `merged' characters.
7149
\lst@GetOutputMacro\lst@delayedoutput
7150
\edef\lst@delayed{\the\lst@token}%
7151
\edef\lst@delayedlength{\the\lst@length}%
7158
\edef\lst@merged{\the\lst@token}%
7159
\edef\lst@mergedlength{\the\lst@length}%
7165
% \begin{macro}{\lst@MergeToken}
7166
% Here we put the things together again.
7168
\def\lst@MergeToken#1#2{%
7169
\advance\lst@length#2%
7170
\lst@lExtend#1{\the\lst@token}%
7171
\expandafter\lst@token\expandafter{#1}%
7176
% \begin{macro}{\lst@CheckDelay}
7177
% We need to print delayed characters. The mode depends on the current output
7178
% macro. If it equals the saved definition, we put the delayed characters in
7179
% front of the character string (we merge them) since there has been no
7180
% letter-to-other or other-to-letter leap. Otherwise we locally reset the
7181
% current character string, merge this empty string with the delayed one,
7184
\def\lst@CheckDelay{%
7185
\ifx\lst@delayed\@empty\else
7186
\lst@GetOutputMacro\@gtempa
7187
\ifx\lst@delayedoutput\@gtempa
7188
\lst@MergeToken\lst@delayed\lst@delayedlength
7191
\lst@MergeToken\lst@delayed\lst@delayedlength
7192
\lst@delayedoutput}%
7193
\let\lst@delayed\@empty
7199
% \begin{macro}{\lst@CheckMerge}
7200
% All this is easier for |\lst@merged|.
7202
\def\lst@CheckMerge{%
7203
\ifx\lst@merged\@empty\else
7204
\lst@MergeToken\lst@merged\lst@mergedlength
7208
\let\lst@delayed\@empty % init
7209
\let\lst@merged\@empty % init
7214
% \subsection{Column formats}
7216
% It's time to deal with fixed and flexible column modes.
7217
% A couple of open definitions are now filled in.
7219
% \begin{macro}{\lst@column@fixed}
7220
% switches to the fixed column format. The definitions here control how the
7221
% output of the above definitions looks like.
7223
\def\lst@column@fixed{%
7225
\lst@width\lst@widthfixed\relax
7226
\let\lst@OutputLostSpace\lst@UseLostSpace
7227
\let\lst@FillOutputBox\lst@FillFixed
7229
\def\lst@hbox{\hbox to\lst@length\lst@width}}
7233
% \begin{macro}{\lst@FillFixed}
7234
% Filling up a fixed mode box is easy.
7236
\def\lst@FillFixed#1{#1\lst@FillFixed@}
7238
% While not reaching the end (|\@empty| from above), we insert dynamic space,
7239
% output the argument and call the submacro again.
7241
\def\lst@FillFixed@#1{%
7242
\ifx\@empty#1\else \lst@hss#1\expandafter\lst@FillFixed@ \fi}
7246
% \begin{macro}{\lst@column@flexible}
7247
% The first flexible format.
7249
\def\lst@column@flexible{%
7251
\lst@width\lst@widthflexible\relax
7252
\let\lst@OutputLostSpace\lst@UseLostSpace
7253
\let\lst@FillOutputBox\@empty
7259
% \begin{macro}{\lst@column@fullflexible}
7260
% This column format inserts no lost space except at the beginning of a line.
7262
\def\lst@column@fullflexible{%
7263
\lst@column@flexible
7264
\def\lst@OutputLostSpace{\lst@ifnewline \lst@UseLostSpace\fi}%
7265
\let\lst@leftinsert\@empty
7266
\let\lst@rightinsert\@empty}
7270
% So far the column formats. Now we define macros to use them.
7272
% \begin{macro}{\lst@outputpos}
7273
% This macro sets the `output-box-positioning' parameter (the old key
7274
% \keyname{outputpos}). We test for |l|, |c| and |r|.
7275
% The fixed formats use |\lst@lefthss| and |\lst@righthss|, whereas the
7276
% flexibles need |\lst@leftinsert| and |\lst@rightinsert|.
7278
\def\lst@outputpos#1#2\relax{%
7279
\def\lst@lefthss{\lst@hss}\let\lst@righthss\lst@lefthss
7280
\let\lst@rightinsert\lst@InsertLostSpace
7282
\let\lst@leftinsert\lst@InsertHalfLostSpace
7284
\let\lst@righthss\@empty
7285
\let\lst@leftinsert\lst@InsertLostSpace
7286
\let\lst@rightinsert\@empty
7288
\let\lst@lefthss\@empty
7289
\let\lst@leftinsert\@empty
7290
\ifx #1l\else \PackageWarning{Listings}%
7291
{Unknown positioning for output boxes}%
7297
% \begin{macro}{\lst@ifflexible}
7298
% indicates the column mode but does not distinguish between different fixed
7299
% or flexible modes.
7301
\def\lst@flexibletrue{\let\lst@ifflexible\iftrue}
7302
\def\lst@flexiblefalse{\let\lst@ifflexible\iffalse}
7306
% \begin{lstkey}{columns}
7307
% This is done here: check optional parameter and then build the control
7308
% sequence of the column format.
7310
\lst@Key{columns}{[c]fixed}{\lstKV@OptArg[]{#1}{%
7311
\ifx\@empty##1\@empty\else \lst@outputpos##1\relax\relax \fi
7312
\expandafter\let\expandafter\lst@arg
7313
\csname\@lst @column@##2\endcsname
7315
% We issue a warning or save the definition for later.
7319
\PackageWarning{Listings}{Unknown column format `##2'}%
7322
\let\lst@columnsflexible\lst@arg
7324
\let\lst@columnsfixed\lst@arg
7329
\let\lst@columnsfixed\lst@column@fixed % init
7330
\let\lst@columnsflexible\lst@column@flexible % init
7334
% \begin{lstkey}{flexiblecolumns}
7335
% Nothing else but a key to switch between the last flexible and fixed mode.
7337
\lst@Key{flexiblecolumns}\relax[t]{%
7338
\lstKV@SetIf{#1}\lst@ifflexible
7339
\lst@ifflexible \lst@columnsflexible
7340
\else \lst@columnsfixed \fi}
7345
% \subsection{New lines}
7347
% \begin{macro}{\lst@newlines}
7348
% This counter holds the number of `new lines' (cr+lf) we have to perform.
7350
\newcount\lst@newlines
7351
\lst@AddToHook{InitVars}{\global\lst@newlines\z@}
7352
\lst@AddToHook{InitVarsBOL}{\global\advance\lst@newlines\@ne}
7356
% \begin{macro}{\lst@NewLine}
7357
% This is how we start a new line: begin new paragraph and output an empty
7358
% box. If low-level definition |\lst@OutputBox| just gobbles the box , we
7359
% don't start a new line. This is used to drop the whole output.
7362
\ifx\lst@OutputBox\@gobble\else
7363
\par\noindent \hbox{}%
7365
\global\advance\lst@newlines\m@ne
7368
% Define |\lst@newlinetrue| and reset if after output.
7370
\def\lst@newlinetrue{\global\let\lst@ifnewline\iftrue}
7371
\lst@AddToHookExe{PostOutput}{\global\let\lst@ifnewline\iffalse}% init
7375
% \begin{macro}{\lst@TrackNewLines}
7376
% If |\lst@newlines| is positive, we execute the hook and insert the
7379
\def\lst@TrackNewLines{%
7380
\ifnum\lst@newlines>\z@
7384
\lst@AddToHook{OnNewLine}{}% init
7388
% \begin{lstkey}{emptylines}
7389
% \lsthelper{Adam~Prugel-Bennett}{2001/02/19}{spacing of empty lines} asked for
7390
% such a key---if I didn't misunderstood him. We check for the optional star
7391
% and set |\lst@maxempty| and switch.
7393
\lst@Key{emptylines}\maxdimen{%
7394
\@ifstar{\lst@true\@tempcnta\@gobble#1\relax\lst@GobbleNil}%
7395
{\lst@false\@tempcnta#1\relax\lst@GobbleNil}#1\@nil
7396
\advance\@tempcnta\@ne
7397
\edef\lst@maxempty{\the\@tempcnta\relax}%
7398
\let\lst@ifpreservenumber\lst@if}
7402
% \begin{macro}{\lst@DoNewLines}
7403
% First we take care of |\lst@maxempty| and then of the remaining empty lines.
7405
\def\lst@DoNewLines{
7406
\@whilenum\lst@newlines>\lst@maxempty \do
7407
{\lst@ifpreservenumber
7409
\global\advance\c@lstnumber\lst@advancelstnum
7411
\global\advance\lst@newlines\m@ne}%
7412
\@whilenum \lst@newlines>\@ne \do
7413
{\lsthk@OnEmptyLine \lst@NewLine}%
7414
\ifnum\lst@newlines>\z@ \lst@NewLine \fi}
7415
\lst@AddToHook{OnEmptyLine}{}% init
7420
% \subsection{High-level output}
7422
% \begin{lstkey}{identifierstyle}
7425
\lst@Key{identifierstyle}{}{\def\lst@identifierstyle{#1}}
7426
\lst@AddToHook{EmptyStyle}{\let\lst@identifierstyle\@empty}
7430
% \begin{macro}{\lst@GotoTabStop}
7431
% Here we look whether the line already contains printed characters.
7432
% If true, we output a box with the width of a blank space.
7434
\def\lst@GotoTabStop{%
7435
\ifnum\lst@newlines=\z@
7436
\setbox\@tempboxa\hbox{\lst@outputspace}%
7437
\setbox\@tempboxa\hbox to\wd\@tempboxa{{\lst@currstyle{\hss}}}%
7438
\lst@CalcLostSpaceAndOutput
7440
% It's probably not clear why it is sufficient to output a single space to go
7441
% to the next tabulator stop. Just note that the space lost by this process is
7442
% `lost space' in the sense above and therefore will be inserted before the
7443
% next characters are output.
7447
% Otherwise (no printed characters) we only need to advance |\lst@lostspace|,
7448
% which is inserted by |\lst@OutputToken| above, and update the column.
7450
\global\advance\lst@lostspace \lst@length\lst@width
7451
\global\advance\lst@column\lst@length \lst@length\z@
7454
% Note that this version works also in flexible column mode.
7455
% In fact, it's mainly the flexible version of \packagename{listings} 0.20.
7457
% Use |\lst@ifnewline| instead of |\ifnum\lst@newlines=\z@|?
7461
% \begin{macro}{\lst@OutputOther}
7462
% becomes easy with the previous definitions.
7464
\def\lst@OutputOther{%
7466
\ifnum\lst@length=\z@\else
7467
\let\lst@thestyle\lst@currstyle
7473
\lst@AddToHook{OutputOther}{}% init
7474
\let\lst@currstyle\relax % init
7478
% \begin{macro}{\lst@Output}
7479
% We might use identifier style as default.
7483
\ifnum\lst@length=\z@\else
7484
\ifx\lst@currstyle\relax
7485
\let\lst@thestyle\lst@identifierstyle
7487
\let\lst@thestyle\lst@currstyle
7492
\let\lst@lastother\relax}
7494
% Note that |\lst@lastother| becomes equivalent to |\relax| and not equivalent
7495
% to |\@empty| as everywhere else. I don't know whether this will be important
7496
% in the future or not.
7498
\lst@AddToHook{Output}{}% init
7502
% \begin{macro}{\lst@GetOutputMacro}
7503
% Just saves the output macro to be used.
7505
\def\lst@GetOutputMacro#1{%
7506
\lst@ifletter \global\let#1\lst@Output
7507
\else \global\let#1\lst@OutputOther\fi}
7511
% \begin{macro}{\lst@PrintToken}
7512
% outputs the current character string in letter or nonletter mode.
7514
\def\lst@PrintToken{%
7515
\lst@ifletter \lst@Output \lst@letterfalse
7516
\else \lst@OutputOther \let\lst@lastother\@empty \fi}
7520
% \begin{macro}{\lst@XPrintToken}
7521
% is a special definition to print also merged characters.
7523
\def\lst@XPrintToken{%
7524
\lst@PrintToken \lst@CheckMerge
7525
\ifnum\lst@length=\z@\else \lst@PrintToken \fi}
7530
% \subsection{Dropping the whole output}
7532
% \begin{macro}{\lst@BeginDropOutput}
7533
% It's sometimes useful to process a part of a listing as usual, but to drop
7534
% the output. This macro does the main work and gets one argument, namely the
7535
% internal mode it enters. We save |\lst@newlines|, restore it |\aftergroup|
7536
% and redefine one macro, namely |\lst@OutputBox|. After a bug report from
7537
% \lsthelper{Gunther~Schmidl}{2002/02/27}{collapsing empty lines don't work
7538
% with printpod=false}
7540
\def\lst@BeginDropOutput#1{%
7541
\xdef\lst@BDOnewlines{\the\lst@newlines}%
7542
\global\let\lst@BDOifnewline\lst@ifnewline
7545
\let\lst@OutputBox\@gobble
7546
\aftergroup\lst@BDORestore}}
7548
% Restoring the date is quite easy:
7550
\def\lst@BDORestore{%
7551
\global\lst@newlines\lst@BDOnewlines
7552
\global\let\lst@ifnewline\lst@BDOifnewline}
7556
% \begin{macro}{\lst@EndDropOutput}
7557
% is equivalent to |\lst@LeaveMode|.
7559
\let\lst@EndDropOutput\lst@LeaveMode
7567
% \subsection{Writing to an external file}
7569
% \begin{aspect}{writefile}
7570
% Now it would be good to know something about character classes since we need
7571
% to access the true input characters, for example a tabulator and not the
7572
% spaces it `expands' to.
7575
\lst@BeginAspect{writefile}
7578
% \begin{macro}{\lst@WF}
7579
% \begin{macro}{\lst@WFtoken}
7580
% The contents of the token will be written to file.
7582
\newtoks\lst@WFtoken % global
7583
\lst@AddToHook{InitVarsBOL}{\global\lst@WFtoken{}}
7587
\global\let\lst@WFifopen\iffalse % init
7592
% \begin{macro}{\lst@WFWriteToFile}
7593
% To do this, we have to expand the contents and then expand this via |\edef|.
7594
% Empty |\lst@UM| ensures that special characters (underscore, dollar, etc.)
7595
% are written correctly.
7597
\gdef\lst@WFWriteToFile{%
7600
\expandafter\edef\expandafter\lst@temp\expandafter{\the\lst@WFtoken}%
7601
\immediate\write\lst@WF{\lst@temp}%
7603
\global\lst@WFtoken{}}
7607
% \begin{macro}{\lst@WFAppend}
7608
% Similar to |\lst@Append| but uses |\lst@WFtoken|.
7610
\gdef\lst@WFAppend#1{%
7611
\global\lst@WFtoken=\expandafter{\the\lst@WFtoken#1}}
7615
% \begin{macro}{\lst@BeginWriteFile}
7616
% \begin{macro}{\lst@BeginAlsoWriteFile}
7617
% use different macros for |\lst@OutputBox| (not) to drop the output.
7619
\gdef\lst@BeginWriteFile{\lst@WFBegin\@gobble}
7620
\gdef\lst@BeginAlsoWriteFile{\lst@WFBegin\lst@OutputBox}
7625
% \begin{macro}{\lst@WFBegin}
7628
\begingroup \catcode`\^^I=11
7629
\gdef\lst@WFBegin#1#2{%
7631
\let\lst@OutputBox#1%
7633
% \ldots\space we have to update |\lst@WFtoken| and \ldots
7635
\def\lst@Append##1{%
7636
\advance\lst@length\@ne
7637
\expandafter\lst@token\expandafter{\the\lst@token##1}%
7638
\ifx ##1\lst@outputspace \else
7641
\lst@lAddTo\lst@PreGotoTabStop{\lst@WFAppend{^^I}}%
7642
\lst@lAddTo\lst@ProcessSpace{\lst@WFAppend{ }}%
7644
% \ldots\space need different `EOL' and `DeInit' definitions to write the
7645
% token register to file.
7647
\let\lst@DeInit\lst@WFDeInit
7648
\let\lst@MProcessListing\lst@WFMProcessListing
7650
% Finally we open the file if necessary.
7653
\immediate\openout\lst@WF=#2\relax
7654
\global\let\lst@WFifopen\iftrue
7661
% \begin{macro}{\lst@EndWriteFile}
7662
% closes the file and restores original definitions.
7664
\gdef\lst@EndWriteFile{%
7665
\immediate\closeout\lst@WF \endgroup
7666
\global\let\lst@WFifopen\iffalse}
7670
% \begin{macro}{\lst@WFMProcessListing}
7671
% \begin{macro}{\lst@WFDeInit}
7672
% write additionally |\lst@WFtoken| to external file.
7674
\global\let\lst@WFMProcessListing\lst@MProcessListing
7675
\global\let\lst@WFDeInit\lst@DeInit
7676
\lst@AddToAtTop\lst@WFMProcessListing{\lst@WFWriteToFile}
7677
\lst@AddToAtTop\lst@WFDeInit{%
7678
\ifnum\lst@length=\z@\else \lst@WFWriteToFile \fi}
7690
% \section{Character classes}\label{iCharacterClasses}
7692
% In this section, we define how the basic character classes do behave, before
7693
% turning over to the selection of character tables and how to specialize
7697
% \subsection{Letters, digits and others}
7703
% \begin{macro}{\lst@ProcessLetter}
7704
% We put the letter, which is not a whitespace, into the output queue.
7706
\def\lst@ProcessLetter{\lst@whitespacefalse \lst@AppendLetter}
7710
% \begin{macro}{\lst@ProcessOther}
7713
\def\lst@ProcessOther{\lst@whitespacefalse \lst@AppendOther}
7717
% \begin{macro}{\lst@ProcessDigit}
7718
% A digit appends the character to the current character string. But we must
7719
% use the right macro. This allows digits to be part of an identifier or
7720
% a numerical constant.
7722
\def\lst@ProcessDigit{%
7723
\lst@whitespacefalse
7724
\lst@ifletter \expandafter\lst@AppendLetter
7725
\else \expandafter\lst@AppendOther\fi}
7729
% \begin{macro}{\lst@ifwhitespace}
7730
% indicates whether the last processed character has been white space.
7732
\def\lst@whitespacetrue{\global\let\lst@ifwhitespace\iftrue}
7733
\def\lst@whitespacefalse{\global\let\lst@ifwhitespace\iffalse}
7734
\lst@AddToHook{InitVarsBOL}{\lst@whitespacetrue}
7739
% \subsection{Whitespaces}
7741
% Here we have to take care of two things: dropping empty lines at the end of
7742
% a listing and the different column formats. Both use |\lst@lostspace|. Lines
7743
% containing only tabulators and spaces should be viewed as empty. In order to
7744
% achieve this, tabulators and spaces at the beginning of a line don't output
7745
% any characters but advance |\lst@lostspace|. Whenever this dimension is
7746
% positive we insert that space before the character string is output. Thus,
7747
% if there are only tabulators and spaces, the line is `empty' since we
7748
% haven't done any output.
7750
% We have to do more for flexible columns. Whitespaces can fix the column
7751
% alignment: if the real line is wider than expected, a tabulator is at least
7752
% one space wide; all remaining space fixes the alignment. If there are two or
7753
% more space characters, at least one is printed; the others fix the column
7757
% \paragraph{Tabulators}
7758
% are processed in three stages. You have already seen the last stage
7759
% |\lst@GotoTabStop|. The other two calculate the necessary width and take care
7760
% of visible tabulators and spaces.
7762
% \begin{lstkey}{tabsize}
7763
% We check for a legal argument before saving it. Default tabsize is 8 as
7764
% proposed by \lsthelper{Rolf~Niepraschk}{1997/04/24}{tabsize=8}.
7766
\lst@Key{tabsize}{8}
7767
{\ifnum#1>\z@ \def\lst@tabsize{#1}\else
7768
\PackageError{Listings}{Strict positive integer expected}%
7769
{You can't use `#1' as tabsize. \@ehc}%
7774
% \begin{lstkey}{showtabs}
7775
% \begin{lstkey}{tab}
7776
% Two more user keys for tab control.
7778
\lst@Key{showtabs}f[t]{\lstKV@SetIf{#1}\lst@ifshowtabs}
7779
\lst@Key{tab}{\kern.06em\hbox{\vrule\@height.3ex}%
7780
\hrulefill\hbox{\vrule\@height.3ex}}
7786
% \begin{macro}{\lst@ProcessTabulator}
7787
% A tabulator outputs the preceding characters, which decrements |\lst@pos| by
7788
% the number of printed characters.
7790
\def\lst@ProcessTabulator{%
7791
\lst@XPrintToken \lst@whitespacetrue
7793
% Then we calculate how many columns we need to reach the next tabulator stop:
7794
% we add |\lst@tabsize| until |\lst@pos| is strict positive. In other words,
7795
% |\lst@pos| is the column modulo |tabsize| and we're looking for a positive
7796
% representative. We assign it to |\lst@length| and reset |\lst@pos| in the
7799
\global\advance\lst@column -\lst@pos
7800
\@whilenum \lst@pos<\@ne \do
7801
{\global\advance\lst@pos\lst@tabsize}%
7803
\lst@PreGotoTabStop}
7807
% \begin{macro}{\lst@PreGotoTabStop}
7808
% Visible tabs print |\lst@tab|.
7810
\def\lst@PreGotoTabStop{%
7813
\setbox\@tempboxa\hbox to\lst@length\lst@width
7814
{{\lst@currstyle{\hss\lst@tab}}}%
7815
\lst@CalcLostSpaceAndOutput
7818
% If we are advised to keep spaces, we insert the correct number of them.
7821
\@tempcnta\lst@length \lst@length\z@
7822
\@whilenum \@tempcnta>\z@ \do
7823
{\lst@AppendOther\lst@outputspace
7824
\advance\@tempcnta\m@ne}%
7830
\lst@length\z@ \global\lst@pos\z@}
7835
% \paragraph{Spaces}
7836
% are implemented as described at the beginning of this subsection. But first
7837
% we define some user keys.
7839
% \begin{macro}{\lst@outputspace}
7840
% \begin{macro}{\lst@visiblespace}
7841
% The first macro is a default definition, \ldots
7843
\def\lst@outputspace{\ }
7844
\def\lst@visiblespace{\lst@ttfamily{\char32}\textvisiblespace}
7849
% \begin{lstkey}{showspaces}
7850
% \begin{lstkey}{keepspaces}
7851
% \ldots\space which is modified on user's request.
7853
\lst@Key{showspaces}{false}[t]{\lstKV@SetIf{#1}\lst@ifshowspaces}
7854
\lst@Key{keepspaces}{false}[t]{\lstKV@SetIf{#1}\lst@ifkeepspaces}
7855
\lst@AddToHook{Init}
7857
\let\lst@outputspace\lst@visiblespace
7860
\def\lst@keepspacestrue{\let\lst@ifkeepspaces\iftrue}
7865
% \begin{macro}{\lst@ProcessSpace}
7866
% We look whether spaces fix the column alignment or not. In the latter case
7867
% we append a space; otherwise \ldots
7869
\def\lst@ProcessSpace{%
7871
\lst@AppendOther\lst@outputspace
7872
\else \ifnum\lst@newlines=\z@
7874
% \ldots\space we append a `special space' if the line isn't empty.
7876
\lst@AppendSpecialSpace
7877
\else \ifnum\lst@length=\z@
7879
% If the line is empty, we check whether there are characters in the output
7880
% queue. If there are no characters we just advance |\lst@lostspace|.
7881
% Otherwise we append the space.
7883
\global\advance\lst@lostspace\lst@width
7884
\global\advance\lst@pos\m@ne
7886
\lst@AppendSpecialSpace
7889
\lst@whitespacetrue}
7891
% Note that this version works for fixed and flexible column output.
7894
% \begin{macro}{\lst@AppendSpecialSpace}
7895
% If there are at least two white spaces, we output preceding characters and
7896
% advance |\lst@lostspace| to avoid alignment problems. Otherwise we append
7897
% a space to the current character string.
7899
\def\lst@AppendSpecialSpace{%
7902
\global\advance\lst@lostspace\lst@width
7903
\global\advance\lst@pos\m@ne
7905
\lst@AppendOther\lst@outputspace
7911
% \paragraph{Form feeds}
7912
% has been introduced after communication with
7913
% \lsthelper{Jan~Braun}{1998/04/27}{formfeed}.
7915
% \begin{lstkey}{formfeed}
7916
% let the user make adjustments.
7918
\lst@Key{formfeed}{\bigbreak}{\def\lst@formfeed{#1}}
7922
% \begin{macro}{\lst@ProcessFormFeed}
7923
% Here we execute some macros according to whether a new line has already
7924
% begun or not. No |\lst@EOLUpdate| is used in the else branch
7925
% anymore---\lsthelper{Kalle~Tuulos}{2001/01/14}{form feed gobbles following
7926
% output unit} sent the bug report.
7928
\def\lst@ProcessFormFeed{%
7930
\ifnum\lst@newlines=\z@
7931
\lst@EOLUpdate \lsthk@InitVarsBOL
7934
\lst@whitespacetrue}
7939
% \subsection{Character tables}\label{iCharacterTables}
7942
% \subsubsection{The standard table}
7944
% The standard character table is selected by |\lst@SelectStdCharTable|, which
7945
% expands to a token sequence
7946
% \ldots|\def| |A{\lst@ProcessLetter| |A}|\ldots\space
7947
% where the first A is active and the second has catcode 12. We use the
7948
% following macros to build the character table.
7950
% \item[0.19] |\lst@CCPut|\meta{class macro}\meta{$c_1$}\ldots\meta{$c_k$}|\z@|
7952
% extends the standard character table by the characters with codes
7953
% \meta{$c_1$}\ldots\meta{$c_k$} making each character use
7954
% \meta{class macro}. All these characters must be printable via
7955
% |\char|\meta{$c_i$}.
7957
% \item[0.20] |\lst@CCPutMacro|\meta{class$_1$}\meta{$c_1$}\meta{definition$_1$}\ldots|\@empty\z@\@empty|
7959
% also extends the standard character table: the character \meta{$c_i$}
7960
% will use \meta{class$_i$} and is printed via \meta{definition$_i$}.
7961
% These definitions must be \meta{spec. token}s in the sense of section
7962
% \ref{dCharacterTables}.
7965
% \begin{macro}{\lst@Def}
7966
% \begin{macro}{\lst@Let}
7967
% For speed we won't use these helpers too often.
7969
\def\lst@Def#1{\lccode`\~=#1\lowercase{\def~}}
7970
\def\lst@Let#1{\lccode`\~=#1\lowercase{\let~}}
7976
% The definition of the space below doesn't hurt anything. But other aspects,
7977
% for example \aspectname{lineshape} and \aspectname{formats}, redefine also
7978
% the macro |\space|. Now, if \LaTeX\ calls |\try@load@fontshape|, the |.log|
7979
% messages would show some strange things since \LaTeX\ uses |\space| in these
7980
% messages. The following addition ensures that |\space| expands to a space
7981
% and not to something different. This was one more bug reported by
7982
% \lsthelper{Denis~Girou}{1999/09/16}{bad font info message with breaklines}.
7984
\lst@AddToAtTop{\try@load@fontshape}{\def\space{ }}
7988
% \begin{macro}{\lst@SelectStdCharTable}
7989
% The first three standard characters. |\lst@Let| has been replaced by
7990
% |\lst@Def| after a bug report from \lsthelper{Chris~Edwards}{2002/02/15}
7991
% {tabulators show up with firstline>1}.
7993
\def\lst@SelectStdCharTable{%
7994
\lst@Def{9}{\lst@ProcessTabulator}%
7995
\lst@Def{12}{\lst@ProcessFormFeed}%
7996
\lst@Def{32}{\lst@ProcessSpace}}
8000
% \begin{macro}{\lst@CCPut}
8001
% The first argument gives the character class, then follow the codes.
8003
\def\lst@CCPut#1#2{%
8005
\expandafter\@gobbletwo
8007
\lccode`\~=#2\lccode`\/=#2\lowercase{\lst@CCPut@~{#1/}}%
8010
\def\lst@CCPut@#1#2{\lst@lAddTo\lst@SelectStdCharTable{\def#1{#2}}}
8012
% Now we insert more standard characters.
8014
\lst@CCPut \lst@ProcessOther
8015
{"21}{"22}{"27}{"28}{"29}{"2B}{"2C}{"2E}{"2F}
8016
{"3A}{"3B}{"3D}{"3F}{"5B}{"5D}{"60}
8018
\lst@CCPut \lst@ProcessDigit
8019
{"30}{"31}{"32}{"33}{"34}{"35}{"36}{"37}{"38}{"39}
8021
\lst@CCPut \lst@ProcessLetter
8022
{"40}{"41}{"42}{"43}{"44}{"45}{"46}{"47}
8023
{"48}{"49}{"4A}{"4B}{"4C}{"4D}{"4E}{"4F}
8024
{"50}{"51}{"52}{"53}{"54}{"55}{"56}{"57}
8026
{"61}{"62}{"63}{"64}{"65}{"66}{"67}
8027
{"68}{"69}{"6A}{"6B}{"6C}{"6D}{"6E}{"6F}
8028
{"70}{"71}{"72}{"73}{"74}{"75}{"76}{"77}
8034
% \begin{macro}{\lst@CCPutMacro}
8035
% Now we come to a delicate point. The characters not inserted yet aren't
8036
% printable (|_|, |$|, \ldots) or aren't printed well (|*|, |-|, \ldots) if we
8037
% enter these characters. Thus we use proper macros to print the characters.
8038
% Works perfectly. The problem is that the current character string is
8039
% printable for speed, for example |_| is already replaced by a macro version,
8040
% but the new keyword tests need the original characters.
8042
% The solution: We define |\def _{\lst@ProcessLetter\lst@um_}| where the first
8043
% underscore is active and the second belongs to the control sequence.
8044
% Moreover we have |\def\lst@um_{\lst@UM _}| where the second underscore has
8045
% the usual meaning. Now the keyword tests can access the original character
8046
% simply by making |\lst@UM| empty. The default definition gets the following
8047
% token and builds the control sequence |\lst@um_@|, which we'll define to
8048
% print the character. Easy, isn't it?^^A ;-)
8050
% The following definition does all this for us. The first parameter gives the
8051
% character class, the second the character code, and the last the definition
8052
% which actually prints the character. We build the names |\lst@um_| and
8053
% |\lst@um_@| and give them to a submacro.
8055
\def\lst@CCPutMacro#1#2#3{%
8057
\begingroup\lccode`\~=#2\relax \lccode`\/=#2\relax
8058
\lowercase{\endgroup\expandafter\lst@CCPutMacro@
8059
\csname\@lst @um/\expandafter\endcsname
8060
\csname\@lst @um/@\endcsname /~}#1{#3}%
8061
\expandafter\lst@CCPutMacro
8064
% The arguments are now |\lst@um_|, |\lst@um_@|, nonactive character, active
8065
% character, character class and printing definition. We add |\def _{|
8066
% |\lst@ProcessLetter| |\lst@um_}| to |\lst@SelectStdCharTable| (and similarly
8067
% other special characters), define |\def\lst@um_{\lst@UM _}| and |\lst@um_@|.
8069
\def\lst@CCPutMacro@#1#2#3#4#5#6{%
8070
\lst@lAddTo\lst@SelectStdCharTable{\def#4{#5#1}}%
8074
% The default definition of |\lst@UM|:
8076
\def\lst@UM#1{\csname\@lst @um#1@\endcsname}
8078
% And all remaining standard characters.
8081
\lst@ProcessOther {"23}\#
8082
\lst@ProcessLetter{"24}\textdollar
8083
\lst@ProcessOther {"25}\%
8084
\lst@ProcessOther {"26}\&
8085
\lst@ProcessOther {"2A}{\lst@ttfamily*\textasteriskcentered}
8086
\lst@ProcessOther {"2D}{\lst@ttfamily{-{}}{$-$}}
8087
\lst@ProcessOther {"3C}{\lst@ttfamily<\textless}
8088
\lst@ProcessOther {"3E}{\lst@ttfamily>\textgreater}
8089
\lst@ProcessOther {"5C}{\lst@ttfamily{\char92}\textbackslash}
8090
\lst@ProcessOther {"5E}\textasciicircum
8091
\lst@ProcessLetter{"5F}{\lst@ttfamily{\char95}\textunderscore}
8092
\lst@ProcessOther {"7B}{\lst@ttfamily{\char123}\textbraceleft}
8093
\lst@ProcessOther {"7C}{\lst@ttfamily|\textbar}
8094
\lst@ProcessOther {"7D}{\lst@ttfamily{\char125}\textbraceright}
8095
\lst@ProcessOther {"7E}\textasciitilde
8096
\lst@ProcessOther {"7F}-
8101
% \begin{macro}{\lst@ttfamily}
8102
% What is this ominous macro? It prints either the first or the second
8103
% argument. In |\ttfamily| it ensures that |----| is typeset |----| and not
8104
% $-$$-$$-$$-$ as in version 0.17. Bug encountered by
8105
% \lsthelper{Dr.~Jobst~Hoffmann}{1998/03/30}{|\lst@minus| and |\ttfamily|}.
8106
% Furthermore I added |\relax| after receiving an error report from
8107
% \lsthelper{Magnus~Lewis-Smith}{1999/08/06}{! Bad character code (920).}
8109
\def\lst@ttfamily#1#2{\ifx\f@family\ttdefault#1\relax\else#2\fi}
8111
% |\ttdefault| is defined |\long|, so the |\ifx| doesn't work since |\f@family|
8112
% isn't |\long|! We go around this problem by redefining |\ttdefault| locally:
8114
\lst@AddToHook{Init}{\edef\ttdefault{\ttdefault}}
8118
% \begin{macro}{\lst@ifactivechars}
8121
\def\lst@activecharstrue{\let\lst@ifactivechars\iftrue}
8122
\def\lst@activecharsfalse{\let\lst@ifactivechars\iffalse}
8123
\lst@activecharstrue
8127
% \begin{macro}{\lst@SelectCharTable}
8128
% We select the standard character table and switch to active catcodes.
8130
\def\lst@SelectCharTable{%
8131
\lst@SelectStdCharTable
8133
\catcode9\active \catcode12\active \catcode13\active
8135
\@whilenum\@tempcnta<128\do
8136
{\catcode\@tempcnta\active\advance\@tempcnta\@ne}%
8138
\lst@ifec \lst@DefEC \fi
8140
% The following line and the according macros below have been added after a
8141
% bug report from \lsthelper{Fr\'ed\'eric~Boulanger}{2001/02/27}{ligatures}.
8143
\let\do@noligs\lst@do@noligs \verbatim@nolig@list
8145
% There are two ways to adjust the standard table: inside the hook or with
8146
% |\lst@DeveloperSCT|. We use these macros and initialize the backslash if
8149
\lsthk@SelectCharTable
8151
\ifx\lst@Backslash\relax\else
8152
\lst@LetSaveDef{"5C}\lsts@backslash\lst@Backslash
8157
% \begin{lstkey}{SelectCharTable}
8158
% \begin{lstkey}{MoreSelectCharTable}
8159
% The keys to adjust |\lst@DeveloperSCT|.
8161
\lst@Key{SelectCharTable}{}{\def\lst@DeveloperSCT{#1}}
8162
\lst@Key{MoreSelectCharTable}\relax{\lst@lAddTo\lst@DeveloperSCT{#1}}
8165
\lst@AddToHook{SetLanguage}{\let\lst@DeveloperSCT\@empty}
8170
% \begin{macro}{\lst@do@noligs}
8171
% To prevent ligatures, this macro inserts the token |\lst@NoLig| in front of
8172
% |\lst@Process|\meta{whatever}\meta{spec.~token}. This is done by
8173
% |\verbatim@nolig@list| for certain characters. Note that the submacro is
8174
% a special kind of a local |\lst@AddToAtTop|.
8176
\def\lst@do@noligs#1{%
8177
\begingroup \lccode`\~=`#1\lowercase{\endgroup
8179
\def\lst@do@noligs#1#2{%
8180
\expandafter\expandafter\expandafter\def
8181
\expandafter\expandafter\expandafter#1%
8182
\expandafter\expandafter\expandafter{\expandafter\lst@NoLig#1}}
8186
% \begin{macro}{\lst@NoLig}
8187
% When this extra macro is processed, it adds |\lst@nolig| to the output queue
8188
% without increasing its length. For keyword detection this must expand to
8189
% nothing if |\lst@UM| is empty.
8191
\def\lst@NoLig{\advance\lst@length\m@ne \lst@Append\lst@nolig}
8192
\def\lst@nolig{\lst@UM\@empty}%
8194
% But the usual meaning of |\lst@UM| builds the following control sequence,
8195
% which prevents ligatures in the manner of \LaTeX's |\do@noligs|.
8197
\@namedef{\@lst @um@}{\leavevmode\kern\z@}
8201
% \begin{macro}{\lst@SaveOutputDef}
8202
% To get the \meta{spec.~token} meaning of character |#1|, we look for |\def|
8203
% `active character |#1|' in |\lst@SelectStdCharTable|, get the replacement
8204
% text, strip off the character class via |\@gobble|, and assign the meaning.
8205
% Note that you get a ``runaway argument'' error if an illegal \meta{character
8206
% code}=|#1| is used.
8208
\def\lst@SaveOutputDef#1#2{%
8209
\begingroup \lccode`\~=#1\relax \lowercase{\endgroup
8210
\def\lst@temp##1\def~##2##3\relax}{%
8211
\global\expandafter\let\expandafter#2\@gobble##2\relax}%
8212
\expandafter\lst@temp\lst@SelectStdCharTable\relax}
8216
% \begin{macro}{\lstum@backslash}
8217
% A commonly used character.
8219
\lst@SaveOutputDef{"5C}\lstum@backslash
8224
% \subsubsection{National characters}
8226
% \begin{lstkey}{extendedchars}
8227
% The user key to activate extended characters 128--255.
8229
\lst@Key{extendedchars}{false}[t]{\lstKV@SetIf{#1}\lst@ifec}
8233
% \begin{macro}{\lst@DefEC}
8234
% Currently each character in the range 128--255 is treated as a letter.
8237
\lst@CCECUse \lst@ProcessLetter
8238
^^80^^81^^82^^83^^84^^85^^86^^87^^88^^89^^8a^^8b^^8c^^8d^^8e^^8f%
8239
^^90^^91^^92^^93^^94^^95^^96^^97^^98^^99^^9a^^9b^^9c^^9d^^9e^^9f%
8240
^^a0^^a1^^a2^^a3^^a4^^a5^^a6^^a7^^a8^^a9^^aa^^ab^^ac^^ad^^ae^^af%
8241
^^b0^^b1^^b2^^b3^^b4^^b5^^b6^^b7^^b8^^b9^^ba^^bb^^bc^^bd^^be^^bf%
8242
^^c0^^c1^^c2^^c3^^c4^^c5^^c6^^c7^^c8^^c9^^ca^^cb^^cc^^cd^^ce^^cf%
8243
^^d0^^d1^^d2^^d3^^d4^^d5^^d6^^d7^^d8^^d9^^da^^db^^dc^^dd^^de^^df%
8244
^^e0^^e1^^e2^^e3^^e4^^e5^^e6^^e7^^e8^^e9^^ea^^eb^^ec^^ed^^ee^^ef%
8245
^^f0^^f1^^f2^^f3^^f4^^f5^^f6^^f7^^f8^^f9^^fa^^fb^^fc^^fd^^fe^^ff%
8250
% \begin{macro}{\lst@CCECUse}
8251
% Reaching end of list (|^^00|) we terminate the loop.
8252
% Otherwise we do the same as in |\lst@CCPut| if the character is not active.
8253
% But if the character is active, we save the meaning before redefinition.
8255
\def\lst@CCECUse#1#2{%
8257
\expandafter\@gobbletwo
8259
\ifnum\catcode`#2=\active
8260
\lccode`\~=`#2\lccode`\/=`#2\lowercase{\lst@CCECUse@#1~/}%
8262
\lst@ifactivechars \catcode`#2=\active \fi
8263
\lccode`\~=`#2\lccode`\/=`#2\lowercase{\def~{#1/}}%
8268
% We save the meaning as mentioned. Here we must also use the `|\lst@UM|
8269
% construction' since extended characters could often appear in words =
8270
% identifiers. Bug reported by \lsthelper{Denis~Girou}{1999/07/26}
8271
% {incompatibility with inputenc}.
8273
\def\lst@CCECUse@#1#2#3{%
8274
\expandafter\def\csname\@lst @EC#3\endcsname{\lst@UM#3}%
8275
\expandafter\let\csname\@lst @um#3@\endcsname #2%
8276
\edef#2{\noexpand#1%
8277
\expandafter\noexpand\csname\@lst @EC#3\endcsname}}
8279
% \lsthelper{Daniel~Gerigk}{2001/10/25}{extendedchars do not work} and
8280
% \lsthelper{Heiko~Oberdiek}{2001/10/26}{extendedchars do not work: um@\#3@
8281
% must be @um\#3@} reported an error and a solution, respectively.
8285
% \subsubsection{Catcode problems}
8287
% \begin{macro}{\lst@nfss@catcodes}
8288
% \lsthelper{Anders~Edenbrandt}{1997/04/22}{preload of .fd files} found a bug
8289
% with \texttt{.fd}-files. Since we change catcodes and these files are read
8290
% on demand, we must reset the catcodes before the files are input. We use a
8291
% local redefinition of |\nfss@catcodes|.
8293
\lst@AddToHook{Init}
8294
{\let\lsts@nfss@catcodes\nfss@catcodes
8295
\let\nfss@catcodes\lst@nfss@catcodes}
8298
\def\lst@nfss@catcodes{%
8300
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\relax
8301
\@makeother 0\@makeother 1\@makeother 2\@makeother 3\@makeother 4%
8302
\@makeother 5\@makeother 6\@makeother 7\@makeother 8\@makeother 9%
8303
\@makeother =\lsts@nfss@catcodes}
8305
% The investigation of a bug reported by \lsthelper{Christian~Gudrian}
8306
% {2000/11/16}{problems with mathpple} showed that the equal sign needs
8307
% to have `other' catcode, as assigned above.
8309
% The name of |\lst@makeletter| is an imitation of \LaTeX's |\@makeother|.
8311
\def\lst@makeletter#1{%
8312
\ifx\relax#1\else\catcode`#111\relax \expandafter\lst@makeletter\fi}
8316
% \begin{macro}{\output}
8317
% Another problem was first reported by \lsthelper{Marcin~Kasperski}
8318
% {1999/04/28}{listings spoil toc}. It is also catcode related and
8319
% \lsthelper{Donald~Arseneau}{1999/05/13}{comp.text.tex Re: delayed write and
8320
% catcode changes} let me understand it. The point is that \TeX\ seems to use
8321
% the \emph{currently} active catcode table when it writes non-|\immediate|
8322
% |\write|s to file and not the catcodes involved when \emph{reading} the
8324
% So a section heading |\L a| was written |\La| if a listing was split on two
8325
% pages since a non-standard catcode table was in use when writing |\La| to
8326
% file, the previously attached catcodes do not matter. One more bug was that
8327
% accents in page headings or footers were lost when a listing was split on
8328
% two pages. \lsthelper{Denis~Girou}{1999/08/03}{Accents lost in heading if
8329
% listing split on two pages} found this latter bug. A similar problem with
8330
% the tilde was reported by \lsthelper{Thorsten~Vitt}{2001/06/25}{fancyhdr +
8331
% listings crossing pages ==> ~ in header, not space}.
8333
% The solution is a local redefinition of the output routine. We interrupt the
8334
% current modes---in particular |\lst@Pmode| with modified catcode table---,
8335
% call the original output routine and reenter the mode. This must be done
8336
% with a little care. First we have to close the group which \TeX\ opens at
8337
% the beginning of the output routine. A single |\egroup| gives an `unbalanced
8338
% output routine' error. But |\expandafter\egroup| works. Again it was
8339
% \lsthelper{Donald~Arseneau}{2001/01/10}{comp.text.tex Re: \output puzzle}
8340
% who gave the explaination: The |\expandafter| set the token type of |\bgroup|
8341
% to |backed_up|, which prevents \TeX's from recovering from an unbalanced
8342
% output routine. \lsthelper{Heiko~Oberdiek}{2001/01/05}{comp.text.tex Re:
8343
% \output puzzle} reported that |\csname| |egroup||\endcsname| does the trick,
8346
% However, since \TeX\ checks the contents of |\box| 255 when we close the
8347
% group (`output routine didn't use all of |\box| 255'), we have to save it
8350
\lst@AddToHook{Init}
8351
{\edef\lst@OrgOutput{\the\output}%
8352
\output{\global\setbox\lst@gtempboxa\box\@cclv
8355
% Now we can interrupt the mode, but we have to save the current character
8356
% string and the current style.
8361
% We restore the contents, use the original output routine, and \ldots
8363
\setbox\@cclv\box\lst@gtempboxa
8364
\bgroup\lst@OrgOutput\egroup
8366
% \ldots\space open a group matching the |}| which \TeX\ inserts at the end of
8367
% the output routine. We reenter modes and restore the character string and
8368
% style |\aftergroup|. Moreover we need to reset |\pagegoal|---added after a
8369
% bug report by \lsthelper{Jochen~Schneider}{2002/03/09}{de.comp.text.tex:
8370
% Problem mit Listings-Paket 1.0-Beta; unmotivated pagebreak with preceding
8374
\aftergroup\pagegoal\aftergroup\vsize
8375
\aftergroup\lst@ReenterModes\aftergroup\lst@RestoreToken}}
8377
% Note that this output routine isn't used too often. It is executed only if
8378
% it's possible that a listing is split on two pages: if a listing ends at
8379
% the bottom or begins at the top of a page, or if a listing is really split.
8383
% \subsubsection{Adjusting the table}
8385
% We begin with modifiers for the basic character classes.
8387
% \begin{lstkey}{alsoletter}
8388
% \begin{lstkey}{alsodigit}
8389
% \begin{lstkey}{alsoother}
8390
% The macros |\lst@also|\ldots\space will hold |\def|\meta{char}|{|\ldots|}|
8391
% sequences, which adjusts the standard character table.
8393
\lst@Key{alsoletter}\relax{%
8394
\lst@DoAlso{#1}\lst@alsoletter\lst@ProcessLetter}
8395
\lst@Key{alsodigit}\relax{%
8396
\lst@DoAlso{#1}\lst@alsodigit\lst@ProcessDigit}
8397
\lst@Key{alsoother}\relax{%
8398
\lst@DoAlso{#1}\lst@alsoother\lst@ProcessOther}
8400
% This is done at \hookname{SelectCharTable} and every language selection
8401
% the macros get empty.
8403
\lst@AddToHook{SelectCharTable}
8404
{\lst@alsoother \lst@alsodigit \lst@alsoletter}
8405
\lst@AddToHookExe{SetLanguage}% init
8406
{\let\lst@alsoletter\@empty
8407
\let\lst@alsodigit\@empty
8408
\let\lst@alsoother\@empty}
8410
% The service macro starts a loop and \ldots
8412
\def\lst@DoAlso#1#2#3{%
8413
\lst@DefOther\lst@arg{#1}\let#2\@empty
8414
\expandafter\lst@DoAlso@\expandafter#2\expandafter#3\lst@arg\relax}
8415
\def\lst@DoAlso@#1#2#3{%
8416
\ifx\relax#3\expandafter\@gobblethree \else
8418
% \ldots\space while not reaching |\relax| we use the \TeX nique from
8419
% |\lst@SaveOutputDef| to replace the class by |#2|. Eventually we append
8420
% the new definition to |#1|.
8422
\begingroup \lccode`\~=`#3\relax \lowercase{\endgroup
8423
\def\lst@temp##1\def~##2##3\relax{%
8424
\edef\lst@arg{\def\noexpand~{\noexpand#2\expandafter
8425
\noexpand\@gobble##2}}}}%
8426
\expandafter\lst@temp\lst@SelectStdCharTable\relax
8427
\lst@lExtend#1{\lst@arg}%
8435
% \begin{macro}{\lst@SaveDef}
8436
% \begin{macro}{\lst@DefSaveDef}
8437
% \begin{macro}{\lst@LetSaveDef}
8438
% These macros can be used in language definitions to make special changes.
8439
% They save the definition and define or assign a new one.
8441
\def\lst@SaveDef#1#2{%
8442
\begingroup \lccode`\~=#1\relax \lowercase{\endgroup\let#2~}}
8443
\def\lst@DefSaveDef#1#2{%
8444
\begingroup \lccode`\~=#1\relax \lowercase{\endgroup\let#2~\def~}}
8445
\def\lst@LetSaveDef#1#2{%
8446
\begingroup \lccode`\~=#1\relax \lowercase{\endgroup\let#2~\let~}}
8452
% Now we get to the more powerful definitions.
8454
% \begin{macro}{\lst@CDef}
8455
% Here we unfold the first parameter \meta{1st}\marg{2nd}\marg{rest} and say
8456
% that this input string is `replaced' by \meta{save 1st}\marg{2nd}^^A
8457
% \marg{rest}---plus \meta{execute}, \meta{pre}, and \meta{post}. This main
8458
% work is done by |\lst@CDefIt|.
8460
\def\lst@CDef#1{\lst@CDef@#1}
8461
\def\lst@CDef@#1#2#3#4{\lst@CDefIt#1{#2}{#3}{#4#2#3}#4}
8465
% \begin{macro}{\lst@CDefX}
8466
% drops the input string.
8468
\def\lst@CDefX#1{\lst@CDefX@#1}
8469
\def\lst@CDefX@#1#2#3{\lst@CDefIt#1{#2}{#3}{}}
8473
% \begin{macro}{\lst@CDefIt}
8474
% is the main working procedure for the previous macros. It redefines the
8475
% sequence |#1#2#3| of characters. At least |#1| must be active; the other two
8476
% arguments might be empty, not equivalent to empty!
8478
\def\lst@CDefIt#1#2#3#4#5#6#7#8{%
8479
\ifx\@empty#2\@empty
8481
% For a single character we just execute the arguments in the correct order.
8482
% You might want to go back to section \ref{dCharacterTablesManipulated} to
8485
\def#1{#6\def\lst@next{#7#4#8}\lst@next}%
8486
\else \ifx\@empty#3\@empty
8488
% For a two character sequence we test whether \meta{pre} and \meta{post}
8493
\ifx##1#2\def\lst@next{#7#4#8}\else
8494
\def\lst@next{#5##1}\fi
8498
% We do the same for an arbitrary character sequence---except that we have to
8499
% use |\lst@IfNextCharsArg| instead of |\ifx|\ldots|\fi|.
8503
\lst@IfNextCharsArg{#2#3}{#7#4#8}%
8504
{\expandafter#5\lst@eaten}}%
8509
% \begin{macro}{\lst@CArgX}
8510
% We make |#1#2| active and call |\lst@CArg|.
8512
\def\lst@CArgX#1#2\relax{%
8513
\lst@DefActive\lst@arg{#1#2}%
8514
\expandafter\lst@CArg\lst@arg\relax}
8518
% \begin{macro}{\lst@CArg}
8519
% arranges the first two arguments for |\lst@CDef|[|X|]. We get an undefined
8520
% macro and use |\@empty\@empty\relax| as delimiter for the submacro.
8522
\def\lst@CArg#1#2\relax{%
8523
\lccode`\/=`#1\lowercase{\def\lst@temp{/}}%
8524
\lst@GetFreeMacro{lst@c\lst@temp}%
8525
\expandafter\lst@CArg@\lst@freemacro#1#2\@empty\@empty\relax}
8527
% Save meaning of \meta{1st}=|#2| in \meta{save 1st}=|#1| and call the macro
8528
% |#6| with correct arguments. From version 1.0 on, |#2|, |#3| and |#4|
8529
% (respectively empty arguments) are tied together with group braces.
8530
% This allows us to save two arguments in other definitions, for example in
8533
\def\lst@CArg@#1#2#3#4\@empty#5\relax#6{%
8535
\ifx\@empty#3\@empty
8536
\def\lst@next{#6{#2{}{}}}%
8538
\def\lst@next{#6{#2#3{#4}}}%
8544
% \begin{macro}{\lst@CArgEmpty}
8545
% `executes' an |\@empty|-delimited argument. We will use it for the delimiters.
8547
\def\lst@CArgEmpty#1\@empty{#1}
8552
% \subsection{Delimiters}
8554
% Here we start with general definitions common to all delimiters.
8556
% \begin{lstkey}{excludedelims}
8557
% controls which delimiters are not printed in \meta{whatever}style. We just
8558
% define |\lst@ifex|\meta{whatever} to be true. Such switches are set false
8559
% in the \hookname{ExcludeDelims} hook and are handled by the individual
8562
\lst@Key{excludedelims}\relax
8563
{\lsthk@ExcludeDelims \lst@NormedDef\lst@temp{#1}%
8564
\expandafter\lst@for\lst@temp\do
8565
{\expandafter\let\csname\@lst @ifex##1\endcsname\iftrue}}
8569
% \begin{macro}{\lst@DelimPrint}
8570
% And this macro might help in doing so. |#1| is |\lst@ifex|\meta{whatever}
8571
% (plus |\else|) or just |\iffalse|, and |#2| will be the delimiter. The
8572
% temporary mode change ensures that the characters can't end the current
8573
% delimiter or start a new one.
8575
\def\lst@DelimPrint#1#2{%
8578
\lst@mode\lst@nomode \lst@modetrue
8586
% \begin{macro}{\lst@DelimOpen}
8587
% We print preceding characters and the delimiter, enter the appropriate mode,
8588
% print the delimiter again, and execute |#3|. In fact, the arguments |#1| and
8589
% |#2| will ensure that the delimiter is printed only once.
8591
\def\lst@DelimOpen#1#2#3#4#5#6\@empty{%
8592
\lst@TrackNewLines \lst@XPrintToken
8593
\lst@DelimPrint#1{#6}%
8594
\lst@EnterMode{#4}{\def\lst@currstyle#5}%
8595
\lst@DelimPrint{#1#2}{#6}%
8600
% \begin{macro}{\lst@DelimClose}
8601
% is the same in reverse order.
8603
\def\lst@DelimClose#1#2#3\@empty{%
8604
\lst@TrackNewLines \lst@XPrintToken
8605
\lst@DelimPrint{#1#2}{#3}%
8607
\lst@DelimPrint{#1}{#3}}
8611
% \begin{macro}{\lst@BeginDelim}
8612
% \begin{macro}{\lst@EndDelim}
8613
% These definitions are applications of |\lst@DelimOpen| and |\lst@DelimClose|:
8614
% the delimiters have the same style as the delimited text.
8616
\def\lst@BeginDelim{\lst@DelimOpen\iffalse\else{}}
8617
\def\lst@EndDelim{\lst@DelimClose\iffalse\else}
8622
% \begin{macro}{\lst@BeginIDelim}
8623
% \begin{macro}{\lst@EndIDelim}
8624
% Another application: no delimiter is printed.
8626
\def\lst@BeginIDelim{\lst@DelimOpen\iffalse{}{}}
8627
\def\lst@EndIDelim{\lst@DelimClose\iffalse{}}
8632
% \begin{macro}{\lst@DefDelims}
8633
% This macro defines all delimiters and is therefore reset every language
8636
\lst@AddToHook{SelectCharTable}{\lst@DefDelims}
8637
\lst@AddToHookExe{SetLanguage}{\let\lst@DefDelims\@empty}
8641
% \begin{macro}{\lst@Delim}
8642
% First we set default values: no |\lst@modetrue|, cumulative style, and no
8643
% argument to |\lst@Delim|[|DM|]|@|\meta{type}.
8646
\lst@false \let\lst@cumulative\@empty \let\lst@arg\@empty
8648
% These are the correct settings for the double-star-form, so we immediately
8649
% call the submacro in this case. Otherwise we either just suppress cumulative
8650
% style, or even indicate the usage of |\lst@modetrue| with |\lst@true|.
8652
\@ifstar{\@ifstar{\lst@Delim@{#1}}%
8653
{\let\lst@cumulative\relax
8655
{\lst@true\lst@Delim@{#1}}}
8657
% The type argument is saved for later use. We check against the optional
8658
% \meta{style} argument using |#1| as default, define |\lst@delimstyle| and
8659
% look for the optional \meta{type option}, which is just saved in |\lst@arg|.
8661
\def\lst@Delim@#1[#2]{%
8662
\gdef\lst@delimtype{#2}%
8663
\@ifnextchar[\lst@Delim@sty
8664
{\lst@Delim@sty[#1]}}
8665
\def\lst@Delim@sty[#1]{%
8666
\def\lst@delimstyle{#1}%
8667
\ifx\@empty#1\@empty\else
8668
\lst@Delim@sty@ #1\@nil
8670
\@ifnextchar[\lst@Delim@option
8672
\def\lst@Delim@option[#1]{\def\lst@arg{#1}\lst@Delim@delim}
8674
% The definition of |\lst@delimstyle| depends on whether the first token is a
8675
% control sequence. Here we possibly build |\lst@|\meta{style}.
8677
\def\lst@Delim@sty@#1#2\@nil{%
8678
\if\relax\noexpand#1\else
8679
\edef\lst@delimstyle{\expandafter\noexpand
8680
\csname\@lst @\lst@delimstyle\endcsname}%
8685
% \begin{macro}{\lst@Delim@delim}
8686
% Eventually this macro is called. First we might need to delete a bunch of
8687
% delimiters. If there is no delimiter, we might delete a subclass.
8689
\def\lst@Delim@delim#1\relax#2#3#4#5#6#7#8{%
8690
\ifx #4\@empty \lst@Delim@delall{#2}\fi
8691
\ifx\@empty#1\@empty
8693
\@ifundefined{\@lst @#2DM@\lst@delimtype}%
8694
{\lst@Delim@delall{#2@\lst@delimtype}}%
8695
{\lst@Delim@delall{#2DM@\lst@delimtype}}%
8699
% If the delimiter is not empty, we convert the delimiter and append it to
8700
% |\lst@arg|. Ditto |\lst@Begin|\ldots, |\lst@End|\ldots, and the style and
8703
\expandafter\lst@Delim@args\expandafter
8704
{\lst@delimtype}{#1}{#5}#6{#7}{#8}#4%
8706
% If the type is known, we either choose dynamic or static mode and use the
8707
% contents of |\lst@arg| as arguments. All this is put into |\lst@delim|.
8709
\let\lst@delim\@empty
8710
\expandafter\lst@IfOneOf\lst@delimtype\relax#3%
8711
{\@ifundefined{\@lst @#2DM@\lst@delimtype}%
8712
{\lst@lExtend\lst@delim{\csname\@lst @#2@\lst@delimtype
8713
\expandafter\endcsname\lst@arg}}%
8714
{\lst@lExtend\lst@delim{\expandafter\lst@UseDynamicMode
8715
\csname\@lst @#2DM@\lst@delimtype
8716
\expandafter\endcsname\lst@arg}}%
8718
% Now, depending on the mode |#4| we either remove this particular delimiter or
8719
% append it to all current ones.
8722
\let\lst@temp\lst@DefDelims \let\lst@DefDelims\@empty
8723
\expandafter\lst@Delim@del\lst@temp\@empty\@nil\@nil\@nil
8725
\lst@lExtend\lst@DefDelims\lst@delim
8728
% An unknown type issues an error.
8730
{\PackageError{Listings}{Illegal type `\lst@delimtype'}%
8731
{#2 types are #3.}}%
8736
% \begin{macro}{\lst@Delim@args}
8737
% Now let's look how we add the arguments to |\lst@arg|. First we initialize
8738
% the conversion just to make all characters active. But if the first character
8739
% of the type equals |#4|, \ldots
8741
\def\lst@Delim@args#1#2#3#4#5#6#7{%
8743
\lst@false \let\lst@next\lst@XConvert
8745
% \ldots\ we remove that character from |\lst@delimtype|, and |#5| might select
8746
% a different conversion setting or macro.
8748
\@ifnextchar #4{\xdef\lst@delimtype{\expandafter\@gobble
8751
\lst@lAddTo\lst@arg{\@empty#6}%
8754
% Since we are in the `special' case above, we've also added the special
8755
% |\lst@Begin|\ldots\space and |\lst@End|\ldots\space macros to |\lst@arg|
8756
% (and |\@empty| as a brake for the delimiter). No special task must be done
8757
% if the characters are not equal.
8760
\lst@lAddTo\lst@arg{\@empty#3}%
8764
% We always transfer the arguments to the outside of the group and append the
8765
% style and mode selection if and only if we're not deleting a delimiter.
8766
% Therefor we expand the delimiter style.
8768
\global\let\@gtempa\lst@arg
8770
\let\lst@arg\@gtempa
8772
\expandafter\lst@Delim@args@\expandafter{\lst@delimstyle}%
8775
% Recall that the style is `selected' by |\def\lst@currstyle#5|, and this
8776
% `argument' |#5| is to be added now. Depending on the settings at the very
8777
% beginning, we use either |{\meta{style}}\lst@modetrue|---which selects the
8778
% style and deactivates keyword detection---, or |{}\meta{style}|---which
8779
% defines an empty style macro and executes the style for cumulative styles---,
8780
% or |{\meta{style}|---which just defines the style macro. Note that we have to
8781
% use two extra group levels below: one is discarded directly by |\lst@lAddTo|
8782
% and the other by |\lst@Delim|[|DM|]|@|\meta{type}.
8784
\def\lst@Delim@args@#1{%
8786
\lst@lAddTo\lst@arg{{{#1}\lst@modetrue}}%
8788
\ifx\lst@cumulative\@empty
8789
\lst@lAddTo\lst@arg{{{}#1}}%
8791
\lst@lAddTo\lst@arg{{{#1}}}%
8797
% \begin{macro}{\lst@Delim@del}
8798
% To delete a particular delimiter, we iterate down the list of delimiters and
8799
% compare the current item with the user supplied.
8801
\def\lst@Delim@del#1\@empty#2#3#4{%
8803
\def\lst@temp{#1\@empty#2#3}%
8804
\ifx\lst@temp\lst@delim\else
8805
\lst@lAddTo\lst@DefDelims{#1\@empty#2#3{#4}}%
8807
\expandafter\lst@Delim@del
8812
% \begin{macro}{\lst@Delim@delall}
8813
% To delete a whole class of delimiters, we first expand the control sequence
8814
% name, init some other data, and call a submacro to do the work.
8816
\def\lst@Delim@delall#1{%
8818
\edef\lst@delim{\expandafter\string\csname\@lst @#1\endcsname}%
8819
\lst@false \global\let\@gtempa\@empty
8820
\expandafter\lst@Delim@delall@\lst@DefDelims\@empty
8822
\let\lst@DefDelims\@gtempa}
8824
% We first discard a preceding |\lst@UseDynamicMode|.
8826
\def\lst@Delim@delall@#1{%
8828
\ifx #1\lst@UseDynamicMode
8830
\let\lst@next\lst@Delim@delall@do
8832
\def\lst@next{\lst@Delim@delall@do#1}%
8834
\expandafter\lst@next
8837
% Then we can check whether (the following) |\lst@|\meta{delimiter name}\ldots\
8838
% matches the delimiter class given by |\lst@delim|.
8840
\def\lst@Delim@delall@do#1#2\@empty#3#4#5{%
8841
\expandafter\lst@IfSubstring\expandafter{\lst@delim}{\string#1}%
8843
{\lst@if \lst@AddTo\@gtempa\lst@UseDynamicMode \fi
8844
\lst@AddTo\@gtempa{#1#2\@empty#3#4{#5}}}%
8845
\lst@false \lst@Delim@delall@}
8849
% \begin{macro}{\lst@DefDelimB}
8850
% Here we put the arguments together to fit |\lst@CDef|. Note that the very
8851
% last argument |\@empty| to |\lst@CDef| is a brake for |\lst@CArgEmpty|
8852
% and |\lst@DelimOpen|.
8854
\gdef\lst@DefDelimB#1#2#3#4#5#6#7#8{%
8857
{\let\lst@bnext\lst@CArgEmpty
8860
\def\lst@bnext{#6{#7}{#8}}%
8865
% After a bug report from \lsthelper{Vespe~Savikko}{2000/11/06}{bad output of
8866
% doc-strings if HTML and Python are loaded} I added braces around |#7|.
8869
% \begin{macro}{\lst@DefDelimE}
8870
% The |\ifnum #7=\lst@mode| in the 5th line ensures that the delimiters
8873
\gdef\lst@DefDelimE#1#2#3#4#5#6#7{%
8876
{\let\lst@enext\lst@CArgEmpty
8877
\ifnum #7=\lst@mode%
8887
\lst@AddToHook{Init}{\let\lst@bnext\relax \let\lst@enext\relax}
8891
% \begin{macro}{\lst@DefDelimBE}
8892
% This service macro will actually define all string delimiters.
8894
\gdef\lst@DefDelimBE#1#2#3#4#5#6#7#8#9{%
8897
{\let\lst@bnext\lst@CArgEmpty
8904
\def\lst@bnext{#6{#7}{#8}}%
8912
% \begin{macro}{\lst@delimtypes}
8913
% is the list of general delimiter types.
8915
\gdef\lst@delimtypes{s,l}
8919
% \begin{macro}{\lst@StringKey}
8920
% We just put together the arguments for |\lst@Delim|.
8922
\gdef\lst@DelimKey#1#2{%
8923
\lst@Delim{}#2\relax
8924
{Delim}\lst@delimtypes #1%
8925
{\lst@BeginDelim\lst@EndDelim}
8926
i\@empty{\lst@BeginIDelim\lst@EndIDelim}}
8930
% \begin{lstkey}{delim}
8931
% \begin{lstkey}{moredelim}
8932
% \begin{lstkey}{deletedelim}
8933
% all use |\lst@DelimKey|.
8935
\lst@Key{delim}\relax{\lst@DelimKey\@empty{#1}}
8936
\lst@Key{moredelim}\relax{\lst@DelimKey\relax{#1}}
8937
\lst@Key{deletedelim}\relax{\lst@DelimKey\@nil{#1}}
8943
% \begin{macro}{\lst@DelimDM@l}
8944
% \begin{macro}{\lst@DelimDM@s}
8945
% Nohting special here.
8947
\gdef\lst@DelimDM@l#1#2\@empty#3#4#5{%
8948
\lst@CArg #2\relax\lst@DefDelimB{}{}{}#3{#1}{#5\lst@Lmodetrue}}
8951
\gdef\lst@DelimDM@s#1#2#3\@empty#4#5#6{%
8952
\lst@CArg #2\relax\lst@DefDelimB{}{}{}#4{#1}{#6}%
8953
\lst@CArg #3\relax\lst@DefDelimE{}{}{}#5{#1}}
8962
% \subsubsection{Strings}
8964
% \begin{aspect}{strings}
8965
% Just starting a new aspect.
8968
\lst@BeginAspect{strings}
8971
% \begin{macro}{\lst@stringtypes}
8972
% is the list of \ldots\space string types?
8974
\gdef\lst@stringtypes{d,b,m,bd,db}
8978
% \begin{macro}{\lst@StringKey}
8979
% We just put together the arguments for |\lst@Delim|.
8981
\gdef\lst@StringKey#1#2{%
8982
\lst@Delim\lst@stringstyle #2\relax
8983
{String}\lst@stringtypes #1%
8984
{\lst@BeginString\lst@EndString}%
8989
% \begin{lstkey}{string}
8990
% \begin{lstkey}{morestring}
8991
% \begin{lstkey}{deletestring}
8992
% all use |\lst@StringKey|.
8994
\lst@Key{string}\relax{\lst@StringKey\@empty{#1}}
8995
\lst@Key{morestring}\relax{\lst@StringKey\relax{#1}}
8996
\lst@Key{deletestring}\relax{\lst@StringKey\@nil{#1}}
9002
% \begin{lstkey}{stringstyle}
9003
% You shouldn't need comments on the following two lines, do you?
9005
\lst@Key{stringstyle}{}{\def\lst@stringstyle{#1}}
9006
\lst@AddToHook{EmptyStyle}{\let\lst@stringstyle\@empty}
9010
% \begin{lstkey}{showstringspaces}
9011
% Thanks to \lsthelper{Knut~M\"uller}{1997/04/28}{\blankstringtrue} for
9012
% reporting problems with |\blankstringtrue| (now |showstringspaces=false|).
9013
% The problem has gone.
9015
\lst@Key{showstringspaces}t[t]{\lstKV@SetIf{#1}\lst@ifshowstringspaces}
9019
% \begin{macro}{\lst@BeginString}
9020
% Note that the tokens after |\lst@DelimOpen| are arguments! The only special
9021
% here is that we switch to `keepspaces' after starting a string, if necessary.
9022
% A bug reported by \lsthelper{Vespe~Savikko}{2000/09/27}{stringstyle used also
9023
% on previous other characters} has gone due to the use of |\lst@DelimOpen|.
9025
\gdef\lst@BeginString{%
9027
\lst@ifexstrings\else
9028
{\lst@ifshowstringspaces
9030
\let\lst@outputspace\lst@visiblespace
9034
\lst@AddToHookExe{ExcludeDelims}{\let\lst@ifexstrings\iffalse}
9038
% \begin{macro}{\lst@EndString}
9039
% Again the two tokens following |\lst@DelimClose| are arguments.
9041
\gdef\lst@EndString{\lst@DelimClose\lst@ifexstrings\else}
9045
% And now all the |\lst@StringDM@|\meta{type} definitions.
9047
% \begin{macro}{\lst@StringDM@d}
9048
% `d' means no extra work.; the first three arguments after |\lst@DefDelimBE|
9049
% are left empty. The others are used to start and end the string.
9051
\gdef\lst@StringDM@d#1#2\@empty#3#4#5{%
9052
\lst@CArg #2\relax\lst@DefDelimBE{}{}{}#3{#1}{#5}#4}
9056
% \begin{macro}{\lst@StringDM@b}
9057
% The |\lst@ifletter|\ldots|\fi| has been inserted after bug reports by
9058
% \lsthelper{Daniel~Gerigk}{2001/10/25}{improper strings in C++} and
9059
% \lsthelper{Peter~Bartke}{2001/11/01}{improper strings in C++}. If the last
9060
% other character is a backslash (4th line), we gobble the `end string' token
9063
\gdef\lst@StringDM@b#1#2\@empty#3#4#5{%
9064
\let\lst@ifbstring\iftrue
9065
\lst@CArg #2\relax\lst@DefDelimBE
9066
{\lst@ifletter \lst@Output \lst@letterfalse \fi}%
9067
{\ifx\lst@lastother\lstum@backslash
9068
\expandafter\@gobblethree
9072
\global\let\lst@ifbstring\iffalse % init
9074
% \lsthelper{Heiko~Heil}{2002/02/08}{string '\\' does not finish after the
9075
% delimiter} reported problems with double backslashes. So:
9077
\lst@AddToHook{SelectCharTable}{%
9079
\lst@CArgX \\\\\relax \lst@CDefX{}%
9080
{\lst@ProcessOther\lstum@backslash
9081
\lst@ProcessOther\lstum@backslash}%
9087
% \begin{macro}{\lst@StringDM@bd}
9088
% \begin{macro}{\lst@StringDM@db}
9089
% are just the same and the same as |\lst@StringDM@b|.
9091
\global\let\lst@StringDM@bd\lst@StringDM@b
9092
\global\let\lst@StringDM@db\lst@StringDM@bd
9094
% \end{macro}\end{macro}
9096
% \begin{macro}{\lst@StringDM@m}
9097
% `M'atlabed is designed for programming languages where string delimiters are
9098
% are also used for other purposes, like Matlab or Ada. Here we enter string
9099
% mode only if the last character has not been a letter and has not been a
9100
% right parenthesis or right bracket. The test for the latter one has been
9101
% added after bug report from \lsthelper{Christian~Kindinger}{2002/03/??}
9102
% {]' starts a string in Matlab}.
9104
\gdef\lst@StringDM@m#1#2\@empty#3#4#5{%
9105
\lst@CArg #2\relax\lst@DefDelimBE{}{}%
9106
{\let\lst@next\@gobblethree
9108
\ifx\lst@lastother)\else \ifx\lst@lastother]\else
9109
\let\lst@next\@empty
9111
\lst@next}#3{#1}{#5}#4}
9122
% \subsubsection{Comments}
9124
% \begin{aspect}{comments}
9125
% That's what we are working on.
9128
\lst@BeginAspect{comments}
9131
% \begin{macro}{\lst@commenttypes}
9132
% Via \keyname{comment} available comment types: \textbf line, \textbf fixed
9133
% column, \textbf single, and \textbf nested and all with
9134
% preceding \textbf i for invisible comments.
9136
\gdef\lst@commenttypes{l,f,s,n}
9140
% \begin{macro}{\lst@CommentKey}
9141
% We just put together the arguments for |\lst@Delim|.
9143
\gdef\lst@CommentKey#1#2{%
9144
\lst@Delim\lst@commentstyle #2\relax
9145
{Comment}\lst@commenttypes #1%
9146
{\lst@BeginComment\lst@EndComment}%
9147
i\@empty{\lst@BeginInvisible\lst@EndInvisible}}
9151
% \begin{lstkey}{comment}
9152
% \begin{lstkey}{morecomment}
9153
% \begin{lstkey}{deletecomment}
9154
% The keys are easy since defined in terms of |\lst@CommentKey|.
9156
\lst@Key{comment}\relax{\lst@CommentKey\@empty{#1}}
9157
\lst@Key{morecomment}\relax{\lst@CommentKey\relax{#1}}
9158
\lst@Key{deletecomment}\relax{\lst@CommentKey\@nil{#1}}
9164
% \begin{lstkey}{commentstyle}
9165
% Any hints necessary?
9167
\lst@Key{commentstyle}{}{\def\lst@commentstyle{#1}}
9168
\lst@AddToHook{EmptyStyle}{\let\lst@commentstyle\itshape}
9172
% \begin{macro}{\lst@BeginComment}
9173
% \begin{macro}{\lst@EndComment}
9174
% Once more the three tokens following |\lst@DelimOpen| are arguments.
9176
\gdef\lst@BeginComment{%
9178
\lst@ifexcomments\else
9179
\lsthk@AfterBeginComment}
9183
\gdef\lst@EndComment{\lst@DelimClose\lst@ifexcomments\else}
9186
\lst@AddToHook{AfterBeginComment}{}
9187
\lst@AddToHookExe{ExcludeDelims}{\let\lst@ifexcomments\iffalse}
9192
% \begin{macro}{\lst@BeginInvisible}
9193
% \begin{macro}{\lst@EndInvisible}
9194
% Print preceding characters and begin dropping the output.
9196
\gdef\lst@BeginInvisible#1#2#3\@empty{%
9197
\lst@TrackNewLines \lst@XPrintToken
9198
\lst@BeginDropOutput{#1}}
9200
% Don't print the delimiter and end dropping the output.
9202
\gdef\lst@EndInvisible#1\@empty{\lst@EndDropOutput}
9207
% Now we provide all |\lst@Comment|[|DM|]|@|\meta{type} macros.
9209
% \begin{macro}{\lst@Comment@l}
9210
% is easy---thanks to |\lst@CArg| and |\lst@DefDelimB|. Note that the
9211
% `end comment' argument |#4| is not used here.
9213
\gdef\lst@CommentDM@l#1#2\@empty#3#4#5{%
9214
\lst@CArg #2\relax\lst@DefDelimB{}{}{}#3{#1}{#5\lst@Lmodetrue}}
9218
% \begin{macro}{\lst@CommentDM@f}
9219
% is slightly more work. First we provide the number of preceding columns.
9221
\gdef\lst@CommentDM@f#1{%
9222
\@ifnextchar[{\lst@Comment@@f{#1}}%
9223
{\lst@Comment@@f{#1}[0]}}
9225
% We define the comment in the same way as above, but we enter comment mode
9226
% if and only if the character is in column |#2| (counting from zero).
9228
\gdef\lst@Comment@@f#1[#2]#3\@empty#4#5#6{%
9229
\lst@CArg #3\relax\lst@DefDelimB{}{}%
9231
\ifnum #2=\@tempcnta\else
9232
\expandafter\@gobblethree
9234
#4{#1}{#6\lst@Lmodetrue}}
9238
% \begin{macro}{\lst@CommentDM@s}
9239
% Nothing special here.
9241
\gdef\lst@CommentDM@s#1#2#3\@empty#4#5#6{%
9242
\lst@CArg #2\relax\lst@DefDelimB{}{}{}#4{#1}{#6}%
9243
\lst@CArg #3\relax\lst@DefDelimE{}{}{}#5{#1}}
9247
% \begin{macro}{\lst@CommentDM@n}
9248
% We either give an error message or define the nested comment.
9250
\gdef\lst@CommentDM@n#1#2#3\@empty#4#5#6{%
9251
\ifx\@empty#3\@empty\else
9252
\def\@tempa{#2}\def\@tempb{#3}%
9254
\PackageError{Listings}{Identical delimiters}%
9255
{These delimiters make no sense with nested comments.}%
9257
\lst@CArg #2\relax\lst@DefDelimB
9260
% Note that the following |\@gobble| eats an |\else| from |\lst@DefDelimB|.
9262
{\ifnum\lst@mode=#1\relax \expandafter\@gobble \fi}%
9264
\lst@CArg #3\relax\lst@DefDelimE{}{}{}#5{#1}%
9277
% \subsubsection{PODs}
9279
% \begin{aspect}{pod}
9280
% PODs are defined as a separate aspect.
9283
\lst@BeginAspect{pod}
9286
% \begin{lstkey}{printpod}
9287
% \begin{lstkey}{podcomment}
9288
% We begin with the user keys, which I introduced after communication with
9289
% \lsthelper{Michael~Piotrowski}{1997/11/11}{printpod}.
9291
\lst@Key{printpod}{false}[t]{\lstKV@SetIf{#1}\lst@ifprintpod}
9292
\lst@Key{podcomment}{false}[t]{\lstKV@SetIf{#1}\lst@ifpodcomment}
9293
\lst@AddToHookExe{SetLanguage}{\let\lst@ifpodcomment\iffalse}
9298
% \begin{macro}{\lst@PODmode}
9299
% is the static mode for PODs.
9301
\lst@NewMode\lst@PODmode
9305
% We adjust some characters if the user has selected |podcomment=true|.
9307
\lst@AddToHook{SelectCharTable}
9309
\lst@CArgX =\relax\lst@DefDelimB{}{}%
9311
% The following code is executed if we've found an equality sign and haven't
9312
% entered a mode (in fact if mode changes are allowed): We `begin drop output'
9313
% and gobble the usual begin of comment sequence (via |\@gobblethree|) if PODs
9314
% aren't be printed. Moreover we gobble it if the current column number is not
9315
% zero---|\@tempcnta| is valued below.
9317
{\ifnum\@tempcnta=\z@
9318
\lst@ifprintpod\else
9319
\def\lst@bnext{\lst@BeginDropOutput\lst@PODmode}%
9320
\expandafter\expandafter\expandafter\@gobblethree
9323
\expandafter\@gobblethree
9325
\lst@BeginComment\lst@PODmode\lst@commentstyle
9327
% If we come to |=|, we calculate the current column number (zero based).
9329
\lst@CArgX =cut\^^M\relax\lst@DefDelimE
9332
% If there is additionally |cut|+EOL and if we are in |\lst@PODmode| but not in
9333
% column one, we must gobble the `end comment sequence'.
9335
{\ifnum\@tempcnta=\z@\else
9336
\expandafter\@gobblethree
9339
\lst@EndComment\lst@PODmode
9350
% \subsection{Replacing input}
9358
% \begin{macro}{\lst@ReplaceInput}
9359
% is defined in terms of |\lst@CArgX| and |\lst@CDefX|.
9361
\def\lst@ReplaceInput#1{\lst@CArgX #1\relax\lst@CDefX{}{}}
9365
% \begin{lstkey}{literate}
9366
% \lsthelper{Jason~Alexander}{1999/03/10}{literate programming} asked for
9367
% something like that. The key simply saves the argument.
9369
\lst@Key{literate}{}{\def\lst@literate{#1}}
9370
\lst@AddToHook{SelectCharTable}
9371
{\ifx\lst@literate\@empty\else
9372
\expandafter\lst@Literate\lst@literate{}\relax\z@
9375
% Internally we make use of the `replace input' feature.
9376
% We print the preceding text, assign token and length, and output it.
9378
\def\lst@Literate#1#2#3{%
9379
\ifx\relax#2\@empty\else
9380
\lst@ReplaceInput{#1}%
9381
{\lst@XPrintToken \lst@letterfalse
9382
\lst@token{#2}\lst@length#3\relax
9384
\expandafter\lst@Literate
9389
% \begin{macro}{\lst@BeginDropInput}
9390
% We deactivate all `process' macros. |\lst@modetrue| does this for all
9391
% up-coming string delimiters, comments, and so on.
9393
\def\lst@BeginDropInput#1{%
9396
\let\lst@ifdropinput\iftrue
9397
\let\lst@ProcessLetter\@gobble
9398
\let\lst@ProcessDigit\@gobble
9399
\let\lst@ProcessOther\@gobble
9400
\let\lst@ProcessSpace\@empty
9401
\let\lst@ProcessTabulator\@empty
9402
\let\lst@ProcessFormFeed\@empty}}
9403
\let\lst@ifdropinput\iffalse % init
9414
% \subsection{Escaping to \LaTeX}
9416
% \begin{aspect}{escape}
9417
% We now define the \ldots\ damned \ldots\ the aspect has escaped!
9420
\lst@BeginAspect{escape}
9423
% \begin{lstkey}{texcl}
9424
% Communication with \lsthelper{J\"orn~Wilms}{1997/07/07}{\TeX\ comments} is
9425
% responsible for this key. The definition and the first hooks are easy.
9427
\lst@Key{texcl}{false}[t]{\lstKV@SetIf{#1}\lst@iftexcl}
9428
\lst@AddToHook{TextStyle}{\let\lst@iftexcl\iffalse}
9430
{\ifnum\lst@mode=\lst@TeXLmode
9431
\expandafter\lst@escapeend
9432
\expandafter\lst@LeaveAllModes
9433
\expandafter\lst@ReenterModes
9436
% If the user wants \TeX\ comment lines, we print the comment separator and
9437
% interrupt the normal processing.
9439
\lst@AddToHook{AfterBeginComment}
9440
{\lst@iftexcl \lst@ifLmode \lst@ifdropinput\else
9442
\lst@LeaveMode \lst@InterruptModes
9443
\lst@EnterMode{\lst@TeXLmode}{\lst@modetrue\lst@commentstyle}%
9444
\expandafter\expandafter\expandafter\lst@escapebegin
9448
\lst@NewMode\lst@TeXLmode
9452
% \begin{macro}{\lst@ActiveCDefX}
9453
% Same as |\lst@CDefX| but we both make |#1| active and assign a new catcode.
9455
\gdef\lst@ActiveCDefX#1{\lst@ActiveCDefX@#1}
9456
\gdef\lst@ActiveCDefX@#1#2#3{
9457
\catcode`#1\active\lccode`\~=`#1%
9458
\lowercase{\lst@CDefIt~}{#2}{#3}{}}
9462
% \begin{macro}{\lst@Escape}
9463
% gets four arguments all in all. The first and second are the `begin' and
9464
% `end' escape sequences, the third is executed when the escape starts, and the
9465
% fourth right before ending it. We use the same mechanism as for \TeX\ comment
9466
% lines. The |\lst@ifdropinput| test has been added after a bug report by
9467
% \lsthelper{Michael~Weber}{2002/03/26}{escape on lines < firstline corrupts
9470
\gdef\lst@Escape#1#2#3#4{%
9471
\lst@CArgX #1\relax\lst@CDefX
9473
{\lst@ifdropinput\else
9474
\lst@TrackNewLines\lst@OutputLostSpace \lst@XPrintToken
9476
\lst@EnterMode{\lst@TeXmode}{\lst@modetrue}%
9478
% Now we must define the character sequence to end the escape.
9481
\lst@CArg #2\relax\lst@ActiveCDefX
9483
{\lst@escapeend #4\lst@LeaveAllModes\lst@ReenterModes}%
9484
{\lst@MProcessListing}%
9486
\lst@CArg #2\relax\lst@ActiveCDefX
9488
{\lst@escapeend #4\lst@LeaveAllModes\lst@ReenterModes
9489
\lst@whitespacefalse}%
9496
% The |\lst@whitespacefalse| above was added after a bug report from
9497
% \lsthelper{Martin~Steffen}{2001/04/07}{mathescape drops subsequent space}.
9499
\lst@NewMode\lst@TeXmode
9503
% \begin{lstkey}{escapebegin}
9504
% \begin{lstkey}{escapeend}
9505
% The keys simply store the arguments.
9507
\lst@Key{escapebegin}{}{\def\lst@escapebegin{#1}}
9508
\lst@Key{escapeend}{}{\def\lst@escapeend{#1}}
9513
% \begin{lstkey}{escapechar}
9514
% The introduction of this key is due to a communication with \lsthelper
9515
% {Rui~Oliveira}{1998/06/05}{escape characters}. We define |\lst@DefEsc| and
9516
% execute it after selecting the standard character table.
9518
\lst@Key{escapechar}{}
9519
{\ifx\@empty#1\@empty
9520
\let\lst@DefEsc\relax
9522
\def\lst@DefEsc{\lst@Escape{#1}{#1}{}{}}%
9524
\lst@AddToHook{TextStyle}{\let\lst@DefEsc\@empty}
9525
\lst@AddToHook{SelectCharTable}{\lst@DefEsc}
9529
% \begin{lstkey}{escapeinside}
9532
\lst@Key{escapeinside}{}{\lstKV@TwoArg{#1}%
9533
{\let\lst@DefEsc\@empty
9534
\ifx\@empty##1@empty\else \ifx\@empty##2\@empty\else
9535
\def\lst@DefEsc{\lst@Escape{##1}{##2}{}{}}%
9540
% \begin{lstkey}{mathescape}
9541
% This is a switch and checked after character table selection. We use
9542
% |\lst@Escape| with math shifts as arguments, but all inside |\hbox|
9543
% to determine the correct width.
9545
\lst@Key{mathescape}{false}[t]{\lstKV@SetIf{#1}\lst@ifmathescape}
9546
\lst@AddToHook{SelectCharTable}
9547
{\lst@ifmathescape \lst@Escape{\$}{\$}%
9548
{\setbox\@tempboxa=\hbox\bgroup$}%
9549
{$\egroup \lst@CalcLostSpaceAndOutput}\fi}
9560
% \section{Keywords}
9563
% \subsection{Making tests}\label{iMakingTests}
9565
% \begin{aspect}{keywords}
9566
% We begin a new and very important aspect.
9567
% First of all we need to initialize some variables in order to work around a
9568
% bug reported by \lsthelper{Beat~Birkhofer}{2001/06/15}{savemem doesn't work}.
9571
\lst@BeginAspect{keywords}
9574
\global\let\lst@ifsensitive\iftrue % init
9575
\global\let\lst@ifsensitivedefed\iffalse % init % \global
9577
% All keyword tests take the following three arguments.
9579
% \item \meta{prefix}
9580
% \item |\lst@|\meta{name}|@list| (a list of macros which contain the keywords)
9581
% \item |\lst@g|\meta{name}|@sty| (global style macro)
9583
% We begin with non memory-saving tests.
9590
% \begin{macro}{\lst@KeywordTest}
9591
% Fast keyword tests take advance of the |\lst@UM| construction in section
9592
% \ref{iCharacterTables}. If |\lst@UM| is empty, all `use macro' characters
9593
% expand to their original characters. Since |\lst|\meta{prefix}|@|\meta{keyword}
9594
% will be equivalent to the appropriate style, we only need to build the control
9595
% sequence |\lst|\meta{prefix}|@|\meta{current token} and assign it to
9598
\gdef\lst@KeywordTest#1#2#3{%
9599
\begingroup \let\lst@UM\@empty
9600
\global\expandafter\let\expandafter\@gtempa
9601
\csname\@lst#1@\the\lst@token\endcsname
9603
\ifx\@gtempa\relax\else
9604
\let\lst@thestyle\@gtempa
9607
% Note that we need neither |#2| nor |#3| here.
9610
% \begin{macro}{\lst@KEYWORDTEST}
9611
% Case insensitive tests make the current character string upper case and give
9612
% it to a submacro similar to |\lst@KeywordTest|.
9614
\gdef\lst@KEYWORDTEST{%
9615
\uppercase\expandafter{\expandafter
9616
\lst@KEYWORDTEST@\the\lst@token}\relax}
9617
\gdef\lst@KEYWORDTEST@#1\relax#2#3#4{%
9618
\begingroup \let\lst@UM\@empty
9619
\global\expandafter\let\expandafter\@gtempa
9620
\csname\@lst#2@#1\endcsname
9622
\ifx\@gtempa\relax\else
9623
\let\lst@thestyle\@gtempa
9628
% \begin{macro}{\lst@WorkingTest}
9629
% \begin{macro}{\lst@WORKINGTEST}
9630
% The same except that |\lst|\meta{prefix}|@|\meta{current token} might be
9631
% a working procedure; it is executed.
9633
\gdef\lst@WorkingTest#1#2#3{%
9634
\begingroup \let\lst@UM\@empty
9635
\global\expandafter\let\expandafter\@gtempa
9636
\csname\@lst#1@\the\lst@token\endcsname
9641
\gdef\lst@WORKINGTEST{%
9642
\uppercase\expandafter{\expandafter
9643
\lst@WORKINGTEST@\the\lst@token}\relax}
9644
\gdef\lst@WORKINGTEST@#1\relax#2#3#4{%
9645
\begingroup \let\lst@UM\@empty
9646
\global\expandafter\let\expandafter\@gtempa
9647
\csname\@lst#2@#1\endcsname
9654
% \begin{macro}{\lst@DefineKeywords}
9655
% Eventually we need macros which define and undefine
9656
% |\lst|\meta{prefix}|@|\meta{keyword}. Here the arguments are
9658
% \item \meta{prefix}
9659
% \item |\lst@|\meta{name} (a keyword list)
9660
% \item |\lst@g|\meta{name}|@sty|
9662
% We make the keywords upper case if necessary, \ldots
9664
\gdef\lst@DefineKeywords#1#2#3{%
9666
\def\lst@next{\lst@for#2}%
9668
\def\lst@next{\uppercase\expandafter{\expandafter\lst@for#2}}%
9672
% \ldots\space iterate through the list, and make
9673
% |\lst|\meta{prefix}|@|\meta{keyword} (if undefined) equivalent to
9674
% |\lst@g|\meta{name}|@sty| which is possibly a working macro.
9676
{\expandafter\ifx\csname\@lst#1@##1\endcsname\relax
9677
\global\expandafter\let\csname\@lst#1@##1\endcsname#3%
9682
% \begin{macro}{\lst@UndefineKeywords}
9683
% We make the keywords upper case if necessary, \ldots
9685
\gdef\lst@UndefineKeywords#1#2#3{%
9686
\lst@ifsensitivedefed
9687
\def\lst@next{\lst@for#2}%
9689
\def\lst@next{\uppercase\expandafter{\expandafter\lst@for#2}}%
9693
% \ldots\space iterate through the list, and `undefine'
9694
% |\lst|\meta{prefix}|@|\meta{keyword} if it's equivalent to
9695
% |\lst@g|\meta{name}|@sty|.
9697
{\expandafter\ifx\csname\@lst#1@##1\endcsname#3%
9698
\global\expandafter\let\csname\@lst#1@##1\endcsname\relax
9701
% Thanks to \lsthelper{Magnus~Lewis-Smith}{1999/09/08}{keywords do not
9702
% undefine} a wrong |#2| in the replacement text could be changed to |#3|.
9706
% And now memory-saving tests.
9713
% \begin{macro}{\lst@IfOneOutOf}
9714
% The definition here is similar to |\lst@IfOneOf|, but its second argument
9715
% is a |\lst@|\meta{name}|@list|. Therefore we test a list of macros here.
9717
\gdef\lst@IfOneOutOf#1\relax#2{%
9718
\def\lst@temp##1,#1,##2##3\relax{%
9719
\ifx\@empty##2\else \expandafter\lst@IOOOfirst \fi}%
9720
\def\lst@next{\lst@IfOneOutOf@#1\relax}%
9721
\expandafter\lst@next#2\relax\relax}
9723
% We either execute the \meta{else} part or make the next test.
9725
\gdef\lst@IfOneOutOf@#1\relax#2#3{%
9727
\expandafter\@secondoftwo
9729
\expandafter\lst@temp\expandafter,#2,#1,\@empty\relax
9730
\expandafter\lst@next
9732
\ifx\iffalse\else\fi
9733
\gdef\lst@IOOOfirst#1\relax#2#3{\fi#2}
9735
% The line |\ifx\iffalse\else\fi| balances the |\fi| inside |\lst@IOOOfirst|.
9738
% \begin{macro}{\lst@IFONEOUTOF}
9739
% As in |\lst@IFONEOF| we need two |\uppercase|s here.
9741
\gdef\lst@IFONEOUTOF#1\relax#2{%
9742
\uppercase{\def\lst@temp##1,#1},##2##3\relax{%
9743
\ifx\@empty##2\else \expandafter\lst@IOOOfirst \fi}%
9744
\def\lst@next{\lst@IFONEOUTOF@#1\relax}%
9745
\expandafter\lst@next#2\relax}
9746
\gdef\lst@IFONEOUTOF@#1\relax#2#3{%
9748
\expandafter\@secondoftwo
9751
{\expandafter\lst@temp\expandafter,#2,#1,\@empty\relax}%
9752
\expandafter\lst@next
9755
% Note: The third last line uses the fact that keyword lists (not the list
9756
% of keyword lists) are already made upper case if keywords are insensitive.
9759
% \begin{macro}{\lst@KWTest}
9760
% is a helper for the keyword and working identifier tests. We expand the
9761
% token and call |\lst@IfOneOf|. The tests below will append appropriate
9762
% \meta{then} and \meta{else} arguments.
9765
\begingroup \let\lst@UM\@empty
9766
\expandafter\xdef\expandafter\@gtempa\expandafter{\the\lst@token}%
9768
\expandafter\lst@IfOneOutOf\@gtempa\relax}
9772
% \begin{macro}{\lst@KeywordTest}
9773
% \begin{macro}{\lst@KEYWORDTEST}
9774
% are fairly easy now. Note that we don't need |#1|=\meta{prefix} here.
9776
\gdef\lst@KeywordTest#1#2#3{\lst@KWTest #2{\let\lst@thestyle#3}{}}
9777
\global\let\lst@KEYWORDTEST\lst@KeywordTest
9779
% For case insensitive tests we assign the insensitive version to
9780
% |\lst@IfOneOutOf|. Thus we need no extra definition here.
9784
% \begin{macro}{\lst@WorkingTest}
9785
% \begin{macro}{\lst@WORKINGTEST}
9788
\gdef\lst@WorkingTest#1#2#3{\lst@KWTest #2#3{}}
9789
\global\let\lst@WORKINGTEST\lst@WorkingTest
9800
% \begin{lstkey}{sensitive}
9801
% is a switch, preset \texttt{true} every language selection.
9803
\lst@Key{sensitive}\relax[t]{\lstKV@SetIf{#1}\lst@ifsensitive}
9804
\lst@AddToHook{SetLanguage}{\let\lst@ifsensitive\iftrue}
9806
% We select case insensitive definitions if necessary.
9808
\lst@AddToHook{Init}
9809
{\lst@ifsensitive\else
9810
\let\lst@KeywordTest\lst@KEYWORDTEST
9811
\let\lst@WorkingTest\lst@WORKINGTEST
9812
\let\lst@IfOneOutOf\lst@IFONEOUTOF
9817
% \begin{macro}{\lst@MakeMacroUppercase}
9818
% makes the contents of |#1| (if defined) upper case.
9820
\gdef\lst@MakeMacroUppercase#1{%
9821
\ifx\@undefined#1\else \uppercase\expandafter
9822
{\expandafter\def\expandafter#1\expandafter{#1}}%
9828
% \subsection{Installing tests}
9830
% \begin{macro}{\lst@InstallTest}
9833
% \item \meta{prefix}
9834
% \item |\lst@|\meta{name}|@list|
9835
% \item |\lst@|\meta{name}
9836
% \item |\lst@g|\meta{name}|@list|
9837
% \item |\lst@g|\meta{name}
9838
% \item |\lst@g|\meta{name}|@sty|
9839
% \item \alternative{w,s} (working procedure or style)
9840
% \item \alternative{d,o} (\hookname{DetectKeywords} or \hookname{Output} hook)
9842
% We just insert hook material. The tests will be inserted on demand.
9844
\gdef\lst@InstallTest#1#2#3#4#5#6#7#8{%
9845
\lst@AddToHook{TrackKeywords}{\lst@TrackKeywords{#1}#2#4#6#7#8}%
9846
\lst@AddToHook{PostTrackKeywords}{\lst@PostTrackKeywords#2#3#4#5}}
9849
\lst@AddToHook{Init}{\lsthk@TrackKeywords\lsthk@PostTrackKeywords}
9850
\lst@AddToHook{TrackKeywords}{}% init
9851
\lst@AddToHook{PostTrackKeywords}{}% init
9853
% We have to detect the keywords somewhere.
9855
\lst@AddToHook{Output}{\lst@ifkeywords \lsthk@DetectKeywords \fi}
9856
\lst@AddToHook{DetectKeywords}{}% init
9857
\lst@AddToHook{ModeTrue}{\let\lst@ifkeywords\iffalse}
9858
\lst@AddToHook{Init}{\let\lst@ifkeywords\iftrue}
9862
% \begin{macro}{\lst@InstallTestNow}
9863
% actually inserts a test.
9865
% \item \meta{prefix}
9866
% \item |\lst@|\meta{name}|@list|
9867
% \item |\lst@g|\meta{name}|@sty|
9868
% \item \alternative{w,s} (working procedure or style)
9869
% \item \alternative{d,o} (\hookname{DetectKeywords} or \hookname{Output} hook)
9871
% For example, |#4#5|=|sd| will add
9872
% |\lst@KeywordTest{|\meta{prefix}|}|
9873
% |\lst@|\meta{name}|@list| |\lst@g|\meta{name}|@sty|
9874
% to the \hookname{DetectKeywords} hook.
9876
\gdef\lst@InstallTestNow#1#2#3#4#5{%
9877
\@ifundefined{\string#2#1}%
9878
{\global\@namedef{\string#2#1}{}%
9880
\noexpand\lst@AddToHook{\ifx#5dDetectKeywords\else Output\fi}%
9881
{\ifx #4w\noexpand\lst@WorkingTest
9882
\else\noexpand\lst@KeywordTest \fi
9883
{#1}\noexpand#2\noexpand#3}}%
9885
% If we are advised to save memory, we insert a test for each \meta{name}.
9886
% Otherwise we install the tests according to \meta{prefix}.
9891
\@ifundefined{\@lst#1@if@ins}%
9892
{\@tempa \global\@namedef{\@lst#1@if@ins}{}}%
9899
% \begin{macro}{\lst@TrackKeywords}
9900
% Now it gets a bit tricky. We expand the class list |\lst@|\meta{name}|@list|
9901
% behind |\lst@TK@{|\meta{prefix}|}||\lst@g|\meta{name}|@sty| and use two
9902
% |\relax|es as terminators. This will define the keywords of all the classes
9903
% as keywords of type \meta{prefix}. More details come soon.
9905
\gdef\lst@TrackKeywords#1#2#3#4#5#6{%
9907
\def\lst@arg{{#1}#4}%
9908
\expandafter\expandafter\expandafter\lst@TK@
9909
\expandafter\lst@arg#2\relax\relax
9911
% And nearly the same to undefine all out-dated keywords, which is necessary
9912
% only if we don't save memory.
9915
\def\lst@arg{{#1}#4#2}%
9916
\expandafter\expandafter\expandafter\lst@TK@@
9917
\expandafter\lst@arg#3\relax\relax
9920
% Finally we install the keyword test if keywords changed, in particular if
9921
% they are defined the first time. Note that |\lst@InstallTestNow| inserts a
9924
\lst@if \lst@InstallTestNow{#1}#2#4#5#6\fi}
9926
% Back to the current keywords. Global macros |\lst@g|\meta{id} contain
9927
% globally defined keywords, whereas |\lst@|\meta{id} conatin the true
9928
% keywords. This way we can keep track of the keywords: If keywords or
9929
% \keyname{sensitive} changed, we undefine the old (= globally defined)
9930
% keywords and define the true ones. The arguments of |\lst@TK@| are
9932
% \item \meta{prefix}
9933
% \item |\lst@g|\meta{name}|@sty|
9934
% \item |\lst@|\meta{id}
9935
% \item |\lst@g|\meta{id}
9938
\gdef\lst@TK@#1#2#3#4{%
9939
\ifx\lst@ifsensitive\lst@ifsensitivedefed
9943
\lst@UndefineKeywords{#1}#4#2%
9944
\lst@DefineKeywords{#1}#3#2%
9951
\lst@UndefineKeywords{#1}#4#2%
9952
\lst@DefineKeywords{#1}#3#2%
9957
% We don't define and undefine keywords if we try to save memory. But we
9958
% possibly need to make them upper case, which again wastes some memory.
9960
\lst@ifsavemem \ifx#3\relax\else
9961
\lst@ifsensitive\else \lst@MakeMacroUppercase#3\fi
9964
% Reaching the end of the class list, we end the loop.
9967
\expandafter\@gobblethree
9971
% Here now we undefine the out-dated keywords. While not reaching the end of
9972
% the global list, we look whether the keyword class |#4#5| is still in use or
9973
% needs to be undefined. Our arguments are
9975
% \item \meta{prefix}
9976
% \item |\lst@g|\meta{name}|@sty|
9977
% \item |\lst@|\meta{name}|@list|
9978
% \item |\lst@|\meta{id}
9979
% \item |\lst@g|\meta{id}
9982
\gdef\lst@TK@@#1#2#3#4#5{%
9984
\expandafter\@gobblefour
9986
\lst@IfSubstring{#4#5}#3{}{\lst@UndefineKeywords{#1}#5#2}%
9990
% Keywords are up-to-date after \hookname{InitVars}.
9992
\lst@AddToHook{InitVars}
9993
{\global\let\lst@ifsensitivedefed\lst@ifsensitive}
9997
% \begin{macro}{\lst@PostTrackKeywords}
9998
% After updating all the keywords, the global keywords and the global list
9999
% become equivalent to the local ones.
10000
% \begin{macrocode}
10001
\gdef\lst@PostTrackKeywords#1#2#3#4{%
10002
\lst@ifsavemem\else
10010
% \subsection{Classes and families}
10012
% \begin{lstkey}{classoffset}
10013
% just stores the argument in a macro.
10014
% \begin{macrocode}
10015
\lst@Key{classoffset}\z@{\def\lst@classoffset{#1}}
10019
% \begin{macro}{\lst@InstallFamily}
10020
% Recall the parameters
10021
% \begin{macroargs}
10022
% \item \meta{prefix}
10023
% \item \meta{name}
10024
% \item \meta{style name}
10025
% \item \meta{style init}
10026
% \item \meta{default style name}
10027
% \item \meta{working procedure}
10028
% \item \alternative{l,o} (language or other key)
10029
% \item \alternative{d,o} (\hookname{DetectKeywords} or \hookname{Output} hook)
10031
% First we define the keys and the style key \meta{style name} if and only if
10032
% the name is not empty.
10033
% \begin{macrocode}
10034
\gdef\lst@InstallFamily#1#2#3#4#5{%
10035
\lst@Key{#2}\relax{\lst@UseFamily{#2}##1\relax\lst@MakeKeywords}%
10036
\lst@Key{more#2}\relax
10037
{\lst@UseFamily{#2}##1\relax\lst@MakeMoreKeywords}%
10038
\lst@Key{delete#2}\relax
10039
{\lst@UseFamily{#2}##1\relax\lst@DeleteKeywords}%
10040
\ifx\@empty#3\@empty\else
10041
\lst@Key{#3}{#4}{\lstKV@OptArg[\@ne]{##1}%
10042
{\@tempcnta\lst@classoffset \advance\@tempcnta####1\relax
10043
\@namedef{lst@#3\ifnum\@tempcnta=\@ne\else \the\@tempcnta
10046
\expandafter\lst@InstallFamily@
10047
\csname\@lst @#2@data\expandafter\endcsname
10048
\csname\@lst @#5\endcsname {#1}{#2}{#3}}
10050
% Now we check whether \meta{working procedure} is empty. Accordingly we use
10051
% \texttt working procedure or \texttt style in the `data' definition.
10052
% The working procedure is defined right here if necessary.
10053
% \begin{macrocode}
10054
\gdef\lst@InstallFamily@#1#2#3#4#5#6#7#8{%
10055
\gdef#1{{#3}{#4}{#5}#2#7}%
10056
\long\def\lst@temp##1{#6}%
10057
\ifx\lst@temp\@gobble
10061
\global\@namedef{lst@g#4@wp}##1{#6}%
10064
% Nothing else is defined here, all the rest is done on demand.
10067
% \begin{macro}{\lst@UseFamily}
10068
% We look for the optional class number, provide this member, \ldots
10069
% \begin{macrocode}
10070
\gdef\lst@UseFamily#1{%
10071
\def\lst@family{#1}%
10072
\@ifnextchar[\lst@UseFamily@{\lst@UseFamily@[\@ne]}}
10073
\gdef\lst@UseFamily@[#1]{%
10074
\@tempcnta\lst@classoffset \advance\@tempcnta#1\relax
10075
\lst@ProvideFamily\lst@family
10077
% \ldots\space and build the control sequences \ldots
10078
% \begin{macrocode}
10080
{\lst@family\ifnum\@tempcnta=\@ne\else \the\@tempcnta \fi}}
10081
\gdef\lst@UseFamily@a#1{%
10082
\expandafter\lst@UseFamily@b
10083
\csname\@lst @#1@list\expandafter\endcsname
10084
\csname\@lst @#1\expandafter\endcsname
10085
\csname\@lst @#1@also\expandafter\endcsname
10086
\csname\@lst @g#1\endcsname}
10088
% \ldots\space required for |\lst@MakeKeywords| and |#6|.
10089
% \begin{macrocode}
10090
\gdef\lst@UseFamily@b#1#2#3#4#5\relax#6{\lstKV@XOptArg[]{#5}#6#1#2#3#4}
10094
% \begin{macro}{\lst@ProvideFamily}
10095
% provides the member `|\the\@tempcnta|' of the family |#1|. We do nothing if
10096
% the member already exists. Otherwise we expand the data macro defined above.
10097
% Note that we don't use the counter if it equals one.
10098
% \begin{macrocode}
10099
\gdef\lst@ProvideFamily#1{%
10100
\@ifundefined{lst@#1\ifnum\@tempcnta=\@ne\else \the\@tempcnta \fi}%
10101
{\expandafter\expandafter\expandafter\lst@ProvideFamily@
10102
\csname\@lst @#1@data\endcsname
10103
{\ifnum\@tempcnta=\@ne\else \the\@tempcnta \fi}}%
10106
% Now we have the following arguments
10107
% \begin{macroargs}
10108
% \item \meta{prefix}
10109
% \item \meta{name}
10110
% \item \meta{style name}
10111
% \item \meta{default style name}
10112
% \item \alternative{l,o} (language or other key)
10113
% \item \alternative{w,s} (working procedure or style)
10114
% \item \alternative{d,o} (\hookname{DetectKeywords} or \hookname{Output} hook)
10115
% \item |\ifnum\@tempcnta=\@ne\else \the\@tempcnta \fi|
10117
% We define |\lst@g|\meta{name}\meta{number}|@sty| to call either
10118
% |\lst@g|\meta{name}|@wp| with the number as argument or
10119
% |\lst@|\meta{style name}\meta{number} where the number belongs to the control
10121
% \begin{macrocode}
10122
\gdef\lst@ProvideFamily@#1#2#3#4#5#6#7#8{%
10123
\expandafter\xdef\csname\@lst @g#2#8@sty\endcsname
10125
\expandafter\noexpand\csname\@lst @g#2@wp\endcsname{#8}%
10127
\expandafter\noexpand\csname\@lst @#3#8\endcsname
10130
% We ensure the existence of the style macro. This is done in the
10131
% \hookname{Init} hook by assigning the default style if necessary.
10132
% \begin{macrocode}
10133
\ifx\@empty#3\@empty\else
10134
\edef\lst@temp{\noexpand\lst@AddToHook{Init}{%
10135
\noexpand\lst@ProvideStyle\expandafter\noexpand
10136
\csname\@lst @#3#8\endcsname\noexpand#4}}%
10140
% We call a submacro to do the rest. It requires some control sequences.
10141
% \begin{macrocode}
10142
\expandafter\lst@ProvideFamily@@
10143
\csname\@lst @#2#8@list\expandafter\endcsname
10144
\csname\@lst @#2#8\expandafter\endcsname
10145
\csname\@lst @#2#8@also\expandafter\endcsname
10146
\csname\@lst @g#2#8@list\expandafter\endcsname
10147
\csname\@lst @g#2#8\expandafter\endcsname
10148
\csname\@lst @g#2#8@sty\expandafter\endcsname
10151
% Now we have (except that \meta{number} is possibly always missing)
10152
% \begin{macroargs}
10153
% \item |\lst@|\meta{name}\meta{number}|@list|
10154
% \item |\lst@|\meta{name}\meta{number}
10155
% \item |\lst@|\meta{name}\meta{number}|@also|
10156
% \item |\lst@g|\meta{name}\meta{number}|@list|
10157
% \item |\lst@g|\meta{name}\meta{number}
10158
% \item |\lst@g|\meta{name}\meta{number}|@sty|
10159
% \item \meta{prefix}
10160
% \item \alternative{l,o} (language or other key)
10161
% \item \alternative{w,s} (working procedure or style)
10162
% \item \alternative{d,o} (\hookname{DetectKeywords} or \hookname{Output} hook)
10164
% Note that |#9| and `|#10|' are read by |\lst@InstallTest|. We initialize all
10165
% required `variables' (at \hookname{SetLanguage}) and install the test (which
10166
% definition is in fact also delayed).
10167
% \begin{macrocode}
10168
\gdef\lst@ProvideFamily@@#1#2#3#4#5#6#7#8{%
10169
\gdef#1{#2#5}\global\let#2\@empty \global\let#3\@empty % init
10170
\gdef#4{#2#5}\global\let#5\@empty % init
10172
\lst@AddToHook{SetLanguage}{\def#1{#2#5}\let#2\@empty}%
10174
\lst@InstallTest{#7}#1#2#4#5#6}
10178
% \begin{macro}{\lst@InstallKeywords}
10179
% Now we take advance of the optional argument construction above. Thus, we
10180
% just insert |[\@ne]| as \meta{number} in the definitions of the keys.
10181
% \begin{macrocode}
10182
\gdef\lst@InstallKeywords#1#2#3#4#5{%
10184
{\lst@UseFamily{#2}[\@ne]##1\relax\lst@MakeKeywords}%
10185
\lst@Key{more#2}\relax
10186
{\lst@UseFamily{#2}[\@ne]##1\relax\lst@MakeMoreKeywords}%
10187
\lst@Key{delete#2}\relax
10188
{\lst@UseFamily{#2}[\@ne]##1\relax\lst@DeleteKeywords}%
10189
\ifx\@empty#3\@empty\else
10190
\lst@Key{#3}{#4}{\@namedef{lst@#3}{##1}}%
10192
\expandafter\lst@InstallFamily@
10193
\csname\@lst @#2@data\expandafter\endcsname
10194
\csname\@lst @#5\endcsname {#1}{#2}{#3}}
10198
% \begin{macro}{\lst@ProvideStyle}
10199
% If the style macro |#1| is not defined, it becomes equivalent to |#2|.
10200
% \begin{macrocode}
10201
\gdef\lst@ProvideStyle#1#2{%
10202
\ifx#1\@undefined \let#1#2%
10203
\else\ifx#1\relax \let#1#2\fi\fi}
10207
% Finally we define |\lst@MakeKeywords|, \ldots, |\lst@DeleteKeywords|.
10208
% We begin with two helper.
10210
% \begin{macro}{\lst@BuildClassList}
10211
% After |#1| follows a comma separated list of keyword classes terminated by
10212
% |,\relax,|, e.g.~|keywords2,emph1,\relax,|. For each \meta{item} in this
10213
% list we \emph{append} the two macros |\lst@|\meta{item}|\lst@g|\meta{item}
10215
% \begin{macrocode}
10216
\gdef\lst@BuildClassList#1#2,{%
10217
\ifx\relax#2\@empty\else
10218
\ifx\@empty#2\@empty\else
10219
\lst@lExtend#1{\csname\@lst @#2\expandafter\endcsname
10220
\csname\@lst @g#2\endcsname}%
10222
\expandafter\lst@BuildClassList\expandafter#1
10227
% \begin{macro}{\lst@DeleteClassesIn}
10228
% deletes pairs of tokens, namely the arguments |#2#3| to the submacro.
10229
% \begin{macrocode}
10230
\gdef\lst@DeleteClassesIn#1#2{%
10231
\expandafter\lst@DCI@\expandafter#1#2\relax\relax}
10232
\gdef\lst@DCI@#1#2#3{%
10234
\expandafter\@gobbletwo
10237
% If we haven't reached the end of the class list, we define a temporary macro
10238
% which removes all appearances.
10239
% \begin{macrocode}
10240
\def\lst@temp##1#2#3##2{%
10241
\lst@lAddTo#1{##1}%
10242
\ifx ##2\relax\else
10243
\expandafter\lst@temp
10245
\let\@tempa#1\let#1\@empty
10246
\expandafter\lst@temp\@tempa#2#3\relax
10252
% \begin{macro}{\lst@MakeKeywords}
10253
% We empty some macros and make use of |\lst@MakeMoreKeywords|.
10254
% Note that this and the next two definitions have the following arguments:
10255
% \begin{macroargs}
10256
% \item class list (in brackets)
10257
% \item keyword list
10258
% \item |\lst@|\meta{name}|@list|
10259
% \item |\lst@|\meta{name}
10260
% \item |\lst@|\meta{name}|@also|
10261
% \item |\lst@g|\meta{name}
10263
% \begin{macrocode}
10264
\gdef\lst@MakeKeywords[#1]#2#3#4#5#6{%
10265
\def#3{#4#6}\let#4\@empty \let#5\@empty
10266
\lst@MakeMoreKeywords[#1]{#2}#3#4#5#6}
10270
% \begin{macro}{\lst@MakeMoreKeywords}
10271
% We append classes and keywords.
10272
% \begin{macrocode}
10273
\gdef\lst@MakeMoreKeywords[#1]#2#3#4#5#6{%
10274
\lst@BuildClassList#3#1,\relax,%
10275
\lst@DefOther\lst@temp{,#2}\lst@lExtend#4\lst@temp}
10279
% \begin{macro}{\lst@DeleteKeywords}
10280
% We convert the keyword arguments via |\lst@MakeKeywords| and remove the
10281
% classes and keywords.
10282
% \begin{macrocode}
10283
\gdef\lst@DeleteKeywords[#1]#2#3#4#5#6{%
10284
\lst@MakeKeywords[#1]{#2}\@tempa\@tempb#5#6%
10285
\lst@DeleteClassesIn#3\@tempa
10286
\lst@DeleteKeysIn#4\@tempb}
10291
% \subsection{Main families and classes}
10294
% \paragraph{Keywords}
10296
% \begin{lstkey}{keywords}
10297
% Defining the keyword family gets very, very easy.
10298
% \begin{macrocode}
10299
\lst@InstallFamily k{keywords}{keywordstyle}\bfseries{keywordstyle}{}ld
10303
% \begin{lstkey}{ndkeywords}
10304
% Second order keywords use the same trick as |\lst@InstallKeywords|.
10305
% \begin{macrocode}
10306
\lst@Key{ndkeywords}\relax
10307
{\lst@UseFamily{keywords}[\tw@]#1\relax\lst@MakeKeywords}%
10308
\lst@Key{morendkeywords}\relax
10309
{\lst@UseFamily{keywords}[\tw@]#1\relax\lst@MakeMoreKeywords}%
10310
\lst@Key{deletendkeywords}\relax
10311
{\lst@UseFamily{keywords}[\tw@]#1\relax\lst@DeleteKeywords}%
10312
\lst@Key{ndkeywordstyle}\relax{\@namedef{lst@keywordstyle2}{#1}}%
10314
% \lsthelper{Dr.~Peter~Leibner}{1999/11/05}{undefined \lst@UseKeywords,
10315
% Illegal parameter number (##1)} reported two bugs: |\lst@UseKeywords| and
10316
% |##1| became |\lst@UseFamily| and |#1|.
10319
% \begin{lstkey}{keywordsprefix}
10320
% is implemented experimentally. The one and only prefix indicates its
10321
% presence by making |\lst@prefixkeyword| empty. We can catch this information
10322
% in the \keyname{Output} hook.
10323
% \begin{macrocode}
10324
\lst@Key{keywordsprefix}\relax{\lst@DefActive\lst@keywordsprefix{#1}}
10325
\global\let\lst@keywordsprefix\@empty
10326
\lst@AddToHook{SelectCharTable}
10327
{\ifx\lst@keywordsprefix\@empty\else
10328
\expandafter\lst@CArg\lst@keywordsprefix\relax
10330
{\lst@ifletter\else
10331
\global\let\lst@prefixkeyword\@empty
10335
\lst@AddToHook{Init}{\global\let\lst@prefixkeyword\relax}
10336
\lst@AddToHook{Output}
10337
{\ifx\lst@prefixkeyword\@empty
10338
\let\lst@thestyle\lst@gkeywords@sty
10339
\global\let\lst@prefixkeyword\relax
10344
% \begin{lstkey}{otherkeywords}
10345
% Thanks to \lsthelper{Bradford~Chamberlain}{2001/07/07}{otherkeywords={@,@^}
10346
% does not work} we now iterate down the list of `other keywords' and make each
10347
% active---instead of making the whole argument active. We append the active
10348
% token sequence to |\lst@otherkeywords| to define each `other' keyword.
10349
% \begin{macrocode}
10350
\lst@Key{otherkeywords}{}{%
10351
\let\lst@otherkeywords\@empty
10353
\lst@MakeActive{##1}%
10354
\lst@lExtend\lst@otherkeywords{%
10355
\expandafter\lst@CArg\lst@temp\relax\lst@CDef
10356
{}\lst@PrintOtherKeyword\@empty}}}
10357
\lst@AddToHook{SelectCharTable}{\lst@otherkeywords}
10359
% |\lst@PrintOtherkeyword| has been changed to |\lst@PrintOtherKeyword| after a
10360
% bug report by \lsthelper{Peter~Bartke}{2001/11/06}{undefined control sequence
10361
% \lst@PrintOtherkeyword}.
10364
% \begin{macro}{\lst@PrintOtherKeyword}
10365
% print preceding characters, prepare the output and typeset the argument in
10367
% \begin{macrocode}
10368
\gdef\lst@PrintOtherKeyword#1\@empty{%
10371
\lst@modetrue \lsthk@TextStyle
10372
\let\lst@ProcessDigit\lst@ProcessLetter
10373
\let\lst@ProcessOther\lst@ProcessLetter
10375
\lst@gkeywords@sty{#1\lst@XPrintToken}%
10379
% Which part of \hookname{TextStyle} hook is required?
10383
% \begin{macrocode}
10390
% \paragraph{The emphasize family}
10392
% \begin{aspect}{emph}
10393
% is just one macro call here.
10394
% \begin{macrocode}
10396
\lst@BeginAspect[keywords]{emph}
10397
\lst@InstallFamily e{emph}{emphstyle}{}{emphstyle}{}od
10404
% \paragraph{\TeX\ control sequences}
10406
% \begin{aspect}{tex}
10407
% Here we check the last `other' processed token.
10408
% \begin{macrocode}
10410
\lst@BeginAspect[keywords]{tex}
10412
% \begin{macrocode}
10413
\lst@InstallKeywords{cs}{texcs}{texcsstyle}\relax{keywordstyle}
10414
{\ifx\lst@lastother\lstum@backslash
10415
\let\lst@thestyle\lst@texcsstyle
10419
% \begin{macrocode}
10426
% \paragraph{Compiler directives}
10428
% \begin{aspect}{directives}
10429
% \begin{lstkey}{directives}
10430
% First some usual stuff.
10431
% \begin{macrocode}
10433
\lst@BeginAspect[keywords]{directives}
10435
% \begin{macrocode}
10436
\lst@NewMode\lst@CDmode
10437
\lst@AddToHook{EOL}{\ifnum\lst@mode=\lst@CDmode \lst@LeaveMode \fi}
10438
\lst@InstallKeywords{d}{directives}{directivestyle}\relax{keywordstyle}
10439
{\ifnum\lst@mode=\lst@CDmode
10440
\let\lst@thestyle\lst@directivestyle
10444
% If the user has defined directives, we redefine the character |#|.
10445
% \begin{macrocode}
10446
\lst@AddToHook{SelectCharTable}
10447
{\ifx\lst@directives\@empty\else
10448
\lst@DefSaveDef{`\#}\lsts@CCD
10452
% We enter `directive mode' (without setting |\lst@ifmode| true) only in the
10454
% \begin{macrocode}
10455
\ifnum\@tempcnta=\z@
10456
\lst@EnterMode{\lst@CDmode}{}%
10459
\ifnum\lst@mode=\lst@CDmode
10461
% We print |#| in directive style if and only if we are in the first column.
10462
% \begin{macrocode}
10463
\ifnum\@tempcnta=\z@
10467
% Is this |\lst@XPrintToken| necessary? First column should imply that the
10468
% current character string is empty and that there are no delayed characters.
10470
% \begin{macrocode}
10471
{\let\lst@currstyle\lst@directivestyle
10472
\lsts@CCD\lst@PrintToken}%
10479
% We introduce a new string type (thanks to \lsthelper{R.~Isernhagen}
10480
% {1999/11/12}{float isn't keyword in #include <float>}), which \ldots
10481
% \begin{macrocode}
10482
\lst@AddTo\lst@stringtypes{,directive}
10483
\gdef\lst@StringDM@directive#1#2#3\@empty{%
10484
\lst@CArg #2\relax\lst@CDef
10487
% \ldots\space is active only in |\lst@CDmode|:
10488
% \begin{macrocode}
10489
{\let\lst@bnext\lst@CArgEmpty
10490
\ifnum\lst@mode=\lst@CDmode
10491
\def\lst@bnext{\lst@BeginString{#1}}%
10495
\lst@CArg #3\relax\lst@CDef
10497
{\let\lst@enext\lst@CArgEmpty
10498
\ifnum #1=\lst@mode
10499
\let\lst@bnext\lst@EndString
10506
% \begin{macrocode}
10513
% \subsection{Restricted keywords}
10515
% \begin{aspect}{html}
10516
% Support HTML and others.
10517
% \begin{macrocode}
10519
\lst@BeginAspect[keywords]{html}
10522
% \begin{lstkey}{keywordsinside}
10523
% Allocate a new mode and start the key.
10524
% \begin{macrocode}
10525
\lst@NewMode\lst@insidemode
10526
\lst@Key{keywordsinside}{}{\lstKV@TwoArg{#1}
10527
{\let\lst@DefInside\@empty
10528
\ifx\@empty##1\@empty\else \ifx\@empty##2\@empty\else
10529
\def\lst@DefInside{%
10531
% The redefinitions of the characters enter respectively leave the mode and
10532
% execute the old meanings.
10533
% \begin{macrocode}
10534
\lst@DefSaveDef{`##1}\lsts@insideb
10535
{\lst@ifmode\else \ifnum\lst@mode=\lst@insidemode\else
10537
\lst@EnterMode\lst@insidemode{}%
10540
\lst@DefSaveDef{`##2}\lsts@insidee
10541
{\ifnum\lst@mode=\lst@insidemode
10542
\lsts@insidee \lst@XPrintToken\lst@LeaveMode
10544
\expandafter\lsts@insidee
10548
% The redefinition is done via \hookname{SelectCharTable}. It is reset in
10549
% \hookname{SetLanguage} since a bug report from \lsthelper{Richard~Hoefter}
10550
% {2000/11/03}{no keyword detection in case of language=HTML,language=Java}.
10551
% \begin{macrocode}
10552
\lst@AddToHook{SelectCharTable}{\lst@DefInside}
10553
\lst@AddToHook{SetLanguage}{\let\lst@DefInside\@empty}
10555
% We reset |\lst@thestyle| if necessary.
10556
% \begin{macrocode}
10557
\lst@AddToHook{Output}
10558
{\ifx\lst@DefInside\@empty\else \ifx\lst@thestyle\lst@gkeywords@sty
10559
\ifnum\lst@mode=\lst@insidemode\else
10560
\let\lst@thestyle\@empty
10566
% \begin{lstkey}{usekeywordsinside}
10567
% Here we set |\lst@thestyle| to keyword style if necessary.
10568
% \begin{macrocode}
10569
\lst@Key{usekeywordsinside}t[t]{\lstKV@SetIf{#1}\lst@ifusekeysinside}
10570
\lst@AddToHook{Output}
10571
{\ifnum\lst@mode=\lst@insidemode \lst@ifusekeysinside\else
10572
\let\lst@thestyle\lst@gkeywords@sty
10577
% \begin{macro}{\lst@BeginCDATA}
10578
% This macro is used by the XML language definition.
10579
% \begin{macrocode}
10580
\gdef\lst@BeginCDATA#1\@empty{%
10581
\lst@TrackNewLines \lst@PrintToken
10582
\lst@EnterMode\lst@GPmode{}\let\lst@ifmode\iffalse
10583
\lst@mode\lst@insidemode #1\lst@mode\lst@GPmode\relax\lst@modetrue}
10587
% \begin{macrocode}
10594
% \subsection{Keyword comments}
10596
% \begin{aspect}{keywordcomments}
10597
% includes both comment types and is possibly split into this and |dkcs|.
10598
% \begin{macrocode}
10600
\lst@BeginAspect[keywords,comments]{keywordcomments}
10603
% \begin{macro}{\lst@BeginKC}
10604
% \begin{macro}{\lst@BeginKCS}
10605
% Starting a keyword comment is easy, but \ldots
10606
% \begin{macrocode}
10607
\lst@NewMode\lst@KCmode \lst@NewMode\lst@KCSmode
10608
\gdef\lst@BeginKC{%
10610
\lst@BeginComment\lst@KCmode\lst@commentstyle\@empty}
10611
\gdef\lst@BeginKCS{%
10613
\lst@BeginComment\lst@KCSmode\lst@commentstyle\@empty}
10615
% \ldots\space we must ensure that the comment starts after printing the
10616
% comment delimiter since it could be a keyword. We assign |\lst@BeginKC|[|S|]
10617
% to |\lst@KCpost|, which is executed and reset in \hookname{PostOutput}.
10618
% \begin{macrocode}
10619
\lst@AddToHook{PostOutput}{\lst@KCpost \global\let\lst@KCpost\@empty}
10620
\global\let\lst@KCpost\@empty % init
10625
% \begin{macro}{\lst@EndKC}
10626
% leaves the comment mode before the (temporaryly saved) comment delimiter is
10628
% \begin{macrocode}
10629
\gdef\lst@EndKC{\lst@SaveToken \lst@LeaveMode \lst@RestoreToken}
10633
% \begin{lstkey}{keywordcomment}
10634
% The delimiters must be identical here, thus we use |\lst@KCmatch|. Note the
10635
% last argument |o| to |\lst@InstallKeywords|: The working test is installed
10636
% in the \hookname{Output} hook and not in \hookname{DetectKeywords}.
10637
% Otherwise we couldn't detect the ending delimiter since keyword detection is
10638
% done if and only if mode changes are allowed.
10639
% \begin{macrocode}
10640
\lst@InstallKeywords{kc}{keywordcomment}{}\relax{}
10641
{\ifnum\lst@mode=\lst@KCmode
10642
\edef\lst@temp{\the\lst@token}%
10643
\ifx\lst@temp\lst@KCmatch
10648
\xdef\lst@KCmatch{\the\lst@token}%
10649
\global\let\lst@KCpost\lst@BeginKC
10656
% \begin{lstkey}{keywordcommentsemicolon}
10657
% The key simply stores the keywords.
10658
% \begin{macrocode}
10659
\lst@Key{keywordcommentsemicolon}{}{\lstKV@ThreeArg{#1}%
10660
{\def\lst@KCAkeywordsB{##1}%
10661
\def\lst@KCAkeywordsE{##2}%
10662
\def\lst@KCBkeywordsB{##3}%
10663
\def\lst@KCkeywords{##1##2##3}}}
10665
% We define an appropriate semicolon if this keyword comment type is defined.
10666
% Appropriate means that we leave any keyword comment mode if active.
10667
% \lsthelper{Oldrich~Jedlicka}{2001/12/12}{keywordcomment(semicolon) fails}
10668
% reported a bug and provided the fix, the two |\@empty|s.
10669
% \begin{macrocode}
10670
\lst@AddToHook{SelectCharTable}
10671
{\ifx\lst@KCkeywords\@empty\else
10672
\lst@DefSaveDef{`\;}\lsts@EKC
10674
\ifnum\lst@mode=\lst@KCmode \lst@EndComment\@empty \else
10675
\ifnum\lst@mode=\lst@KCSmode \lst@EndComment\@empty
10680
% The `working identifier' macros enter respectively leave comment mode.
10681
% \begin{macrocode}
10682
\gdef\lst@KCAWorkB{%
10683
\lst@ifmode\else \global\let\lst@KCpost\lst@BeginKC \fi}
10684
\gdef\lst@KCBWorkB{%
10685
\lst@ifmode\else \global\let\lst@KCpost\lst@BeginKCS \fi}
10686
\gdef\lst@KCAWorkE{\ifnum\lst@mode=\lst@KCmode \lst@EndKC \fi}
10688
% Now we install the tests and initialize the given macros.
10689
% \begin{macrocode}
10690
\lst@ProvideFamily@@
10691
\lst@KCAkeywordsB@list\lst@KCAkeywordsB \lst@KC@also
10692
\lst@gKCAkeywordsB@list\lst@gKCAkeywordsB \lst@KCAWorkB
10693
{kcb}owo % prefix, other key, working procedure, Output hook
10694
\lst@ProvideFamily@@
10695
\lst@KCAkeywordsE@list\lst@KCAkeywordsE \lst@KC@also
10696
\lst@gKCAkeywordsE@list\lst@gKCAkeywordsE \lst@KCAWorkE
10698
\lst@ProvideFamily@@
10699
\lst@KCBkeywordsB@list\lst@KCBkeywordsB \lst@KC@also
10700
\lst@gKCBkeywordsB@list\lst@gKCBkeywordsB \lst@KCBWorkB
10705
% \begin{macrocode}
10712
% \subsection{Export of identifiers}
10714
% \begin{aspect}{index}
10715
% \begin{macro}{\lstindexmacro}
10716
% One more `keyword' class.
10717
% \begin{macrocode}
10719
\lst@BeginAspect[keywords]{index}
10720
\lst@InstallFamily w{index}{indexstyle}\lstindexmacro{indexstyle}
10721
{\csname\@lst @indexstyle#1\expandafter\endcsname
10722
\expandafter{\the\lst@token}}
10724
\lst@UserCommand\lstindexmacro#1{\index{{\ttfamily#1}}}
10731
% \begin{aspect}{procnames}
10732
% \begin{lstkey}{procnamestyle}
10733
% \begin{lstkey}{procnamekeys}
10734
% \begin{lstkey}{indexprocnames}
10735
% The `idea' here is the usage of a global |\lst@ifprocname|, indicating a
10736
% preceding `procedure keyword'. All the other is known stuff.
10737
% \begin{macrocode}
10739
\lst@BeginAspect[keywords]{procnames}
10740
\gdef\lst@procnametrue{\global\let\lst@ifprocname\iftrue}
10741
\gdef\lst@procnamefalse{\global\let\lst@ifprocname\iffalse}
10742
\lst@AddToHook{Init}{\lst@procnamefalse}
10743
\lst@AddToHook{DetectKeywords}
10745
\let\lst@thestyle\lst@procnamestyle
10746
\lst@ifindexproc \csname\@lst @gindex@sty\endcsname \fi
10750
% \begin{macrocode}
10751
\lst@Key{procnamestyle}{}{\def\lst@procnamestyle{#1}}
10752
\lst@Key{indexprocnames}{false}[t]{\lstKV@SetIf{#1}\lst@ifindexproc}
10753
\lst@AddToHook{Init}{\lst@ifindexproc \lst@indexproc \fi}
10754
\gdef\lst@indexproc{%
10755
\@ifundefined{lst@indexstyle1}%
10756
{\@namedef{lst@indexstyle1}##1{}}%
10759
% The default definition of |\lst@indexstyle| above has been moved outside the
10760
% hook after a bug report from \lsthelper{Ulrich~G.~Wortmann}{2002/01/22}
10761
% {procnames doesn't work}.
10762
% \begin{macrocode}
10763
\lst@InstallKeywords w{procnamekeys}{}\relax{}
10764
{\global\let\lst@PNpost\lst@procnametrue}
10766
\lst@AddToHook{PostOutput}{\lst@PNpost\global\let\lst@PNpost\@empty}
10767
\global\let\lst@PNpost\@empty % init
10777
% \section{More aspects and keys}
10779
% \begin{lstkey}{basicstyle}
10780
% \begin{lstkey}{inputencoding}
10781
% There is no better place to define these keys, I think.
10782
% \begin{macrocode}
10784
\lst@Key{basicstyle}\relax{\def\lst@basicstyle{#1}}
10785
\lst@Key{inputencoding}\relax{\def\lst@inputenc{#1}}
10786
\lst@AddToHook{Init}
10788
\ifx\lst@inputenc\@empty\else
10789
\@ifundefined{inputencoding}{}%
10790
{\inputencoding\lst@inputenc}%
10792
\lst@AddToHookExe{EmptyStyle}
10793
{\let\lst@basicstyle\@empty
10794
\let\lst@inputenc\@empty}
10797
% Michael Niedermair asked for a key like \keyname{inputencoding}.
10802
% \subsection{Styles and languages}
10804
% \begin{aspect}{style}
10805
% We begin with style definition and selection.
10806
% \begin{macrocode}
10808
\lst@BeginAspect{style}
10811
% \begin{macro}{\lststylefiles}
10812
% This macro is defined if and only if it's undefined yet.
10813
% \begin{macrocode}
10814
\@ifundefined{lststylefiles}
10815
{\lst@UserCommand\lststylefiles{lststy0.sty}}{}
10819
% \begin{macro}{\lstdefinestyle}
10820
% \begin{macro}{\lst@definestyle}
10821
% \begin{macro}{\lst@DefStyle}
10822
% are defined in terms of |\lst@DefStyle|, which is defined via
10823
% |\lst@DefDriver|.
10824
% \begin{macrocode}
10825
\lst@UserCommand\lstdefinestyle{\lst@DefStyle\iftrue}
10826
\lst@UserCommand\lst@definestyle{\lst@DefStyle\iffalse}
10827
\gdef\lst@DefStyle{\lst@DefDriver{style}{sty}\lstset}
10829
% The `empty' style calls the initial empty hook \hookname{EmptyStyle}.
10830
% \begin{macrocode}
10831
\global\@namedef{lststy@$}{\lsthk@EmptyStyle}
10832
\lst@AddToHook{EmptyStyle}{}% init
10838
% \begin{lstkey}{style}
10839
% is an application of |\lst@LAS|. We just specify the hook and an empty
10840
% argument as `pre' and `post' code.
10841
% \begin{macrocode}
10842
\lst@Key{style}\relax{%
10843
\lst@LAS{style}{sty}{[]{#1}}\lst@NoAlias\lststylefiles
10847
% \begin{macrocode}
10848
\lst@AddToHook{SetStyle}{}% init
10852
% \begin{macrocode}
10858
% \begin{aspect}{language}
10859
% Now we deal with commands used in defining and selecting programming
10860
% languages, in particular with aliases.
10861
% \begin{macrocode}
10863
\lst@BeginAspect{language}
10866
% \begin{macro}{\lstlanguagefiles}
10867
% This macro is defined if and only if it's undefined yet.
10868
% \begin{macrocode}
10869
\@ifundefined{lstdriverfiles}
10870
{\lst@UserCommand\lstlanguagefiles{lstlang0.sty}}{}
10874
% \begin{macro}{\lstdefinelanguage}
10875
% \begin{macro}{\lst@definelanguage}
10876
% \begin{macro}{\lst@DefLang}
10877
% are defined in terms of |\lst@DefLang|, which is defined via
10878
% |\lst@DefDriver|.
10879
% \begin{macrocode}
10880
\lst@UserCommand\lstdefinelanguage{\lst@DefLang\iftrue}
10881
\lst@UserCommand\lst@definelanguage{\lst@DefLang\iffalse}
10882
\gdef\lst@DefLang{\lst@DefDriver{language}{lang}\lstset}
10884
% Now we can provide the `empty' language.
10885
% \begin{macrocode}
10886
\lstdefinelanguage{}{}
10892
% \begin{lstkey}{language}
10893
% \begin{lstkey}{alsolanguage}
10894
% is mainly an application of |\lst@LAS|.
10895
% \begin{macrocode}
10896
\lst@Key{language}\relax{\lstKV@OptArg[]{#1}%
10897
{\lst@LAS{language}{lang}{[##1]{##2}}\lst@FindAlias\lstlanguagefiles
10899
{\lst@FindAlias[##1]{##2}%
10900
\let\lst@language\lst@malias
10901
\let\lst@dialect\lst@oalias}}}
10903
% Ditto, we simply don't execute |\lsthk@SetLanguage|.
10904
% \begin{macrocode}
10905
\lst@Key{alsolanguage}\relax{\lstKV@OptArg[]{#1}%
10906
{\lst@LAS{language}{lang}{[##1]{##2}}\lst@FindAlias\lstlanguagefiles
10908
{\lst@FindAlias[##1]{##2}%
10909
\let\lst@language\lst@malias
10910
\let\lst@dialect\lst@oalias}}}
10912
% \begin{macrocode}
10913
\lst@AddToHook{SetLanguage}{}% init
10918
% \begin{macro}{\lstalias}
10919
% Now we concentrate on aliases and default dialects.
10920
% |\lsta@|\meta{language}|$|\meta{dialect} and |\lsta@|\meta{language} contain
10921
% the aliases of a particular dialect respectively a complete language.
10922
% We'll use a |$|-character to separate a language name from its dialect.
10923
% \begin{macrocode}
10924
\lst@UserCommand\lstalias{\@ifnextchar[\lstalias@\lstalias@@}
10925
\gdef\lstalias@[#1]#2[#3]#4{\lst@NormedNameDef{lsta@#2$#1}{#4$#3}}
10926
\gdef\lstalias@@#1#2{\lst@NormedNameDef{lsta@#1}{#2}}
10930
% \begin{lstkey}{defaultdialect}
10931
% We simply store the dialect.
10932
% \begin{macrocode}
10933
\lst@Key{defaultdialect}\relax
10934
{\lstKV@OptArg[]{#1}{\lst@NormedNameDef{lstdd@##2}{##1}}}
10938
% \begin{macro}{\lst@FindAlias}
10939
% Now we have to find a language. First we test for a complete language alias,
10940
% then we set the default dialect if necessary.
10941
% \begin{macrocode}
10942
\gdef\lst@FindAlias[#1]#2{%
10943
\lst@NormedDef\lst@oalias{#1}%
10944
\lst@NormedDef\lst@malias{#2}%
10945
\@ifundefined{lsta@\lst@malias}{}%
10946
{\edef\lst@malias{\csname\@lst a@\lst@malias\endcsname}}%
10948
% \begin{macrocode}
10949
\ifx\@empty\lst@oalias \@ifundefined{lstdd@\lst@malias}{}%
10950
{\edef\lst@oalias{\csname\@lst dd@\lst@malias\endcsname}}%
10953
% Now we are ready for an alias of a single dialect.
10954
% \begin{macrocode}
10955
\edef\lst@temp{\lst@malias $\lst@oalias}%
10956
\@ifundefined{lsta@\lst@temp}{}%
10957
{\edef\lst@temp{\csname\@lst a@\lst@temp\endcsname}}%
10959
% Finally we again set the default dialect---for the case of a dialect alias.
10960
% \begin{macrocode}
10961
\expandafter\lst@FindAlias@\lst@temp $}
10962
\gdef\lst@FindAlias@#1$#2${%
10963
\def\lst@malias{#1}\def\lst@oalias{#2}%
10964
\ifx\@empty\lst@oalias \@ifundefined{lstdd@\lst@malias}{}%
10965
{\edef\lst@oalias{\csname\@lst dd@\lst@malias\endcsname}}%
10970
% \begin{macro}{\lst@RequireLanguages}
10971
% This definition will be equivalent to |\lstloadlanguages|. We requested the
10972
% given list of languages and load additionally required aspects.
10973
% \begin{macrocode}
10974
\gdef\lst@RequireLanguages#1{%
10975
\lst@Require{language}{lang}{#1}\lst@FindAlias\lstlanguagefiles
10976
\ifx\lst@loadaspects\@empty\else
10977
\lst@RequireAspects\lst@loadaspects
10982
% \begin{macro}{\lstloadlanguages}
10983
% is the same as |\lst@RequireLanguages|.
10984
% \begin{macrocode}
10985
\global\let\lstloadlanguages\lst@RequireLanguages
10989
% \begin{macrocode}
10996
% \subsection{Format definitions*}
10998
% \begin{aspect}{formats}
10999
% \begin{macrocode}
11001
\lst@BeginAspect{formats}
11004
% \begin{macro}{\lstformatfiles}
11005
% This macro is defined if and only if it's undefined yet.
11006
% \begin{macrocode}
11007
\@ifundefined{lstformatfiles}
11008
{\lst@UserCommand\lstformatfiles{lstfmt0.sty}}{}
11012
% \begin{macro}{\lstdefineformat}
11013
% \begin{macro}{\lst@defineformat}
11014
% \begin{macro}{\lst@DefFormat}
11015
% are defined in terms of |\lst@DefFormat|, which is defined via
11016
% |\lst@DefDriver|.
11017
% \begin{macrocode}
11018
\lst@UserCommand\lstdefineformat{\lst@DefFormat\iftrue}
11019
\lst@UserCommand\lst@defineformat{\lst@DefFormat\iffalse}
11020
\gdef\lst@DefFormat{\lst@DefDriver{format}{fmt}\lst@UseFormat}
11022
% We provide the `empty' format.
11023
% \begin{macrocode}
11024
\lstdefineformat{}{}
11030
% \begin{lstkey}{format}
11031
% is an application of |\lst@LAS|. We just specify the hook as `pre' and an
11032
% empty argument as `post' code.
11033
% \begin{macrocode}
11034
\lst@Key{format}\relax{%
11035
\lst@LAS{format}{fmt}{[]{#1}}\lst@NoAlias\lstformatfiles
11039
% \begin{macrocode}
11040
\lst@AddToHook{SetFormat}{\let\lst@fmtformat\@empty}% init
11045
% \paragraph{Helpers}
11046
% Our goal is to define the yet unkown |\lst@UseFormat|. This definition
11047
% will parse the user supplied format. We start with some general macros.
11049
% \begin{macro}{\lst@fmtSplit}
11050
% splits the content of the macro |#1| at |#2| in the preceding characters
11051
% |\lst@fmta| and the following ones |\lst@fmtb|. |\lst@if| is false if and
11052
% only if |#1| doesn't contain |#2|.
11053
% \begin{macrocode}
11054
\gdef\lst@fmtSplit#1#2{%
11055
\def\lst@temp##1#2##2\relax##3{%
11057
\ifx\@empty##2\@empty
11060
\let\lst@fmtb\@empty
11062
\expandafter\lst@temp#1\relax\@ne
11065
\def\lst@fmta{##1}\def\lst@fmtb{##2}%
11068
\expandafter\lst@temp#1#2\relax\z@}
11072
% \begin{macro}{\lst@IfNextCharWhitespace}
11073
% is defined in terms of |\lst@IfSubstring|.
11074
% \begin{macrocode}
11075
\gdef\lst@IfNextCharWhitespace#1#2#3{%
11076
\lst@IfSubstring#3\lst@whitespaces{#1}{#2}#3}
11078
% And here come all white space characters.
11079
% \begin{macrocode}
11081
\catcode`\^^I=12\catcode`\^^J=12\catcode`\^^M=12\catcode`\^^L=12\relax%
11082
\lst@DefActive\lst@whitespaces{\ ^^I^^J^^M}% add ^^L
11083
\global\let\lst@whitespaces\lst@whitespaces%
11088
% \begin{macro}{\lst@fmtIfIdentifier}
11089
% tests the first character of |#1|
11090
% \begin{macrocode}
11091
\gdef\lst@fmtIfIdentifier#1{%
11092
\ifx\relax#1\@empty
11093
\expandafter\@secondoftwo
11095
\expandafter\lst@fmtIfIdentifier@\expandafter#1%
11098
% against the `letters' |_|, |@|, |A|,\ldots,|Z| and |a|,\ldots,|z|.
11099
% \begin{macrocode}
11100
\gdef\lst@fmtIfIdentifier@#1#2\relax{%
11101
\let\lst@next\@secondoftwo
11104
\ifnum`#1<91\let\lst@next\@firstoftwo\else
11106
\ifnum`#1<123\let\lst@next\@firstoftwo\else
11107
\fi \fi \fi \fi \fi
11112
% \begin{macro}{\lst@fmtIfNextCharIn}
11113
% is required for the optional \meta{exceptional characters}.
11114
% The implementation is easy---refer section \ref{iSubstringTests}.
11115
% \begin{macrocode}
11116
\gdef\lst@fmtIfNextCharIn#1{%
11117
\ifx\@empty#1\@empty \expandafter\@secondoftwo \else
11118
\def\lst@next{\lst@fmtIfNextCharIn@{#1}}%
11119
\expandafter\lst@next\fi}
11120
\gdef\lst@fmtIfNextCharIn@#1#2#3#4{%
11121
\def\lst@temp##1#4##2##3\relax{%
11122
\ifx \@empty##2\expandafter\@secondoftwo
11123
\else \expandafter\@firstoftwo \fi}%
11124
\lst@temp#1#4\@empty\relax{#2}{#3}#4}
11128
% \begin{macro}{\lst@fmtCDef}
11129
% We need derivations of |\lst@CDef| and |\lst@CDefX|: we have to test the
11130
% next character against the sequence |#5| of exceptional characters.
11131
% These tests are inserted here.
11132
% \begin{macrocode}
11133
\gdef\lst@fmtCDef#1{\lst@fmtCDef@#1}
11134
\gdef\lst@fmtCDef@#1#2#3#4#5#6#7{%
11135
\lst@CDefIt#1{#2}{#3}%
11136
{\lst@fmtIfNextCharIn{#5}{#4#2#3}{#6#4#2#3#7}}%
11142
% \begin{macro}{\lst@fmtCDefX}
11143
% The same but `drop input'.
11144
% \begin{macrocode}
11145
\gdef\lst@fmtCDefX#1{\lst@fmtCDefX@#1}
11146
\gdef\lst@fmtCDefX@#1#2#3#4#5#6#7{%
11148
\ifx\@empty#2\@empty
11149
\def#1{\lst@fmtIfNextCharIn{#5}{#4}{#6#7}}%
11150
\else \ifx\@empty#3\@empty
11153
\def\lst@next{\lst@fmtIfNextCharIn{#5}{#4##1}%
11156
\def\lst@next{#4##1}%
11161
\lst@IfNextCharsArg{#2#3}%
11162
{\lst@fmtIfNextCharIn{#5}{\expandafter#4\lst@eaten}%
11164
{\expandafter#4\lst@eaten}}%
11170
% \paragraph{The parser}
11171
% applies |\lst@fmtSplit| to cut a format definition into items, items into
11172
% `input' and `output', and `output' into `pre' and 'post'. This should be
11173
% clear if you are in touch with format definitions.
11175
% \begin{macro}{\lst@UseFormat}
11176
% Now we can start with the parser.
11177
% \begin{macrocode}
11178
\gdef\lst@UseFormat#1{%
11179
\def\lst@fmtwhole{#1}%
11181
\gdef\lst@UseFormat@{%
11182
\lst@fmtSplit\lst@fmtwhole,%
11184
% We assign the rest of the format definition, \ldots
11185
% \begin{macrocode}
11186
\let\lst@fmtwhole\lst@fmtb
11187
\ifx\lst@fmta\@empty\else
11189
% \ldots\space split the item at the equal sign, and work on the item.
11190
% \begin{macrocode}
11191
\lst@fmtSplit\lst@fmta=%
11192
\ifx\@empty\lst@fmta\else
11195
% Insert |\let\lst@arg\@empty| |\expandafter\lst@XConvert\lst@fmtb\@nil|
11196
% |\let\lst@fmtb\lst@arg|.
11198
% \begin{macrocode}
11199
\expandafter\lstKV@XOptArg\expandafter[\expandafter]%
11200
\expandafter{\lst@fmtb}\lst@UseFormat@b
11204
% Finally we process the next item if the rest is not empty.
11205
% \begin{macrocode}
11206
\ifx\lst@fmtwhole\@empty\else
11207
\expandafter\lst@UseFormat@
11210
% We make |\lst@fmtc| contain the preceding characters as a braced argument.
11211
% To add more arguments, we first split the replacement tokens at the control
11212
% sequence |\string|.
11213
% \begin{macrocode}
11214
\gdef\lst@UseFormat@b[#1]#2{%
11215
\def\lst@fmtc{{#1}}\lst@lExtend\lst@fmtc{\expandafter{\lst@fmta}}%
11217
\lst@fmtSplit\lst@fmtb\string
11219
% We append an empty argument or |\lst@fmtPre| with `|\string|-preceding'
11220
% tokens as argument. We do the same for the tokens after |\string|.
11221
% \begin{macrocode}
11222
\ifx\@empty\lst@fmta
11223
\lst@lAddTo\lst@fmtc{{}}%
11225
\lst@lExtend\lst@fmtc{\expandafter
11226
{\expandafter\lst@fmtPre\expandafter{\lst@fmta}}}%
11228
\ifx\@empty\lst@fmtb
11229
\lst@lAddTo\lst@fmtc{{}}%
11231
\lst@lExtend\lst@fmtc{\expandafter
11232
{\expandafter\lst@fmtPost\expandafter{\lst@fmtb}}}%
11235
% Eventually we extend |\lst@fmtformat| appropriately. Note that |\lst@if|
11236
% still indicates whether the replacement tokens contain |\string|.
11237
% \begin{macrocode}
11238
\expandafter\lst@UseFormat@c\lst@fmtc}
11240
% \begin{macrocode}
11241
\gdef\lst@UseFormat@c#1#2#3#4{%
11242
\lst@fmtIfIdentifier#2\relax
11243
{\lst@fmtIdentifier{#2}%
11244
\lst@if\else \PackageWarning{Listings}%
11245
{Cannot drop identifier in format definition}%
11248
\lst@lAddTo\lst@fmtformat{\lst@CArgX#2\relax\lst@fmtCDef}%
11250
\lst@lAddTo\lst@fmtformat{\lst@CArgX#2\relax\lst@fmtCDefX}%
11252
\lst@DefActive\lst@fmtc{#1}%
11253
\lst@lExtend\lst@fmtformat{\expandafter{\lst@fmtc}{#3}{#4}}}}
11255
% \begin{macrocode}
11256
\lst@AddToHook{SelectCharTable}{\lst@fmtformat}
11257
\global\let\lst@fmtformat\@empty
11262
% \paragraph{The formatting}
11264
% \begin{macro}{\lst@fmtPre}
11265
% \begin{macrocode}
11266
\gdef\lst@fmtPre#1{%
11269
\let\newline\lst@fmtEnsureNewLine
11270
\let\space\lst@fmtEnsureSpace
11271
\let\indent\lst@fmtIndent
11272
\let\noindent\lst@fmtNoindent
11278
% \begin{macro}{\lst@fmtPost}
11279
% \begin{macrocode}
11280
\gdef\lst@fmtPost#1{%
11281
\global\let\lst@fmtPostOutput\@empty
11283
\def\newline{\lst@AddTo\lst@fmtPostOutput\lst@fmtEnsureNewLine}%
11284
\def\space{\aftergroup\lst@fmtEnsurePostSpace}%
11285
\def\indent{\lst@AddTo\lst@fmtPostOutput\lst@fmtIndent}%
11286
\def\noindent{\lst@AddTo\lst@fmtPostOutput\lst@fmtNoindent}%
11287
\aftergroup\lst@PrintToken
11291
% \begin{macrocode}
11292
\lst@AddToHook{Init}{\global\let\lst@fmtPostOutput\@empty}
11293
\lst@AddToHook{PostOutput}
11294
{\lst@fmtPostOutput \global\let\lst@fmtPostOutput\@empty}
11298
% \begin{macro}{\lst@fmtEnsureSpace}
11299
% \begin{macro}{\lst@fmtEnsurePostSpace}
11300
% \begin{macrocode}
11301
\gdef\lst@fmtEnsureSpace{%
11302
\lst@ifwhitespace\else \expandafter\lst@ProcessSpace \fi}
11303
\gdef\lst@fmtEnsurePostSpace{%
11304
\lst@IfNextCharWhitespace{}{\lst@ProcessSpace}}
11309
% \begin{lstkey}{fmtindent}
11310
% \begin{macro}{\lst@fmtIndent}
11311
% \begin{macro}{\lst@fmtNoindent}
11312
% \begin{macrocode}
11313
\lst@Key{fmtindent}{20pt}{\def\lst@fmtindent{#1}}
11314
\newdimen\lst@fmtcurrindent
11315
\lst@AddToHook{InitVars}{\global\lst@fmtcurrindent\z@}
11316
\gdef\lst@fmtIndent{\global\advance\lst@fmtcurrindent\lst@fmtindent}
11317
\gdef\lst@fmtNoindent{\global\advance\lst@fmtcurrindent-\lst@fmtindent}
11323
% \begin{macro}{\lst@fmtEnsureNewLine}
11324
% \begin{macrocode}
11325
\gdef\lst@fmtEnsureNewLine{%
11326
\global\advance\lst@newlines\@ne
11327
\global\advance\lst@newlinesensured\@ne
11328
\lst@fmtignoretrue}
11330
% \begin{macrocode}
11331
\lst@AddToAtTop\lst@DoNewLines{%
11332
\ifnum\lst@newlines>\lst@newlinesensured
11333
\global\advance\lst@newlines-\lst@newlinesensured
11335
\global\lst@newlinesensured\z@}
11336
\newcount\lst@newlinesensured % global
11337
\lst@AddToHook{Init}{\global\lst@newlinesensured\z@}
11339
% \begin{macrocode}
11340
\gdef\lst@fmtignoretrue{\let\lst@fmtifignore\iftrue}
11341
\gdef\lst@fmtignorefalse{\let\lst@fmtifignore\iffalse}
11342
\lst@AddToHook{InitVars}{\lst@fmtignorefalse}
11343
\lst@AddToHook{Output}{\lst@fmtignorefalse}
11347
% \begin{macro}{\lst@fmtUseLostSpace}
11348
% \begin{macrocode}
11349
\gdef\lst@fmtUseLostSpace{%
11350
\lst@ifnewline \kern\lst@fmtcurrindent \global\lst@lostspace\z@
11354
\lst@AddToHook{Init}
11356
\ifx\lst@fmtformat\@empty \ifx\lst@fmt\@empty \lst@false \fi\fi
11358
\let\lst@OldOLS\lst@OutputLostSpace
11359
\let\lst@OutputLostSpace\lst@fmtUseLostSpace
11360
\let\lst@ProcessSpace\lst@fmtProcessSpace
11364
% This `lost space' doesn't use |\lst@alloverstyle| yet!
11368
% \begin{macro}{\lst@fmtProcessSpace}
11369
% \begin{macrocode}
11370
\gdef\lst@fmtProcessSpace{%
11373
\lst@fmtifignore\else
11374
\lst@AppendOther\lst@outputspace
11376
\else \lst@ifkeepspaces
11377
\lst@AppendOther\lst@outputspace
11378
\else \ifnum\lst@newlines=\z@
11379
\lst@AppendSpecialSpace
11380
\else \ifnum\lst@length=\z@
11381
\global\advance\lst@lostspace\lst@width
11382
\global\advance\lst@pos\m@ne
11384
\lst@AppendSpecialSpace
11387
\lst@whitespacetrue}
11392
% \paragraph{Formatting identifiers}
11394
% \begin{macro}{\lst@fmtIdentifier}
11395
% We install a (keyword) test for the `format identifiers'.
11396
% \begin{macrocode}
11397
\lst@InstallTest{f}
11398
\lst@fmt@list\lst@fmt \lst@gfmt@list\lst@gfmt
11401
\gdef\lst@fmt@list{\lst@fmt\lst@gfmt}\global\let\lst@fmt\@empty
11402
\gdef\lst@gfmt@list{\lst@fmt\lst@gfmt}\global\let\lst@gfmt\@empty
11404
% The working procedure expands |\lst@fmt$|\meta{string} (and defines
11405
% |\lst@PrintToken| to do nothing).
11406
% \begin{macrocode}
11407
\gdef\lst@gfmt@wp{%
11408
\begingroup \let\lst@UM\@empty
11409
\let\lst@PrintToken\@empty
11410
\csname\lst@ @fmt$\the\lst@token\endcsname
11413
% This control sequence is probably defined as `working identifier'.
11414
% \begin{macrocode}
11415
\gdef\lst@fmtIdentifier#1#2#3#4{%
11416
\lst@DefOther\lst@fmta{#2}\edef\lst@fmt{\lst@fmt,\lst@fmta}%
11417
\@namedef{\lst@ @fmt$\lst@fmta}{#3#4}}
11419
% |\lst@fmt$|\meta{identifier} expands to a |\lst@fmtPre|/|\lst@fmtPost|
11420
% sequence defined by |#2| and |#3|.
11423
% \begin{macrocode}
11431
% \subsection{Line numbers}
11433
% \begin{aspect}{labels}
11434
% \lsthelper{Rolf~Niepraschk}{1997/04/24}{line numbers} asked for line numbers.
11435
% \begin{macrocode}
11437
\lst@BeginAspect{labels}
11440
% \begin{lstkey}{numbers}
11441
% Depending on the argument we define |\lst@PlaceNumber| to print the line
11443
% \begin{macrocode}
11444
\lst@Key{numbers}{none}{%
11445
\let\lst@PlaceNumber\@empty
11446
\lstKV@SwitchCases{#1}%
11448
left&\def\lst@PlaceNumber{\llap{\normalfont
11449
\lst@numberstyle{\thelstnumber}\kern\lst@numbersep}}\\%
11450
right&\def\lst@PlaceNumber{\rlap{\normalfont
11451
\kern\linewidth \kern\lst@numbersep
11452
\lst@numberstyle{\thelstnumber}}}%
11453
}{\PackageError{Listings}{Numbers #1 unknown}\@ehc}}
11457
% \begin{lstkey}{numberstyle}
11458
% \begin{lstkey}{numbersep}
11459
% \begin{lstkey}{stepnumber}
11460
% \begin{lstkey}{numberblanklines}
11461
% Definition of the keys.
11462
% \begin{macrocode}
11463
\lst@Key{numberstyle}{}{\def\lst@numberstyle{#1}}
11464
\lst@Key{numbersep}{10pt}{\def\lst@numbersep{#1}}
11465
\lst@Key{stepnumber}{1}{\def\lst@stepnumber{#1\relax}}
11466
\lst@AddToHook{EmptyStyle}{\let\lst@stepnumber\@ne}
11467
\lst@Key{numberblanklines}{true}[t]
11468
{\lstKV@SetIf{#1}\lst@ifnumberblanklines}
11475
% \begin{lstkey}{firstnumber}
11476
% We select the first number according to the argument.
11477
% \begin{macrocode}
11478
\lst@Key{firstnumber}{auto}{%
11479
\lstKV@SwitchCases{#1}%
11480
{auto&\let\lst@firstnumber\@undefined\\%
11481
last&\let\lst@firstnumber\c@lstnumber
11482
}{\def\lst@firstnumber{#1\relax}}}
11483
\lst@AddToHook{PreSet}{\let\lst@advancenumber\z@}
11484
\lst@AddToHook{PreInit}
11485
{\ifx\lst@firstnumber\@undefined
11486
\let\lst@firstnumber\lst@firstline
11491
% \begin{macro}{\lst@SetFirstNumber}
11492
% \begin{macro}{\lst@SaveFirstNumber}
11493
% \lsthelper{Boris~Veytsman}{1998/03/25}{continue line numbering: a.c b.c a.c}
11494
% proposed to continue line numbers according to listing names. We define the
11495
% label number of the first printing line here. A bug reported by
11496
% \lsthelper{Jens~Schwarzer}{2001/05/29}{wrong line numbering of lstlisting
11497
% with first>1} has been removed by replacing |\@ne| by |\lst@firstline|.
11498
% \begin{macrocode}
11499
\gdef\lst@SetFirstNumber{%
11500
\ifx\lst@firstnumber\@undefined
11501
\@tempcnta 0\csname\@lst no@\lst@intname\endcsname\relax
11502
\ifnum\@tempcnta=\z@ \@tempcnta\lst@firstline
11503
\else \lst@nololtrue \fi
11504
\advance\@tempcnta\lst@advancenumber
11505
\edef\lst@firstnumber{\the\@tempcnta\relax}%
11508
% The current label is stored in|\lstno@|\meta{name}. If the name is empty,
11509
% we use a space instead, which leaves |\lstno@| undefined.
11510
% \begin{macrocode}
11511
\gdef\lst@SaveFirstNumber{%
11513
\csname\@lst no\ifx\lst@intname\@empty @ \else @\lst@intname\fi
11514
\endcsname{\the\c@lstnumber}}
11519
% \begin{macro}{\c@lstnumber}
11520
% This counter keeps the current label number. We use it as current label to
11521
% make line numbers referenced by |\ref|. This was proposed by
11522
% \lsthelper{Boris~Veytsman}{1998/03/25}{make line numbers referenced via
11523
% \label and \ref}. We now use |\refstepcounter| to do the job---thanks to a
11524
% bug report from \lsthelper{Christian~Gudrian}{2000/11/13}{\ref{lst:line}
11525
% jumps to top of listing and not to the line}.
11526
% \begin{macrocode}
11527
\newcounter{lstnumber}% \global
11528
\global\c@lstnumber\@ne % init
11529
\renewcommand*\thelstnumber{\@arabic\c@lstnumber}
11530
\lst@AddToHook{EveryPar}
11531
{\global\advance\c@lstnumber\lst@advancelstnum
11532
\global\advance\c@lstnumber\m@ne \refstepcounter{lstnumber}%
11533
\lst@SkipOrPrintLabel}%
11534
\global\let\lst@advancelstnum\@ne
11536
% Note that the counter advances \emph{before} the label is printed and not
11537
% afterwards. Otherwise we have wrong references---reported by
11538
% \lsthelper{Gregory~Van~Vooren}{1999/06/04}{reference one unit too large}.
11539
% \begin{macrocode}
11540
\lst@AddToHook{Init}{\def\@currentlabel{\thelstnumber}}
11542
% The label number is initialized and we ensure correct line numbers for
11543
% continued listings.
11544
% \begin{macrocode}
11545
\lst@AddToHook{InitVars}
11546
{\global\c@lstnumber\lst@firstnumber
11547
\global\advance\c@lstnumber\lst@advancenumber
11548
\global\advance\c@lstnumber-\lst@advancelstnum
11549
\ifx \lst@firstnumber\c@lstnumber
11550
\global\advance\c@lstnumber-\lst@advancelstnum
11552
\lst@AddToHook{ExitVars}
11553
{\global\advance\c@lstnumber\lst@advancelstnum}
11555
% \lsthelper{Walter~E.~Brown}{2001/05/22}{pdftex 3.14159-14f warning:
11556
% destination with the same identifier} reported problems with pdftex and
11557
% \packagename{hyperref}. A bad default of |\theHlstlabel| was the reason.
11558
% \lsthelper{Heiko~Oberdiek}{2001/11/08}{pdftex warning: destination with
11559
% the same identifier} found another bug which was due to the localization
11560
% of |\lst@neglisting|. He also provided the following fix, replacing
11561
% |\thelstlisting| with the |\ifx| \ldots\ |\fi| construction.
11562
% \begin{macrocode}
11564
\def\theHlstnumber{\ifx\lst@@caption\@empty \lst@neglisting
11565
\else \thelstlisting \fi
11570
% \begin{macro}{\lst@skipnumbers}
11571
% There are more things to do. We calculate how many lines must skip their
11572
% label. The formula is
11573
% $$|\lst@skipnumbers|=
11574
% \textrm{\emph{first printing line}}\bmod|\lst@stepnumber|.$$
11575
% Note that we use a nonpositive representative for |\lst@skipnumbers|.
11576
% \begin{macrocode}
11577
\newcount\lst@skipnumbers % \global
11578
\lst@AddToHook{Init}
11579
{\ifnum \z@>\lst@stepnumber
11580
\let\lst@advancelstnum\m@ne
11581
\edef\lst@stepnumber{-\lst@stepnumber}%
11583
\ifnum \z@<\lst@stepnumber
11584
\global\lst@skipnumbers\lst@firstnumber
11585
\global\divide\lst@skipnumbers\lst@stepnumber
11586
\global\multiply\lst@skipnumbers-\lst@stepnumber
11587
\global\advance\lst@skipnumbers\lst@firstnumber
11588
\ifnum\lst@skipnumbers>\z@
11589
\global\advance\lst@skipnumbers -\lst@stepnumber
11592
% If |\lst@stepnumber| is zero, no line numbers are printed:
11593
% \begin{macrocode}
11595
\let\lst@SkipOrPrintLabel\relax
11600
% \begin{macro}{\lst@SkipOrPrintLabel}
11601
% But default is this. We use the fact that |\lst@skipnumbers| is nonpositive.
11602
% The counter advances every line and if that counter is zero, we print a line
11603
% number and decrement the counter by |\lst@stepnumber|.
11604
% \begin{macrocode}
11605
\gdef\lst@SkipOrPrintLabel{%
11606
\ifnum\lst@skipnumbers=\z@
11607
\global\advance\lst@skipnumbers-\lst@stepnumber\relax
11610
\global\advance\lst@skipnumbers\@ne}
11612
% \begin{macrocode}
11613
\lst@AddToHook{OnEmptyLine}{%
11614
\lst@ifnumberblanklines\else \ifnum\lst@skipnumbers=\z@
11615
\global\advance\lst@skipnumbers-\lst@stepnumber\relax
11620
% \begin{macrocode}
11627
% \subsection{Line shape and line breaking}
11629
% \begin{macro}{\lst@parshape}
11630
% We define a default version of |\lst@parshape| for the case that the
11631
% \aspectname{lineshape} aspect is not loaded. We use this parshape every line
11632
% (in fact every paragraph). Furthermore we must repeat the parshape if we
11633
% close a group level---or the shape is forgotten.
11634
% \begin{macrocode}
11636
\def\lst@parshape{\parshape\@ne \z@ \linewidth}
11637
\lst@AddToHookAtTop{EveryLine}{\lst@parshape}
11638
\lst@AddToHookAtTop{EndGroup}{\lst@parshape}
11643
% \begin{aspect}{lineshape}
11644
% Our first aspect in this section.
11645
% \begin{macrocode}
11647
\lst@BeginAspect{lineshape}
11650
% \begin{lstkey}{xleftmargin}
11651
% \begin{lstkey}{xrightmargin}
11652
% \begin{lstkey}{resetmargins}
11653
% \begin{lstkey}{linewidth}
11655
% \begin{macrocode}
11656
\lst@Key{xleftmargin}{\z@}{\def\lst@xleftmargin{#1}}
11657
\lst@Key{xrightmargin}{\z@}{\def\lst@xrightmargin{#1}}
11658
\lst@Key{resetmargins}{false}[t]{\lstKV@SetIf{#1}\lst@ifresetmargins}
11660
% The margins become zero if we make an exact box around the listing.
11661
% \begin{macrocode}
11662
\lst@AddToHook{BoxUnsafe}{\let\lst@xleftmargin\z@
11663
\let\lst@xrightmargin\z@}
11664
\lst@AddToHook{TextStyle}{%
11665
\let\lst@xleftmargin\z@ \let\lst@xrightmargin\z@
11666
\let\lst@ifresetmargins\iftrue}
11668
% Added above hook after bug report from \lsthelper{Magnus~Lewis-Smith}
11669
%{1999/08/06}{|\lstinline| indented} and \lsthelper{Jos\'e~Romildo~Malaquias}
11670
%{2000/08/22}{|\lstinline| indented (resetmargins)} respectively.
11671
% \begin{macrocode}
11672
\lst@Key{linewidth}\linewidth{\def\lst@linewidth{#1}}
11673
\lst@AddToHook{PreInit}{\linewidth\lst@linewidth\relax}
11680
% \begin{macro}{\lst@parshape}
11681
% The definition itself is easy.
11682
% \begin{macrocode}
11683
\gdef\lst@parshape{%
11684
\parshape\@ne \@totalleftmargin \linewidth}
11686
% We calculate the line width and (inner/outer) indent for a listing.
11687
% \begin{macrocode}
11688
\lst@AddToHook{Init}
11689
{\lst@ifresetmargins
11690
\advance\linewidth\@totalleftmargin
11691
\advance\linewidth\rightmargin
11692
\@totalleftmargin\z@
11694
\advance\linewidth-\lst@xleftmargin
11695
\advance\linewidth-\lst@xrightmargin
11696
\advance\@totalleftmargin\lst@xleftmargin\relax}
11700
% \begin{lstkey}{lineskip}
11701
% The introduction of this key is due to communication with
11702
% \lsthelper{Andreas~Bartelt}{1997/09/11}{problem with redefed \parskip;
11703
% \lstlineskip introduced}. Version 1.0 implements this feature by
11704
% redefining |\baselinestretch|.
11705
% \begin{macrocode}
11706
\lst@Key{lineskip}{\z@}{\def\lst@lineskip{#1\relax}}
11707
\lst@AddToHook{Init}
11709
\ifdim\z@=\lst@lineskip\else
11710
\@tempdima\baselineskip
11711
\advance\@tempdima\lst@lineskip
11712
\divide\@tempdima\strip@pt\baselineskip\relax
11713
\edef\baselinestretch{\strip@pt\@tempdima}%
11719
% \begin{lstkey}{breaklines}
11720
% \begin{lstkey}{breakindent}
11721
% \begin{lstkey}{breakautoindent}
11722
% \begin{lstkey}{prebreak}
11723
% \begin{lstkey}{postbreak}
11724
% As usual we have no problems in announcing more keys.
11725
% \begin{macrocode}
11726
\lst@Key{breaklines}{false}[t]{\lstKV@SetIf{#1}\lst@ifbreaklines}
11727
\lst@Key{breakindent}{20pt}{\def\lst@breakindent{#1}}
11728
\lst@Key{breakautoindent}{t}[t]{\lstKV@SetIf{#1}\lst@ifbreakautoindent}
11729
\lst@Key{prebreak}{}{\def\lst@prebreak{#1}}
11730
\lst@Key{postbreak}{}{\def\lst@postbreak{#1}}
11732
% We assign some different macros and (if necessary) suppress ``underfull
11733
% |\hbox|'' messages (and use different pretolerance):
11734
% \begin{macrocode}
11735
\lst@AddToHook{Init}
11737
\hbadness\@M \pretolerance\@M
11739
% We use the normal parshape and the calculated |\lst@breakshape| (see below).
11740
% \begin{macrocode}
11741
\def\lst@parshape{\parshape\tw@ \@totalleftmargin\linewidth
11744
\let\lst@discretionary\@empty
11746
\lst@AddToHook{OnNewLine}
11747
{\lst@ifbreaklines \lst@breakNewLine \fi}
11749
% \end{lstkey}\end{lstkey}\end{lstkey}\end{lstkey}
11752
% \begin{macro}{\lst@discretionary}
11753
% \begin{macro}{\lst@spacekern}
11754
% Here comes the whole magic: We set a discretionary break after each `output
11755
% unit'. However we redefine |\space| to be used inside |\discretionary| and
11756
% use \hookname{EveryLine} hook.
11757
% \begin{macrocode}
11758
\gdef\lst@discretionary{%
11759
\discretionary{\let\space\lst@spacekern\lst@prebreak}%
11760
{\llap{\lsthk@EveryLine \kern\lst@breakcurrindent}%
11761
\let\space\lst@spacekern\lst@postbreak}{}}
11762
\lst@AddToHook{PostOutput}{\lst@discretionary}
11763
\gdef\lst@spacekern{\kern\lst@width}
11765
% \begin{ALTERNATIVE}
11766
% |\penalty\@M \hskip\z@ plus 1fil \penalty0\hskip\z@ plus-1fil| \emph{before}
11767
% each `output unit' (i.e.~before |\hbox{...}| in the output macros) also break
11768
% the lines as desired. But we wouldn't have |prebreak| and |postbreak|.
11769
% \end{ALTERNATIVE}
11770
% \end{macro}\end{macro}
11772
% \begin{macro}{\lst@breakNewLine}
11773
% We use \keyname{breakindent}, and additionally the current line indention
11774
% (coming from white spaces at the beginning of the line) if `auto indent' is
11776
% \begin{macrocode}
11777
\gdef\lst@breakNewLine{%
11778
\@tempdima\lst@breakindent\relax
11779
\lst@ifbreakautoindent \advance\@tempdima\lst@lostspace \fi
11781
% Now we calculate the margin and line width of the wrapped part \ldots
11782
% \begin{macrocode}
11783
\@tempdimc-\@tempdima \advance\@tempdimc\linewidth
11784
\advance\@tempdima\@totalleftmargin
11786
% \ldots\space and store it in |\lst@breakshape|.
11787
% \begin{macrocode}
11788
\xdef\lst@breakshape{\noexpand\lst@breakcurrindent \the\@tempdimc}%
11789
\xdef\lst@breakcurrindent{\the\@tempdima}}
11792
% We could speed this up by allocating two global dimensions.
11796
% \begin{macro}{\lst@breakshape}
11797
% \lsthelper{Andreas~Deininger}{2000/08/25}{`breaklines,first>1' leads to
11798
% ``undefined control sequence'' error} reported a problem which is resolved
11799
% by providing a default break shape.
11800
% \begin{macrocode}
11801
\gdef\lst@breakshape{\@totalleftmargin \linewidth}
11805
% \begin{macro}{\lst@breakProcessOther}
11806
% is the same as |\lst@ProcessOther| except that it also outputs the current
11807
% token string. This inserts a potential linebreak point.
11808
% Only the closing parenthesis uses this macro yet.
11809
% \begin{macrocode}
11810
\gdef\lst@breakProcessOther#1{\lst@ProcessOther#1\lst@OutputOther}
11811
\lst@AddToHook{SelectCharTable}
11812
{\lst@ifbreaklines \lst@Def{`)}{\lst@breakProcessOther)}\fi}
11814
% A bug reported by \lsthelper{Gabriel~Tauro}{2001/04/18}{unexpected `)' if
11815
% the character appears before first printed line} has been removed by using
11816
% |\lst@ProcessOther| instead of |\lst@AppendOther|.
11819
% \begin{macrocode}
11826
% \subsection{Frames}
11828
% \begin{aspect}{frames}
11830
% \begin{macrocode}
11832
\lst@BeginAspect[lineshape]{frames}
11835
% \begin{lstkey}{framexleftmargin}
11836
% \begin{lstkey}{framexrightmargin}
11837
% \begin{lstkey}{framextopmargin}
11838
% \begin{lstkey}{framexbottommargin}
11839
% These keys just save the argument.
11840
% \begin{macrocode}
11841
\lst@Key{framexleftmargin}{\z@}{\def\lst@framexleftmargin{#1}}
11842
\lst@Key{framexrightmargin}{\z@}{\def\lst@framexrightmargin{#1}}
11843
\lst@Key{framextopmargin}{\z@}{\def\lst@framextopmargin{#1}}
11844
\lst@Key{framexbottommargin}{\z@}{\def\lst@framexbottommargin{#1}}
11851
% \begin{lstkey}{backgroundcolor}
11852
% \lsthelper{Ralf~Imh\"auser}{2000/01/08}{coloured background} inspired the
11853
% key \keyname{backgroundcolor}. All keys save the argument, and \ldots
11854
% \begin{macrocode}
11855
\lst@Key{backgroundcolor}{}{\def\lst@bkgcolor{#1}}
11856
\lst@Key{fillcolor}{}{\def\lst@fillcolor{#1}}
11857
\lst@Key{rulecolor}{}{\def\lst@rulecolor{#1}}
11858
\lst@Key{rulesepcolor}{}{\def\lst@rulesepcolor{#1}}
11860
% \ldots\space some have default settings if they are empty.
11861
% \begin{macrocode}
11862
\lst@AddToHook{Init}{%
11863
\ifx\lst@fillcolor\@empty
11864
\let\lst@fillcolor\lst@bkgcolor
11866
\ifx\lst@rulesepcolor\@empty
11867
\let\lst@rulesepcolor\lst@fillcolor
11872
% \begin{lstkey}{rulesep}
11873
% \begin{lstkey}{framerule}
11874
% \begin{lstkey}{framesep}
11875
% \begin{lstkey}{frameshape}
11876
% Another set of keys, which mainly save their respective argument.
11877
% \keyname{frameshape} capitalizes all letters, and checks whether at least one
11878
% round corner is specified. Eventually we define |\lst@frame| to be empty if
11879
% and only if there is no frameshape.
11880
% \begin{macrocode}
11881
\lst@Key{rulesep}{2pt}{\def\lst@rulesep{#1}}
11882
\lst@Key{framerule}{.4pt}{\def\lst@framerulewidth{#1}}
11883
\lst@Key{framesep}{3pt}{\def\lst@frametextsep{#1}}
11884
\lst@Key{frameshape}{}{%
11885
\let\lst@xrulecolor\@empty
11886
\lstKV@FourArg{#1}%
11887
{\uppercase{\def\lst@frametshape{##1}}%
11888
\uppercase{\def\lst@framelshape{##2}}%
11889
\uppercase{\def\lst@framershape{##3}}%
11890
\uppercase{\def\lst@framebshape{##4}}%
11891
\let\lst@ifframeround\iffalse
11892
\lst@IfSubstring R\lst@frametshape{\let\lst@ifframeround\iftrue}{}%
11893
\lst@IfSubstring R\lst@framebshape{\let\lst@ifframeround\iftrue}{}%
11894
\def\lst@frame{##1##2##3##4}}}
11901
% \begin{lstkey}{frameround}
11902
% \begin{lstkey}{frame}
11903
% We have to do some conversion here.
11904
% \begin{macrocode}
11905
\lst@Key{frameround}\relax
11906
{\uppercase{\def\lst@frameround{#1}}%
11907
\expandafter\lstframe@\lst@frameround ffff\relax}
11908
\global\let\lst@frameround\@empty
11910
% In case of an verbose argument, we use the |trbl|-subset replacement.
11911
% \begin{macrocode}
11912
\lst@Key{frame}\relax{%
11913
\let\lst@xrulecolor\@empty
11914
\lstKV@SwitchCases{#1}%
11915
{none&\let\lst@frame\@empty\\%
11916
leftline&\def\lst@frame{l}\\%
11917
topline&\def\lst@frame{t}\\%
11918
bottomline&\def\lst@frame{b}\\%
11919
lines&\def\lst@frame{tb}\\%
11920
single&\def\lst@frame{trbl}\\%
11921
shadowbox&\def\lst@frame{tRBl}%
11922
\def\lst@xrulecolor{\lst@rulesepcolor}%
11923
\def\lst@rulesep{\lst@frametextsep}%
11924
}{\def\lst@frame{#1}}%
11925
\expandafter\lstframe@\lst@frameround ffff\relax}
11927
% Adding |t|, |r|, |b|, and |l| in case of their upper case versions makes
11928
% later tests easier.
11929
% \begin{macrocode}
11930
\gdef\lstframe@#1#2#3#4#5\relax{%
11931
\lst@IfSubstring T\lst@frame{\edef\lst@frame{t\lst@frame}}{}%
11932
\lst@IfSubstring R\lst@frame{\edef\lst@frame{r\lst@frame}}{}%
11933
\lst@IfSubstring B\lst@frame{\edef\lst@frame{b\lst@frame}}{}%
11934
\lst@IfSubstring L\lst@frame{\edef\lst@frame{l\lst@frame}}{}%
11936
% We now check top and bottom frame rules, \ldots
11937
% \begin{macrocode}
11938
\let\lst@frametshape\@empty \let\lst@framebshape\@empty
11940
ltr\lst@framelshape\lst@frametshape\lst@framershape #4#1%
11942
LTR\lst@framelshape\lst@frametshape\lst@framershape #4#1%
11944
lbr\lst@framelshape\lst@framebshape\lst@framershape #3#2%
11946
LBR\lst@framelshape\lst@framebshape\lst@framershape #3#2%
11948
% \ldots\space look for round corners \ldots
11949
% \begin{macrocode}
11950
\let\lst@ifframeround\iffalse
11951
\lst@IfSubstring R\lst@frametshape{\let\lst@ifframeround\iftrue}{}%
11952
\lst@IfSubstring R\lst@framebshape{\let\lst@ifframeround\iftrue}{}%
11954
% and define left and right frame shape.
11955
% \begin{macrocode}
11956
\let\lst@framelshape\@empty \let\lst@framershape\@empty
11957
\lst@IfSubstring L\lst@frame
11958
{\def\lst@framelshape{YY}}%
11959
{\lst@IfSubstring l\lst@frame{\def\lst@framelshape{Y}}{}}%
11960
\lst@IfSubstring R\lst@frame
11961
{\def\lst@framershape{YY}}%
11962
{\lst@IfSubstring r\lst@frame{\def\lst@framershape{Y}}{}}}
11964
% Now comes the macro used to define top and bottom frame shape.
11965
% It extends the macro |#5|.
11966
% The last two arguments show whether left and right corners are round.
11967
% |#4| and |#6| are temporary macros.
11968
% |#1#2#3| are the three characters we test for.
11969
% \begin{macrocode}
11970
\gdef\lst@frameCheck#1#2#3#4#5#6#7#8{%
11971
\lst@IfSubstring #1\lst@frame
11972
{\if #7T\def#4{R}\else \def#4{Y}\fi}%
11974
\lst@IfSubstring #3\lst@frame
11975
{\if #8T\def#6{R}\else \def#6{Y}\fi}%
11977
\lst@IfSubstring #2\lst@frame{\edef#5{#5#4Y#6}}{}}
11982
% \begin{macro}{\lst@frameMakeVBox}
11983
% \begin{macrocode}
11984
\gdef\lst@frameMakeBoxV#1#2#3{%
11986
\color@begingroup \lst@rulecolor
11987
\llap{\setbox\z@\hbox{\vrule\@width\z@\@height#2\@depth#3%
11989
\rlap{\lst@frameBlock\lst@rulesepcolor{\wd\z@}%
11992
\ifx\lst@framelshape\@empty
11993
\kern\lst@frametextsep\relax
11995
\lst@frameBlock\lst@fillcolor\lst@frametextsep{#2}{#3}%
11997
\kern\lst@framexleftmargin}%
11998
\rlap{\kern-\lst@framexleftmargin
11999
\@tempdima\linewidth
12000
\advance\@tempdima\lst@framexleftmargin
12001
\advance\@tempdima\lst@framexrightmargin
12002
\lst@frameBlock\lst@bkgcolor\@tempdima{#2}{#3}%
12003
\ifx\lst@framershape\@empty
12004
\kern\lst@frametextsep\relax
12006
\lst@frameBlock\lst@fillcolor\lst@frametextsep{#2}{#3}%
12008
\setbox\z@\hbox{\vrule\@width\z@\@height#2\@depth#3%
12010
\rlap{\lst@frameBlock\lst@rulesepcolor{\wd\z@}%
12017
% \begin{macro}{\lst@frameBlock}
12018
% \begin{macrocode}
12019
\gdef\lst@frameBlock#1#2#3#4{%
12022
\setbox\z@\hbox{\vrule\@height#3\@depth#4%
12023
\ifx#1\@empty \@width\z@ \kern#2\relax
12024
\else \@width#2\relax \fi}%
12030
% \begin{macro}{\lst@frameR}
12031
% typesets right rules.
12032
% We only need to iterate through |\lst@framershape|.
12033
% \begin{macrocode}
12035
\expandafter\lst@frameR@\lst@framershape\relax
12036
\kern-\lst@rulesep}
12037
\gdef\lst@frameR@#1{%
12038
\ifx\relax#1\@empty\else
12039
\if #1Y\lst@framevrule \else \kern\lst@framerulewidth \fi
12041
\expandafter\lst@frameR@b
12043
\gdef\lst@frameR@b#1{%
12044
\ifx\relax#1\@empty
12046
\if #1Y\color@begingroup
12051
\kern\lst@framerulewidth
12054
\expandafter\lst@frameR@
12059
% \begin{macro}{\lst@frameL}
12060
% Ditto left rules.
12061
% \begin{macrocode}
12064
\expandafter\lst@frameL@\lst@framelshape\relax}
12065
\gdef\lst@frameL@#1{%
12066
\ifx\relax#1\@empty\else
12068
\if#1Y\lst@framevrule \else \kern\lst@framerulewidth \fi
12069
\expandafter\lst@frameL@
12074
% \begin{macro}{\lst@frameH}
12075
% This is the central macro used to draw top and bottom frame rules.
12076
% The first argument is either |T| or |B| and the second contains the shape.
12077
% We use |\@tempcntb| as size counter.
12078
% \begin{macrocode}
12079
\gdef\lst@frameH#1#2{%
12080
\global\let\lst@framediml\z@ \global\let\lst@framedimr\z@
12081
\setbox\z@\hbox{}\@tempcntb\z@
12082
\expandafter\lst@frameH@\expandafter#1#2\relax\relax\relax
12083
\@tempdimb\lst@frametextsep\relax
12084
\advance\@tempdimb\lst@framerulewidth\relax
12085
\@tempdimc-\@tempdimb
12086
\advance\@tempdimc\ht\z@
12087
\advance\@tempdimc\dp\z@
12089
\lst@frameHBkg\lst@fillcolor\@tempdimb\@firstoftwo
12090
\if#1T\rlap{\raise\dp\@tempboxa\box\@tempboxa}%
12091
\else\rlap{\lower\ht\@tempboxa\box\@tempboxa}\fi
12092
\lst@frameHBkg\lst@rulesepcolor\@tempdimc\@secondoftwo
12093
\advance\@tempdimb\ht\@tempboxa
12094
\if#1T\rlap{\raise\lst@frametextsep\box\@tempboxa}%
12095
\else\rlap{\lower\@tempdimb\box\@tempboxa}\fi
12098
\gdef\lst@frameH@#1#2#3#4{%
12099
\ifx\relax#4\@empty\else
12100
\lst@frameh \@tempcntb#1#2#3#4%
12101
\advance\@tempcntb\@ne
12102
\expandafter\lst@frameH@\expandafter#1%
12104
\gdef\lst@frameHBkg#1#2#3{%
12105
\setbox\@tempboxa\hbox{%
12106
\kern-\lst@framexleftmargin
12107
#3{\kern-\lst@framediml\relax}{\@tempdima\z@}%
12108
\ifdim\lst@framediml>\@tempdimb
12109
#3{\@tempdima\lst@framediml \advance\@tempdima-\@tempdimb
12110
\lst@frameBlock\lst@rulesepcolor\@tempdima\@tempdimb\z@}%
12111
{\kern-\lst@framediml
12112
\advance\@tempdima\lst@framediml\relax}%
12115
\ifx\lst@framelshape\@empty\else
12116
\advance\@tempdima\@tempdimb
12118
\ifx\lst@framershape\@empty\else
12119
\advance\@tempdima\@tempdimb
12121
{\ifdim\lst@framedimr>\@tempdimb
12122
\advance\@tempdima\lst@framedimr\relax
12124
\advance\@tempdima\linewidth
12125
\advance\@tempdima\lst@framexleftmargin
12126
\advance\@tempdima\lst@framexrightmargin
12127
\lst@frameBlock#1\@tempdima#2\z@
12128
#3{\ifdim\lst@framedimr>\@tempdimb
12129
\@tempdima-\@tempdimb
12130
\advance\@tempdima\lst@framedimr\relax
12131
\lst@frameBlock\lst@rulesepcolor\@tempdima\@tempdimb\z@
12137
% \begin{macro}{\lst@frameh}
12138
% This is the low-level macro used to draw top and bottom frame rules.
12139
% It \emph{adds} one rule plus corners to box 0.
12140
% The first parameter gives the size of the corners and the second is either
12142
% |#3#4#5| is a left-to-right description of the frame and is in
12143
% $\{$\texttt{Y,N,R}$\}\times\{$\texttt{Y,N}$\}\times\{$\texttt{Y,N,R}$\}$.
12144
% We move to the correct horizontal position, set the left corner, the
12145
% horizontal line, and the right corner.
12146
% \begin{macrocode}
12147
\gdef\lst@frameh#1#2#3#4#5{%
12148
\lst@frameCalcDimA#1%
12149
\lst@ifframeround \@getcirc\@tempdima \fi
12151
% \begin{macrocode}
12155
\kern-\lst@framexleftmargin
12157
\ifnum#1=\z@ \lst@rulecolor \else \lst@xrulecolor \fi
12159
% |\lst@frameCorner| gets four arguments:
12160
% |\llap|, |TL| or |BL|, the corner type $\in\{$\texttt{Y,N,R}$\}$, and the
12162
% \begin{macrocode}
12163
\lst@frameCornerX\llap{#2L}#3#1%
12164
\ifdim\lst@framediml<\@tempdimb
12165
\xdef\lst@framediml{\the\@tempdimb}%
12168
\if#4Y\else \let\lst@framerulewidth\z@ \fi
12169
\@tempdima\lst@framexleftmargin
12170
\advance\@tempdima\lst@framexrightmargin
12171
\advance\@tempdima\linewidth
12172
\vrule\@width\@tempdima\@height\lst@framerulewidth \@depth\z@
12174
\lst@frameCornerX\rlap{#2R}#5#1%
12175
\ifdim\lst@framedimr<\@tempdimb
12176
\xdef\lst@framedimr{\the\@tempdimb}%
12180
% \begin{macrocode}
12181
\if#2T\rlap{\raise\dp\z@\box\z@}%
12182
\else\rlap{\lower\ht\z@\box\z@}\fi
12188
% \begin{macro}{\lst@frameCornerX}
12189
% typesets a single corner and returns |\@tempdimb|, the width of the corner.
12190
% \begin{macrocode}
12191
\gdef\lst@frameCornerX#1#2#3#4{%
12192
\setbox\@tempboxa\hbox{\csname\@lst @frame\if#3RR\fi #2\endcsname}%
12193
\@tempdimb\wd\@tempboxa
12195
#1{\box\@tempboxa}%
12197
\if #3Y\expandafter#1\else
12198
\@tempdimb\z@ \expandafter\vphantom \fi
12204
% \begin{macro}{\lst@frameCalcDimA}
12205
% calculates an all over width; used by |\lst@frameh| and |\lst@frameInit|.
12206
% \begin{macrocode}
12207
\gdef\lst@frameCalcDimA#1{%
12208
\@tempdima\lst@rulesep
12209
\advance\@tempdima\lst@framerulewidth
12210
\multiply\@tempdima#1\relax
12211
\advance\@tempdima\lst@frametextsep
12212
\advance\@tempdima\lst@framerulewidth
12213
\multiply\@tempdima\tw@}
12217
% \begin{macro}{\lst@frameInit}
12218
% First we look which frame types we have on the left and on the right.
12219
% We speed up things if there are no vertical rules.
12220
% \begin{macrocode}
12221
\lst@AddToHook{Init}{\lst@frameInit}
12222
\newbox\lst@framebox
12223
\gdef\lst@frameInit{%
12224
\ifx\lst@framelshape\@empty \let\lst@frameL\@empty \fi
12225
\ifx\lst@framershape\@empty \let\lst@frameR\@empty \fi
12226
\def\lst@framevrule{\vrule\@width\lst@framerulewidth\relax}%
12228
% We adjust values to round corners if necessary.
12229
% \begin{macrocode}
12231
\lst@frameCalcDimA\z@ \@getcirc\@tempdima
12232
\@tempdimb\@tempdima \divide\@tempdimb\tw@
12233
\advance\@tempdimb -\@wholewidth
12234
\edef\lst@frametextsep{\the\@tempdimb}%
12235
\edef\lst@framerulewidth{\the\@wholewidth}%
12237
% \begin{macrocode}
12238
\lst@frameCalcDimA\@ne \@getcirc\@tempdima
12239
\@tempdimb\@tempdima \divide\@tempdimb\tw@
12240
\advance\@tempdimb -\tw@\@wholewidth
12241
\advance\@tempdimb -\lst@frametextsep
12242
\edef\lst@rulesep{\the\@tempdimb}%
12245
% \begin{macrocode}
12246
\lst@frameMakeBoxV\lst@framebox{\ht\strutbox}{\dp\strutbox}%
12247
\def\lst@framelr{\copy\lst@framebox}%
12249
% Finally we typeset the rules (+ corners).
12250
% We possibly need to insert negative |\vskip| to remove space between
12251
% preceding text and top rule.
12253
% Use |\vspace| instead of |\vskip|?
12255
% \begin{macrocode}
12256
\ifx\lst@frametshape\@empty\else
12257
\lst@frameH T\lst@frametshape
12260
\@tempdima-\baselineskip \advance\@tempdima\ht\z@
12261
\ifdim\prevdepth<\@cclvi\p@\else
12262
\advance\@tempdima\prevdepth
12264
\ifdim\@tempdima<\z@
12265
\vskip\@tempdima\vskip\lineskip
12267
\noindent\box\z@\par
12268
\lineskiplimit\maxdimen \lineskip\z@
12270
\lst@frameSpreadV\lst@framextopmargin
12273
% |\parshape\lst@parshape| ensures that the top rules correctly indented.
12274
% The bug was reported by \lsthelper{Marcin~Kasperski}{1999/04/28}{top rules
12275
% indented right inside itemize}.
12277
% We typeset left and right rules every line.
12278
% \begin{macrocode}
12279
\lst@AddToHook{EveryLine}{\lst@framelr}
12280
\global\let\lst@framelr\@empty
12284
% \begin{macro}{\lst@frameExit}
12285
% The rules at the bottom.
12286
% \begin{macrocode}
12287
\lst@AddToHook{DeInit}
12288
{\ifx\lst@framebshape\@empty\else \lst@frameExit \fi}
12289
\gdef\lst@frameExit{%
12290
\lst@frameSpreadV\lst@framexbottommargin
12291
\lst@frameH B\lst@framebshape
12293
\everypar{}\par\lst@parshape\nointerlineskip\noindent\box\z@
12298
% \begin{macro}{\lst@frameSpreadV}
12299
% sets rules for vertical spread.
12300
% \begin{macrocode}
12301
\gdef\lst@frameSpreadV#1{%
12303
\everypar{}\par\lst@parshape\nointerlineskip\noindent
12304
\lst@frameMakeBoxV\z@{#1}{\z@}%
12310
% \begin{macro}{\lst@frameTR}
12311
% \begin{macro}{\lst@frameBR}
12312
% \begin{macro}{\lst@frameBL}
12313
% \begin{macro}{\lst@frameTL}
12314
% These macros make a vertical and horizontal rule.
12315
% The implicit argument |\@tempdima| gives the size of two corners and is
12316
% provided by |\lst@frameh|.
12317
% \begin{macrocode}
12318
\gdef\lst@frameTR{%
12319
\vrule\@width.5\@tempdima\@height\lst@framerulewidth\@depth\z@
12320
\kern-\lst@framerulewidth
12321
\raise\lst@framerulewidth\hbox{%
12322
\vrule\@width\lst@framerulewidth\@height\z@\@depth.5\@tempdima}}
12323
\gdef\lst@frameBR{%
12324
\vrule\@width.5\@tempdima\@height\lst@framerulewidth\@depth\z@
12325
\kern-\lst@framerulewidth
12326
\vrule\@width\lst@framerulewidth\@height.5\@tempdima\@depth\z@}
12327
\gdef\lst@frameBL{%
12328
\vrule\@width\lst@framerulewidth\@height.5\@tempdima\@depth\z@
12329
\kern-\lst@framerulewidth
12330
\vrule\@width.5\@tempdima\@height\lst@framerulewidth\@depth\z@}
12331
\gdef\lst@frameTL{%
12332
\raise\lst@framerulewidth\hbox{%
12333
\vrule\@width\lst@framerulewidth\@height\z@\@depth.5\@tempdima}%
12334
\kern-\lst@framerulewidth
12335
\vrule\@width.5\@tempdima\@height\lst@framerulewidth\@depth\z@}
12337
% \end{macro}\end{macro}\end{macro}\end{macro}
12339
% \begin{macro}{\lst@frameRoundT}
12340
% \begin{macro}{\lst@frameRoundB}
12341
% are helper macros to typeset round corners. We set height and depth to
12342
% the visible parts of the circle font.
12343
% \begin{macrocode}
12344
\gdef\lst@frameRoundT{%
12345
\setbox\@tempboxa\hbox{\@circlefnt\char\@tempcnta}%
12346
\ht\@tempboxa\lst@framerulewidth
12348
\gdef\lst@frameRoundB{%
12349
\setbox\@tempboxa\hbox{\@circlefnt\char\@tempcnta}%
12356
% \begin{macro}{\lst@frameRTR}
12357
% \begin{macro}{\lst@frameRBR}
12358
% \begin{macro}{\lst@frameRBL}
12359
% \begin{macro}{\lst@frameRTL}
12360
% The round corners.
12361
% \begin{macrocode}
12362
\gdef\lst@frameRTR{%
12363
\hb@xt@.5\@tempdima{\kern-\lst@framerulewidth
12364
\kern.5\@tempdima \lst@frameRoundT \hss}}
12365
\gdef\lst@frameRBR{%
12366
\hb@xt@.5\@tempdima{\kern-\lst@framerulewidth
12367
\advance\@tempcnta\@ne \kern.5\@tempdima \lst@frameRoundB \hss}}
12368
\gdef\lst@frameRBL{%
12369
\advance\@tempcnta\tw@ \lst@frameRoundB
12370
\kern-.5\@tempdima}
12371
\gdef\lst@frameRTL{%
12372
\advance\@tempcnta\thr@@\lst@frameRoundT
12373
\kern-.5\@tempdima}
12375
% \end{macro}\end{macro}\end{macro}\end{macro}
12377
% \begin{macrocode}
12384
% \subsection{Macro use for make}
12386
% \begin{aspect}{make}
12387
% \begin{macro}{\lst@makemode}
12388
% \begin{macro}{\lst@ifmakekey}
12389
% If we've entered the special mode for Make, we save whether the last
12390
% identifier has been a first order keyword.
12391
% \begin{macrocode}
12393
\lst@BeginAspect[keywords]{make}
12395
% \begin{macrocode}
12396
\lst@NewMode\lst@makemode
12397
\lst@AddToHook{Output}{%
12398
\ifnum\lst@mode=\lst@makemode
12399
\ifx\lst@thestyle\lst@gkeywords@sty
12404
% \begin{macrocode}
12405
\gdef\lst@makekeytrue{\let\lst@ifmakekey\iftrue}
12406
\gdef\lst@makekeyfalse{\let\lst@ifmakekey\iffalse}
12407
\global\lst@makekeyfalse % init
12409
% \end{macro}\end{macro}
12411
% \begin{lstkey}{makemacrouse}
12412
% adjusts the character table if necessary
12413
% \begin{macrocode}
12414
\lst@Key{makemacrouse}f[t]{\lstKV@SetIf{#1}\lst@ifmakemacrouse}
12418
% \begin{macro}{\lst@MakeSCT}
12419
% If `macro use' is on, the opening |$(| prints preceding characters, enters
12420
% the special mode and merges the two characters with the following output.
12422
% \begin{macrocode}
12423
\gdef\lst@MakeSCT{%
12424
\lst@ifmakemacrouse
12425
\lst@ReplaceInput{$(}{%
12427
\lst@EnterMode\lst@makemode{\lst@makekeyfalse}%
12428
\lst@Merge{\lst@ProcessOther\$\lst@ProcessOther(}}%
12430
% The closing parenthesis tests for the mode and either processes |)| as usual
12431
% or outputs it right here (in keyword style if a keyword was between |$(| and
12433
% \begin{macrocode}
12434
\lst@ReplaceInput{)}{%
12435
\ifnum\lst@mode=\lst@makemode
12438
\lst@ProcessOther)%
12440
\let\lst@currstyle\lst@gkeywords@sty
12446
\expandafter\lst@ProcessOther\expandafter)%
12449
% If \keyname{makemacrouse} is off then both |$(| are just `others'.
12450
% \begin{macrocode}
12452
\lst@ReplaceInput{$(}{\lst@ProcessOther\$\lst@ProcessOther(}%
12457
% \begin{macrocode}
12464
% \section{Typesetting a listing}
12467
% \begin{macrocode}
12471
% \begin{macro}{\lst@lineno}
12472
% \begin{lstkey}{print}
12473
% \begin{lstkey}{firstline}
12474
% \begin{lstkey}{lastline}
12475
% The `current line' counter and three keys.
12476
% \begin{macrocode}
12477
\newcount\lst@lineno % \global
12478
\lst@AddToHook{InitVars}{\global\lst@lineno\@ne}
12480
% \begin{macrocode}
12481
\lst@Key{print}{true}[t]{\lstKV@SetIf{#1}\lst@ifprint}
12482
\lst@Key{firstline}\relax{\def\lst@firstline{#1\relax}}
12483
\lst@Key{lastline}\relax{\def\lst@lastline{#1\relax}}
12485
% \begin{macrocode}
12486
\lst@AddToHook{PreSet}
12487
{\let\lst@firstline\@ne \def\lst@lastline{9999999\relax}}
12489
% \end{lstkey}\end{lstkey}\end{lstkey}\end{macro}
12491
% \begin{lstkey}{nolol}
12492
% is just a key here. We'll use it below, of course.
12493
% \begin{macrocode}
12494
\lst@Key{nolol}{false}[t]{\lstKV@SetIf{#1}\lst@ifnolol}
12495
\def\lst@nololtrue{\let\lst@ifnolol\iftrue}
12496
\let\lst@ifnolol\iffalse % init
12501
% \subsection{Floats, boxes and captions}
12503
% \begin{lstkey}{captionpos}
12504
% \begin{lstkey}{abovecaptionskip}
12505
% \begin{lstkey}{belowcaptionskip}
12506
% \begin{lstkey}{label}
12507
% \begin{lstkey}{title}
12508
% \begin{lstkey}{caption}
12509
% Some keys and \ldots
12510
% \begin{macrocode}
12511
\lst@Key{captionpos}{t}{\def\lst@captionpos{#1}}
12512
\lst@Key{abovecaptionskip}\smallskipamount{\def\lst@abovecaption{#1}}
12513
\lst@Key{belowcaptionskip}\smallskipamount{\def\lst@belowcaption{#1}}
12515
% \lsthelper{Rolf~Niepraschk}{2000/01/10}{key: title} proposed \keyname{title}.
12516
% \begin{macrocode}
12517
\lst@Key{label}\relax{\def\lst@label{#1}}
12518
\lst@Key{title}\relax{\def\lst@title{#1}\let\lst@caption\relax}
12519
\lst@Key{caption}\relax{\lstKV@OptArg[{#1}]{#1}%
12520
{\def\lst@caption{##2}\def\lst@@caption{##1}}%
12521
\let\lst@title\@empty}
12522
\lst@AddToHookExe{TextStyle}
12523
{\let\lst@caption\@empty \let\lst@@caption\@empty
12524
\let\lst@title\@empty \let\lst@label\@empty}
12533
% \begin{macro}{\thelstlisting}
12534
% \begin{macro}{\lstlistingname}
12535
% \ldots\space and how the caption numbers look like. I switched to
12536
% |\@ifundefined| (instead of |\ifx| |\@undefined|) after an error report from
12537
% \lsthelper{Denis~Girou}{1999/07/26}{incompatible if hyperref loaded before
12539
% \begin{macrocode}
12540
\@ifundefined{thechapter}
12541
{\newcounter{lstlisting}
12542
\renewcommand\thelstlisting{\@arabic\c@lstlisting}}
12543
{\newcounter{lstlisting}[chapter]
12544
\renewcommand\thelstlisting
12545
{\ifnum \c@chapter>\z@ \thechapter.\fi \@arabic\c@lstlisting}}
12547
% \begin{macrocode}
12548
\lst@UserCommand\lstlistingname{Listing}
12553
% \begin{macro}{\lst@MakeCaption}
12554
% Before defining this macro, we ensure that some other control sequences
12555
% exist---\lsthelper{Adam~Prugel-Bennett}{2001/02/19}{\abovecaptionskip
12556
% undefined in slides.cls} reported problems with the slides document class.
12557
% In particular we allocate above- and belowcaption skip registers and define
12558
% |\@makecaption|, which is an exact copy of the definition in the article
12559
% class. To respect the LPPL: you should have a copy of this class on your
12560
% \TeX\ system or you can obtain a copy from the CTAN, e.g.~from the ftp-server
12561
% \texttt{ftp.dante.de}.
12562
% \begin{macrocode}
12563
\@ifundefined{abovecaptionskip}
12564
{\newskip\abovecaptionskip
12565
\newskip\belowcaptionskip
12566
\long\def\@makecaption#1#2{%
12567
\vskip\abovecaptionskip
12568
\sbox\@tempboxa{#1: #2}%
12569
\ifdim \wd\@tempboxa >\hsize
12572
\global \@minipagefalse
12573
\hb@xt@\hsize{\hfil\box\@tempboxa\hfil}%
12575
\vskip\belowcaptionskip}%
12578
% We |\refstepcounter| the listing counter if and only if |\lst@@caption| is
12579
% not empty. Otherwise we ensure correct hyper-references,
12580
% see |\lst@HRefStepCounter| below. We do this once a listing, namely at the
12582
% \begin{macrocode}
12583
\def\lst@MakeCaption#1{%
12585
\ifx\lst@@caption\@empty\expandafter\lst@HRefStepCounter \else
12586
\expandafter\refstepcounter
12588
\ifx\lst@label\@empty\else \label{\lst@label}\fi
12591
% We make a caption if and only if the caption is not empty and the user
12592
% requested a caption at |#1| $\in\{\mathtt t,\mathtt b\}$. To disallow
12593
% pagebreaks between caption (or title) and a listing, we redefine the
12594
% primitive |\vskip| locally to insert |\nobreak|s. Note that we allow
12595
% pagebreaks in front of a `top-caption' and after a `bottom-caption'.
12597
% This redefinition is a brute force method. Is there a better one?
12599
% \begin{macrocode}
12600
\ifx\lst@caption\@empty\else
12601
\lst@IfSubstring #1\lst@captionpos
12602
{\begingroup \let\@@vskip\vskip
12603
\def\vskip{\afterassignment\lst@vskip \@tempskipa}%
12604
\def\lst@vskip{\nobreak\@@vskip\@tempskipa\nobreak}%
12605
\par\normalsize\normalfont
12606
\ifx #1t\allowbreak \fi
12607
\ifx\lst@title\@empty
12608
\expandafter\@makecaption
12610
\expandafter\lst@maketitle
12612
{\noindent\lstlistingname
12613
\ifx\lst@@caption\@empty\else~\thelstlisting\fi}%
12615
\ifx #1b\allowbreak \fi
12619
% I've inserted |\normalsize| after a bug report from
12620
% \lsthelper{Andreas~Matthias}{2000/01/04}{caption affected by basicstyle}
12621
% and moved it in front of |\@makecaption| after receiving another from
12622
% \lsthelper{Sonja~Weidmann}{2000/02/01}{listings and caption packages
12626
% \begin{macro}{\lst@maketitle}
12627
% This definition depends on the existence of the \packagename{caption}
12628
% package. The default gobbles the delimiter and ignores spaces. Note that
12629
% this definition isn't compatible with all packages and classes.
12630
% \begin{macrocode}
12631
\def\lst@maketitle#1#2{\@makecaption\lst@title@dropdelim\lst@title}
12632
\def\lst@title@dropdelim#1{\ignorespaces}
12634
% For \packagename{caption2} we modify the caption style locally and make this
12636
% \begin{macrocode}
12638
\@ifundefined{caption@make}{}{%
12639
\def\lst@maketitle#1#2{%
12641
\captionstyle{lsttitle}\@makecaption{}\lst@title
12644
% \ldots\space print only the title = caption text.
12645
% \begin{macrocode}
12646
\newcaptionstyle{lsttitle}{\caption@make{lsttitle}}%
12647
\def\caption@@@lsttitle{\captiontext\par}%
12652
% \begin{macro}{\lst@HRefStepCounter}
12653
% This macro sets the listing number to a negative value since the user
12654
% shouldn't refer to such a listing. If the \packagename{hyperref} package
12655
% is present, we use `lstlisting' (argument from above) to hyperref to.
12656
% The groups have been added to prevent other packages (namely
12657
% \packagename{tabularx}) from reading the locally changed counter
12658
% and writing it back globally. Thanks to \lsthelper{Michael~Niedermair}
12659
% {2001/09/18}{strange numbering of listings} for the report. Unfortunately
12660
% this localization led to another bug, see |\theHlstnumber|.
12661
% \begin{macrocode}
12662
\def\lst@HRefStepCounter#1{%
12664
\c@lstlisting\lst@neglisting
12665
\advance\c@lstlisting\m@ne \xdef\lst@neglisting{\the\c@lstlisting}%
12666
\ifx\hyper@refstepcounter\@undefined\else
12667
\hyper@refstepcounter{#1}%
12670
\gdef\lst@neglisting{\z@}% init
12674
% \begin{lstkey}{boxpos}
12675
% \begin{macro}{\lst@boxtrue}
12676
% sets the vertical alignment of the (possibly) used box respectively indicates
12677
% that a box is used.
12678
% \begin{macrocode}
12679
\lst@Key{boxpos}{c}{\def\lst@boxpos{#1}}
12681
% \begin{macrocode}
12682
\def\lst@boxtrue{\let\lst@ifbox\iftrue}
12683
\let\lst@ifbox\iffalse
12685
% \end{macro}\end{lstkey}
12687
% \begin{lstkey}{float}
12688
% \begin{lstkey}{floatplacement}
12689
% Matthias Zenger asked for double-column floats, so I've inserted some code.
12690
% We first check for a star \ldots
12691
% \begin{macrocode}
12692
\lst@Key{float}\relax[\lst@floatplacement]{%
12693
\def\lst@next{\@ifstar{\let\lst@beginfloat\@dblfloat
12694
\let\lst@endfloat\end@dblfloat
12696
{\let\lst@beginfloat\@float
12697
\let\lst@endfloat\end@float
12699
\edef\lst@float{#1}%
12700
\expandafter\lst@next\lst@float\relax}
12702
% \ldots\ and define |\lst@float|.
12703
% \begin{macrocode}
12704
\def\lst@KFloat#1\relax{%
12705
\ifx\@empty#1\@empty
12706
\let\lst@float\lst@floatplacement
12708
\def\lst@float{#1}%
12711
% \begin{macrocode}
12712
\lst@Key{floatplacement}{tbp}{\def\lst@floatplacement{#1}}
12713
\lst@AddToHook{PreSet}{\let\lst@float\relax}
12714
\lst@AddToHook{TextStyle}{\let\lst@float\relax}
12716
% The float type |\ftype@lstlisting| is set according to whether the
12717
% \packagename{float} package is loaded and whether \texttt{figure} and
12718
% \texttt{table} floats are defined. This is done at |\begin{document}| to
12719
% make the code independent of the order of package loading.
12720
% \begin{macrocode}
12722
\@ifundefined{c@float@type}%
12723
{\edef\ftype@lstlisting{\ifx\c@figure\@undefined 1\else 4\fi}}
12724
{\edef\ftype@lstlisting{\the\c@float@type}%
12725
\addtocounter{float@type}{\value{float@type}}}%
12732
% \subsection{Init and EOL}
12734
% \begin{lstkey}{aboveskip}
12735
% \begin{lstkey}{belowskip}
12736
% We define and initialize these keys and prevent extra spacing for `inline'
12737
% listings (in particular if \packagename{fancyvrb} interface is active,
12738
% problem reported by \lsthelper{Denis~Girou}{1999/08/03}{wrong spacing}).
12739
% \begin{macrocode}
12740
\lst@Key{aboveskip}\medskipamount{\def\lst@aboveskip{#1}}
12741
\lst@Key{belowskip}\medskipamount{\def\lst@belowskip{#1}}
12742
\lst@AddToHook{TextStyle}
12743
{\let\lst@aboveskip\z@ \let\lst@belowskip\z@}
12745
% \end{lstkey}\end{lstkey}
12747
% \begin{lstkey}{everydisplay}
12748
% \begin{macro}{\lst@ifdisplaystyle}
12749
% Some things depend on display-style listings.
12750
% \begin{macrocode}
12751
\lst@Key{everydisplay}{}{\def\lst@EveryDisplay{#1}}
12752
\lst@AddToHook{TextStyle}{\let\lst@ifdisplaystyle\iffalse}
12753
\lst@AddToHook{DisplayStyle}{\let\lst@ifdisplaystyle\iftrue}
12754
\let\lst@ifdisplaystyle\iffalse
12759
% \begin{macro}{\lst@Init}
12760
% Begin a float if requested.
12761
% \begin{macrocode}
12764
\ifx\lst@float\relax\else
12765
\edef\@tempa{\noexpand\lst@beginfloat{lstlisting}[\lst@float]}%
12766
\expandafter\@tempa
12769
% In restricted horizontal \TeX\ mode we switch to |\lst@boxtrue|.
12770
% In that case we make appropriate box(es) around the listing.
12771
% \begin{macrocode}
12772
\ifhmode\ifinner \lst@boxtrue \fi\fi
12776
$\if t\lst@boxpos \vtop
12777
\else \if b\lst@boxpos \vbox
12778
\else \vcenter \fi\fi
12779
\bgroup \par\noindent
12781
\lst@ifdisplaystyle
12783
\par\penalty-50\relax
12784
\vspace\lst@aboveskip
12788
% Moved |\vspace| after |\par|---or we can get an empty line atop listings.
12789
% Bug reported by \lsthelper{Jim~Hefferon}{1999/08/27}{empty line before
12790
% listings with |\lstinputlisting|}.
12792
% Now make the top caption.
12793
% \begin{macrocode}
12795
\abovecaptionskip\lst@abovecaption\relax
12796
\belowcaptionskip\lst@belowcaption\relax
12797
\lst@MakeCaption t%
12799
% Some initialization.
12800
% I removed |\par\nointerlineskip| |\normalbaselines| after bug report from
12801
% \lsthelper{Jim~Hefferon}{1999/08/23}{bad vertical space after lstlisting}.
12802
% He reported the same problem as Aidan Philip Heerdegen (see below), but I
12803
% immediately saw the bug here since Jim used |\parskip|$\,\neq0$.
12804
% \begin{macrocode}
12805
\lsthk@PreInit \lsthk@Init
12806
\lst@ifdisplaystyle
12807
\global\let\lst@ltxlabel\@empty
12809
\lst@ifresetmargins
12812
\xdef\lst@ltxlabel{\the\everypar}%
12813
\lst@AddTo\lst@ltxlabel{%
12814
\global\let\lst@ltxlabel\@empty
12815
\everypar{\lsthk@EveryLine\lsthk@EveryPar}}%
12818
\everypar\expandafter{\lst@ltxlabel
12819
\lsthk@EveryLine\lsthk@EveryPar}%
12821
\everypar{}\let\lst@NewLine\@empty
12823
\lsthk@InitVars \lsthk@InitVarsBOL
12825
% The end of line character chr(13)=|^^M| controls the processing, see the
12826
% definition of |\lst@MProcessListing| below.
12827
% The argument |#1| is either |\relax| or |\lstenv@backslash|.
12828
% \begin{macrocode}
12829
\lst@Let{13}\lst@MProcessListing
12830
\let\lst@Backslash#1%
12831
\lst@EnterMode{\lst@Pmode}{\lst@SelectCharTable}}
12833
% Note: From version 0.19 on `listing processing' is implemented as an internal
12834
% mode, namely a mode with special character table.
12835
% \begin{macrocode}
12836
\lst@AddToHook{InitVars}
12837
{\rightskip\z@ \leftskip\z@ \parfillskip=\z@ plus 1fil
12839
\lst@AddToHook{EveryLine}{}% init
12840
\lst@AddToHook{EveryPar}{}% init
12844
% \begin{lstkey}{showlines}
12845
% lets the user control whether empty lines at the end of a listing are
12846
% printed. But you know that if you've read the User's guide.
12847
% \begin{macrocode}
12848
\lst@Key{showlines}f[t]{\lstKV@SetIf{#1}\lst@ifshowlines}
12852
% \begin{macro}{\lst@DeInit}
12853
% Output the remaining characters and update all things. First I missed to
12854
% to use |\lst@ifdisplaystyle| here, but then \lsthelper{KP~Gores}{2001/07/11}
12855
% {\csname{par} after each \lstinline} reported a problem.
12856
% \begin{macrocode}
12858
\lst@XPrintToken \lst@EOLUpdate
12859
\global\advance\lst@newlines\m@ne
12863
\setbox\@tempboxa\vbox{\lst@DoNewLines}%
12865
\lst@ifdisplaystyle \par\removelastskip \fi
12866
\everypar{}\lsthk@ExitVars \lsthk@DeInit
12868
% Making the bottom caption.
12869
% \begin{macrocode}
12870
\lst@MakeCaption b%
12872
% Close the boxes if necessary and make a rule to get the right width.
12873
% I added the |\par\nointerlineskip| (and removed |\nointerlineskip| later
12874
% again) after receiving a bug report from \lsthelper{Aidan~Philip~Heerdegen}
12875
% {1999/07/23}{wrong vertical spacing}. |\everypar{}| is due to a bug report
12876
% from \lsthelper{Sonja~Weidmann}{2000/02/01}{listings and caption packages
12878
% \begin{macrocode}
12880
\egroup $\hss \egroup
12881
\vrule\@width\lst@maxwidth\@height\z@\@depth\z@
12883
\lst@ifdisplaystyle
12884
\par\penalty-50\vspace\lst@belowskip
12888
% End the float if necessary.
12889
% \begin{macrocode}
12890
\ifx\lst@float\relax\else
12891
\expandafter\lst@endfloat
12897
% \begin{macro}{\lst@maxwidth}
12898
% is to be allocated, initialized and updated.
12899
% \begin{macrocode}
12900
\newdimen\lst@maxwidth % \global
12901
\lst@AddToHook{InitVars}{\global\lst@maxwidth\z@}
12902
\lst@AddToHook{InitVarsEOL}
12903
{\ifdim\lst@currlwidth>\lst@maxwidth
12904
\global\lst@maxwidth\lst@currlwidth
12909
% \begin{macro}{\lst@EOLUpdate}
12910
% What do you think this macro does?
12911
% \begin{macrocode}
12912
\def\lst@EOLUpdate{\lsthk@EOL \lsthk@InitVarsEOL}
12916
% \begin{macro}{\lst@MProcessListing}
12917
% This is what we have to do at EOL while processing a listing.
12918
% We output all remaining characters and update the variables.
12919
% We call |\lst@EndProcessListing| if the next line number is greater than the
12920
% last printing line.
12921
% Finally we gobble characters to come to the beginning of the next line.
12922
% \begin{macrocode}
12923
\def\lst@MProcessListing{%
12924
\lst@XPrintToken \lst@EOLUpdate \lsthk@InitVarsBOL
12925
\global\advance\lst@lineno\@ne
12926
\ifnum \lst@lineno>\lst@lastline
12927
\expandafter\lst@EndProcessListing
12929
\expandafter\lst@BOLGobble
12934
% \begin{macro}{\lst@EndProcessListing}
12935
% Default definition is |\endinput|.
12936
% This works for |\lstinputlisting|.
12937
% \begin{macrocode}
12938
\let\lst@EndProcessListing\endinput
12942
% \begin{lstkey}{gobble}
12943
% The key sets the number of characters to gobble each line.
12944
% \begin{macrocode}
12945
\lst@Key{gobble}{0}{\def\lst@gobble{#1}}
12949
% \begin{macro}{\lst@BOLGobble}
12950
% If the number is positive, we set a temporary counter and start a loop.
12951
% \begin{macrocode}
12952
\def\lst@BOLGobble{%
12953
\ifnum\lst@gobble>\z@
12954
\@tempcnta\lst@gobble\relax
12955
\expandafter\lst@BOLGobble@
12958
% A nonpositive number terminates the loop (by not continuing).
12959
% Note: This is not the macro just used in |\lst@BOLGobble|.
12960
% \begin{macrocode}
12961
\def\lst@BOLGobble@@{%
12962
\ifnum\@tempcnta>\z@
12963
\expandafter\lst@BOLGobble@
12966
% If we gobble a backslash, we have to look whether this backslash ends an
12967
% environment. Whether the coming characters equal e.g.~|end{lstlisting}|,
12968
% we either end the environment or insert all just eaten characters after the
12969
% `continue loop' macro.
12970
% \begin{macrocode}
12971
\def\lstenv@BOLGobble@@{%
12972
\lst@IfNextChars\lstenv@endstring{\lstenv@End}%
12973
{\advance\@tempcnta\m@ne \expandafter\lst@BOLGobble@@\lst@eaten}}
12975
% Now comes the loop: if we read |\relax|, EOL or FF, the next operation is
12976
% exactly the same token.
12977
% \begin{macrocode}
12978
\def\lst@BOLGobble@#1{%
12980
\ifx \lst@next\relax\else
12981
\ifx \lst@next\lst@MProcessListing\else
12982
\ifx \lst@next\lst@ProcessFormFeed\else
12984
% Otherwise we use one of the two submacros.
12985
% \begin{macrocode}
12986
\ifx \lst@next\lstenv@backslash
12987
\let\lst@next\lstenv@BOLGobble@@
12989
\let\lst@next\lst@BOLGobble@@
12991
% Now we really gobble characters. A tabulator decreases the temporary counter
12992
% by |\lst@tabsize| (and deals with remaining amounts, if necessary), \ldots
12993
% \begin{macrocode}
12994
\ifx #1\lst@ProcessTabulator
12995
\advance\@tempcnta-\lst@tabsize\relax
12996
\ifnum\@tempcnta<\z@
12997
\lst@length-\@tempcnta \lst@PreGotoTabStop
13000
% \ldots\space whereas any other character decreases the counter by one.
13001
% \begin{macrocode}
13003
\advance\@tempcnta\m@ne
13011
% \subsection{List of listings}
13013
% \begin{lstkey}{name}
13014
% \begin{macro}{\lstname}
13015
% \begin{macro}{\lst@name}
13016
% \begin{macro}{\lst@intname}
13017
% Each pretty-printing command values |\lst@intname| before setting any keys.
13018
% \begin{macrocode}
13019
\lst@Key{name}\relax{\def\lst@intname{#1}}
13020
\lst@AddToHookExe{PreSet}{\global\let\lst@intname\@empty}
13021
\lst@AddToHook{PreInit}{%
13022
\let\lst@arg\lst@intname \lst@ReplaceIn\lst@arg\lst@filenamerpl
13023
\global\let\lst@name\lst@arg \global\let\lstname\lst@name}
13025
% Use of |\lst@ReplaceIn| removes a bug first reported by
13026
% \lsthelper{Magne~Rudshaug}{1998/01/09}{_ and list of listings}.
13027
% Here is the replacement list.
13028
% \begin{macrocode}
13029
\def\lst@filenamerpl{_\textunderscore $\textdollar -\textendash}
13036
% \begin{macro}{\l@lstlisting}
13037
% prints one `lol' line.
13038
% \begin{macrocode}
13039
\def\l@lstlisting#1#2{\@dottedtocline{1}{1.5em}{2.3em}{#1}{#2}}
13041
% We make a `lol' entry if the name is neither empty nor a single space.
13042
% But we test |\lst@|(|@|)|caption| and |\lst@ifnolol| first.
13043
% \begin{macrocode}
13044
\lst@AddToHook{Init}
13046
\ifx\lst@@caption\@empty
13047
\ifx\lst@caption\@empty
13048
\ifx\lst@intname\@empty \else \def\lst@temp{ }%
13049
\ifx\lst@intname\lst@temp \else
13050
\addcontentsline{lol}{lstlisting}\lst@name
13054
\addcontentsline{lol}{lstlisting}%
13055
{\protect\numberline{\thelstlisting}\lst@@caption}%
13061
% \begin{macro}{\lstlistlistingname}
13062
% contains simply the header name.
13063
% \begin{macrocode}
13064
\lst@UserCommand\lstlistlistingname{Listings}
13068
% \begin{macro}{\lstlistoflistings}
13069
% We make local adjustments and call |\tableofcontents|. This way,
13070
% redefinitions of that macro (e.g.~without any |\MakeUppercase| inside)
13071
% also take effect on the list of listings.
13072
% \begin{macrocode}
13073
\lst@UserCommand\lstlistoflistings{\bgroup
13074
\let\contentsname\lstlistlistingname
13075
\let\lst@temp\@starttoc \def\@starttoc##1{\lst@temp{lol}}%
13076
\tableofcontents \egroup}
13081
% \subsection{Inline listings}\label{iInlineListings}
13083
% \begin{macro}{\lstinline}
13084
% In addition to |\lsthk@PreSet|, we use |boxpos=b| and flexiblecolumns.
13085
% I've inserted |\leavevmode| after bug report from \lsthelper{Michael~Weber}
13086
% {1999/12/16}{wrong spacing in list environments}. \lsthelper{Olivier~Lecarme}
13087
% {2001/07/30}{inconsistent `break' when \lstinline is used inside caption}
13088
% reported a problem which has gone after removing |\let| |\lst@newlines|
13089
% |\@empty| (now |\lst@newlines| is a counter!). Unfortunately I don't know
13090
% the reason for inserting this code some time ago! At the end of the macro we
13091
% check the delimiter.
13092
% \begin{macrocode}
13093
\newcommand\lstinline[1][]{%
13094
\leavevmode\bgroup % \hbox\bgroup --> \bgroup
13095
\def\lst@boxpos{b}%
13096
\lsthk@PreSet\lstset{flexiblecolumns,#1}%
13098
\@ifnextchar\bgroup{\afterassignment\lst@InlineG \let\@let@token}%
13100
\def\lstinline@#1{%
13102
\lst@IfNextCharActive{\lst@InlineM#1}{\lst@InlineJ#1}}
13103
\lst@AddToHook{TextStyle}{}% init
13105
% \begin{macrocode}
13106
\lst@AddToHook{SelectCharTable}{\lst@inlinechars}
13107
\global\let\lst@inlinechars\@empty
13111
% \begin{macro}{\lst@InlineM}
13112
% \begin{macro}{\lst@InlineJ}
13113
% treat the cases of `normal' inlines and inline listings inside an argument.
13114
% In the first case the given character ends the inline listing and EOL within
13115
% such a listing immediately ends it and produces an error message.
13116
% \begin{macrocode}
13117
\def\lst@InlineM#1{\gdef\lst@inlinechars{%
13118
\lst@Def{`#1}{\lst@DeInit\egroup\global\let\lst@inlinechars\@empty}%
13119
\lst@Def{13}{\lst@DeInit\egroup \global\let\lst@inlinechars\@empty
13120
\PackageError{Listings}{lstinline ended by EOL}\@ehc}}%
13123
% In the other case we get all characters up to |#1|, make these characters
13124
% active, execute (typeset) them and end the listing (all via temporary macro).
13125
% That's all about it.
13126
% \begin{macrocode}
13127
\def\lst@InlineJ#1{%
13128
\def\lst@temp##1#1{%
13129
\let\lst@arg\@empty \lst@InsideConvert{##1}\lst@arg
13130
\lst@DeInit\egroup}%
13136
% \begin{macro}{\lst@InlineG}
13138
% \begin{macrocode}
13141
\lst@IfNextCharActive{\lst@InlineM\}}%
13142
{\let\lst@arg\@empty \lst@InlineGJ}}
13143
\def\lst@InlineGJ{\futurelet\@let@token\lst@InlineGJTest}
13144
\def\lst@InlineGJTest{%
13145
\ifx\@let@token\egroup
13146
\afterassignment\lst@InlineGJEnd
13147
\expandafter\let\expandafter\@let@token
13149
\ifx\@let@token\@sptoken
13150
\let\lst@next\lst@InlineGJReadSp
13152
\let\lst@next\lst@InlineGJRead
13154
\expandafter\lst@next
13156
\def\lst@InlineGJEnd{\lst@arg\lst@DeInit\egroup}
13157
\def\lst@InlineGJRead#1{%
13158
\lccode`\~=`#1\lowercase{\lst@lAddTo\lst@arg~}%
13160
\def\lst@InlineGJReadSp#1{%
13161
\lccode`\~=`\ \lowercase{\lst@lAddTo\lst@arg~}%
13164
% \begin{macrocode}
13169
% \subsection{The input command}\label{iTheInputCommand}
13171
% \begin{macro}{\lstinputlisting}
13172
% inputs the listing or asks the user for a new file name.
13173
% \begin{macrocode}
13174
\newcommand\lstinputlisting[2][]{%
13177
{\lst@InputListing{#2}}%
13178
{\filename@parse{#2}%
13179
\edef\reserved@a{\noexpand\lst@MissingFileError
13180
{\filename@area\filename@base}%
13181
{\ifx\filename@ext\relax tex\else\filename@ext\fi}}%
13183
\@doendpe \@newlistfalse \ignorespaces}
13185
% We use |\@doendpe| to remove indention at the beginning of the next
13186
% line---except there is an empty line after |\lstinputlisting|. Bug was
13187
% reported by \lsthelper{David~John~Evans}{1999/06/08}{indention after
13188
% listings} and \lsthelper{David~Carlisle}{1999/06/08}{LaTeX `display
13189
% environment' code} pointed me to the solution.
13192
% \begin{macro}{\lst@MissingFileError}
13193
% is a derivation of \LaTeX's |\@missingfileerror|:
13194
% \begin{macrocode}
13195
\def\lst@MissingFileError#1#2{%
13196
\typeout{^^J! Package Listings Error: File `#1.#2' not found.^^J^^J%
13197
Type X to quit or <RETURN> to proceed,^^J%
13198
or enter new name. (Default extension: #2)^^J}%
13199
\message{Enter file name: }%
13200
{\endlinechar\m@ne \global\read\m@ne to\@gtempa}%
13202
% Typing |x| or |X| exits.
13203
% \begin{macrocode}
13204
\ifx\@gtempa\@empty \else
13205
\def\reserved@a{x}\ifx\reserved@a\@gtempa\batchmode\@@end\fi
13206
\def\reserved@a{X}\ifx\reserved@a\@gtempa\batchmode\@@end\fi
13208
% In all other cases we try the new file name.
13209
% \begin{macrocode}
13210
\filename@parse\@gtempa
13211
\edef\filename@ext{%
13212
\ifx\filename@ext\relax#2\else\filename@ext\fi}%
13213
\edef\reserved@a{\noexpand\IfFileExists %
13214
{\filename@area\filename@base.\filename@ext}%
13215
{\noexpand\lst@InputListing %
13216
{\filename@area\filename@base.\filename@ext}}%
13217
{\noexpand\lst@MissingFileError
13218
{\filename@area\filename@base}{\filename@ext}}}%
13219
\expandafter\reserved@a %
13224
% \begin{macro}{\lst@ifdraft}
13225
% makes use of |\lst@ifprint|.
13226
% \begin{macrocode}
13227
\let\lst@ifdraft\iffalse
13228
\DeclareOption{draft}{\let\lst@ifdraft\iftrue}
13229
\lst@AddToHook{PreSet}
13231
\let\lst@ifprint\iffalse
13237
% \begin{macro}{\lst@InputListing}
13238
% The one and only argument is the file name, but we have the `implicit'
13239
% argument |\lst@set|. Note that |\lst@Init| takes |\relax| as argument.
13240
% \begin{macrocode}
13241
\def\lst@InputListing#1{%
13243
\lsthk@PreSet \gdef\lst@intname{#1}%
13244
\expandafter\lstset\expandafter{\lst@set}%
13245
\lsthk@DisplayStyle
13246
\lst@Init\relax \let\lst@gobble\z@
13248
\lst@ifprint \def\lst@next{\input{#1}}%
13249
\else \let\lst@next\@empty \fi
13256
% \begin{macro}{\lst@SkipToFirst}
13257
% The end of line character either processes the listing or is responsible for
13258
% dropping lines up to first printing line.
13259
% \begin{macrocode}
13260
\def\lst@SkipToFirst{%
13261
\ifnum \lst@lineno<\lst@firstline
13263
% We drop the input and redefine the end of line characters.
13264
% \begin{macrocode}
13265
\lst@BeginDropInput\lst@Pmode
13266
\lst@Let{13}\lst@MSkipToFirst
13267
\lst@Let{10}\lst@MSkipToFirst
13269
\expandafter\lst@BOLGobble
13274
% \begin{macro}{\lst@MSkipToFirst}
13275
% We just look whether to drop more lines or to leave the mode which restores
13276
% the definition of chr(13) and chr(10).
13277
% \begin{macrocode}
13278
\def\lst@MSkipToFirst{%
13279
\global\advance\lst@lineno\@ne
13280
\ifnum \lst@lineno=\lst@firstline
13281
\lst@LeaveMode \global\lst@newlines\z@
13283
\expandafter\lst@BOLGobble
13289
% \subsection{The environment}
13292
% \subsubsection{Low-level processing}
13294
% \begin{macro}{\lstenv@DroppedWarning}
13295
% gives a warning if characters have been dropped.
13296
% \begin{macrocode}
13297
\def\lstenv@DroppedWarning{%
13298
\ifx\lst@dropped\@undefined\else
13299
\PackageWarning{Listings}{Text dropped after begin of listing}%
13301
\let\lst@dropped\@undefined % init
13305
% \begin{macro}{\lstenv@Process}
13306
% We execute `|\lstenv@ProcessM|' or |\lstenv@ProcessJ| according to whether we
13307
% find an active EOL or a nonactive |^^J|.
13308
% \begin{macrocode}
13309
\begingroup \lccode`\~=`\^^M\lowercase{%
13310
\gdef\lstenv@Process#1{%
13313
% We make no extra |\lstenv@ProcessM| definition since there is nothing to do
13314
% at all if we've found an active EOL.
13315
% \begin{macrocode}
13316
\lstenv@DroppedWarning \let\lst@next\lst@SkipToFirst
13318
\lstenv@DroppedWarning \let\lst@next\lstenv@ProcessJ
13320
\let\lst@dropped#1\let\lst@next\lstenv@Process
13327
% \begin{macro}{\lstenv@ProcessJ}
13328
% Now comes the horrible scenario: a listing inside an argument. We've
13329
% already worked in section \ref{iApplicationsTo} for this. Here we must get
13330
% all characters up to `end environment'. We distinguish the cases `command
13331
% fashion' and `true environment'.
13332
% \begin{macrocode}
13333
\def\lstenv@ProcessJ{%
13334
\let\lst@arg\@empty
13335
\ifx\@currenvir\lstenv@name
13336
\expandafter\lstenv@ProcessJEnv
13339
% The first case is pretty simple: The code is terminated by
13340
% |\end|\meta{name of environment}. Thus we expand that control sequence
13341
% before defining a temporary macro, which gets the listing and does all
13342
% the rest. Back to the definition of |\lstenv@ProcessJ| we call the
13343
% temporary macro after expanding |\fi|.
13344
% \begin{macrocode}
13345
\expandafter\def\expandafter\lst@temp\expandafter##1%
13346
\csname end\lstenv@name\endcsname
13347
{\lst@InsideConvert{##1}\lstenv@ProcessJ@}%
13348
\expandafter\lst@temp
13351
% We must append an active backslash and the `end string' to |\lst@arg|. So all
13352
% (in fact most) other processing won't notice that the code has been inside
13353
% an argument. But the EOL character is chr(10)=|^^J| now and not chr(13).
13354
% \begin{macrocode}
13355
\begingroup \lccode`\~=`\\\lowercase{%
13356
\gdef\lstenv@ProcessJ@{%
13357
\lst@lExtend\lst@arg
13358
{\expandafter\ \expandafter~\lstenv@endstring}%
13359
\catcode10=\active \lst@Let{10}\lst@MProcessListing
13361
% We execute |\lst@arg| to typeset the listing.
13362
% \begin{macrocode}
13363
\lst@SkipToFirst \lst@arg}
13368
% \begin{macro}{\lstenv@ProcessJEnv}
13369
% The `true environment' case is more complicated. We get all characters up to
13370
% an |\end| and the following argument. If that equals |\lstenv@name|, we have
13371
% found the end of environment and start typesetting.
13372
% \begin{macrocode}
13373
\def\lstenv@ProcessJEnv#1\end#2{\def\lst@temp{#2}%
13374
\ifx\lstenv@name\lst@temp
13375
\lst@InsideConvert{#1}%
13376
\expandafter\lstenv@ProcessJ@
13379
% Otherwise we append the characters including the eaten |\end| and the eaten
13380
% argument to current |\lst@arg|. And we look for the end of environment again.
13381
% \begin{macrocode}
13382
\lst@InsideConvert{#1\\end\{#2\}}%
13383
\expandafter\lstenv@ProcessJEnv
13388
% \begin{macro}{\lstenv@backslash}
13389
% Coming to a backslash we either end the listing or process a backslash and
13390
% insert the eaten characters again.
13391
% \begin{macrocode}
13392
\def\lstenv@backslash{%
13393
\lst@IfNextChars\lstenv@endstring
13395
{\expandafter\lsts@backslash \lst@eaten}}%
13399
% \begin{macro}{\lstenv@End}
13400
% This macro has just been used and terminates a listing environment:
13401
% We call the `end environment' macro using |\end| or as a command.
13402
% \begin{macrocode}
13404
\ifx\@currenvir\lstenv@name
13405
\edef\lst@next{\noexpand\end{\lstenv@name}}%
13407
\def\lst@next{\csname end\lstenv@name\endcsname}%
13414
% \subsubsection{\cs{lstnewenvironment}}
13416
% \begin{macro}{\lstnewenvironment}
13417
% Now comes the main command. We define undefined environments only. On the
13418
% parameter text |#1#2#| (in particular the last sharp) see the paragraph
13419
% following example 20.5 on page 204 of `The \TeX book'.
13420
% \begin{macrocode}
13421
\lst@UserCommand\lstnewenvironment#1#2#{%
13423
{\let\lst@arg\@empty
13424
\lst@XConvert{#1}\@nil
13425
\expandafter\lstnewenvironment@\lst@arg{#1}{#2}}%
13426
{\PackageError{Listings}{Environment `#1' already defined}\@eha
13428
\def\@tempa#1#2#3{%
13429
\gdef\lstnewenvironment@##1##2##3##4##5{%
13432
% A lonely `end environment' produces an error.
13433
% \begin{macrocode}
13434
\global\@namedef{end##2}{\lstenv@Error{##2}}%
13436
% The `main' environment macro defines the environment name for later use and
13437
% calls a submacro getting all arguments. We open a group and make EOL active.
13438
% This ensures |\@ifnextchar[| not to read characters of the listing---it reads
13439
% the active EOL instead.
13440
% \begin{macrocode}
13441
\global\@namedef{##2}{\def\lstenv@name{##2}%
13442
\begingroup \catcode\active=\active \csname##2@\endcsname}%
13444
% The submacro is defined via |\new@command|. We misuse |\l@ngrel@x| to make
13445
% the definition |\global| and refine \LaTeX's |\@xargdef|.
13446
% \begin{macrocode}
13447
\let\l@ngrel@x\global
13448
\let\@xargdef\lstenv@xargdef
13449
\expandafter\new@command\csname##2@\endcsname##3%
13451
% First we execute |##4|=\meta{begin code}. Then follows the definition of
13452
% the terminating string (|end{lstlisting}| or |endlstlisting|, for example):
13453
% \begin{macrocode}
13454
{\lsthk@PreSet ##4%
13455
\ifx\@currenvir\lstenv@name
13456
\def\lstenv@endstring{#1#2##1#3}%
13458
\def\lstenv@endstring{#1##1}%
13461
% We redefine (locally) `end environment' since ending is legal now.
13462
% Note that the redefinition also works inside a \TeX\ comment line.
13463
% \begin{macrocode}
13464
\@namedef{end##2}{\lst@DeInit ##5\endgroup
13465
\@doendpe \@ignoretrue}%
13467
% |\@doendpe| again removes the indention problem.
13468
% Finally we start the processing.
13469
% \begin{macrocode}
13470
\lsthk@DisplayStyle
13471
\lst@Init\lstenv@backslash
13472
\let\lst@EndProcessListing\lstenv@SkipToEnd
13474
\expandafter\expandafter\expandafter\lstenv@Process
13476
\expandafter\lstenv@SkipToEnd
13481
\let\lst@arg\@empty \lst@XConvert{end}\{\}\@nil
13482
\expandafter\@tempa\lst@arg
13483
\let\lst@insertargs\@empty
13487
% \begin{macro}{\lstenv@xargdef}
13488
% This is a derivation of \LaTeX's |\@xargdef|. We expand the submacro's name,
13489
% use |\gdef| instead of |\def|, and hard code a kind of |\@protected@testopt|.
13490
% \begin{macrocode}
13491
\def\lstenv@xargdef#1{
13492
\expandafter\lstenv@xargdef@\csname\string#1\endcsname#1}
13493
\def\lstenv@xargdef@#1#2[#3][#4]#5{%
13496
\ifx\protect\@typeset@protect
13497
\expandafter\lstenv@testopt
13511
% \begin{macro}{\lstenv@testopt}
13512
% The difference between this macro and |\@testopt| is that we temporaryly
13513
% reset the catcode of the EOL character |^^M| to read the optional argument.
13514
% \begin{macrocode}
13515
\long\def\lstenv@testopt#1#2{%
13516
\@ifnextchar[{\catcode\active5\relax \lstenv@testopt@#1}%
13518
\def\lstenv@testopt@#1[#2]{%
13519
\catcode\active\active
13524
% \begin{macro}{\lstenv@SkipToEnd}
13525
% We use the temporary definition
13526
% \begin{itemize}\item[]
13527
% |\long\def\lst@temp##1\|\meta{content of \textup{\cs{lstenv@endstring}}}|{\lstenv@End}|
13529
% which gobbles all characters up to the end of environment and finishes it.
13530
% \begin{macrocode}
13531
\begingroup \lccode`\~=`\\\lowercase{%
13532
\gdef\lstenv@SkipToEnd{%
13533
\long\expandafter\def\expandafter\lst@temp\expandafter##\expandafter
13534
1\expandafter~\lstenv@endstring{\lstenv@End}%
13540
% \begin{macro}{\lstenv@Error}
13541
% is called by a lonely `end environment'.
13542
% \begin{macrocode}
13543
\def\lstenv@Error#1{\PackageError{Listings}{Extra \string\end#1}%
13544
{I'm ignoring this, since I wasn't doing a \csname#1\endcsname.}}
13548
% \begin{macro}{\lst@TestEOLChar}
13549
% Here we test for the two possible EOL characters.
13550
% \begin{macrocode}
13551
\begingroup \lccode`\~=`\^^M\lowercase{%
13552
\gdef\lst@TestEOLChar#1{%
13553
\def\lst@insertargs{#1}%
13554
\ifx ~#1\@empty \else
13555
\ifx^^J#1\@empty \else
13556
\global\let\lst@intname\lst@insertargs
13557
\let\lst@insertargs\@empty
13563
% \begin{environment}{lstlisting}
13564
% The awkward work is done, the definition is quite easy now. We test whether
13565
% the user has given the name argument, set the keys, and deal with
13566
% continued line numbering.
13567
% \begin{macrocode}
13568
\lstnewenvironment{lstlisting}[2][]
13569
{\lst@TestEOLChar{#2}%
13571
\csname\@lst @SetFirstNumber\endcsname}
13572
{\csname\@lst @SaveFirstNumber\endcsname}
13574
% \begin{macrocode}
13577
% \end{environment}
13580
% \section{Documentation support}
13584
% |\begin{lstsample}|\marg{point list}\marg{left}\marg{right}
13586
% \leavevmode\hspace*{-\leftmargini}|\end{lstsample}|
13588
% Roughly speaking all material in between this environment is executed
13589
% `on the left side' and typeset verbatim on the right. \meta{left} is
13590
% executed before the left side is typeset, and similarly \meta{right}
13591
% before the right-hand side.
13593
% \meta{point list} is used as argument to the \keyname{point} key.
13594
% This is a special key used to highlight the keys in the examples.
13597
% |\begin{lstxsample}|\marg{point list}
13599
% \leavevmode\hspace*{-\leftmargini}|\end{lstxsample}|
13601
% The material in between is (a) added to the left side of the next
13602
% \texttt{lstsample} environment and (b) typeset verbatim using the
13603
% whole line width.
13605
% \item[0.21] |\newdocenvironment|\marg{name}\marg{short name}\marg{begin code}\marg{end code}
13607
% The \meta{name} environment can be used in the same way as `macro'.
13608
% The provided(!) definitions
13609
% |\Print|\meta{short name}|Name|
13610
% and |\SpecialMain|\meta{short name}|Index|
13611
% control printing in the margin and indexing as the defaults
13612
% |\PrintMacroName| and |\SpecialMainIndex| do.
13614
% This command is used to define the `aspect' and `lstkey' environments.
13616
%\item[0.21] \texttt{macroargs} environment
13618
% This `enumerate' environment uses as labels `|#1| =', `|#2| =',
13621
% \item \texttt{TODO} environment
13622
% \item \texttt{ALTERNATIVE} environment
13623
% \item \texttt{REMOVED} environment
13624
% \item \texttt{OLDDEF} environment
13626
% These environments enclose comments on `to do's', alternatives and
13627
% removed or old definitions.
13629
% \item[0.21] |\lstscanlanguages|\meta{list macro}\marg{input files}\marg{don't input}
13631
% scans \marg{input files}$\setminus$\marg{don't input} for language
13632
% definitions. The available languages are stored in \meta{list macro}
13633
% using the form \meta{language}|(|\meta{dialtect}|),|.
13635
% \item[0.21] |\lstprintlanguages|\meta{list macro}
13637
% prints the languages in two column format.
13639
% and a lot of more simple commands.
13642
% \subsection{Required packages}
13644
% Most of the `required' packages are optional.
13645
% \begin{macrocode}
13647
\let\lstdoc@currversion\fileversion
13648
\RequirePackage[writefile]{listings}[2002/04/01]
13649
\newif\iffancyvrb \IfFileExists{fancyvrb.sty}{\fancyvrbtrue}{}
13650
\newif\ifcolor \IfFileExists{color.sty}{\colortrue}{}
13651
\newif\ifhyper \@ifundefined{pdfoutput}{}
13652
{\IfFileExists{hyperref.sty}{\hypertrue}{}}
13653
\newif\ifalgorithmic \IfFileExists{algorithmic.sty}{\algorithmictrue}{}
13654
\iffancyvrb \RequirePackage{fancyvrb}\fi
13655
\ifhyper \RequirePackage[colorlinks]{hyperref}\else
13656
\def\href#1{\texttt}\fi
13657
\ifcolor \RequirePackage{color}\fi
13658
\ifalgorithmic \RequirePackage{algorithmic}\fi
13659
\RequirePackage{nameref}
13660
\renewcommand\ref{\protect\T@ref}
13661
\renewcommand\pageref{\protect\T@pageref}
13665
% \subsection{Environments for notes}
13667
% \begin{macro}{\lst@BeginRemark}
13668
% \begin{macro}{\lst@EndRemark}
13669
% We begin with two simple definitions \ldots
13670
% \begin{macrocode}
13671
\def\lst@BeginRemark#1{%
13672
\begin{quote}\topsep0pt\let\small\footnotesize\small#1:}
13673
\def\lst@EndRemark{\end{quote}}
13675
% \end{macro}\end{macro}
13677
% \begin{environment}{TODO}
13678
% \begin{environment}{ALTERNATIVE}
13679
% \begin{environment}{REMOVED}
13680
% \begin{environment}{OLDDEF}
13681
% \ldots\space used to define some environments.
13682
% \begin{macrocode}
13683
\newenvironment{TODO}
13684
{\lst@BeginRemark{To do}}{\lst@EndRemark}
13685
\newenvironment{ALTERNATIVE}
13686
{\lst@BeginRemark{Alternative}}{\lst@EndRemark}
13687
\newenvironment{REMOVED}
13688
{\lst@BeginRemark{Removed}}{\lst@EndRemark}
13689
\newenvironment{OLDDEF}
13690
{\lst@BeginRemark{Old definition}}{\lst@EndRemark}
13692
% \end{environment}\end{environment}\end{environment}\end{environment}
13694
% \begin{environment}{advise}
13695
% \begin{macro}{\advisespace}
13696
% The environment uses |\@listi|.
13697
% \begin{macrocode}
13698
\def\advise{\par\list\labeladvise
13699
{\advance\linewidth\@totalleftmargin
13700
\@totalleftmargin\z@
13702
\let\small\footnotesize \small\sffamily
13703
\parsep \z@ \@plus\z@ \@minus\z@
13704
\topsep6\p@ \@plus1\p@\@minus2\p@
13705
\def\makelabel##1{\hss\llap{##1}}}}
13706
\let\endadvise\endlist
13708
% \begin{macrocode}
13709
\def\advisespace{\hbox{}\qquad}
13710
\def\labeladvise{$\to$}
13713
% \end{environment}
13715
% \begin{environment}{syntax}
13716
% \begin{macro}{\syntaxbreak}
13717
% \begin{macro}{\syntaxnewline}
13718
% \begin{macro}{\syntaxor}
13719
% This environment uses |\list| with a special |\makelabel|, \ldots
13720
% \begin{macrocode}
13721
\newenvironment{syntax}
13722
{\list{}{\itemindent-\leftmargin
13723
\def\makelabel##1{\hss\lst@syntaxlabel##1,,,,\relax}}}
13726
% \ldots\ which is defined here. The comma separated items are placed as
13728
% \begin{macrocode}
13729
\def\lst@syntaxlabel#1,#2,#3,#4\relax{%
13730
\llap{\scriptsize\itshape#3}%
13732
\expandafter\lst@syntaxlabel@\meaning\lst@temp\relax
13733
\rlap{\hskip-\itemindent\hskip\itemsep\hskip\linewidth
13734
\llap{\ttfamily\lst@temp}\hskip\labelwidth
13736
\ifx\lst@temp\lstdoc@currversion#1\fi}}
13737
\def\lst@syntaxlabel@#1>#2\relax
13738
{\edef\lst@temp{\zap@space#2 \@empty}}
13740
% \begin{macrocode}
13741
\newcommand*\syntaxnewline{\newline\hbox{}\kern\labelwidth}
13742
\newcommand*\syntaxor{\qquad or\qquad}
13743
\newcommand*\syntaxbreak
13744
{\hfill\kern0pt\discretionary{}{\kern\labelwidth}{}}
13745
\let\syntaxfill\hfill
13750
% \end{environment}
13752
% \begin{macro}{\alternative}
13753
% iterates down the list and inserts vertical rule(s).
13754
% \begin{macrocode}
13755
\def\alternative#1{\lst@true \alternative@#1,\relax,}
13756
\def\alternative@#1,{%
13757
\ifx\relax#1\@empty
13758
\expandafter\@gobble
13760
\ifx\@empty#1\@empty\else
13761
\lst@if \lst@false \else $\vert$\fi
13762
\textup{\texttt{#1}}%
13770
% \subsection{Extensions to \textsf{doc}}
13772
% \begin{macro}{\m@cro@}
13773
% We need a slight modification of \packagename{doc}'s internal macro.
13774
% The former argument |#2| has become |#3|. This change is not marked below.
13775
% The second argument is now \meta{short name}.
13776
% \begin{macrocode}
13777
\long\def\m@cro@#1#2#3{\endgroup \topsep\MacroTopsep \trivlist
13778
\edef\saved@macroname{\string#3}%
13779
\def\makelabel##1{\llap{##1}}%
13781
\let\@tempa\@empty \count@\macro@cnt
13782
\loop \ifnum\count@>\z@
13783
\edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat
13784
\edef\makelabel##1{\llap{\vtop to\baselineskip
13785
{\@tempa\hbox{##1}\vss}}}%
13786
\advance \macro@cnt \@ne
13787
\else \macro@cnt\@ne \fi
13788
\edef\@tempa{\noexpand\item[%
13790
\noexpand\PrintMacroName
13793
% The next line has been modified.
13794
% \begin{macrocode}
13795
\expandafter\noexpand\csname Print#2Name\endcsname % MODIFIED
13799
\global\advance\c@CodelineNo\@ne
13801
\SpecialMainIndex{#3}\nobreak
13806
% \begin{macrocode}
13807
\csname SpecialMain#2Index\endcsname{#3}\nobreak % MODIFIED
13809
\global\advance\c@CodelineNo\m@ne
13814
% \begin{macro}{\macro}
13815
% \begin{macro}{\environment}
13816
% These two definitions need small adjustments due to the modified |\m@cro@|.
13817
% \begin{macrocode}
13818
\def\macro{\begingroup
13820
\MakePrivateLetters \m@cro@ \iftrue {Macro}}% MODIFIED
13821
\def\environment{\begingroup
13823
\MakePrivateLetters \m@cro@ \iffalse {Env}}% MODIFIED
13825
% \end{macro}\end{macro}
13827
% \begin{macro}{\newdocenvironment}
13828
% This command simply makes definitions similar to `environment' and provides
13829
% the printing and indexing commands.
13830
% \begin{macrocode}
13831
\def\newdocenvironment#1#2#3#4{%
13832
\@namedef{#1}{#3\begingroup \catcode`\\12\relax
13833
\MakePrivateLetters \m@cro@ \iffalse {#2}}%
13834
\@namedef{end#1}{#4\endmacro}%
13835
\@ifundefined{Print#2Name}{\expandafter
13836
\let\csname Print#2Name\endcsname\PrintMacroName}{}%
13837
\@ifundefined{SpecialMain#2Index}{\expandafter
13838
\let\csname SpecialMain#2Index\endcsname\SpecialMainIndex}{}}
13842
% \begin{environment}{aspect}
13843
% \begin{macro}{\PrintAspectName}
13844
% \begin{macro}{\SpecialMainAspectIndex}
13845
% The environment and its `print' and `index' commands.
13846
% \begin{macrocode}
13847
\newdocenvironment{aspect}{Aspect}{}{}
13848
\def\PrintAspectName#1{}
13849
\def\SpecialMainAspectIndex#1{%
13851
\index{aspects:\levelchar\protect\aspectname{#1}\encapchar main}%
13854
% \end{macro}\end{macro}\end{environment}
13856
% \begin{environment}{lstkey}
13857
% \begin{macro}{\PrintKeyName}
13858
% \begin{macro}{\SpecialMainKeyIndex}
13859
% One more environment with its `print' and `index' commands.
13860
% \begin{macrocode}
13861
\newdocenvironment{lstkey}{Key}{}{}
13862
\def\PrintKeyName#1{\strut\keyname{#1}\ }
13863
\def\SpecialMainKeyIndex#1{%
13865
\index{keys\levelchar\protect\keyname{#1}\encapchar main}%
13868
% \end{macro}\end{macro}\end{environment}
13870
% \begin{macro}{\labelargcount}
13871
% \begin{environment}{macroargs}
13872
% We just allocate a counter and use \LaTeX's |\list| to implement this
13874
% \begin{macrocode}
13875
\newcounter{argcount}
13876
\def\labelargcount{\texttt{\#\arabic{argcount}}\hskip\labelsep$=$}
13878
% \begin{macrocode}
13879
\def\macroargs{\list\labelargcount
13880
{\usecounter{argcount}\leftmargin=2\leftmargin
13881
\parsep \z@ \@plus\z@ \@minus\z@
13882
\topsep4\p@ \@plus\p@ \@minus2\p@
13883
\itemsep\z@ \@plus\z@ \@minus\z@
13884
\def\makelabel##1{\hss\llap{##1}}}}
13885
\def\endmacroargs{\endlist\@endparenv}
13887
% \end{environment}\end{macro}
13890
% \subsection{The \texttt{lstsample} environment}
13892
% \begin{environment}{lstsample}
13893
% We store the verbatim part and write the source code also to file.
13894
% \begin{macrocode}
13895
\lst@RequireAspects{writefile}
13897
% \begin{macrocode}
13898
\newbox\lst@samplebox
13899
\lstnewenvironment{lstsample}[3][]
13900
{\global\let\lst@intname\@empty
13901
\gdef\lst@sample{#2}%
13902
\setbox\lst@samplebox=\hbox\bgroup
13903
\setkeys{lst}{language={},style={},tabsize=4,gobble=5,%
13904
basicstyle=\small\ttfamily,basewidth=0.51em,point={#1}}
13906
\lst@BeginAlsoWriteFile{\jobname.tmp}}
13907
{\lst@EndWriteFile\egroup
13909
% Now |\lst@samplebox| contains the verbatim part.
13910
% If it's too wide, we use atop and below instead of left and right.
13911
% \begin{macrocode}
13912
\ifdim \wd\lst@samplebox>.5\linewidth
13914
\hbox to\linewidth{\box\lst@samplebox\hss}%
13919
\begin{minipage}{0.45\linewidth}\lst@sampleInput\end{minipage}%
13921
\begin{minipage}{0.45\linewidth}%
13922
\hbox to\linewidth{\box\lst@samplebox\hss}%
13927
% The new keyword class \keyname{point}.
13928
% \begin{macrocode}
13929
\lst@InstallKeywords{p}{point}{pointstyle}\relax{keywordstyle}{}ld
13931
% \end{environment}
13933
% \begin{environment}{lstxsample}
13934
% Omitting |\lst@EndWriteFile| leaves the file open.
13935
% \begin{macrocode}
13936
\lstnewenvironment{lstxsample}[1][]
13938
\setkeys{lst}{belowskip=-\medskipamount,language={},style={},%
13939
tabsize=4,gobble=5,basicstyle=\small\ttfamily,%
13940
basewidth=0.51em,point={#1}}
13941
\lst@BeginAlsoWriteFile{\jobname.tmp}}
13945
% \end{environment}
13947
% \begin{macro}{\lst@sampleInput}
13948
% inputs the `left-hand' side.
13949
% \begin{macrocode}
13950
\def\lst@sampleInput{%
13951
\MakePercentComment\catcode`\^^M=10\relax
13953
{\setkeys{lst}{SelectCharTable=\lst@ReplaceInput{\^\^I}%
13954
{\lst@ProcessTabulator}}%
13955
\leavevmode \input{\jobname.tmp}}\MakePercentIgnore}
13960
% \subsection{Miscellaneous}
13962
% \paragraph{Sectioning and cross referencing}
13963
% We begin with a redefinition paragraph.
13964
% \begin{macrocode}
13965
\renewcommand\paragraph{\@startsection{paragraph}{4}{\z@}%
13966
{1.25ex \@plus1ex \@minus.2ex}%
13968
{\normalfont\normalsize\bfseries}}
13970
% We introduce |\lstref| which prints section number together with its name.
13971
% \begin{macrocode}
13972
\def\lstref#1{\emph{\ref{#1} \nameref{#1}}}
13974
% Moreover we adjust the table of contents.
13975
% \begin{macrocode}
13976
\def\@part[#1]#2{\addcontentsline{toc}{part}{#1}%
13977
{\parindent\z@ \raggedright \interlinepenalty\@M
13978
\normalfont \huge \bfseries #2\markboth{}{}\par}%
13979
\nobreak\vskip 3ex\@afterheading}
13980
\renewcommand*\l@section[2]{%
13981
\addpenalty\@secpenalty
13982
\addvspace{.25em \@plus\p@}%
13983
\setlength\@tempdima{1.5em}%
13985
\parindent \z@ \rightskip \@pnumwidth
13986
\parfillskip -\@pnumwidth
13988
\advance\leftskip\@tempdima
13990
#1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
13992
\renewcommand*\l@subsection{\@dottedtocline{2}{0pt}{2.3em}}
13993
\renewcommand*\l@subsubsection{\@dottedtocline{3}{0pt}{3.2em}}
13996
% \paragraph{Indexing}
13997
% The `user' commands. |\rstyle| is defined below.
13998
% \begin{macrocode}
13999
\newcommand\ikeyname[1]{%
14000
\lstkeyindex{#1}{}%
14001
\lstaspectindex{#1}{}%
14003
\newcommand\ekeyname[1]{%
14005
\lstkeyindex{#1}{\encapchar usage}%
14006
\lstaspectindex{#1}{\encapchar usage}%
14008
\newcommand\rkeyname[1]{%
14010
\lstkeyindex{#1}{\encapchar main}%
14011
\lstaspectindex{#1}{\encapchar main}%
14012
\@esphack{\rstyle\keyname{#1}}}
14014
% \begin{macrocode}
14015
\newcommand\icmdname[1]{%
14017
\lstaspectindex{#1}{}%
14018
\@esphack\texttt{\string#1}}
14019
\newcommand\rcmdname[1]{%
14021
\lstaspectindex{#1}{\encapchar main}%
14022
\@esphack\texttt{\rstyle\string#1}}
14024
% One of the two yet unknown `index'-macros is empty, the other looks up
14025
% the aspect name for the given argument.
14026
% \begin{macrocode}
14027
\def\lstaspectindex#1#2{%
14028
\global\@namedef{lstkandc@\string#1}{}%
14029
\@ifundefined{lstisaspect@\string#1}
14030
{\index{unknown\levelchar
14031
\protect\texttt{\protect\string\string#1}#2}}%
14032
{\index{\@nameuse{lstisaspect@\string#1}\levelchar
14033
\protect\texttt{\protect\string\string#1}#2}}%
14035
\def\lstkeyindex#1#2{%
14036
% \index{key\levelchar\protect\keyname{#1}#2}%
14039
% The key/command to aspect relation is defined near the top of this file using
14040
% the following command. In future the package should read this information
14041
% from the aspect files.
14042
% \begin{macrocode}
14043
\def\lstisaspect[#1]#2{%
14044
\global\@namedef{lstaspect@#1}{#2}%
14045
\lst@AddTo\lst@allkeysandcmds{,#2}%
14046
\@for\lst@temp:=#2\do
14047
{\ifx\@empty\lst@temp\else
14048
\global\@namedef{lstisaspect@\lst@temp}{#1}%
14050
\gdef\lst@allkeysandcmds{}
14052
% This relation is also good to print all keys and commands of a particular
14054
% \begin{macrocode}
14055
\def\lstprintaspectkeysandcmds#1{%
14057
\expandafter\@for\expandafter\lst@temp
14058
\expandafter:\expandafter=\csname lstaspect@#1\endcsname\do
14059
{\lst@if\lst@false\else, \fi \texttt{\lst@temp}}}
14061
% \ldots\ or to check the reference. Note that we've defined
14062
% |\lstkandc@|\meta{name} in |\lstaspectindex|.
14063
% \begin{macrocode}
14064
\def\lstcheckreference{%
14065
\@for\lst@temp:=\lst@allkeysandcmds\do
14066
{\ifx\lst@temp\@empty\else
14067
\@ifundefined{lstkandc@\lst@temp}
14068
{\typeout{\lst@temp\space not in reference guide?}}{}%
14072
% \paragraph{Unique styles}
14073
% \begin{macrocode}
14074
\newcommand*\lst{\texttt{lst}}
14075
\newcommand*\Cpp{C\texttt{++}}
14076
\let\keyname\texttt
14077
\let\keyvalue\texttt
14078
\let\hookname\texttt
14079
\newcommand*\aspectname[1]{{\normalfont\sffamily#1}}
14081
% \begin{macrocode}
14082
\DeclareRobustCommand\packagename[1]{%
14083
{\leavevmode\text@command{#1}%
14084
\switchfontfamily\sfdefault\rmdefault
14085
\check@icl #1\check@icr
14087
\def\switchfontfamily#1#2{%
14088
\begingroup\xdef\@gtempa{#1}\endgroup
14089
\ifx\f@family\@gtempa\fontfamily#2%
14090
\else\fontfamily#1\fi
14093
% The color mainly for keys and commands in the reference guide.
14094
% \begin{macrocode}
14096
\definecolor{darkgreen}{rgb}{0,0.6,0}
14097
\def\rstyle{\color{darkgreen}}
14103
% \paragraph{Commands for credits and helpers}
14104
% \begin{macrocode}
14106
\newcommand*\lstthanks[2]
14107
{#1\lst@AddTo\lst@emails{,#1,<#2>}%
14108
\ifx\@empty#2\@empty\typeout{Missing email for #1}\fi}
14109
\newcommand*\lsthelper[3]
14111
\lst@IfOneOf#1\relax\lst@emails
14112
{}{\typeout{^^JWarning: Unknown helper #1.^^J}}}
14115
% \paragraph{Languages and styles}
14116
% \begin{macrocode}
14117
\lstdefinelanguage[doc]{Pascal}{%
14118
morekeywords={alfa,and,array,begin,boolean,byte,case,char,const,div,%
14119
do,downto,else,end,false,file,for,function,get,goto,if,in,%
14120
integer,label,maxint,mod,new,not,of,or,pack,packed,page,program,%
14121
procedure,put,read,readln,real,record,repeat,reset,rewrite,set,%
14122
text,then,to,true,type,unpack,until,var,while,with,write,writeln},%
14124
morecomment=[s]{(*}{*)},%
14125
morecomment=[s]{\{}{\}},%
14128
% \begin{macrocode}
14131
keywordstyle=\bfseries,identifierstyle={},%
14132
commentstyle=\itshape,stringstyle={},%
14133
numberstyle={},stepnumber=1,%
14134
pointstyle=\pointstyle}
14136
{\let\lst@um\@empty \xdef\@gtempa{\the\lst@token}}%
14137
\expandafter\lstkeyindex\expandafter{\@gtempa}{}%
14138
\expandafter\lstaspectindex\expandafter{\@gtempa}{}%
14140
\lstset{defaultdialect=[doc]Pascal,language=Pascal,style={}}
14144
% \subsection{Scanning languages}
14146
% \begin{macro}{\lstscanlanguages}
14147
% We modify some internal definitions and input the files.
14148
% \begin{macrocode}
14149
\def\lstscanlanguages#1#2#3{%
14151
\def\lst@DefDriver@##1##2##3##4[##5]##6{%
14153
\lst@lAddTo\lst@scan{##6(##5),}%
14155
\@ifnextchar[{\lst@XDefDriver{##1}##3}{\lst@DefDriver@@##3}}%
14156
\def\lst@XXDefDriver[##1]{}%
14158
\def\lst@dontinput{#3}%
14159
\let\lst@scan\@empty
14161
\lst@IfOneOf##1\relax\lst@dontinput
14163
{\InputIfFileExists{##1}{}{}}}%
14164
\global\let\@gtempa\lst@scan
14170
% \begin{macro}{\lstprintlanguages}
14171
% |\do| creates a box of width 0.5|\linewidth| or |\linewidth| depending
14172
% on how wide the argument is. This leads to `two column' output.
14173
% The other main thing is sorting the list and begin with the output.
14174
% \begin{macrocode}
14175
\def\lstprintlanguages#1{%
14176
\def\do##1{\setbox\@tempboxa\hbox{##1\space\space}%
14177
\ifdim\wd\@tempboxa<.5\linewidth \wd\@tempboxa.5\linewidth
14178
\else \wd\@tempboxa\linewidth \fi
14179
\box\@tempboxa\allowbreak}%
14182
\hyphenpenalty=\@M \rightskip=\z@\@plus\linewidth\relax
14184
\expandafter\lst@NextLanguage#1\relax(\relax),%
14187
% We get and define the current language and \ldots
14188
% \begin{macrocode}
14189
\def\lst@NextLanguage#1(#2),{%
14191
\def\lst@language{#1}\def\lst@dialects{(#2),}%
14192
\expandafter\lst@NextLanguage@
14195
% \ldots\space gather all available dialect of this language (note that the
14196
% list has been sorted)
14197
% \begin{macrocode}
14198
\def\lst@NextLanguage@#1(#2),{%
14200
\ifx\lst@temp\lst@language
14201
\lst@lAddTo\lst@dialects{(#2),}%
14202
\expandafter\lst@NextLanguage@
14205
% or begin to print this language with all its dialects. Therefor we sort the
14207
% \begin{macrocode}
14209
\ifx\lst@dialects\lst@emptydialect\else
14210
\expandafter\lst@NormedDef\expandafter\lst@language
14211
\expandafter{\lst@language}%
14213
\lst@BubbleSort\lst@dialects
14214
\expandafter\lst@PrintDialects\lst@dialects(\relax),%
14217
\def\lst@next{\lst@NextLanguage#1(#2),}%
14218
\expandafter\lst@next
14220
\def\lst@emptydialect{(),}
14222
% and print the dialect with appropriate commas in between.
14223
% \begin{macrocode}
14224
\def\lst@PrintDialects(#1),{%
14225
\ifx\@empty#1\@empty empty\else
14226
\lst@PrintDialect{#1}%
14228
\lst@PrintDialects@}
14229
\def\lst@PrintDialects@(#1),{%
14231
, \lst@PrintDialect{#1}%
14232
\expandafter\lst@PrintDialects@
14235
% Here we take care of default dialects.
14236
% \begin{macrocode}
14237
\def\lst@PrintDialect#1{%
14238
\lst@NormedDef\lst@temp{#1}%
14239
\expandafter\ifx\csname\@lst dd@\lst@language\endcsname\lst@temp
14240
\texttt{\underbar{#1}}%
14248
% \subsection{Bubble sort}
14250
% \begin{macro}{\lst@IfLE}
14251
% \meta{string 1}|\relax\@empty|\meta{string 2}|\relax\@empty|\marg{then}\meta{else}.
14252
% If \meta{string 1} $\leq$ \meta{string 2}, we execute \meta{then} and
14253
% \meta{else} otherwise.
14254
% Note that this comparision is case insensitive.
14255
% \begin{macrocode}
14256
\def\lst@IfLE#1#2\@empty#3#4\@empty{%
14258
\let\lst@next\@firstoftwo
14259
\else \ifx #3\relax
14260
\let\lst@next\@secondoftwo
14262
\lowercase{\ifx#1#3}%
14263
\def\lst@next{\lst@IfLE#2\@empty#4\@empty}%
14265
\lowercase{\ifnum`#1<`#3}\relax
14266
\let\lst@next\@firstoftwo
14268
\let\lst@next\@secondoftwo
14276
% \begin{macro}{\lst@BubbleSort}
14277
% is in fact a derivation of bubble sort.
14278
% \begin{macrocode}
14279
\def\lst@BubbleSort#1{%
14283
% We `bubble sort' the first, second, \ldots\ elements and \ldots
14284
% \begin{macrocode}
14285
\expandafter\lst@BubbleSort@#1\relax,\relax,%
14287
% \ldots\space then the second, third, \ldots\ elements until no elemets have
14289
% \begin{macrocode}
14290
\expandafter\lst@BubbleSort@\expandafter,\lst@sorted
14294
\def\lst@next{\lst@BubbleSort#1}%
14295
\expandafter\expandafter\expandafter\lst@next
14298
\def\lst@BubbleSort@#1,#2,{%
14299
\ifx\@empty#1\@empty
14300
\def\lst@sorted{#2,}%
14301
\def\lst@next{\lst@BubbleSort@@}%
14303
\let\lst@sorted\@empty
14304
\def\lst@next{\lst@BubbleSort@@#1,#2,}%
14308
% But the bubbles rise only one step per call. Putting the elements at their
14309
% top most place would be inefficient (since \TeX\ had to read much more
14310
% parameters in this case).
14311
% \begin{macrocode}
14312
\def\lst@BubbleSort@@#1,#2,{%
14315
\lst@lAddTo\lst@sorted{#1,}%
14316
\expandafter\expandafter\expandafter\lst@BubbleSort@@@
14318
\lst@IfLE #1\relax\@empty #2\relax\@empty
14319
{\lst@lAddTo\lst@sorted{#1,#2,}}%
14320
{\lst@true \lst@lAddTo\lst@sorted{#2,#1,}}%
14321
\expandafter\expandafter\expandafter\lst@BubbleSort@@
14324
\def\lst@BubbleSort@@@#1\relax,{}
14326
% \begin{macrocode}
14332
% \section{Interfaces to other programs}
14335
% \subsection{0.21 compatibility}
14337
% \begin{aspect}{0.21}
14338
% Some keys have just been renamed.
14339
% \begin{macrocode}
14341
\lst@BeginAspect{0.21}
14344
% \begin{macrocode}
14345
\lst@Key{labelstyle}{}{\def\lst@numberstyle{#1}}
14346
\lst@Key{labelsep}{10pt}{\def\lst@numbersep{#1}}
14347
\lst@Key{labelstep}{0}{%
14348
\ifnum #1=\z@ \KV@lst@numbers{none}%
14349
\else \KV@lst@numbers{left}\fi
14350
\def\lst@stepnumber{#1\relax}}
14351
\lst@Key{firstlabel}\relax{\def\lst@firstnumber{#1\relax}}
14352
\lst@Key{advancelabel}\relax{\def\lst@advancenumber{#1\relax}}
14353
\let\c@lstlabel\c@lstnumber
14354
\lst@AddToHook{Init}{\let\thelstnumber\thelstlabel}
14355
\newcommand*\thelstlabel{\@arabic\c@lstlabel}
14357
% \begin{macrocode}
14358
\lst@Key{first}\relax{\def\lst@firstline{#1\relax}}
14359
\lst@Key{last}\relax{\def\lst@lastline{#1\relax}}
14361
% \begin{macrocode}
14362
\lst@Key{framerulewidth}{.4pt}{\def\lst@framerulewidth{#1}}
14363
\lst@Key{framerulesep}{2pt}{\def\lst@rulesep{#1}}
14364
\lst@Key{frametextsep}{3pt}{\def\lst@frametextsep{#1}}
14365
\lst@Key{framerulecolor}{}{\lstKV@OptArg[]{#1}%
14366
{\ifx\@empty##2\@empty
14367
\let\lst@rulecolor\@empty
14369
\ifx\@empty##1\@empty
14370
\def\lst@rulecolor{\color{##2}}%
14372
\def\lst@rulecolor{\color[##1]{##2}}%
14375
\lst@Key{backgroundcolor}{}{\lstKV@OptArg[]{#1}%
14376
{\ifx\@empty##2\@empty
14377
\let\lst@bkgcolor\@empty
14379
\ifx\@empty##1\@empty
14380
\def\lst@bkgcolor{\color{##2}}%
14382
\def\lst@bkgcolor{\color[##1]{##2}}%
14385
\lst@Key{framespread}{\z@}{\def\lst@framespread{#1}}
14386
\lst@AddToHook{PreInit}
14387
{\@tempdima\lst@framespread\relax \divide\@tempdima\tw@
14388
\edef\lst@framextopmargin{\the\@tempdima}%
14389
\let\lst@framexrightmargin\lst@framextopmargin
14390
\let\lst@framexbottommargin\lst@framextopmargin
14391
\advance\@tempdima\lst@xleftmargin\relax
14392
\edef\lst@framexleftmargin{\the\@tempdima}}
14394
% \lsthelper{Harald~Harders}{1998/03/30}{inner- and outerspread} had the idea
14395
% of two spreads (inner and outer). We either divide the dimension by two or
14396
% assign the two dimensions to inner- and outerspread.
14397
% \begin{macrocode}
14398
\newdimen\lst@innerspread \newdimen\lst@outerspread
14399
\lst@Key{spread}{\z@,\z@}{\lstKV@CSTwoArg{#1}%
14400
{\lst@innerspread##1\relax
14401
\ifx\@empty##2\@empty
14402
\divide\lst@innerspread\tw@\relax
14403
\lst@outerspread\lst@innerspread
14405
\lst@outerspread##2\relax
14407
\lst@AddToHook{BoxUnsafe}{\lst@outerspread\z@ \lst@innerspread\z@}
14408
\lst@Key{wholeline}{false}[t]{\lstKV@SetIf{#1}\lst@ifresetmargins}
14409
\lst@Key{indent}{\z@}{\def\lst@xleftmargin{#1}}
14410
\lst@AddToHook{PreInit}
14411
{\lst@innerspread=-\lst@innerspread
14412
\lst@outerspread=-\lst@outerspread
14413
\ifodd\c@page \advance\lst@innerspread\lst@xleftmargin
14414
\else \advance\lst@outerspread\lst@xleftmargin \fi
14416
\edef\lst@xleftmargin{\the\lst@innerspread}%
14417
\edef\lst@xrightmargin{\the\lst@outerspread}%
14419
\edef\lst@xleftmargin{\the\lst@outerspread}%
14420
\edef\lst@xrightmargin{\the\lst@innerspread}%
14423
% \begin{macrocode}
14424
\lst@Key{defaultclass}\relax{\def\lst@classoffset{#1}}
14425
\lst@Key{stringtest}\relax{}% dummy
14426
\lst@Key{outputpos}\relax{\lst@outputpos#1\relax\relax}
14428
% \begin{macrocode}
14429
\lst@Key{stringspaces}\relax[t]{\lstKV@SetIf{#1}\lst@ifshowstringspaces}
14430
\lst@Key{visisblespaces}\relax[t]{\lstKV@SetIf{#1}\lst@ifshowspaces}
14431
\lst@Key{visibletabs}\relax[t]{\lstKV@SetIf{#1}\lst@ifshowtabs}
14434
% \begin{macrocode}
14441
% \subsection{\textsf{fancyvrb}}
14443
% \lsthelper{Denis~Girou}{1998/07/26}{fancyvrb} asked whether
14444
% \packagename{fancyvrb} and \packagename{listings} could work together.
14445
% This is still the second attempt.
14447
% \begin{lstkey}{fancyvrb}
14448
% We set the boolean and call a submacro.
14449
% \begin{macrocode}
14451
\lst@Key{fancyvrb}\relax[t]{%
14452
\lstKV@SetIf{#1}\lst@iffancyvrb
14454
\ifx\lstFV@fancyvrb\@undefined
14455
\gdef\lstFV@fancyvrb{\lst@RequireAspects{fancyvrb}\lstFV@fancyvrb}
14461
% \begin{aspect}{fancyvrb}
14462
% We end the job if \packagename{fancyvrb} is not present.
14463
% \begin{macrocode}
14465
\lst@BeginAspect{fancyvrb}
14467
% \begin{macrocode}
14468
\@ifundefined{FancyVerbFormatLine}
14471
*** `listings.sty' needs `fancyvrb.sty' right now.^^J%
14472
*** Please ensure its availability and try again.^^J%
14474
\batchmode \@@end}{}
14477
% \begin{macro}{\lstFV@fancyvrb}
14478
% We assign the correct |\FancyVerbFormatLine| macro.
14479
% \begin{macrocode}
14480
\gdef\lstFV@fancyvrb{%
14482
\ifx\FancyVerbFormatLine\lstFV@FancyVerbFormatLine\else
14483
\let\lstFV@FVFL\FancyVerbFormatLine
14484
\let\FancyVerbFormatLine\lstFV@FancyVerbFormatLine
14487
\ifx\lstFV@FVFL\@undefined\else
14488
\let\FancyVerbFormatLine\lstFV@FVFL
14489
\let\lstFV@FVFL\@undefined
14495
% \begin{macro}{\lstFV@VerbatimBegin}
14496
% We initialize things if necessary.
14497
% \begin{macrocode}
14498
\gdef\lstFV@VerbatimBegin{%
14499
\ifx\FancyVerbFormatLine\lstFV@FancyVerbFormatLine
14500
\lsthk@TextStyle \lsthk@BoxUnsafe
14502
\lst@activecharsfalse
14503
\let\normalbaselines\relax
14506
% Is this |\let| bad?
14508
% I inserted |\lst@ifresetmargins|\ldots|\fi| after a bug report from
14509
% \lsthelper{Peter~Bartke}{1999/11/18}{wrong fancyvrb frame}.
14510
% \begin{macrocode}
14512
\lst@ifresetmargins \advance\linewidth-\@totalleftmargin \fi
14513
\everypar{}\global\lst@newlines\z@
14514
\lst@mode\lst@nomode \let\lst@entermodes\@empty
14515
\lst@InterruptModes
14517
% \lsthelper{Rolf~Niepraschk}{1998/11/25}{ligatures problem} reported a bug
14518
% concerning ligatures to \lsthelper{Denis~Girou}{1998/11/27}{use |\@noligs|}.
14519
% \begin{macrocode}
14520
%% D.G. modification begin - Nov. 25, 1998
14522
%% D.G. modification end
14527
% \begin{macro}{\lstFV@VerbatimEnd}
14528
% A box and macro must exist after |\lst@DeInit|.
14529
% We store them globally.
14530
% \begin{macrocode}
14531
\gdef\lstFV@VerbatimEnd{%
14532
\ifx\FancyVerbFormatLine\lstFV@FancyVerbFormatLine
14533
\global\setbox\lstFV@gtempboxa\box\@tempboxa
14534
\global\let\@gtempa\FV@ProcessLine
14535
\lst@mode\lst@Pmode
14537
\let\FV@ProcessLine\@gtempa
14538
\setbox\@tempboxa\box\lstFV@gtempboxa
14541
% \begin{macrocode}
14542
\newbox\lstFV@gtempboxa
14547
% We insert |\lstFV@VerbatimBegin| and |\lstFV@VerbatimEnd| where necessary.
14548
% \begin{macrocode}
14549
\lst@AddTo\FV@VerbatimBegin\lstFV@VerbatimBegin
14550
\lst@AddToAtTop\FV@VerbatimEnd\lstFV@VerbatimEnd
14551
\lst@AddTo\FV@LVerbatimBegin\lstFV@VerbatimBegin
14552
\lst@AddToAtTop\FV@LVerbatimEnd\lstFV@VerbatimEnd
14553
\lst@AddTo\FV@BVerbatimBegin\lstFV@VerbatimBegin
14554
\lst@AddToAtTop\FV@BVerbatimEnd\lstFV@VerbatimEnd
14557
% \begin{macro}{\lstFV@FancyVerbFormatLine}
14558
% `@' terminates the argument of |\lst@FVConvert|.
14559
% Moreover |\lst@ReenterModes| and |\lst@InterruptModes| encloses some code.
14560
% This ensures that we have same group level at the beginning and at the end of
14561
% the macro---even if the user begins but doesn't end a comment, which means
14563
% Furthermore we use |\vtop| and reset |\lst@newlines| to allow line breaking.
14564
% \begin{macrocode}
14565
\gdef\lstFV@FancyVerbFormatLine#1{%
14566
\let\lst@arg\@empty \lst@FVConvert#1\@nil
14567
\global\lst@newlines\z@
14568
\vtop{\leavevmode\lst@parshape
14570
\lst@arg \lst@PrintToken\lst@EOLUpdate\lsthk@InitVarsBOL
14571
\lst@InterruptModes}}
14573
% The |\lst@parshape| inside |\vtop| is due to a bug report from
14574
% \lsthelper{Peter~Bartke}{1999/11/18}{wrong par indention with fancyvrb}.
14577
% \begin{macro}{\lst@FVConvert}
14578
% Since |\@ifnextchar\bgroup| might fail, we have to use |\ifcat| here.
14579
% Bug reported by \lsthelper{Denis~Girou}{1999/07/26}{fancyvrb=true + `second
14580
% commandchar' other than \{ doesn't work}.
14581
% However we don't gobble space tokens as |\@ifnextchar| does.
14582
% \begin{macrocode}
14583
\gdef\lst@FVConvert{\futurelet\@let@token\lst@FVConvert@@}
14584
\gdef\lst@FVConvert@@{%
14585
\ifcat\noexpand\@let@token\bgroup \expandafter\lst@FVConvertArg
14586
\else \expandafter\lst@FVConvert@ \fi}
14588
% Coming to such a catcode${}={}$1 character we convert the argument and add
14589
% it together with group delimiters to |\lst@arg|.
14590
% We also add |\lst@PrintToken|, which prints all collected characters before
14592
% Finally we continue the conversion.
14593
% \begin{macrocode}
14594
\gdef\lst@FVConvertArg#1{%
14595
{\let\lst@arg\@empty
14596
\lst@FVConvert#1\@nil
14597
\global\let\@gtempa\lst@arg}%
14598
\lst@lExtend\lst@arg{\expandafter{\@gtempa\lst@PrintToken}}%
14601
% Having no |\bgroup|, we look whether we've found the end of the input, and
14602
% convert one token ((non)active character or control sequence) and continue.
14603
% \begin{macrocode}
14604
\gdef\lst@FVConvert@#1{%
14606
\if\relax\noexpand#1%
14607
\lst@lAddTo\lst@arg{\lst@OutputLostSpace\lst@PrintToken#1}%
14609
\lccode`\~=`#1\lowercase{\lst@lAddTo\lst@arg~}%
14611
\expandafter\lst@FVConvert
14616
% \begin{macrocode}
14623
% \subsection{Omega support}
14626
% $\Omega$ support looks easy---I hope it works at least in some cases.
14627
% \begin{macrocode}
14630
% \begin{macrocode}
14631
\@ifundefined{ocp}{}
14632
{\lst@AddToHook{OutputBox}%
14633
{\let\lst@ProcessLetter\@firstofone
14634
\let\lst@ProcessDigit\@firstofone
14635
\let\lst@ProcessOther\@firstofone}}
14637
% \begin{macrocode}
14643
% \subsection{\textsf{LGrind}}
14645
% \begin{aspect}{lgrind}
14646
% \begin{macro}{\lst@LGGetNames}
14647
% is used to extract the language names from |\lst@arg| (the
14648
% \packagename{LGrind} definition).
14649
% \begin{macrocode}
14651
\lst@BeginAspect[keywords,comments,strings,language]{lgrind}
14653
% \begin{macrocode}
14654
\gdef\lst@LGGetNames#1:#2\relax{%
14655
\lst@NormedDef\lstlang@{#1}\lst@ReplaceInArg\lstlang@{|,}%
14660
% \begin{macro}{\lst@LGGetValue}
14661
% returns in |\lst@LGvalue| the value of capability |#1| given by the list
14662
% |\lst@arg|. If |#1| is not found, we have |\lst@if|=|\iffalse|.
14663
% Otherwise it is true and the ``cap=value'' pair is removed from the list.
14664
% First we test for |#1| and
14665
% \begin{macrocode}
14666
\gdef\lst@LGGetValue#1{%
14668
\def\lst@temp##1:#1##2##3\relax{%
14669
\ifx\@empty##2\else \lst@LGGetValue@{#1}\fi}
14670
\expandafter\lst@temp\lst@arg:#1\@empty\relax}
14672
% remove the pair if necessary.
14673
% \begin{macrocode}
14674
\gdef\lst@LGGetValue@#1{%
14676
\def\lst@temp##1:#1##2:##3\relax{%
14677
\@ifnextchar=\lst@LGGetValue@@{\lst@LGGetValue@@=}##2\relax
14678
\def\lst@arg{##1:##3}}%
14679
\expandafter\lst@temp\lst@arg\relax}
14680
\gdef\lst@LGGetValue@@=#1\relax{\def\lst@LGvalue{#1}}
14684
% \begin{macro}{\lst@LGGetComment}
14685
% stores the comment delimiters (enclosed in braces) in |#2| if comment of type
14686
% |#1| is present and not a comment line. Otherwise |#2| is empty.
14687
% \begin{macrocode}
14688
\gdef\lst@LGGetComment#1#2{%
14690
\lst@LGGetValue{#1b}%
14693
\lst@LGGetValue{#1e}%
14694
\ifx\lst@LGvalue\lst@LGEOL
14695
\edef\lstlang@{\lstlang@,commentline={#2}}%
14698
\edef#2{{#2}{\lst@LGvalue}}%
14704
% \begin{macro}{\lst@LGGetString}
14705
% does the same for string delimiters, but it doesn't `return' any value.
14706
% \begin{macrocode}
14707
\gdef\lst@LGGetString#1#2{%
14708
\lst@LGGetValue{#1b}%
14711
\lst@LGGetValue{#1e}%
14712
\ifx\lst@LGvalue\lst@LGEOL
14713
\edef\lstlang@{\lstlang@,morestringizer=[l]{#2}}%
14716
% we must check for |\e|, i.e.~whether we have to use \texttt doubled or
14717
% \texttt backslashed stringizer.
14718
% \begin{macrocode}
14719
\ifx #2\lst@LGvalue
14720
\edef\lstlang@{\lstlang@,morestringizer=[d]{#2}}%
14722
\edef\lst@temp{\lst@LGe#2}%
14723
\ifx \lst@temp\lst@LGvalue
14724
\edef\lstlang@{\lstlang@,morestringizer=[b]{#2}}%
14726
\PackageWarning{Listings}%
14727
{String #2...\lst@LGvalue\space not supported}%
14735
% \begin{macro}{\lst@LGDefLang}
14736
% defines the language given by |\lst@arg|, the definition part, and
14737
% |\lst@language@|, the language name. First we remove unwanted stuff from
14738
% |\lst@arg|, e.g.~we replace |:\ :| by |:|.
14739
% \begin{macrocode}
14740
\gdef\lst@LGDefLang{%
14742
\let\lstlang@\empty
14744
% Get the keywords and values of friends.
14745
% \begin{macrocode}
14746
\lst@LGGetValue{kw}%
14748
\lst@ReplaceInArg\lst@LGvalue{{ },}%
14749
\edef\lstlang@{\lstlang@,keywords={\lst@LGvalue}}%
14752
% \begin{macrocode}
14753
\lst@LGGetValue{oc}%
14755
\edef\lstlang@{\lstlang@,sensitive=f}%
14758
% \begin{macrocode}
14759
\lst@LGGetValue{id}%
14761
\edef\lstlang@{\lstlang@,alsoletter=\lst@LGvalue}%
14764
% Now we get the comment delimiters and use them as single or double comments
14765
% according to whether there are two or four delimiters.
14766
% Note that |\lst@LGGetComment| takes care of comment lines.
14767
% \begin{macrocode}
14768
\lst@LGGetComment a\lst@LGa
14769
\lst@LGGetComment c\lst@LGc
14770
\ifx\lst@LGa\@empty
14771
\ifx\lst@LGc\@empty\else
14772
\edef\lstlang@{\lstlang@,singlecomment=\lst@LGc}%
14775
\ifx\lst@LGc\@empty
14776
\edef\lstlang@{\lstlang@,singlecomment=\lst@LGa}%
14778
\edef\lstlang@{\lstlang@,doublecomment=\lst@LGc\lst@LGa}%
14782
% Now we parse the stringizers.
14783
% \begin{macrocode}
14784
\lst@LGGetString s\lst@LGa
14785
\lst@LGGetString l\lst@LGa
14787
% We test for the continuation capability and
14788
% \begin{macrocode}
14789
\lst@LGGetValue{tc}%
14791
\edef\lstlang@{\lstlang@,lgrindef=\lst@LGvalue}%
14794
% define the language.
14795
% \begin{macrocode}
14796
\expandafter\xdef\csname\@lst LGlang@\lst@language@\endcsname
14797
{\noexpand\lstset{\lstlang@}}%
14799
% Finally we inform the user of all ignored capabilities.
14800
% \begin{macrocode}
14801
\lst@ReplaceInArg\lst@arg{{: :}:}\let\lst@LGvalue\@empty
14802
\expandafter\lst@LGDroppedCaps\lst@arg\relax\relax
14803
\ifx\lst@LGvalue\@empty\else
14804
\PackageWarningNoLine{Listings}{Ignored capabilities for
14805
\space `\lst@language@' are\MessageBreak\lst@LGvalue}%
14810
% \begin{macro}{\lst@LGDroppedCaps}
14811
% just drops a previous value and appends the next capabilty name to
14813
% \begin{macrocode}
14814
\gdef\lst@LGDroppedCaps#1:#2#3{%
14816
\lst@RemoveCommas\lst@LGvalue
14818
\edef\lst@LGvalue{\lst@LGvalue,#2#3}%
14819
\expandafter\lst@LGDroppedCaps
14824
% \begin{macro}{\lst@LGReplace}
14825
% \begin{macro}{\lst@LGe}
14826
% We replace `escaped \verb!:^$|!' by catcode 11 versions, and other strings
14827
% by some kind of short versions (which is necessary to get the above
14828
% definitions work).
14829
% \begin{macrocode}
14832
\lccode`\z=`\:\lccode`\y=`\^\lccode`\x=`\$\lccode`\v=`\|
14833
\catcode`\\=12\relax
14835
/gdef/lst@LGReplace{/lst@ReplaceInArg/lst@arg
14836
{{\:}{z }{\^}{y}{\$}{x}{\|}{v}{ \ }{ }{:\ :}{:}{\ }{ }{\(}({\)})}}
14841
% \end{macro}\end{macro}
14843
% \begin{macro}{\lst@LGRead}
14844
% reads one language definition and defines the language if the correct one
14846
% \begin{macrocode}
14847
\gdef\lst@LGRead#1\par{%
14848
\lst@LGGetNames#1:\relax
14849
\def\lst@temp{endoflanguagedefinitions}%
14850
\ifx\lstlang@\lst@temp
14851
\let\lst@next\endinput
14853
\expandafter\lst@IfOneOf\lst@language@\relax\lstlang@
14854
{\lst@LGDefLang \let\lst@next\endinput}%
14855
{\let\lst@next\lst@LGRead}%
14861
% \begin{lstkey}{lgrindef}
14862
% We only have to request the language and
14863
% \begin{macrocode}
14864
\lst@Key{lgrindef}\relax{%
14865
\lst@NormedDef\lst@language@{#1}%
14867
\@ifundefined{lstLGlang@\lst@language@}%
14868
{\everypar{\lst@LGRead}%
14869
\catcode`\\=12\catcode`\{=12\catcode`\}=12\catcode`\%=12%
14870
\catcode`\#=14\catcode`\$=12\catcode`\^=12\catcode`\_=12\relax
14871
\input{\lstlgrindeffile}%
14875
% select it or issue an error message.
14876
% \begin{macrocode}
14877
\@ifundefined{lstLGlang@\lst@language@}%
14878
{\PackageError{Listings}%
14879
{LGrind language \lst@language@\space undefined}%
14880
{The language is not loadable. \@ehc}}%
14881
{\lsthk@SetLanguage
14882
\csname\@lst LGlang@\lst@language@\endcsname}}
14886
% \begin{macro}{\lstlgrindeffile}
14887
% contains just the file name.
14888
% \begin{macrocode}
14889
\@ifundefined{lstlgrindeffile}
14890
{\lst@UserCommand\lstlgrindeffile{lgrindef.}}{}
14894
% \begin{macrocode}
14901
% \subsection{\textsf{hyperref}}
14903
% \begin{aspect}{hyper}
14904
% \begin{macrocode}
14906
\lst@BeginAspect[keywords]{hyper}
14909
% \begin{lstkey}{hyperanchor}
14910
% \begin{lstkey}{hyperlink}
14911
% determine the macro to set an anchor and a link, respectively.
14912
% \begin{macrocode}
14913
\lst@Key{hyperanchor}\hyper@@anchor{\let\lst@hyperanchor#1}
14914
\lst@Key{hyperlink}\hyperlink{\let\lst@hyperlink#1}
14916
% \end{lstkey}\end{lstkey}
14917
% Again, the main thing is a special working procedure. First we extract the
14918
% contents of |\lst@token| and get a free macro name for this current character
14919
% string (using prefix |lstHR@| and a number as suffix). Then we make this
14920
% free macro equivalent to |\@empty|, so it is not used the next time.
14921
% \begin{macrocode}
14922
\lst@InstallKeywords{h}{hyperref}{}\relax{}
14924
\let\lst@UM\@empty \xdef\@gtempa{\the\lst@token}%
14926
\lst@GetFreeMacro{lstHR@\@gtempa}%
14927
\global\expandafter\let\lst@freemacro\@empty
14929
% |\@tempcnta| is the suffix of the free macro. We use it here to refer to
14930
% the last occurence of the same string. To do this, we redefine the output
14931
% macro |\lst@alloverstyle| to set an anchor \ldots
14932
% \begin{macrocode}
14933
\@tempcntb\@tempcnta \advance\@tempcntb\m@ne
14934
\edef\lst@alloverstyle##1{%
14935
\let\noexpand\lst@alloverstyle\noexpand\@empty
14936
\noexpand\smash{\raise\baselineskip\hbox
14937
{\noexpand\lst@hyperanchor{lst.\@gtempa\the\@tempcnta}%
14940
% \ldots\space and a link to the last occurence (if there is any).
14941
% \begin{macrocode}
14942
\ifnum\@tempcnta=\z@ ##1\else
14943
\noexpand\lst@hyperlink{lst.\@gtempa\the\@tempcntb}{##1}%
14949
% \begin{macrocode}
14956
% \section{Epilogue}
14959
% \begin{macrocode}
14962
% Each option adds the aspect name to |\lst@loadaspects| or removes it from that data macro.
14963
% \begin{macrocode}
14964
\DeclareOption*{\expandafter\lst@ProcessOption\CurrentOption\relax}
14965
\def\lst@ProcessOption#1#2\relax{%
14967
\lst@DeleteKeysIn\lst@loadaspects{#2}%
14969
\lst@lAddTo\lst@loadaspects{,#1#2}%
14972
% The following aspects are loaded by default.
14973
% \begin{macrocode}
14974
\@ifundefined{lst@loadaspects}
14975
{\def\lst@loadaspects{strings,comments,escape,style,language,%
14976
keywords,labels,lineshape,frames,emph,index}%
14979
% We load the patch file, \ldots
14980
% \begin{macrocode}
14981
\InputIfFileExists{lstpatch.sty}{}{}
14983
% \ldots\ process the options, \ldots
14984
% \begin{macrocode}
14985
\let\lst@ifsavemem\iffalse
14986
\DeclareOption{savemem}{\let\lst@ifsavemem\iftrue}
14987
\DeclareOption{noaspects}{\let\lst@loadaspects\@empty}
14990
% \ldots\ and load the aspects.
14991
% \begin{macrocode}
14992
\lst@RequireAspects\lst@loadaspects
14993
\let\lst@loadaspects\@empty
14995
% If present we select the empty style and language.
14996
% \begin{macrocode}
14997
\lst@UseHook{SetStyle}\lst@UseHook{EmptyStyle}
14998
\lst@UseHook{SetLanguage}\lst@UseHook{EmptyLanguage}
15000
% Finally we load the configuration files.
15001
% \begin{macrocode}
15002
\InputIfFileExists{listings.cfg}{}{}
15003
\InputIfFileExists{lstlocal.cfg}{}{}
15004
%<info>\lst@ReportAllocs
15006
% \begin{macrocode}
15012
% \section{History}
15013
% \begingroup\small
15014
% Only major changes are listed here. Introductory version numbers of commands
15015
% and keys are in the sources of the guides, which makes this history fairly
15017
% \renewcommand\labelitemi{--}
15019
% \item[0.1] from 1996/03/09
15020
% \item test version to look whether package is possible or not
15021
% \item[0.11] from 1996/08/19
15023
% \item additional blank option (= language)
15025
% \item improved alignment
15026
% \item[0.12] from 1997/01/16
15027
% \item nearly `perfect' alignment
15028
% \item[0.13] from 1997/02/11
15030
% \item additional languages: Eiffel, Fortran 90, Modula-2, Pascal XSC
15032
% \item load on demand: language specific macros moved to driver files
15033
% \item comments are declared now and not implemented for each language again
15034
% (this makes the \TeX\ sources easier to read)
15035
% \item[0.14] from 1997/02/18
15036
% \item User's guide rewritten, Implementation guide uses macro environment
15037
% \item (non) case sensitivity implemented and multiple string types,
15038
% i.e.~Modula-2 handles both string types: quotes and double quotes
15040
% \item comment declaration is user-accessible
15041
% \item package compatible to \verb!german.sty!
15043
% \item[0.15] from 1997/04/18
15045
% \item additional languages: Java, Turbo Pascal
15047
% \item package renamed from \packagename{listing} to \packagename{listings}
15048
% since the first already exists
15049
% \item[0.16] from 1997/06/01
15051
% \item changed `$<$' to `$>$' in |\lst@SkipToFirst|
15052
% \item bug removed: |\lst@Init| must be placed before |\lst@SkipToFirst|
15054
% \item listing environment rewritten
15055
% \item[0.17] from 1997/09/29
15057
% \item |\spreadlisting| works correct now (e.g.~page numbers don't move right)
15059
% \item speed up things (quick `if parameter empty', all |\long| except one
15060
% removed, faster \verb!\lst@GotoNextTabStop!, etc.)
15061
% \item improved alignment of wide other characters (e.g.~$==$)
15063
% \item many new languages: Ada, Algol, Cobol, Comal 80, Elan, Fortran 77,
15064
% Lisp, Logo, Matlab, Oberon, Perl, PL/I, Simula, SQL, \TeX
15066
% \item[pre-0.18] from 1998/03/24 (unpublished)
15068
% \item bug concerning |\labelstyle| (becomes \keyname{numberstyle}) removed
15069
% (now oldstylenum example works)
15071
% \item experimental implementation of character classes
15072
% \item[0.19] from 1998/11/09
15073
% \item character classes and new \lst-aspects seem to be good
15074
% \item user interface uses \packagename{keyval} package
15075
% \item \packagename{fancyvrb} support
15076
% \item[0.20] from 1999/07/12
15077
% \item new keyword detection mechanism
15078
% \item new aspects: \aspectname{writefile}, \aspectname{breaklines},
15079
% captions, \aspectname{html}
15081
% \item improved \packagename{fancyvrb} support
15083
% \item all aspects reside in a single file and the language drivers in
15084
% currently two files
15085
% \item[0.21] 2000/08/23
15086
% \item completely new User's guide
15087
% \item experimental format definitions
15088
% \item keyword classes replaced by families
15089
% \item dynamic modes
15090
% \item[1.0$\beta$] 2001/09/21
15091
% \item keynames synchronized with \packagename{fancyvrb}
15092
% \item \aspectname{frames} aspect extended
15093
% \item new output concept (delaying and merging)
15094
% \item[1.0] 2002/04/01
15095
% \item update of all documentation sections including Developer's guide
15096
% \item delimiters unified
added
removed
fpcdocs/packages/listings/listings.dtx
