FScript

FScript is a lightweight, embeddable interpreter with an F#/ML-style language.

It is designed for host applications that need:

• a concise functional scripting language,
• strong static checks (Hindley-Milner type inference),
• controlled host extensibility,
• and a clear sandbox/security boundary.

Why FScript

• F#/ML lineage: immutable data, expressions-first style, pattern matching, let/fun, algebraic modeling.
• Interpreter pipeline: lexer -> parser -> type inference -> evaluator.
• Host-first extensibility: add external functions with explicit type schemes and runtime implementations.
• Security-aware embedding: script capabilities are defined by what the host exposes.

Language Snapshot

FScript currently includes:

• bindings and functions: let, let rec, and mutual recursion, lambdas,
• control flow: if/elif/else, match, for ... in ... do,
• data: list, option, tuple, map, record, discriminated unions,
• pattern matching: list, option, tuple, record, union cases,
• optional type annotations on parameters,
• type declarations: records and unions (including recursive forms),
• interpolation, pipeline operator, typeof type tokens, and nameof identifier tokens for host workflows.
• unified brace literals for records/maps ({ Field = value }, { [key] = value }, {} for empty map), with map keys typed as string.

Getting Started Tutorial

If you are new to FScript, start with the progressive tutorial:

• docs/guides/getting-started-tutorial.md

It covers installation, syntax basics, flow control, collections, pattern matching, stdlib usage, includes, and host/export concepts.

Installation

CLI via Homebrew

brew install magnusopera/tap/fscript

Embeddable language via NuGet

• MagnusOpera.FScript.Language
• MagnusOpera.FScript.Runtime

VS Code Extension

FScript has a first-party VS Code extension with syntax highlighting and Language Server features (diagnostics, completion, hover, symbols, go-to-definition, references, rename, semantic tokens, inlay hints).

• VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=MagnusOpera.fscript
• Open VSX: https://open-vsx.org/extension/MagnusOpera/fscript

The extension uses automatic .NET runtime acquisition via .NET Install Tool and falls back to dotnet from PATH when needed. Source lives in vscode-fscript/.

Repository Development

Build

make build

Test

make test

Run a script

dotnet run --project src/FScript -- samples/types-showcase.fss

Run a script with script arguments (after --):

dotnet run --project src/FScript -- samples/fibonacci.fss -- 10

Optional sandbox root override:

dotnet run --project src/FScript -- --root /tmp/sandbox samples/types-showcase.fss

Run a script from stdin:

cat samples/types-showcase.fss | dotnet run --project src/FScript -- -r .

Run stdin mode with script arguments:

cat samples/types-showcase.fss | dotnet run --project src/FScript -- -r . -- foo bar

Show CLI version:

dotnet run --project src/FScript -- version

In CLI execution modes, scripts get:

• stdlib type Environment = { ScriptName: string option; Arguments: string list }
• CLI-injected let Env = ...

Start REPL:

dotnet run --project src/FScript --

Useful samples:

• samples/types-showcase.fss
• samples/patterns-and-collections.fss
• samples/tree.fss
• samples/mutual-recursion.fss
• samples/imports-and-exports.fss

Interpreter Architecture

The core engine lives in src/FScript.Language and runs in four stages:

1. Lexing: indentation-aware tokenization.
2. Parsing: AST construction with expression/layout rules.
3. Type inference: Hindley-Milner inference + unification + optional annotations.
4. Evaluation: typed AST evaluation with immutable values and pattern matching.

Host integration lives in src/FScript.Runtime.

Extensibility Model

FScript is extended through host-provided externs.

Each extern declares:

• a public name (for script calls),
• a type scheme,
• arity,
• implementation.

Built-in host extern families include Fs.*, Json.*, Xml.*, Regex.*, hashing, GUIDs, and print. List.*, Map.*, and Option.* are provided by the embedded stdlib prelude.

For details and extension workflow, see docs/specs/external-functions.md.

Sandbox and Security

FScript runs in-process. Security is capability-based:

• scripts can only do what exposed externs allow,
• core language evaluation is deterministic over in-memory values,
• side effects and external I/O are controlled at host extern boundaries.

Operational controls (timeouts, cancellation, resource limits, process/container isolation) are host responsibilities.

See docs/specs/sandbox-and-security.md for the full model and checklist.

Documentation

• Documentation portal: docs/README.md
• Tutorial: docs/guides/getting-started-tutorial.md
• Specifications index: docs/specs/README.md
• Architecture index: docs/architecture/README.md
• FScript vs F# / OCaml: docs/guides/fsharp-ocaml-differences.md

Changelog

• CHANGELOG.md

License

This project is licensed under the MIT License.
See LICENSE.