This file serves as an index of the documents in this directory. Links are relative and can be opened directly on Git hosting or locally.

Basics

  • Handbook - Comprehensive handbook for the Fun language and VM: install/build, configuration flags, usage, and full feature overview.
  • REPL - REPL user guide: how to build/launch, editing and history, completions, REPL-on-error, and tips.
  • Specification
  • Examples
  • Standard Library

The examples directory contains demonstrations of most Fun features, from basic “Hello, World!” to threading, networking, classes, and more. The lib directory includes modules written in Fun itself.

Overview

  • Types - Core types (numbers, strings, arrays, maps, nil/bool), common operations, patterns, and interop notes.
    • Numbers - Working with integers and floats: arithmetic, conversions, clamping, bitwise ops, and patterns.
    • Strings - Working with strings: literals/escaping, concatenation, substr/find, split, and conversions.
    • Arrays - Working with arrays: creation, indexing/slicing, iteration patterns, helpers, and idioms.
    • Maps - Working with maps: construction, lookup/update, merging, iteration, and common patterns.
  • Includes - Using local vs. system includes, FUN_LIB_DIR, DEFAULT_LIB_DIR, and namespaced includes with as.
  • Opcodes - VM opcodes overview grouped by domain with brief behavior/stack notes.
  • Internals - Implementation details: bytecode format, VM architecture, stacks/frames, parser, and dispatch.
    • VM - VM configuration constants: maximum stack depth, local/global variable limits, and output buffer size.
    • Rust - Writing Rust-backed opcodes and wiring them into the C VM; build/setup notes.
  • Examples - How to run the examples and the interactive showcase script, with environment tips.
  • Testing - How to build and run tests/targets with CMake/CTest, and where to add new tests.
  • Troubleshooting - Common issues and quick fixes for build, includes, and REPL usage.

New and supplemental guides

  • Build - How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST, FUN_WITH_OPENSSL).
  • CLI - Command-line usage of the fun executable: synopsis, options, exit codes, includes and library paths.
  • fun - Full usage guide for the fun executable: invocation patterns, REPL, env vars, include paths, examples, and install locations.
  • Asyncio - Async I/O primitives and patterns: non-blocking sockets, fd polling, examples, and best practices.
  • funstx - Syntax checker for .fun files with optional –fix auto-corrections; usage, exit codes, and limitations.
  • Contributing - How to contribute: project structure, coding style, running tests, and PR guidelines.
  • Style-Guide - Coding conventions for C and Fun (indentation, naming, idioms).
  • stdlib - Overview of the standard library modules under ./lib with one-line summaries.
  • Embedding - Embedding the VM from C/Rust, lifecycle, and host integration tips.
  • Errors-and-Diagnostics - Understanding parser/runtime errors and enabling diagnostics.
  • Performance - Build/runtime tuning tips and patterns for better performance.
  • Security-and-Sandboxing - Trust boundaries, I/O expectations, and capability restrictions.
  • FAQ - Frequently asked questions and quick answers.
  • Website - Documentation for the fun-lang.xyz website in the ./web/ directory.
  • Writing-Tests - How to author new tests for Fun and opcode components.
  • Bytecode-Format - Reference for the bytecode format (split out from internals for convenience).
  • Roadmap - High-level direction, planned features, and pointers to issues.

Examples

Extensions

Documentation for optional, build-time selectable integrations lives in ./extensions/:

Tips

  • When building from the repo without installing, set FUN_LIB_DIR to the local ./lib directory so examples and the REPL can locate the stdlib.
  • For a broader project overview and quickstart, see the repository root README.
  • Crypto examples:
    • If built with -DFUN_WITH_OPENSSL=ON, try examples/crypto/openssl_md5.fun.

Comments