hanez/fun
1
0
Fork 0
forked from fun/fun
Code Pull requests Activity

Holiday is over, now I have fun again. No code changes. (0.38.11)

Browse source
This commit is contained in:
Johannes Findeisen 2026-02-18 18:11:21 +01:00
commit 15082bdc3e
9 changed files with 78 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

54
docs/README.md
View file

@ -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

4
docs/bytecode-format.md
View file

@ -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.

18
docs/cli.md
View file

@ -7,24 +7,24 @@ Reference for the `fun` command-line interface.
fun [options] <script.fun> [-- 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:

22
docs/contributing.md
View file

@ -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.

10
docs/embedding.md
View file

@ -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.

2
docs/errors-and-diagnostics.md
View file

@ -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

14
docs/faq.md
View file

@ -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).

12
docs/roadmap.md
View file

@ -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.

20
docs/stdlib.md
View file

@ -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).