5 releases
0.2.0 | Sep 7, 2022 |
---|---|
0.1.3 | Sep 6, 2022 |
0.1.2 | Sep 5, 2022 |
0.1.1 | Sep 5, 2022 |
0.1.0 | Nov 30, 2021 |
#1399 in Parser implementations
25 downloads per month
17KB
188 lines
Standalone Syntax highlighter for OpenFOAM dictionaries
DISCLAIMER: This offering is not approved or endorsed by OpenCFD Limited, producer and distributor of the OpenFOAM software and owner of the OPENFOAM® and OpenCFD® trade marks.
Installation & Usage
As this is a Rust (mini) project, you'll have to have cargo
installed:
cargo install foam-highlighter
Then, provide both the output format and the input filename to parse:
foam-highlighter html /path/to/foam/Dict
If parsing was successful, a styled HTML snippet will be sent to your stdout
.
Configuration
Options for the output format are html
and pygtex
:
- html output gives you a populated
<code>
tag and uses highlight.js classes for styling. Currently no way of changing the class names is provided (Aside from changing the hard-coded names insrc/main.rs
). This output format is ideal obviously if you want to highlight OpenFOAM code on webpages and HTML-based presentations. - pygtex output gives a (fake-but-valid) Pygments output in the
pygtex
format. This is the format used byminted
package to highlight code in Latex. Starting with an empty minted environment, copying the output into the empty Verbatim environment of the corresponding*pytex
file and recompiling will result in correct highlighting of OpenFOAM snippets in academic publications.
From an efficiency point view, both the parse and the highlighter are quite fast. A Pygments lexer for OpenFOAM is not available unfortunately so no performance comparisons are possible.
We're also depending on OpenFOAM grammar for Tree-Sitter, which can parse all tutorial files from OpenFOAM 8 and Foam-Extend 4 repositories. If you suspect there is an issue with the parser, please open an issue there.
Potential use cases
Highlighted HTML code blocks
Consider the following OpenFOAM dictionary:
// this is ?{\color{orange} \LaTeX code}?
key val;
dict {
key1 "val";
key2 {
/*
More ?\LaTeX code if you want: $\phi$?
*/
}
}
Running the highlighter with foam-highlighter html dictName
returns a populated code tag which
can be used in HTML documents:
<pre><code class="language-foam hljs">
<span class="hljs-comment">// this is ?{\color{orange} \LaTeX code}?</span>
<span class="hljs-title">key</span> val<span class="hljs-punctuation">;</span>
<span class="hljs-type">dict</span> <span class="hljs-punctuation">{</span>
<span class="hljs-title">key1</span> <span class="hljs-string">"val"</span><span class="hljs-punctuation">;</span>
<span class="hljs-type">key2</span> <span class="hljs-punctuation">{</span>
<span class="hljs-comment">/*
More ?\LaTeX code if you want: $\phi$?
*/</span>
<span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>
</code></pre>
Highlighted code listings in Tex documents through minted
For usage within LaTeX documents, a bit of special treatment is needed which is demonstrated
by the demo files where some modifications to the minted macros is carried out so
it calls the highlighter instead of pygmentize
only in the actual highlighting operation.
For convenience, the user of the minted-openfoam.sty file can toggle between this behavior and the original one (for highlighting other code snippets).
The Tex file looks like this:
\documentclass[9pt]{article}
%% A minimal example of working OpenFOAM highlighting using minted
%% Compiles with all major engines (pdflatex, lualatex and xelatex)
\usepackage{amsmath, amsfonts}
\usepackage{tikz}
\usetikzlibrary{tikzmark}
\usepackage[cachedir=_minted-cache]{minted}
\makeatletter
\def\minted@jobname{openfoam-highlight}
\makeatother
%% Step 0: include the provided sty file
\input{minted-openfoam.sty}
\begin{document}
%% Turn on Foam Highlighter in this section
\usefoamhlttrue
%% Use ?? for Tex escape inside the highlighter
\renewcommand{\escapeinsidechar}{?}
\LaTeX code and math mode in OpenFOAM comments
\tikz[remember picture,overlay,baseline=0pt] \draw[->,thick,dashed,blue] (0,-0.5em)
to[bend left] ([shift={(1ex,1ex)}]pic cs:code); and even inline OpenFOAM expressions
\mintinline{cpp}{key val;} get highlighted.
\inputminted[escapeinside=??]{cpp}{of-dicts/sampleDict}
%% Turn if off to render other code snippets normally
\usefoamhltfalse
\end{document}
By doing this, you get nicely highlighted OpenFOAM dictionaries in Latex documents with the ability to run arbitrary Tex code in the OpenFOAM comments.
Note 1: the
escapeinside=??
minted option needs to what's used in the OpenFOAM dictionary and the last (optional) parameter to the highlighter
Note 2:
escapeinside
is the only supported minted option which relates to the input file's content. E.g.mathescape
and the like are not supported by the highlighter
Sounds painful? Well this is the best we can do - The only other option is to write a Pygments Lexer for OpenFOAM case files; and nobody will do that!
To see what's supported by the parser, head over to OpenFOAM grammar for Tree-Sitter
Dependencies
~3.5–5.5MB
~107K SLoC