doc requireswritefileand 1\box lstsample,lstxsample
0.21 defines old keys in terms of the new ones.
fancyvrb requires 1\box
fancyvrb,fvcmdparams,morefvcmdparams lgrind
lgrindef,\lstlgrindeffile hyper requireskeywords
hyperref,morehyperref, deletehyperref, hyperanchor,hyperlink The kernel allocates 6 \count, 4 \dimen and 1 \toks. Moreover it defines the following keys, commands, and environments:
basewidth,fontadjust,columns,flexiblecolumns,identifierstyle, tabsize, showtabs,tab, showspaces, keepspaces, formfeed,
SelectCharTable,MoreSelectCharTable, extendedchars,alsoletter, alsodigit,alsoother,excludedelims,literate,basicstyle,print, firstline, lastline, linerange,consecutivenumbers, nolol, captionpos,abovecaptionskip,belowcaptionskip,label, title, caption, \lstlistingname, \lstlistingnamestyle,boxpos,float, floatplacement, aboveskip, belowskip, everydisplay,showlines, emptylines, gobble,name,\lstname, \lstlistlistingname,
\lstlistoflistings,\lstnewenvironment, \lstinline,
\lstinputlisting, lstlisting, \lstloadaspects, \lstset,
\thelstlisting, \lstaspectfiles, inputencoding, inputpath, delim,moredelim, deletedelim, upquote, numberbychapter,
\lstMakeShortInline,\lstDeleteShortInline, fancyvrb
Consequently you can’t define a part of an aspect and later on another part. But it is possible to define aspectA1 and later aspectA2 which requiresA1.
→ Put local add-ons into ‘lstmisc0.sty’—this file is searched first by default. If you want to make add-ons for one particular document just replace the surrounding ‘\lst@BeginAspect’
and ‘\lst@EndAspect’ by ‘\makeatletter’ and ‘\makeatother’ and use the definitions in the preamble of your document. However, you have to load required aspects on your own.
You can put any TEX material in between the two commands, but note that defini- tions must be\globalif you need them later—LATEX’s\newcommandmakes local definitions and can’t be preceded by \global. So use the following commands,
\gdef, and commands described in later sections.
\lst@UserCommandhmacroihparameter texti{hreplacement texti}
The macro is (mainly) equivalent to \gdef. The purpose is to distinguish user commands and internal global definitions.
\lst@Key{hkey namei}{hinit valuei}[[hdefault valuei]]{hdefinitioni}
\lst@Key{hkey namei}\relax[[hdefault valuei]]{hdefinitioni}
defines a key using the keyval package from David Carlisle. hdefinitioni is the replacement text of a macro with one parameter. The argument is either the value from ‘key=value’ or hdefault valuei if no ‘=value’ is given. The helper macros \lstKV@...below might simplifyhdefinitioni.
The key is not initialized if the second argument is\relax. Otherwisehinit valueiis the initial value given to the key. Note that we locally switch to
\globalsdefs=1to ensure that initialization is not effected by grouping.
\lst@AddToHook{hname of hooki}{hTEX materiali}
adds TEX material at predefined points. Section9.4lists all hooks and where they are defined respectively executed. \lst@AddToHook{A}{\csa} before
\lst@AddToHook{A}{\csb}does not guarantee that\csais executed before
\csb.
\lst@AddToHookExe{hname of hooki}{hTEX materiali}
also executes hTEX materiali for initialization. You might use local variables—local in the sense of TEX and/or usual programming languages—
but when the code is executed for initialization all assignments are global:
we set \globaldefslocally to one.
\lst@UseHook{hname of hooki}
executes the hook.
→ Let’s look at two examples. The first extends the package by adding some hook-material. If you want status messages, you might write
% \lst@AddToHook{Init}{\message{\MessageBreak Processing listing ...}}
% \lst@AddToHook{DeInit}{\message{complete.\MessageBreak}}
The second example introduces two keys to let the user control the messages. The macro
\lst@AddTois described in section11.1.
% \lst@BeginAspect{message}
% \lst@Key{message}{Annoying message.}{\gdef\lst@message{#1}}
% \lst@Key{moremessage}\relax{\lst@AddTo\lst@message{\MessageBreak#1}}
% \lst@AddToHook{Init}{\typeout{\MessageBreak\lst@message}}
% \lst@EndAspect
However, there are certainly aspects which are more useful.
The following macros can be used in the hdefinitioni argument of the \lst@Key command to evaluate the argument. The additional prefixKVrefers to thekeyval package.
\lstKV@SetIf{hvaluei}hif macroi
hif macroi becomes \iftrue if the first character ofhvaluei equals t or T.
Otherwise it becomes \iffalse. Usually you will use#1ashvaluei.
\lstKV@SwitchCases{hvaluei}
{hstring 1i&hexecute 1i\\
hstring 2i&hexecute 2i\\
...
hstring ni&hexecuteni}{helsei}
Either execute helseior thehvalueimatching part.
This implementation of C. Heinz has a problem, if the listing is part of a tabular environment as found out by Nasser M. Abbasi. David Carlisle gave a hint how to avoid this problem and so the separator&is replaced by:.
\lstKV@TwoArg{hvaluei}{hsubdefinitioni}
\lstKV@ThreeArg{hvaluei}{hsubdefinitioni}
\lstKV@FourArg{hvaluei}{hsubdefinitioni}
hsubdefinitioniis the replacement text of a macro with two, three, and four parameters. We call this macro with the arguments given byhvaluei. Empty arguments are added if necessary.
\lstKV@OptArg[hdefault arg.i]{hvaluei}{hsubdefinitioni}
[hdefault arg.i] is not optional. hsubdefinitioni is the replacement text of a macro with parameter text [##1]##2. Note that the macro parameter character # is doubled since used within another macro. hsubdefinitioni accesses these arguments via ##1and##2.
hvalueiis usually the argument#1passed by the keyvalpackage. If hvaluei has no optional argument,hdefault arg.iis inserted to provide the arguments to hsubdefinitioni.
\lstKV@XOptArg[hdefault arg.i]{hvaluei}hsubmacroi
Same as \lstKV@OptArg but the third argument hsubmacroi is already a definition and not replacement text.
\lstKV@CSTwoArg{hvaluei}{hsubdefinitioni}
hvaluei is a comma separated list of one or two arguments. These are given to the subdefinition which is the replacement text of a macro with two parameters. An empty second argument is added if necessary.
→ One more example. The key ‘sensitive’ belongs to the aspect keywords. Therefore it is defined in between ‘\lst@BeginAspect{keywords}’ and ‘\lst@EndAspect’, which is not shown here.
% \lst@Key{sensitive}\relax[t]{\lstKV@SetIf{#1}\lst@ifsensitive}
% \lst@AddToHookExe{SetLanguage}{\let\lst@ifsensitive\iftrue}
The last line is equivalent to
% \lst@AddToHook{SetLanguage}{\let\lst@ifsensitive\iftrue}
% \global\let\lst@ifsensitive\iftrue
We initialize the variable globally since the user might request an aspect in a group. Afterwards the variable is used locally—there is no\globalinhTEX materiali. Note that we could define and init the key as follows:
% \lst@Key{sensitive}t[t]{\lstKV@SetIf{#1}\lst@ifsensitive}
% \lst@AddToHook{SetLanguage}{\let\lst@ifsensitive\iftrue}