WFL — the WebFirst Language

Programming that reads like plain English.

WFL is a natural-language programming language: you write what you want to do in words, and it runs. It aims to be a genuine first language for newcomers while staying powerful enough for production — with no cliff in between.

store name as "World"
display "Hello, " with name with "!"

Hello, World!

Why WFL?

• Reads like English. check if score is greater than 90: — no cryptic symbols to memorize.
• Safe by default. Static typing with inference, clear Elm-style error messages, and secure defaults (output escaping; subprocess execution disabled unless opted in via .wflcfg).
• Batteries included. Text, math, lists, filesystem I/O, crypto, time, async/await, pattern matching, containers (objects), an HTTP client, and a built-in web server.
• No unlearning. The beginner form and the expert form are the same form — advanced features extend what you already know rather than replacing it.

See the 19 founding principles for the full philosophy.

A quick taste

define action called area with parameters width and height:
    return width times height
end action

store shapes as [3, 5, 8]
for each side in shapes:
    display "Square " with side with " has area " with area of side and side
end for

Square 3 has area 9
Square 5 has area 25
Square 8 has area 64

More runnable, output-verified examples live in the Friendly WFL Tour — eight small programs from Hello, World! to objects, each checked against the current build.

Install & build

WFL is written in Rust (edition 2024, which requires Rust 1.85 or newer).

# Build the compiler/runtime
cargo build --release

# Run a program
target/release/wfl path/to/program.wfl

# Start the interactive REPL
target/release/wfl

Windows users can install from the MSI in Releases. Full instructions: Docs/02-getting-started/installation.md.

Handy CLI flags

Command	What it does
wfl <file>	Run a program
wfl --lint <file>	Lint; add --fix --in-place to auto-fix
wfl --analyze <file>	Static analysis
wfl --test <file>	Run describe/test blocks
wfl --parse <file> / wfl --lex <file>	Dump the AST / tokens

Documentation

The complete guide lives in Docs/, organized as a learning path:

1. Introduction — what WFL is and why
2. Getting Started — install and first programs
3. Language Basics — variables, control flow, actions
4. Advanced Features — async, containers, web, patterns
5. Standard Library — every built-in module
6. Best Practices — style, testing, security

Reference: keywords · operators · built-in functions · error codes.

Documentation is tested

Every ```wfl block in the docs is extracted and — unless it is a placeholder template, an illustrative fragment, or a long-running server demo — executed against the release binary by scripts/test_docs_code_blocks.py; where a doc shows an Output: block, the script compares real stdout against it. The current state — including a per-file list of anything that doesn't run — is tracked in TestPrograms/docs_examples/DOC_CODE_AUDIT.md.

python3 scripts/test_docs_code_blocks.py           # run the whole audit
python3 scripts/test_docs_code_blocks.py --filter 03-language-basics --show-errors

Repository layout

Path	Contents
src/	Compiler & runtime (lexer, parser, analyzer, type checker, interpreter)
Docs/	User documentation (the six sections above + guides & reference)
TestPrograms/	End-to-end WFL programs (must all pass on the release build)
tests/, benches/	Rust integration tests and Criterion benchmarks
wfl-lsp/, vscode-extension/	Language Server and editor integration
examples/, Nexus/	Example and experimental WFL programs

Contributing

Contributions are welcome — including AI-assisted work. WFL itself was built with AI help; we do not discriminate against contributors for using AI tools. See AI_POLICY.md.

Document	What it covers
CONTRIBUTING.md	How to contribute & apply for Contributor status
GOVERNANCE.md	Project authority and binding policies
CODE_OF_CONDUCT.md	Community standards
REPOSITORY_HYGIENE.md	Repository layout & hygiene policy (binding)
Docs/contributing/contributing-guide.md	Day-to-day TDD / fmt / clippy / test workflow

Project conventions (also binding under governance):

• Test-driven: write failing tests first (tests/ for Rust, TestPrograms/ for WFL end-to-end).
• Backward compatibility is sacred — existing WFL programs must keep working.
• Docs ship with the feature — update Docs/ in the same change.
• One canonical home per file — placement, tracked-content, and output rules are enforced by the repo-hygiene CI gate (python3 scripts/check_repo_hygiene.py --mode static); see REPOSITORY_HYGIENE.md.
• Before a PR: cargo fmt --all -- --check, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all.

License

Licensed under the Apache License 2.0.