Lex Runner

Run and develop Lex/Flex scanner programs directly from VS Code and Cursor.

Lex Runner brings the classic Lex/Flex workflow into your editor: syntax highlighting for .l files, one-click compile and run, input-file support, and compiler errors surfaced right in the Problems panel.

Supports .l Lex/Flex source files.

Features

• Run Lex files — compile and run the active .l file from the editor title bar or the Command Palette.
• Flex execution — generates lex.yy.c using Flex.
• GCC / G++ compiler support — compiles the generated C/C++ scanner with gcc or g++.
• Automatic C/C++ compiler detection — picks C or C++ based on %option declarations and source heuristics, with a configurable fallback.
• Compile Only — the Flex + compiler pipeline without executing.
• Input file support — feed a file to the program's standard input, with a remembered last-selected input and automatic input.txt detection.
• Diagnostics / Problems integration — Flex and compiler errors and warnings appear as clickable diagnostics in the Problems panel.
• Syntax highlighting — TextMate grammar for Lex/Flex sections, rules, and embedded C/C++.
• Autocomplete / snippets — starter snippets for common Lex constructs (lex, %option, character classes, start conditions, and more).
• Debugging — a cppdbg launch configuration snippet for GDB.

Requirements

Lex Runner needs Flex and a C or C++ compiler (GCC/G++) installed and on your PATH.

Linux (Debian/Ubuntu)

sudo apt install flex gcc g++

macOS (Homebrew)

brew install flex
# gcc/g++ come with the Command Line Tools; install them if prompted:
xcode-select --install

Windows

• Install Flex via WinFlexBison or a package manager (e.g. choco install flex).
• Install a C/C++ compiler such as MinGW-w64 or the GCC toolchain, and make sure gcc/g++ are on your PATH.

The compiler defaults to gcc/g++ and Flex defaults to flex. Override these in Settings if your tools use different names or locations.

Getting Started

1. Open a .l Lex/Flex file.
2. Click the Run (▶) button in the editor title bar, or open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and search for Lex Runner.
3. Choose an action.

Available actions:

• Run Lex File — compile and run the current file.
• Run with Input File — compile and run, feeding a file to standard input.
• Compile Only — run Flex and compile without executing.
• Lex Runner Settings — open the extension settings.

Example Lex Program

%{
#include <stdio.h>
%}

%%
[ \t\n]+      { /* skip whitespace */ }
[0-9]+        { printf("NUMBER: %s\n", yytext); }
[a-zA-Z_]+    { printf("WORD: %s\n", yytext); }
.             { printf("OTHER: %s\n", yytext); }
%%

int main() {
    yylex();
    return 0;
}

Open this as example.l, press Run, and Lex Runner will run flex, compile the generated lex.yy.c, and execute the result.

C / C++ Compiler Detection

Lex Runner decides whether to use the C or C++ compiler:

1. An explicit %option c++ selects C++, and %option c selects C.
2. Otherwise, heuristics look for C/C++ constructs (#include <iostream>, using namespace std, cout, printf, etc.).
3. If the source is ambiguous, the lexRunner.defaultCompiler setting (C by default) is used.

You can force a mode at any time with the lexRunner.compilerMode setting (auto, c, or cpp).

Settings

All settings are in the Lex Runner configuration group (prefixed lexRunner.). Notable options:

Open them via Lex Runner → Settings or the Settings editor.

Diagnostics & Problems

When Flex or the compiler reports errors or warnings, Lex Runner parses the output and shows them as clickable diagnostics in the Problems panel. Errors from the generated lex.yy.c are mapped back to the originating .l file where possible. The raw output remains in the integrated Lex Runner terminal.

Compatibility

Lex Runner is a standard VS Code extension, so it works in Visual Studio Code, Cursor, and other VS Code-compatible editors through the same install mechanism.

Install from VSIX

1. Download the lex-runner-0.1.0.vsix file from the release.
2. In VS Code/Cursor, open the Extensions view.
3. Click ... (More Actions) → Install from VSIX....
4. Select the downloaded .vsix and restart the editor if prompted.

Troubleshooting

• "Flex was not found" — Install Flex and ensure it is on your PATH, or set lexRunner.flexCommand to its location.
• "C/C++ compiler was not found" — Install GCC/G++ (or MinGW on Windows) and set lexRunner.cCompiler/lexRunner.cppCompiler if needed.
• Linker errors about yywrap or other Flex symbols — Lex Runner automatically retries with -lfl (disable with lexRunner.autoLinkFlex).
• Wrong language selected (C vs C++) — Set lexRunner.compilerMode or lexRunner.defaultCompiler explicitly.
• Enabled lexRunner.debugLogging for more detail in the extension output console.

Making a Release

Releases are published automatically by the GitHub Actions workflow .github/workflows/release.yml when you create a version tag or a GitHub Release. Publishing never happens on a normal push to main — only on tagged releases.

Prerequisites

• GitHub repository access (the workflow is triggered by tags/releases you create).
• A VS Code Marketplace Personal Access Token stored as the repository secret VSCE_PAT (publisher: akshajbisht). Required — the workflow fails if it is missing.
• An Open VSX token stored as the repository secret OVSX_TOKEN. Optional — Open VSX publishing is skipped (with a clear notice) if it is absent.

Secrets are configured at Settings → Secrets and variables → Actions on GitHub. Never commit token values.

As long as @vscode/vsce and ovsx are in devDependencies, no global install is needed — the workflow installs them via npm ci.

Local release process

1. Bump the version in package.json (e.g. to 0.3.0) and commit it. The workflow requires the Git tag to match package.json exactly.
2. Push the commit, then create and push a matching v* tag.
3. Create a GitHub Release for that tag.

With the GitHub CLI (gh):

# 1. update version in package.json, then:
git add package.json
git commit -m "release: v0.3.0"
git push

# 2. tag must match package.json version
git tag v0.3.0
git push --tags

# 3. create the GitHub Release (triggers the workflow)
gh release create v0.3.0 --generate-notes

or use npm version 0.3.0 to bump and tag in one step (it commits and tags for you), then push.

What the workflow does

1. Installs dependencies (npm ci), then runs check-types, lint, and compile.
2. Verifies the Git tag matches the package.json version — aborts on mismatch.
3. Packages lex-runner-<version>.vsix.
4. Uploads the VSIX as a workflow artifact and attaches it to the GitHub Release.
5. Publishes to the VS Code Marketplace (VSCE_PAT) and Open VSX (OVSX_TOKEN).

Even if a registry credential is not configured, the VSIX artifact and Release asset are still produced.

License

Lex Runner is released under the MIT License.