OpenFOAM Language Support for VS Code

VS Code support for OpenFOAM case files: syntax highlighting, hover docs, completions, diagnostics, a case explorer, and quick geometry preview.

What's New

0.7.3

• Search & Configure — @ inline trigger. Type @ (or @pimple, @fixed, …) where a key or block name would go — the completion popup fills with scaffoldable features ranked for the current file, and accepting one drops the block in as a snippet right where you typed, with the parameters as tab-stops. Covers boundary conditions and the SIMPLE/PIMPLE/PISO blocks with a full field draft, plus turbulence models and schemes as a searchable starting-point insert.
• ? — OpenFOAM C++ API help. Type ?name (e.g. ?kOmegaSST, ?fixedValue) to search cpp.openfoam.org's class list — the detail pane shows each match's brief, and with openfoam.docs.onlineHelp on, the class page's full Detailed Description rendered inline. Enter opens the docs in a persistent panel beside the editor (openfoam.docs.onAccept: panel default, or browser / comment / none). Hovering an identifier that names an OpenFOAM class shows the brief + description inline. Ships with a bundled class index (briefs + links work offline); openfoam.docs.onlineHelp opts into all cpp.openfoam.org traffic (index refresh + page fetches, cached ~7 days), openfoam.docs.apiVersion picks the version.
• Staging tab. Set openfoam.scaffold.insertMode to "stagingTab", or run OpenFOAM: Search & Configure (Ctrl+Alt+O / Cmd+Alt+O), to open the block in an editable buffer instead — full highlighting and diagnostics while you edit, with Write → <target>, Change target (autocompletes over the case's dictionary files; add > block to change nesting) and Discard buttons. Nothing is written until Write, which creates the enclosing block (and the file) if needed.

0.7.2

• Semantic highlighting for resolvable references. Values that point at something real in the case get a distinct, theme-aware colour by category — a geometry file in constant/triSurface/, a .eMesh, a $variable with a definition, a boundary patch in constant/polyMesh/boundary, a resolvable #include path. Names that resolve to nothing stay the default colour, so typos and stale references visibly stand out.

0.7.1

• Fixed a false-positive "#include: cannot find" error on paths using $FOAM_CASE (and other standard OpenFOAM variables) — common in HELYX cases with a system/includeDicts/ convention.

0.7.0 — tree-sitter overhaul

This release replaced the extension's parsing engine with tree-sitter, a real parser built specifically for OpenFOAM/Helyx dictionary syntax. That change unlocked several new features and fixed a number of longstanding bugs:

New features

• Smarter diagnostics: the extension now catches more real mistakes — unknown keywords, missing required keywords, and invalid values (e.g. an unrecognized startFrom option) — for controlDict, blockMeshDict, decomposeParDict, snappyHexMeshDict, helyxHexMeshDict, fvSchemes, fvSolution, turbulenceProperties, boundaryField, regionProperties, phaseProperties, and mapFieldsDict.
• Precise syntax-error locations: a missing semicolon or unbalanced brace is now reported at its exact location in every file type, instead of only a generic whole-file warning.
• Smarter boundary-condition completions: typing a type inside a boundary condition now only suggests conditions that are actually valid for that field — editing U no longer suggests pressure-only types, and editing p no longer suggests velocity-only types.
• Helyx helyxHexMeshDict keyword support: Helyx-specific snappyHexMeshDict extensions (feature refinement, gap closure, layer/mesh-quality controls, and more) are now recognized instead of being flagged as unknown or missing entirely from completions.

Bugs fixed

• Signature help (parameter hints while typing a scheme like Gauss linearUpwind grad(U)) previously never actually triggered for the standard single-line entry format — it does now.
• Hover and completion for several controlDict/blockMeshDict/ snappyHexMeshDict keywords were silently broken due to a data-lookup bug; fixed.
• Dotted and composite identifiers (alpha.water, div(phi,U)) now resolve correctly everywhere (hover, rename, go-to-definition) instead of being cut off at the first special character.
• Quoted strings, comments, and multi-line list values are now parsed correctly in every case, including edge cases (braces inside comments or strings) that could previously corrupt parsing of the rest of the file.
• The packaged extension is roughly 17x smaller than before (no longer accidentally bundling large example case files).

See CHANGELOG.md for the full technical write-up.

Features

Syntax Highlighting

Understands the main OpenFOAM dictionary patterns and highlights them clearly:

• FoamFile header fields
• Keywords: ddtSchemes, SIMPLE, PIMPLE, solvers, relaxationFactors, …
• Scheme names: Gauss, linearUpwind, vanLeer, CrankNicolson, …
• Turbulence models: kOmegaSST, SpalartAllmaras, Smagorinsky, WALE, …
• Boundary conditions: fixedValue, zeroGradient, kqRWallFunction, nutkWallFunction, …
• Linear solvers and preconditioners: GAMG, PCG, PBiCGStab, DIC, DILU, …
• Decomposition methods: scotch, simple, hierarchical, …
• Dimension sets [kg m s K mol A cd], vectors (x y z), numbers, booleans
• $variable references and #include directives

On top of that, semantic highlighting gives a distinct colour to values that resolve to something real — a geometry file in constant/triSurface/, a $variable with a definition, a boundary patch in constant/polyMesh/boundary, a resolvable #include — so a typo stands out from a correct reference.

Hover Documentation

Hover a keyword to see what it does, common values, and a short usage hint. Coverage includes:

Auto-Completion

Completion suggestions are based on where you are in the file:

• Inside ddtSchemes { } → offers Euler, backward, CrankNicolson, …
• Inside gradSchemes { } → offers Gauss linear, leastSquares, cellLimited, …
• Inside divSchemes { } → offers Gauss <scheme> variants
• Inside solvers { } → offers solver names and required keywords
• Inside SIMPLE { } / PIMPLE { } → offers algorithm-specific keywords
• Inside RAS { } → lists all RANS model names
• Inside boundaryField { } → lists boundary condition types
• Inside controlDict → all control keywords with defaults

Outline View

Shows the document structure in the Explorer and outline view so it is easier to move through large dictionaries.

Case Explorer

A dedicated OpenFOAM view in the Activity Bar that shows your case directory tree, with quick actions (copy relative path, reveal in Finder, duplicate file, find file in case) available from each item's context menu.

Geometry Preview

Right-click an .stl, .obj, or .vtk file (in the Case Explorer or a geometry { }/triSurface reference) and choose OpenFOAM: Preview Geometry (3D) to open an interactive 3D viewer.

Viewer controls:

• Left drag: rotate
• Right drag or Shift + drag: pan
• Mouse wheel: zoom

Auto-Detection

Files in system/, constant/, and time directories such as 0/ or 1/ are detected automatically even when they have no extension.

Commands

Supported Files

system/

controlDict, fvSchemes, fvSolution, blockMeshDict, snappyHexMeshDict, decomposeParDict, fvOptions, topoSetDict, setFieldsDict, refineMeshDict

constant/

transportProperties, turbulenceProperties, momentumTransport, thermophysicalProperties, thermophysicalProperties.gas, phaseProperties, g, RASProperties

0/ (boundary conditions)

U, p, p_rgh, k, epsilon, omega, nut, nuTilda, T, rho, alpha.*, G, Ii, and any other field file

Installation

# Install dependencies and build from source
git clone https://github.com/arefhm94/openfoam-vscode-extension.git
cd openfoam-vscode-extension
npm install
npm run compile

# Package and install the extension locally
vsce package
code --install-extension openfoam-language-support-*.vsix

Rebuilding the Keyword Database

The extension ships with a pre-built data/keyword-db.json. To regenerate it from a local OpenFOAM 13 source tree:

1. Run Ctrl+Shift+P → OpenFOAM: Rebuild Keyword Database
2. Enter the path to your OpenFOAM 13 source root (e.g. /path/to/OpenFOAM-13)
3. The terminal runs 13 extraction scripts and merges the results
4. Reload VS Code when complete

Project Structure

src/
  extension.ts                       # Extension entry point
  language-server/server.ts          # LSP server (hover, completion, diagnostics)
  treeSitter/                        # tree-sitter parsing, schema-driven diagnostics, semantic tokens
  scaffold/                          # "Search & Configure" `@` insert engine
  docs/                              # `?` cpp.openfoam.org lookup + hover
  workflow/GeometryPreviewPanel.ts   # Standalone 3D geometry preview
  providers/
    OpenFOAMDocumentSymbolProvider.ts  # Outline view
    OpenFOAMCodeLensProvider.ts        # Inlay hints / boolean toggles
    OpenFOAMCaseTreeProvider.ts        # Case Explorer
syntaxes/openfoam.tmLanguage.json    # TextMate grammar (editor syntax highlighting)
data/keyword-db.json                 # Keyword database
data/openfoam-classes.json           # Bundled cpp.openfoam.org class index (scripts/build-doc-index.js)
scripts/                             # Python extraction scripts (01–13)
examples/                            # Example OpenFOAM cases (dev/test only, not packaged)

Parsing itself lives in a separate tree-sitter grammar package, tree-sitter-openfoam, consumed via web-tree-sitter.

Notes

• The geometry viewer is built as a webview panel, so final placement still depends on the current VS Code layout.
• Geometry preview currently focuses on STL-based workflows and common case-relative geometry paths.
• Deep keyword-level diagnostics currently cover the file types listed under "What's New" above; other file types still get syntax highlighting, hover, outline, and parse-error diagnostics, just not unknown-keyword/missing-required-keyword checks yet.

License

GPL-3.0 — same as OpenFOAM.