From 15082bdc3ed26a03621556ef9aabf3a1beb7b774 Mon Sep 17 00:00:00 2001 From: hanez Date: Wed, 18 Feb 2026 18:11:21 +0100 Subject: [PATCH] Holiday is over, now I have fun again. No code changes. (0.38.11) --- docs/README.md | 54 +++++++++++++++++----------------- docs/bytecode-format.md | 4 +-- docs/cli.md | 18 ++++++------ docs/contributing.md | 22 +++++++------- docs/embedding.md | 10 +++---- docs/errors-and-diagnostics.md | 2 +- docs/faq.md | 14 ++++----- docs/roadmap.md | 12 ++++---- docs/stdlib.md | 20 ++++++------- 9 files changed, 78 insertions(+), 78 deletions(-) diff --git a/docs/README.md b/docs/README.md index eb01ea2..75e488f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,36 +4,36 @@ This file serves as an index of the documents in this directory. Links are relat ## Overview -- [handbook.md](./handbook.md) — Comprehensive handbook for the Fun language and VM: install/build, configuration flags, usage, and full feature overview. -- [types.md](./types.md) — Core types (numbers, strings, arrays, maps, nil/bool), common operations, patterns, and interop notes. -- [numbers.md](./numbers.md) — Working with integers and floats: arithmetic, conversions, clamping, bitwise ops, and patterns. -- [strings.md](./strings.md) — Working with strings: literals/escaping, concatenation, substr/find, split, and conversions. -- [arrays.md](./arrays.md) — Working with arrays: creation, indexing/slicing, iteration patterns, helpers, and idioms. -- [maps.md](./maps.md) — Working with maps: construction, lookup/update, merging, iteration, and common patterns. -- [includes.md](./includes.md) — Using local vs. system includes, FUN_LIB_DIR, DEFAULT_LIB_DIR, and namespaced includes with `as`. -- [repl.md](./repl.md) — REPL guide: how to build/launch, editing and history, completions, REPL‑on‑error, and tips. -- [opcodes.md](./opcodes.md) — VM opcodes overview grouped by domain with brief behavior/stack notes. -- [internals.md](./internals.md) — Implementation details: bytecode format, VM architecture, stacks/frames, parser, and dispatch. -- [rust.md](./rust.md) — Writing Rust‑backed opcodes and wiring them into the C VM; build/setup notes. -- [examples.md](./examples.md) — How to run the examples and the interactive showcase script, with environment tips. -- [testing.md](./testing.md) — How to build and run tests/targets with CMake/CTest, and where to add new tests. -- [troubleshooting.md](./troubleshooting.md) — Common issues and quick fixes for build, includes, and REPL usage. +- [handbook.md](./handbook.md) - Comprehensive handbook for the Fun language and VM: install/build, configuration flags, usage, and full feature overview. +- [types.md](./types.md) - Core types (numbers, strings, arrays, maps, nil/bool), common operations, patterns, and interop notes. +- [numbers.md](./numbers.md) - Working with integers and floats: arithmetic, conversions, clamping, bitwise ops, and patterns. +- [strings.md](./strings.md) - Working with strings: literals/escaping, concatenation, substr/find, split, and conversions. +- [arrays.md](./arrays.md) - Working with arrays: creation, indexing/slicing, iteration patterns, helpers, and idioms. +- [maps.md](./maps.md) - Working with maps: construction, lookup/update, merging, iteration, and common patterns. +- [includes.md](./includes.md) - Using local vs. system includes, FUN_LIB_DIR, DEFAULT_LIB_DIR, and namespaced includes with `as`. +- [repl.md](./repl.md) - REPL guide: how to build/launch, editing and history, completions, REPL-on-error, and tips. +- [opcodes.md](./opcodes.md) - VM opcodes overview grouped by domain with brief behavior/stack notes. +- [internals.md](./internals.md) - Implementation details: bytecode format, VM architecture, stacks/frames, parser, and dispatch. +- [rust.md](./rust.md) - Writing Rust-backed opcodes and wiring them into the C VM; build/setup notes. +- [examples.md](./examples.md) - How to run the examples and the interactive showcase script, with environment tips. +- [testing.md](./testing.md) - How to build and run tests/targets with CMake/CTest, and where to add new tests. +- [troubleshooting.md](./troubleshooting.md) - Common issues and quick fixes for build, includes, and REPL usage. ## New and supplemental guides -- [build.md](./build.md) — How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST). -- [cli.md](./cli.md) — Command‑line usage of the `fun` executable: synopsis, options, exit codes, includes and library paths. -- [contributing.md](./contributing.md) — How to contribute: project structure, coding style, running tests, and PR guidelines. -- [style-guide.md](./style-guide.md) — Coding conventions for C and Fun (indentation, naming, idioms). -- [stdlib.md](./stdlib.md) — Overview of the standard library modules under ./lib with one‑line summaries. -- [embedding.md](./embedding.md) — Embedding the VM from C/Rust, lifecycle, and host integration tips. -- [errors-and-diagnostics.md](./errors-and-diagnostics.md) — Understanding parser/runtime errors and enabling diagnostics. -- [performance.md](./performance.md) — Build/runtime tuning tips and patterns for better performance. -- [security-and-sandboxing.md](./security-and-sandboxing.md) — Trust boundaries, I/O expectations, and capability restrictions. -- [faq.md](./faq.md) — Frequently asked questions and quick answers. -- [writing-tests.md](./writing-tests.md) — How to author new tests for Fun and opcode components. -- [bytecode-format.md](./bytecode-format.md) — Reference for the bytecode format (split out from internals for convenience). -- [roadmap.md](./roadmap.md) — High‑level direction, planned features, and pointers to issues. +- [build.md](./build.md) - How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST). +- [cli.md](./cli.md) - Command-line usage of the `fun` executable: synopsis, options, exit codes, includes and library paths. +- [contributing.md](./contributing.md) - How to contribute: project structure, coding style, running tests, and PR guidelines. +- [style-guide.md](./style-guide.md) - Coding conventions for C and Fun (indentation, naming, idioms). +- [stdlib.md](./stdlib.md) - Overview of the standard library modules under ./lib with one-line summaries. +- [embedding.md](./embedding.md) - Embedding the VM from C/Rust, lifecycle, and host integration tips. +- [errors-and-diagnostics.md](./errors-and-diagnostics.md) - Understanding parser/runtime errors and enabling diagnostics. +- [performance.md](./performance.md) - Build/runtime tuning tips and patterns for better performance. +- [security-and-sandboxing.md](./security-and-sandboxing.md) - Trust boundaries, I/O expectations, and capability restrictions. +- [faq.md](./faq.md) - Frequently asked questions and quick answers. +- [writing-tests.md](./writing-tests.md) - How to author new tests for Fun and opcode components. +- [bytecode-format.md](./bytecode-format.md) - Reference for the bytecode format (split out from internals for convenience). +- [roadmap.md](./roadmap.md) - High-level direction, planned features, and pointers to issues. ## Tips diff --git a/docs/bytecode-format.md b/docs/bytecode-format.md index 6d58d76..762188f 100644 --- a/docs/bytecode-format.md +++ b/docs/bytecode-format.md @@ -1,6 +1,6 @@ # Bytecode Format (Overview) -This document summarizes the Fun bytecode format. For deep VM details, see `docs/internals.md`. +This document summarizes the Fun bytecode format. For deep VM details, see [internals.md](./internals.md). ## Goals - Compact representation for fast loading and dispatch @@ -25,5 +25,5 @@ This document summarizes the Fun bytecode format. For deep VM details, see `docs - Operands encoded inline following the opcode (width varies by instruction). ## Versioning and compatibility -- The header’s version field allows the VM to refuse or translate older/newer formats. +- The header's version field allows the VM to refuse or translate older/newer formats. - Keep additions backward-compatible when possible by appending sections or flags. diff --git a/docs/cli.md b/docs/cli.md index ff036fa..0874569 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -7,24 +7,24 @@ Reference for the `fun` command-line interface. fun [options] [-- args...] ``` -If no script is supplied and interactive mode is available, `fun` starts a REPL (see `docs/repl.md`). +If no script is supplied and interactive mode is available, `fun` starts a REPL (see [repl.md](./repl.md)). ## Common options -- `-i`, `--repl` — start an interactive REPL -- `-v`, `--version` — print version and exit -- `-h`, `--help` — show help and exit +- `-i`, `--repl` - start an interactive REPL +- `-v`, `--version` - print version and exit +- `-h`, `--help` - show help and exit Options may vary between versions; run `fun --help` to see what your build supports. ## Exit codes -- `0` — success -- non-zero — error during parse, compile, or runtime +- `0` - success +- non-zero - error during parse, compile, or runtime ## Includes and library paths -- `FUN_LIB_DIR` — environment variable that points to the stdlib location; when running from the repo, set this to `./lib`. -- `DEFAULT_LIB_DIR` — compiled-in fallback path determined at build/install time. +- `FUN_LIB_DIR` - environment variable that points to the stdlib location; when running from the repo, set this to `./lib`. +- `DEFAULT_LIB_DIR` - compiled-in fallback path determined at build/install time. -See also: `docs/includes.md` for namespaced includes and search order. +See also: [includes.md](./includes.md) for namespaced includes and search order. ## Examples Run a script: diff --git a/docs/contributing.md b/docs/contributing.md index 806c833..04191e0 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -3,25 +3,25 @@ Thanks for your interest in contributing! This guide covers the basics to get you productive quickly. ## Getting started -- Clone the repo and build (see `docs/build.md`). -- Run tests locally (see `docs/testing.md`). -- Explore examples (see `docs/examples.md`). +- Clone the repo and build (see [build.md](./build.md)). +- Run tests locally (see [testing.md](./testing.md)). +- Explore examples (see [examples.md](./examples.md)). ## Project structure -- `src/` — C core, VM, and opcode implementations (`src/vm/*`). -- `lib/` — Standard library written in Fun. -- `examples/` — Example programs and showcases. -- `docs/` — Documentation. -- `spec/` — Language specification drafts. +- `src/` - C core, VM, and opcode implementations ([src/vm](../src/vm/)). +- `lib/` - Standard library written in Fun. +- `examples/` - Example programs and showcases. +- `docs/` - Documentation. +- `spec/` - Language specification drafts. ## Code style - C: C99, two-space indent, no tabs. Keep functions short and focused. - Fun: two-space indent, snake_case for functions, PascalCase for classes/constructors. -- Prefer clear names over abbreviations. See `docs/style-guide.md`. +- Prefer clear names over abbreviations. See [style-guide.md](./style-guide.md). ## Development workflow 1. Create a small, focused branch. -2. Add/adjust tests for behavior changes (see `docs/writing-tests.md`). +2. Add/adjust tests for behavior changes (see [writing-tests.md](./writing-tests.md)). 3. Update docs if user-visible behavior changes. 4. Submit a PR with a clear description and rationale. @@ -37,4 +37,4 @@ Please include: - `fun --version` output ## Code of Conduct -Be respectful and inclusive. See `CODE_OF_CONDUCT.md` in the repository root. +Be respectful and inclusive. See [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) in the repository root. diff --git a/docs/embedding.md b/docs/embedding.md index f603250..321f9fb 100644 --- a/docs/embedding.md +++ b/docs/embedding.md @@ -3,8 +3,8 @@ This guide outlines how to embed the Fun VM in a host application and extend it from C/Rust. ## Overview -- The VM is implemented in C (see `src/vm/`). -- Optional Rust-based opcodes can be enabled via `FUN_WITH_RUST` (see `docs/rust.md`). +- The VM is implemented in C (see [src/vm](../src/vm/)). +- Optional Rust-based opcodes can be enabled via `FUN_WITH_RUST` (see [rust.md](./rust.md)). ## Embedding from C While the exact API surface may evolve, a typical embedding flow looks like: @@ -14,7 +14,7 @@ While the exact API surface may evolve, a typical embedding flow looks like: 4. Execute entry function or script body. 5. Retrieve results and clean up. -See `src/vm/core` and related headers for public entry points and value types. +See [src/vm/core](../src/vm/core/) and related headers for public entry points and value types. ### Hosting considerations - Threading: share VM state cautiously or create one VM per thread. @@ -22,8 +22,8 @@ See `src/vm/core` and related headers for public entry points and value types. - Errors: propagate parse/runtime errors back to the host with useful messages. ## Extending with Rust -When `FUN_WITH_RUST=ON`, a Rust static library from `src/rust/` is built and linked. You can: +When `FUN_WITH_RUST=ON`, a Rust static library from [`src/rust/`](../src/rust/) is built and linked. You can: - Implement new opcodes/functions in Rust. - Expose a C ABI for the VM to call into. -See `docs/rust.md` for details and example code. +See [rust.md](./rust.md) for details and example code. diff --git a/docs/errors-and-diagnostics.md b/docs/errors-and-diagnostics.md index f2b5757..fc92ee3 100644 --- a/docs/errors-and-diagnostics.md +++ b/docs/errors-and-diagnostics.md @@ -8,7 +8,7 @@ This guide helps you understand common error messages and how to collect useful - Runtime errors: type mismatches, out-of-range access, invalid operations. ## Enabling diagnostics -- Build with `-DFUN_DEBUG=ON` to enable additional assertions and debug messages (see `docs/build.md`). +- Build with `-DFUN_DEBUG=ON` to enable additional assertions and debug messages (see [build.md](./build.md)). - Run with smaller, focused scripts to isolate issues. ## Getting useful reports diff --git a/docs/faq.md b/docs/faq.md index 82947b4..5e98acf 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -2,21 +2,21 @@ Answers to common questions. -## I built Fun but includes aren’t found -Set `FUN_LIB_DIR` to the repository’s `./lib` directory when running without installation: +## I built Fun but includes aren't found +Set `FUN_LIB_DIR` to the repository's `./lib` directory when running without installation: ``` FUN_LIB_DIR=./lib ./build_debug/fun examples/hello.fun ``` -See `docs/includes.md`. +See [includes.md](./includes.md). ## How do I start the REPL? -Run `fun -i` (or run `fun` without a script, depending on version). See `docs/repl.md`. +Run `fun -i` (or run `fun` without a script, depending on version). See [repl.md](./repl.md). ## Which build target should I use? -Use the aggregate `build` target to build `fun`, `fun_test`, and `test_opcodes`. See `docs/build.md`. +Use the aggregate `build` target to build `fun`, `fun_test`, and `test_opcodes`. See [build.md](./build.md). ## Where are the standard libraries? -Under `./lib/`. See `docs/stdlib.md` for an overview. +Under [`./lib/`](../lib/). See [stdlib.md](./stdlib.md) for an overview. ## Where can I find internals and opcodes? -Browse `src/vm/` and `docs/internals.md` / `docs/opcodes.md`. +Browse [src/vm](../src/vm/) and [internals.md](./internals.md) / [opcodes.md](./opcodes.md). diff --git a/docs/roadmap.md b/docs/roadmap.md index 4792b8f..3235a4f 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -9,13 +9,13 @@ This page outlines high-level areas of focus and points to places where you can - Safety: clearer error messages, diagnostics, and sandboxing guidance ## Near-term -- Expand CLI reference and examples (`docs/cli.md`) -- Improve testing docs and coverage (`docs/writing-tests.md`) -- Fill gaps in stdlib documentation (`docs/stdlib.md`) +- Expand CLI reference and examples ([cli.md](./cli.md)) +- Improve testing docs and coverage ([writing-tests.md](./writing-tests.md)) +- Fill gaps in stdlib documentation ([stdlib.md](./stdlib.md)) ## Medium-term -- Bytecode/reference updates as internals evolve (`docs/bytecode-format.md`, `docs/internals.md`) -- Embedding guides and host API stability (`docs/embedding.md`, `docs/rust.md`) +- Bytecode/reference updates as internals evolve ([bytecode-format.md](./bytecode-format.md), [internals.md](./internals.md)) +- Embedding guides and host API stability ([embedding.md](./embedding.md), [rust.md](./rust.md)) ## Contributing -See `docs/contributing.md` for how to propose and implement items. Track concrete tasks via repository issues and PRs. +See [contributing.md](./contributing.md) for how to propose and implement items. Track concrete tasks via repository issues and PRs. diff --git a/docs/stdlib.md b/docs/stdlib.md index a075823..c580379 100644 --- a/docs/stdlib.md +++ b/docs/stdlib.md @@ -1,19 +1,19 @@ # Standard Library Overview -This page provides a quick orientation to the standard library located under `./lib/`. +This page provides a quick orientation to the standard library located under [`./lib/`](../lib/). The stdlib is written in Fun and organized by domain. Below are top-level modules and what they generally cover. Refer to the source for full APIs and examples. ## Module index (selected) -- `crypt/` — cryptographic helpers (hashing, encoding helpers). See also `lib/crypt`. -- `encoding/` — text/binary encodings and conversions. -- `io/` — file and stream utilities. -- `net/` — basic networking helpers. -- `regex/` — regular expression utilities (PCRE2 when available). -- `ui/` — UI helpers (e.g., Tk if enabled at build time). -- `utils/` — small reusable helpers and utilities. +- `crypt/` - cryptographic helpers (hashing, encoding helpers). See also [lib/crypt](../lib/crypt/). +- `encoding/` - text/binary encodings and conversions. +- `io/` - file and stream utilities. +- `net/` - basic networking helpers. +- `regex/` - regular expression utilities (PCRE2 when available). +- `ui/` - UI helpers (e.g., Tk if enabled at build time). +- `utils/` - small reusable helpers and utilities. -Note: Availability of some modules can depend on optional extensions selected at build time (see `docs/build.md`). +Note: Availability of some modules can depend on optional extensions selected at build time (see [build.md](./build.md)). ## Using modules ```fun @@ -23,4 +23,4 @@ let s = strings.trim(" hello ") print(s) ``` -For search paths and namespacing details, see `docs/includes.md` and `docs/cli.md` (FUN_LIB_DIR and DEFAULT_LIB_DIR). +For search paths and namespacing details, see [includes.md](./includes.md) and [cli.md](./cli.md) (FUN_LIB_DIR and DEFAULT_LIB_DIR).