fun/web/documentation/documentation.md

layout	published	noToc	noComments	noDate	title	subtitle	description	permalink	lang	tags
page	true	true	false	false	Fun - Documentation	Detailed documentation for the Fun programming language.	The Fun Documentation Index	/documentation/	en	documentation handbook installation usage introduction help guide howto docs specifications specs repl

Fun Documentation Index

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.md - Comprehensive handbook for the Fun language and VM: install/build, configuration flags, usage, and full feature overview.
• Fun REPL Guide - REPL guide: how to build/launch, editing and history, completions, REPL-on-error, and tips.
• Specification v0.3{:class="git"}
• Specification v0.2{:class="git"}
• Specification v0.1{:class="git"}
• Examples{:class="git"}
• Standard Library{:class="git"}

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.md - Core types (numbers, strings, arrays, maps, nil/bool), common operations, patterns, and interop notes.
• numbers.md - Working with integers and floats: arithmetic, conversions, clamping, bitwise ops, and patterns.
• strings.md - Working with strings: literals/escaping, concatenation, substr/find, split, and conversions.
• arrays.md - Working with arrays: creation, indexing/slicing, iteration patterns, helpers, and idioms.
• maps.md - Working with maps: construction, lookup/update, merging, iteration, and common patterns.
• includes.md - Using local vs. system includes, FUN_LIB_DIR, DEFAULT_LIB_DIR, and namespaced includes with as.
• opcodes.md - VM opcodes overview grouped by domain with brief behavior/stack notes.
• internals.md - Implementation details: bytecode format, VM architecture, stacks/frames, parser, and dispatch.
• rust.md - Writing Rust-backed opcodes and wiring them into the C VM; build/setup notes.
• examples.md - How to run the examples and the interactive showcase script, with environment tips.
• testing.md - How to build and run tests/targets with CMake/CTest, and where to add new tests.
• troubleshooting.md - Common issues and quick fixes for build, includes, and REPL usage.

New and supplemental guides

• build.md - 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.md - Command-line usage of the fun executable: synopsis, options, exit codes, includes and library paths.
• fun.md - Full usage guide for the fun executable: invocation patterns, REPL, env vars, include paths, examples, and install locations.
• asyncio.md - Async I/O primitives and patterns: non-blocking sockets, fd polling, examples, and best practices.
• funstx.md - Syntax checker for .fun files with optional --fix auto-corrections; usage, exit codes, and limitations.
• contributing.md - How to contribute: project structure, coding style, running tests, and PR guidelines.
• style-guide.md - Coding conventions for C and Fun (indentation, naming, idioms).
• stdlib.md - Overview of the standard library modules under ./lib with one-line summaries.
• embedding.md - Embedding the VM from C/Rust, lifecycle, and host integration tips.
• errors-and-diagnostics.md - Understanding parser/runtime errors and enabling diagnostics.
• performance.md - Build/runtime tuning tips and patterns for better performance.
• security-and-sandboxing.md - Trust boundaries, I/O expectations, and capability restrictions.
• faq.md - Frequently asked questions and quick answers.
• website.md - Documentation for the fun-lang.xyz website in the ./web/ directory.
• writing-tests.md - How to author new tests for Fun and opcode components.
• bytecode-format.md - Reference for the bytecode format (split out from internals for convenience).
• roadmap.md - High-level direction, planned features, and pointers to issues.

Examples

• examples/README.md - Catalog of all example scripts under ./examples/: what each area contains, how to run them, required env vars, and extension requirements.

External extensions

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

• Index of extensions
• Highlights: cURL, INI, JSON, XML (libxml2), SQLite, PCRE2, PC/SC, OpenSSL

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.md.
• Crypto examples:
  • If built with -DFUN_WITH_OPENSSL=ON, try examples/crypto/openssl_md5.fun.