Skip to content

README.md

Latest commit

 

History

History
690 lines (483 loc) · 21.6 KB

README.md

File metadata and controls

690 lines (483 loc) · 21.6 KB
Raw

Ask DeepWiki

WFL Documentation Hub

Welcome to the complete documentation for the WebFirst Language (WFL)! This is your starting point for learning WFL, from your first "Hello, World!" to building production web servers.

Programming that reads like plain English

🧪 The code in these docs is tested. Every runnable wfl example is executed against the release binary by scripts/test_docs_code_blocks.py — placeholder templates, illustrative fragments, and long-running server demos are classified rather than run. Generate a fresh audit with python3 scripts/test_docs_code_blocks.py --audit target/reports/docs-audit/DOC_CODE_AUDIT.md (reports are ephemeral output per REPOSITORY_HYGIENE.md; a historical snapshot is archived at Archive/reports/DOC_CODE_AUDIT.md). New here? Start with the output-verified Friendly WFL Tour.

📚 Documentation Sections

🎯 1. Introduction

Learn what WFL is and why it matters.

Start here if you're new to WFL or want to understand the philosophy behind the language.

Time to read: 30-45 minutes

🚀 2. Getting Started

Install WFL and write your first programs.

Hands-on guide to get you productive in under an hour.

Time to complete: 45-60 minutes

📖 3. Language Basics

Master the fundamental building blocks of WFL.

Everything you need to write effective WFL programs.

Time to complete: 3-4 hours (or skim in 1 hour if experienced)

⚡ 4. Advanced Features

Unlock WFL's powerful capabilities.

Web servers, async operations, pattern matching, and object-oriented programming — still in the same natural-language style as the basics (foundation).

Time to complete: 4-5 hours

📦 5. Standard Library

Explore WFL's 181+ built-in functions.

Complete reference for all standard library modules.

Time to read: 2-3 hours (reference material)

✨ 6. Best Practices

Write better WFL code.

Guidelines for quality, security, performance, and collaboration — aligned with the WFL foundation (readability, secure defaults, no-unlearning).

Time to read: 2-3 hours

🎓 Learning Paths

New to Programming?

Week 1: Foundations

  1. What is WFL?
  2. Installation
  3. Hello, World!
  4. Your First Program
  5. REPL Guide

Week 2: Basics

  1. Variables and Types
  2. Operators
  3. Control Flow
  4. Loops

Week 3: Building Blocks

  1. Actions (Functions)
  2. Lists
  3. Error Handling

Week 4: Practice

Month 2+: Advanced Features, Standard Library

Experienced Developer?

Quick Start (1-2 hours):

  1. Key Features - See what's different
  2. First Look - Code comparisons
  3. Installation - Get set up (5 min)
  4. Skim Language Basics - Note the natural syntax
  5. Jump to Advanced Features - Where you'll spend time

Migration Guides:

Use as reference:

Want to Build Something Specific?

Web Server:

  1. Installation
  2. Skip to Web Servers
  3. Reference Standard Library as needed

File Processing:

  1. Language Basics - Quick skim
  2. File I/O
  3. Filesystem Module

Data Validation:

  1. Pattern Matching
  2. Pattern Module

API Development:

  1. Web Servers
  2. Error Handling
  3. Best Practices

📑 Additional Resources

Guides & Tutorials

Language Reference

Contributing

🔍 Quick Reference

Common Syntax

// Variables
store name as "Alice"
change name to "Bob"

// Display
display "Hello, World!"
display "Value: " with variable

// Conditionals
check if condition:
    // code
otherwise:
    // code
end check

// Loops
count from 1 to 10:
    display count
end count

for each item in list:
    display item
end for

// Actions
define action called name with parameters x and y:
    return x plus y
end action

call name with 5 and 3

// Lists
create list items:
    add "first"
    add "second"
end list

push with items and "third"

// Error Handling
try:
    // risky code
catch:
    // handle error
end try

Common Built-in Functions

// Core
display "text"
typeof of value
isnothing of value

// Math
abs of -5          // 5
round of 3.7       // 4
floor of 3.7       // 3
ceil of 3.2        // 4

// Text
touppercase of "hello"      // "HELLO"
tolowercase of "HELLO"      // "hello"
length of "hello"           // 5
substring of "hello" from 0 length 2  // "he"

// Lists
length of list
push with list and item
pop of list

🎯 Find What You Need

"How do I...?"

...create variables? → Variables and Types

...make decisions? → Control Flow

...repeat actions? → Loops and Iteration

...organize code? → Actions (Functions)

...work with lists? → Lists and Collections

...handle errors? → Error Handling

...build a web server? → Web Servers

...read/write files? → File I/O

...validate data? → Pattern Matching

"What is...?"

...the store keyword? → Variables and Types

...check if syntax? → Control Flow

...a count loop? → Loops and Iteration

...an action? → Actions (Functions)

...typeof? → Variables and Types

"I'm getting an error..."

..."Variable 'x' is not defined" → Variables and Types

..."Expected identifier, found Keyword..." → Variables: Reserved Keywords

..."Type mismatch" → Variables: Type Safety

...General troubleshooting → Troubleshooting Guide

📊 Documentation Status

✅ Complete

  • Introduction (6 files) - What WFL is, why it matters, philosophy
  • Getting Started (7 files) - Installation through editor setup
  • Language Basics (9 files) - All fundamental concepts

🚧 In Progress

  • Advanced Features (1 of 8 complete) - Modules documentation added
  • Standard Library (11 files planned) - Coming soon
  • Best Practices (9 files planned) - Coming soon

📋 Planned

  • Guides (6 files) - Examples, cookbook, migrations, FAQ
  • Reference (6 files) - Formal specs and quick lookups
  • Development (6 files) - For contributors

Total planned: 60+ documentation files

🎓 Recommended Learning Order

Path 1: Complete Beginner (First Programming Language)

Start Here
    ↓
[Introduction]
    ↓
[Getting Started] ← Practice as you go!
    ↓
[Language Basics] ← Exercises in each section
    ↓
[Build Small Programs]
    ↓
[Advanced Features]
    ↓
[Best Practices]

Timeline: 1-2 months to proficiency

Path 2: Experienced Developer (Know Another Language)

[Key Features] → [First Look]
        ↓
[Installation (5 min)]
        ↓
[Language Basics (Skim)]
        ↓
[Advanced Features] ← Focus here
        ↓
[Standard Library] ← Use as reference

Timeline: 1-2 days to productivity

Path 3: Quick Reference (Just Need Syntax)

[Syntax Reference] ← Bookmark this
        ↓
[Cookbook] ← Copy-paste recipes
        ↓
[Standard Library] ← Function lookup

Timeline: Minutes to find what you need

💡 Learning Tips

1. Experiment in the REPL

The REPL is perfect for learning:

$ wfl
> display "Hello!"
Hello!
> store x as 10
> x plus 5
15

Learn more about the REPL →

2. Try the Examples

Every section has code examples. Type them yourself! Copying and pasting doesn't teach as well as typing.

3. Do the Exercises

Each section has practice exercises. Actually do them! They reinforce concepts.

4. Explore TestPrograms

The repository includes 90+ working WFL programs:

cd TestPrograms
ls *.wfl

These are validated, working examples you can learn from.

5. Use Your Editor

Set up VS Code with syntax highlighting:

Editor Setup Guide →

Real-time error checking helps you learn faster!

6. Ask for Help

Stuck? Check these resources:

📖 Documentation Principles

This documentation follows WFL's guiding principles:

✅ Friendly and encouraging - Welcoming tone for beginners ✅ Example-rich - Show, don't just tell ✅ Progressive - Start simple, add complexity gradually ✅ Natural language - Mirrors WFL's philosophy ✅ Practical - Real-world examples and use cases ✅ Accurate - All code examples are validated

Every code example is tested with the WFL compiler to ensure accuracy!

🔗 Essential Links

Official

Quick Access

Policy Documents

📝 Quick Start for the Impatient

Install (5 minutes):

# Download MSI from GitHub releases (Windows)
# Or: cargo build --release

First Program (2 minutes):

display "Hello, World!"

Run it:

wfl hello.wfl

Learn the Basics (1 hour):

Build Something:

🌟 Highlights

Why WFL?

// Code that reads like English
for each customer in premium_customers:
    check if customer_balance is greater than 1000:
        send_loyalty_reward to customer
    end check
end for

Learn why natural language syntax matters →

Built-in Web Server

listen on port 8080 as server

wait for request comes in on server as req
respond to req with "Hello from WFL!"

No frameworks needed! Web servers are built-in.

Type Safety

store age as 25
store name as "Alice"

// WFL catches this error before running:
// display age plus name  // ERROR: Cannot add Number and Text

Learn about type safety →

⚠️ Important Notes

Alpha Software

WFL is in alpha development (v26.1.17). This means:

  • ✅ Core features work and are tested
  • ✅ Great for learning and experimentation
  • ✅ Good for side projects and prototypes
  • ⚠️ NOT recommended for production (yet)
  • 🔄 Active development and improvements

Backward Compatibility Promise: Your code will work with future versions!

Documentation Status

Current: Sections 1-3 complete (22 files, ~61,000 words) Coming soon: Sections 4-6 and additional resources

This documentation is actively being developed. New sections are added regularly!

💬 Feedback

Found an issue with the documentation? Have a suggestion?

All contributions welcome! Even fixing typos helps.

🚀 Ready to Learn WFL?

Start your journey:

Never Programmed Before?

What is WFL? →

Ready to Install?

Installation Guide →

Want to See Code First?

First Look →

Already Installed?

Your First Program →

Welcome to WFL - Programming in Plain English! 🎉

Built by Logbie LLC • Open Source (Apache 2.0)

Documentation validated with WFL MCP Server