%! 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}
