1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
%! TEX program = lualatex
\ProvidesFile{prettytok.tex} [2022/07/08 v0.0.1 ]
\documentclass{l3doc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
\GetFileInfo{\jobname.tex}
\DoNotIndex{\newcommand,\newenvironment}
\title{\textsf{prettytok} --- Pretty-print token lists\thanks{This file
describes version \fileversion, last revised \filedate.}
}
\author{user202729%
%\thanks{E-mail: (not set)}
}
\date{Released \filedate}
\maketitle
\changes{v0.0.0}{2022/05/18}{First public release}
\begin{abstract}
Pretty-print token lists to HTML file for debugging purposes.
Open the file in any browser to view the result.
Can be used to replace |\tl_analysis_show:n|.
\end{abstract}
\section{Usage}
\subsection{Main function}
\begin{function}{\pretty:n,\pretty:x,\pretty:o,\pretty:V}
\begin{syntax}
\cs{pretty:n} \Arg{token list}
\end{syntax}
Print the content of \meta{token list}.
\end{function}
\begin{function}{\pretty:N,\pretty:c}
\begin{syntax}
\cs{pretty:N} \meta{token}
\cs{pretty:c} \Arg{control sequence name}
\end{syntax}
Print \meta{token}.
This function is not very useful. Usually it's preferable to use |\pretty:V| to print a token list variable's value,
or |\prettyshow:N| to print a control sequence's meaning.
\end{function}
\begin{function}{\prettyinit:}
\begin{syntax}
\cs{prettyinit:}
\end{syntax}
Do necessary initialization.
This should be called right after the package is loaded, after setting the configuration variables described below.
\end{function}
\subsection{Expandable interface (\LuaTeX\ only)}
\cs{prettyinit:} must be called before calling the functions in this section.
\begin{function}[EXP]{\prettye:n}
\begin{syntax}
\cs{prettye:n} \Arg{token list}
\end{syntax}
Print the token list, similar to \cs{pretty:n}, but is fully expandable.
\end{function}
\begin{function}[EXP]{\prettye:w}
\begin{syntax}
\cs{prettye:w} \meta{tokens} \cs{prettystop}
\end{syntax}
Print the tokens until \cs{prettystop} is seen. Useful for inspecting the content of the input stream.
Note that the input stream will be tokenized and has catcode frozen. Use with care.
\end{function}
\subsection{Lua programming interface}
\cs{prettyinit:} must also be called before calling the functions in this section.
\begin{function}{prettyprint}
\begin{syntax}
|prettyprint(|\meta{content}|)|
\end{syntax}
Print the content, which should be a table of token objects.
For convenience, you can pass multiple arguments. Strings are also supported.
\end{function}
\subsection{View result}
The result is printed to a HTML file named |pretty-|\meta{jobname}|.html| by default.
Open the file in any browser to view the result.
Note that the HTML file will not be touched if nothing is printed, as such it's encouraged to add a line such as |\pretty:n {start}| right after loading the file.
Why HTML file?
\begin{itemize}
\item If the \TeX\ program stops with error / has some error that corrupts the PDF output, the output will even with corrupted more by the debug print.
\item Printing to the console is extremely limited (difficult syntax highlighting/scrolling/line wrapping), and most likely cluttered with the traceback/other \TeX\ default output.
(nevertheless, there might be plan to support output to console with syntax highlighting later.)
\item Output to another \TeX\ file to be compiled works as well; however it's necessary to run another instance of |latexmk| (or other tool used to compile \TeX\ code)
and compiling \TeX\ file takes longer than loading a HTML file.
\end{itemize}
By default, the output refreshes whenever the \TeX\ file is recompiled. The behavior
can be customized with \cs{prettyrefreshstrategy} and \cs{prettyrefreshduration}.
\subsection{Additional functions}
There are also these functions, for convenience.
\begin{function}{\pretty:nn, \pretty:nnn}
\begin{syntax}
\cs{pretty:nn} \Arg{token list} \Arg{token list}
\cs{pretty:nnn} \Arg{token list} \Arg{token list} \Arg{token list}
\end{syntax}
Print multiple token lists. Its effect is similar to multiple consecutive calls to \cs{pretty:n}.
\end{function}
\begin{function}[EXP]{\prettye:nn, \prettye:nnn}
\begin{syntax}
\cs{prettye:nn} \Arg{token list} \Arg{token list}
\cs{prettye:nnn} \Arg{token list} \Arg{token list} \Arg{token list}
\end{syntax}
Similar to multiple consecutive calls to \cs{prettye:n}.
\end{function}
\begin{function}[EXP]{\prettye:nw, \prettye:nnw}
\begin{syntax}
\cs{prettye:nw} \Arg{token list} \meta{tokens} \cs{prettystop}
\cs{prettye:nnw} \Arg{token list} \Arg{token list} \meta{tokens} \cs{prettystop}
\end{syntax}
Similar to call(s) to \cs{prettye:n} followed by a call to \cs{prettye:w}.
\end{function}
\begin{function}{\pretty:w}
\begin{syntax}
\cs{pretty:w} \meta{token list} \cs{prettystop}
\end{syntax}
Print the content of \meta{token list}.
Same restriction applies -- the catcode is frozen.
In addition -- for now, it must be brace-balanced and if \meta{token list} has a surrounding brace group it will be removed. Use \cs{prettye:w} instead if possible.
\end{function}
\begin{function}[EXP]{\prettystop}
\begin{syntax}
\cs{prettystop}
\end{syntax}
Only used as a delimiter for |:w| functions. For convenience, this function is defined to do nothing.
\end{function}
\begin{function}{\prettyshow:N,\prettyshow:c}
\begin{syntax}
\cs{prettyshow:N} \meta{token}
\cs{prettyshow:c} \Arg{control sequence name}
\end{syntax}
Show the meaning of a |N|-type argument.
\end{function}
\subsection{\LaTeXe\ interface}
\begin{function}{\prettyN,\prettyX,\prettyO,\prettyV,\prettyinit,\prettyshowN,\prettyshowC}
\begin{syntax}
\tn{prettyN} \Arg{token list}
\tn{prettyX} \Arg{token list}
\tn{prettyO} \Arg{token list}
\tn{prettyV} \meta{tl var}
\tn{prettyinit}
\tn{prettyshowN} \meta{token}
\tn{prettyshowC} \Arg{control sequence name}
\end{syntax}
Alias of the correspondingly-named commands.
\end{function}
\begin{function}[EXP]{\prettyeN,\prettyeW}
\begin{syntax}
\cs{prettyeN} \Arg{token list}
\cs{prettyeW} \meta{tokens} \cs{prettystop}
\end{syntax}
Alias of the correspondingly-named commands. Only available in \LuaTeX.
\end{function}
\subsection{Customization}
These variables can be redefined before the
first call to \cs{pretty:n} or \cs{prettyinit:} to customize the behavior.
\begin{variable}{\prettyfilename}
The output file name. Defaults to |pretty-|\meta{jobname}|.html|, as mentioned above.
\end{variable}
\begin{variable}{\prettyrefreshstrategy}
The auto-refresh strategy. Allowed values are 0-4. 0 is no refresh. \\
Which value works best depends on the particular browser. \\
On Google Chrome, passing |--allow-file-access-from-files| may be useful.
\end{variable}
\begin{variable}{\prettyrefreshduration}
The duration between two consecutive refresh check, in milliseconds. Defaults to 1000.
\end{variable}
\section{Implementation}
Unfortunately, the implementation is not typesetted in \TeX. Read the |.sty| file.
\StopEventually{^^A
\PrintChanges
\PrintIndex
}
\Finale
\end{document}
|
