\begin{filecontents*}[overwrite]{dat.hex} 00 00 00 00 00 00 00 00 00 08 00 00 00 00 00 00 00 00 10 00 00 00 00 00 00 00 00 7fffffffee10 58 ee ff ff ff 7f 00 00 7fffffffee18 55 24 40 00 00 00 00 00 7fffffffeea0 55 24 40 00 00 00 00 00 7fffffffeea8 55 24 40 00 00 00 00 00 \end{filecontents*} \begin{filecontents*}[overwrite]{dat-small.hex} 0 00 00 2 00 00 4 00 00 6 00 00 8 00 00 \end{filecontents*} \documentclass{ltxdoc} \usepackage{hexdumptikz} \usepackage[numbered]{hypdoc} \usepackage{csquotes} \usepackage[T1]{fontenc} \usepackage{amsmath} \usepackage{cleveref} \usepackage[per-mode=fraction,sticky-per]{siunitx} \newcommand{\TikZ}{Ti\emph{k}Z} \usepackage{naive-ebnf} \usepackage{tcolorbox} \tcbuselibrary{listingsutf8,documentation,breakable,skins} \tcbset{ docexample/.append style={ skin=enhanced, fonttitle=\bfseries\sffamily, } } \colorlet{ExampleFrame}{blue!60} \makeindex \tcbset{ doc head={colback=yellow!10!white,interior style=fill}, doc head key={colback=magenta!5!white,interior style=fill}, index colorize, index annotate, index format=pgfsection, } \GetFileInfo{hexdumptikz.sty} \title{\textsf{hexdumptikz} -- \fileinfo} \author{Lukas Heindl\thanks{% E-Mail: \href{oss.heindl+latex@protonmail.com}{oss.heindl+latex@protonmail.com}\\% Issue tracker: \href{https://codeberg.org/atticus-sullivan/hexdumptikz/issues}{codeberg.org/atticus-sullivan/hexdumptikz/issues}\\% Codeberg (mirror): \href{https://codeberg.org/atticus-sullivan/hexdumptikz}{codeberg.org/atticus-sullivan/hexdumptikz}\\% }} \date{\fileversion~from \filedate} \addtolength{\textwidth}{\oddsidemargin} \setlength\marginparwidth{0pt} \setlength\oddsidemargin{0pt} \setlength\evensidemargin{0pt} \begin{document} \maketitle \begin{abstract} Showing hexdumps\footnote{\url{https://en.wikipedia.org/wiki/Hex_dump}} is a common task in some fields. The most rudimentary form doing this in \LaTeX is using a simple listings package (like \refPkg{listings}). But often just showing the data is not enough. Instead, it needs to be annotated and explained. This package leverages \refPkg{tikz} for printing the hexdumps. This way, it is very easy to highlight and annotate parts of the hexdump afterwards. But be careful, for large dumps, the \TikZ{} drawing alone can take some time. One key aspect of this package is that it tries to avoid calculating on the addresses as much as possible. In the cases where it is unavoidable, the package calculates just with the last digits of the addresses. This way the package tries to avoid issues where the address/offset gets too large\footnote{This happens quickly if hexdump is the dump of a processes the stack on a 64-bit machine} to represent it as an integer in \LaTeX{}. Keep in mind the drawing happens with \TikZ{} and every byte gets its own node. Thus, it may take a while to show larger hexdumps\footnote{According to my measurements it really it \TikZ{} which is responsible for the slowdown and not the selection/styling logic or the parser}. \end{abstract} \section{General remarks on the documentation} Note this documentation makes use of \emph{EBNF}\footnote{\url{https://en.wikipedia.org/wiki/Extended_Backus\%E2\%80\%93Naur_form}} for specifying valid input of some parsers. For typesetting these, the documentation uses \refPkg{naive-ebnf} which is not \qty{100}{\percent} in line with \emph{ISO/IEC 14977}. So if in doubt, better check that package's documentation ($1^\text{st}$ page) for the notation. \section{Usage} \label{usage} \begin{docEnvironment}[]{hexdumptikz}{\oarg{options}\marg{filename/path}} The environment which scopes working with a single hexdump. The commands \refCom{hexdumptikzPrint} and \refCom{hexdumptikzLabelBytes} are intended to be only used within this environment. Specify the path to the / the filename of the file with the hexdump in it as \marg{filename/path}. \oarg{options} allows to set keys from the \texttt{/hexdumptikz} space (see \cref{options}, searches also \texttt{/tikz}) for the whole scope/group. This still is inside a \TikZ{} environment (it just opens a new \TikZ{}-\texttt{scope}), so you may use arbitrary additional \TikZ{} commands inside the environment. \end{docEnvironment} \begin{docCommand}[]{hexdumptikzPrint}{\oarg{options}\marg{selector}} Read/Parse the hexdump as far as needed to fulfill the \marg{selector} and generate the \TikZ{} nodes to show the dump. See \cref{selector} for how to specify the selector. Note for this purpose, the selectors must \emph{not overlap} and be sorted in the order of occurence (thus usually it does not make sense to mix address and index selectors). Also here it does not make sense to specify a \emph{style} (but it is not an error). \oarg{options} allows to set keys from the \texttt{/hexdumptikz} space (see \cref{options}, searches also \texttt{/tikz}). Common options here are \refKey{/hexdumptikz/tikz}, \texttt{/hexdumptikz/show*}, \refKey{/hexdumptikz/styled bytes} and redefining styles automatically used when drawing. You can also set options regarding the parsing here, but usually it makes more sense to specify these for the whole environment. \end{docCommand} \begin{docCommand}[]{hexdumptikzLabelBytes}{\oarg{options}\marg{start-addr}\marg{end-addr}} Label/Highlight a sequence of bytes in the hexdump. It will draw a path around the selected bytes (a rectangle by default). The sequence of bytes is specified by \marg{start-addr} and \marg{end-addr}. It works across multiple lines and can jump over gaps and skipped offsets. Note you can only specify based on addresses, not based on indices. \oarg{options} is evaluated in the \texttt{/hexdumptikz} space (see \cref{options}, searches also \texttt{/tikz}) and allows customizing how the path is drawn. Note this command relys on information gathered during \refCom{hexdumptikzPrint} and thus needs to be executed after that command. Also \refEnv{hexdumptikz} cleans up its state in the end, so \refCom{hexdumptikzLabelBytes} must be executed within that environment. \end{docCommand} \begin{docCommand}[]{hexdumptikzLabelBytesFallback}{\oarg{options}\marg{start}\marg{end}} Basically the same as \refCom{hexdumptikzLabelBytes} but does not rely on information gathered during \refCom{hexdumptikzPrint}. Thus, it can also be used outside of \refEnv{hexdumptikz} but the line does not perfectly fit the right row in the hexdump. \Cref{simple-example} shows an example for the difference. \end{docCommand} \subsection{Simple Example} \label{simple-example} \tcbinputlisting{/tcb/docexample,/tcb/documentation listing style,listing only,listing file=dat.hex,title={file: \texttt{dat.hex}}} \begin{dispExample*}{listing options={language=[LaTeX]TeX},breakable,title={A simple example}} \begin{tikzpicture} \begin{hexdumptikz}{dat.hex} \hexdumptikzPrint{0,0x08,0x7fffffffee18-0x7fffffffeea8} \hexdumptikzLabelBytes[rounded corners]{0x2}{0xa} \end{hexdumptikz} \hexdumptikzLabelBytesFallback[rounded corners,tikz=red]{0x2}{0xa} \end{tikzpicture} \end{dispExample*} \subsection{Hexdump-Parser} \label{hd-parser} This package can implement multiple hexdump-parsers. But currently only one is implemented. % \begin{docKey}[hexdumptikz]{parser}{=\meta{parser}}{} % \end{docKey} \subsubsection{hd} \label{hd-parser-hd} This parser works with most formats. At some places it can be adjusted slightly to work with slightly different formats. Note this parser stops parsing a line after \refKey{/hexdumptikz/bytes per row} have been parsed from the line (continues with the next line then). This is the whole grammar which it can parse (for some of the optional stuff, specific keys need to be set): \begin{ebnf} := { [ '\textbackslash n' ] }+ \\ :=
[ "0x" ] \\
:= { 'SPACE' } [ "0x" ] { }+ { 'SPACE' } [ ":" ] { 'SPACE' } \\ := /[0-9a-fA-F]/ \\ := { { 'SPACE' } { 'SPACE' } } \end{ebnf} % \begin{docKey}[hexdumptikz]{parser}{=\meta{parser}}{} % \end{docKey} \subsection{Selector} \label{selector} \begin{ebnf} := { "," } \\ := [ "$\vert$" ] [ "->"