diff --git a/CMakeLists.txt b/CMakeLists.txt index 96d5229..329223f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,5 @@ cmake_minimum_required(VERSION 3.10) -project(fun VERSION 0.40.5 LANGUAGES C) +project(fun VERSION 0.40.6 LANGUAGES C) set(CMAKE_C_STANDARD 99) set(CMAKE_C_STANDARD_REQUIRED ON) diff --git a/examples/blocking/net/http_server_docs.fun b/examples/blocking/net/http_server_docs.fun new file mode 100755 index 0000000..bfe2390 --- /dev/null +++ b/examples/blocking/net/http_server_docs.fun @@ -0,0 +1,22 @@ +#!/usr/bin/env fun + +/* + * This file is part of the Fun programming language. + * https://fun-lang.xyz/ + * + * Copyright 2025 Johannes Findeisen + * Licensed under the terms of the Apache-2.0 license. + * https://opensource.org/license/apache-2-0 + * + * Added: 2026-04-21 + */ + +#include + +port = 8080 +htdocs = "./web/_site/" + +server = HTTPServer(port) +server.set_htdocs(htdocs) + +server.start() diff --git a/scripts/play.fun b/scripts/play.fun new file mode 100755 index 0000000..54eb5f9 --- /dev/null +++ b/scripts/play.fun @@ -0,0 +1,129 @@ +#!/usr/bin/env fun + +/* + * This file is part of the Fun programming language. + * https://fun-lang.xyz/ + * + * Copyright 2026 Johannes Findeisen + * Licensed under the terms of the Apache-2.0 license. + * https://opensource.org/license/apache-2-0 + * + * Added: 2026-04-21 + */ + +// Interactive showcase script for Fun examples. +// Converted from Bash to Fun. + +#include +#include +#include + +// Set FUN_LIB_DIR to ensure stdlib is found +// We try to use existing environment or default to ./lib +lib_dir = env("FUN_LIB_DIR") +if (len(to_string(lib_dir)) == 0) + lib_dir = "./lib" + +// Discovery logic for the interpreter +fun find_interpreter() + bin = env("FUN_BIN") + if (len(to_string(bin)) > 0) + return bin + + // Check common build locations + // We use 'system' with 'test -f' as we don't have a direct 'is_file' yet + if (system("test -f ./build/fun") == 0) + return "./build/fun" + if (system("test -f ./build_debug/fun") == 0) + return "./build_debug/fun" + if (system("test -f ./build_release/fun") == 0) + return "./build_release/fun" + + // Check PATH + if (system("command -v fun >/dev/null 2>&1") == 0) + return "fun" + + return "" + +interpreter = find_interpreter() +if (len(interpreter) == 0) + print("Error: fun interpreter not found. Please build it or set FUN_BIN.") + exit(1) + +print("Using interpreter: " + interpreter) +print("Searching for examples in ./examples...") + +// Recursive file discovery +// Since we don't have a robust recursive os_list_dir yet, +// and the original used 'find', we'll use 'find' via system to get the list. +fun get_examples() + // We use 'find' to get all .fun files and sort them. + // We redirect to a temporary file as we don't have a 'proc_capture' that returns an array easily + // Actually, os_list_dir uses 'ls -1'. We can use a similar approach or just call find. + + cmd = "find examples -name \"*.fun\" | sort > ./tmp/examples_list.txt" + system(cmd) + + list_str = read_file("./tmp/examples_list.txt") + // We don't have a built-in 'split' that handles newlines easily in all versions? + // Wait, lib/strings.fun might have it. + + lines = str_split(list_str, "\n") + + // Filter out empty lines + examples = [] + i = 0 + n = len(lines) + while (i < n) + line = str_trim(lines[i]) + if (len(line) > 0) + push(examples, line) + i = i + 1 + return examples + +examples = get_examples() +if (len(examples) == 0) + print("No examples found in ./examples") + exit(0) + +failed_examples = [] +console = Console() + +i = 0 +n = len(examples) +while (i < n) + example = examples[i] + print("--------------------------------------------------------------------------------") + print("Example: " + example) + + // ask_yes_no returns 1 for yes, 0 for no + print("Do you want to run this example? [y/N]") + ans = str_to_lower(str_trim(input(""))) + if (ans == "y" || ans == "yes") + print("Running: " + interpreter + " " + example) + + // Prepare command with environment variable + // FUN_LIB_DIR must be passed to the child process + cmd = "FUN_LIB_DIR=\"" + lib_dir + "\" " + interpreter + " " + example + exit_code = system(cmd) + + print("Exit code: " + to_string(exit_code)) + if (exit_code != 0) + push(failed_examples, example + " (exit code: " + to_string(exit_code) + ")") + else + print("Skipping.") + + i = i + 1 + +print("--------------------------------------------------------------------------------") +print("Done.") + +if (len(failed_examples) > 0) + print("The following examples failed:") + i = 0 + while (i < len(failed_examples)) + print(" - " + failed_examples[i]) + i = i + 1 + exit(1) + +exit(0) diff --git a/web/documentation/build/build.md b/web/documentation/build/build.md index 6c7bb5a..a5449f7 100644 --- a/web/documentation/build/build.md +++ b/web/documentation/build/build.md @@ -4,7 +4,7 @@ published: true noToc: false noComments: false noDate: false -title: Fun - Building Fun +title: Building Fun subtitle: 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). description: 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). permalink: /documentation/build/ @@ -27,11 +27,13 @@ tags: This guide describes how to build Fun from source using CMake and the available build options. ## Prerequisites + - A C compiler with C99 support - CMake 3.20+ (or newer) - Optional: Rust toolchain with cargo (required when building with `FUN_WITH_RUST=ON`) ## Common targets + - `build` - aggregate target that depends on `fun`, `fun_test`, and `test_opcodes` - `fun` - the CLI executable - `fun_test` - unit/feature tests (run with CTest) @@ -40,6 +42,7 @@ This guide describes how to build Fun from source using CMake and the available These targets are defined by the project; use your configured CMake build directory/profile. ## Build options + Fun exposes several options you can toggle at configure time: - `FUN_DEBUG` (ON/OFF) - Enables extra assertions and logging in the VM and runtime @@ -49,6 +52,7 @@ Fun exposes several options you can toggle at configure time: - `FUN_WITH_OPENSSL` (ON/OFF) - Enable OpenSSL-backed helpers (MD5/SHA-256/SHA-512/RIPEMD-160) ### VM configuration constants + You can override internal VM limits at compile time by passing `-D=` to CMake: - `MAX_FRAMES` (default: 128) - Maximum depth of the call stack (frames) @@ -61,45 +65,48 @@ These are defined as `CACHE` variables, so they will persist in your `CMakeCache When configuring, the build prints a summary like: -See [../vm/](../vm/) for more information. +See [VM](../vm/) for more information.
==== Fun build options ====
   FUN_DEBUG: ENABLED|DISABLED
   FUN_USE_MUSL: ENABLED|DISABLED
   FUN_WITH_CPP: ENABLED|DISABLED
   FUN_WITH_RUST: ENABLED|DISABLED
-===========================
-
+=========================== + ## Example commands + Use the CLion-provided build directories or your own. Typical invocations: ### Debug
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug \
   -DFUN_DEBUG=ON -DFUN_WITH_RUST=OFF
-cmake --build build --target build
-
+cmake --build build --target build + ### Release +
cmake -S . -B build_release -DCMAKE_BUILD_TYPE=Release \
   -DFUN_DEBUG=OFF -DFUN_WITH_RUST=OFF
-cmake --build build_release --target build
-
+cmake --build build_release --target build + ### Enabling optional extensions +
cmake -S . -B build_release -DCMAKE_BUILD_TYPE=Release \
   -DFUN_WITH_CPP=ON -DFUN_WITH_RUST=ON -DFUN_WITH_OPENSSL=ON
-cmake --build build_release --target build
-
+cmake --build build_release --target build + ### Customizing VM limits +
cmake -S . -B build_custom -DSTACK_SIZE=4096 -DMAX_GLOBALS=512
-cmake --build build_custom --target fun
-
+cmake --build build_custom --target fun + If `FUN_WITH_RUST` is enabled, ensure `cargo` is available in PATH; the build will invoke it and link the produced static library. If `FUN_WITH_OPENSSL` is enabled, CMake must detect your system OpenSSL (libcrypto). - ## Running - CLI: run the `fun` executable from your build directory. -- REPL: `fun -i` or just run `fun` without a script, depending on your CLI version (see [../cli/](../cli/)). -- Examples: see [../examples/](../examples/). +- REPL: `fun -i` or just run `fun` without a script, depending on your CLI version (see [CLI](../cli/)). +- Examples: see [Examples](../examples/). Tip: When running from the repository without installation, set `FUN_LIB_DIR` to the local `./lib` so includes can find the stdlib. diff --git a/web/documentation/examples/examples.md b/web/documentation/examples/examples.md index 41f4a44..1e16476 100644 --- a/web/documentation/examples/examples.md +++ b/web/documentation/examples/examples.md @@ -4,7 +4,7 @@ published: true noToc: false noComments: false noDate: false -title: Fun - Running the Examples +title: Running the Examples subtitle: How to run the examples and the interactive showcase script, with environment tips. description: How to run the examples and the interactive showcase script, with environment tips. permalink: /documentation/examples/ @@ -21,7 +21,6 @@ tags: - tips --- - This page shows how to run the example programs included with the repository and how to use the interactive showcase script. All commands assume you are in the repository root. @@ -33,33 +32,33 @@ All commands assume you are in the repository root. Example (Linux/macOS/BSD): -
FUN_LIB_DIR="$(pwd)/lib" ./build/fun examples/include_lib.fun
-
+
FUN_LIB_DIR="$(pwd)/lib" ./build/fun examples/include_lib.fun
+ Windows (PowerShell):
$env:FUN_LIB_DIR = "$PWD/lib"
-./build/fun.exe .\examples\include_lib.fun
-
+./build/fun.exe .\examples\include_lib.fun + ## Interactive showcase: play.fun -The script `./play.fun` discovers all `.fun` files under `./examples` and offers to run them one by one: +The script `./scripts/play.fun` discovers all `.fun` files under `./examples` and offers to run them one by one: + +
./scripts/play.fun
-
./play.fun
-
Notes: + - The script auto-picks your interpreter (FUN_BIN env or `fun` in PATH) and ensures `FUN_LIB_DIR=./lib` so examples resolve includes correctly. - It shows the exit code for each run and summarizes failures at the end. Tip: you can run specific examples directly too: -
FUN_LIB_DIR="$(pwd)/lib" fun examples/crypto/openssl_md5.fun
-
+
FUN_LIB_DIR="$(pwd)/lib" fun examples/crypto/openssl_md5.fun
+ ## Example categories Browse the `examples/` tree for areas of interest: - crypto — crypto demonstrations (e.g., OpenSSL MD5/SHA-256/SHA-512 helpers; requires build with `-DFUN_WITH_OPENSSL=ON`) - - crypto — crypto demonstrations (e.g., OpenSSL MD5/SHA-256/SHA-512/RIPEMD‑160 helpers; requires build with `-DFUN_WITH_OPENSSL=ON`) - blocking / interactive — I/O or user-interactive patterns - error / broken — negative tests and error showcases - math — numeric operations @@ -70,6 +69,6 @@ Browse the `examples/` tree for areas of interest: Place your `.fun` files anywhere under `examples/` to have them picked up by `play.fun`. Use quoted includes for project-local helpers and angle brackets for stdlib modules:
#include "examples/my_lib/common.fun"
-#include 
-
+#include + If you add an example showcasing a new feature, also consider adding a brief note to the relevant doc (types.md, includes.md, opcodes.md, etc.). diff --git a/web/documentation/faq/faq.md b/web/documentation/faq/faq.md index 1a60f70..37f1d9e 100644 --- a/web/documentation/faq/faq.md +++ b/web/documentation/faq/faq.md @@ -4,7 +4,7 @@ published: true noToc: false noComments: false noDate: false -title: Fun - FAQ +title: FAQ subtitle: Frequently asked questions and quick answers. description: Frequently asked questions and quick answers. permalink: /documentation/faq/ @@ -23,22 +23,22 @@ 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: -
FUN_LIB_DIR=./lib ./build/fun examples/hello.fun
-
-See [../includes/](../includes/). +
FUN_LIB_DIR=./lib ./build/fun examples/hello.fun
+ +See [Includes](../includes/). ## How do I start the REPL? -Run `fun -i` (or run `fun` without a script, depending on version). See [../repl/](../repl/). +Run `fun -i` (or run `fun` without a script, depending on version). See [REPL](../repl/). ## Which build target should I use? -Use the aggregate `build` target to build `fun`, `fun_test`, and `test_opcodes`. See [../build/](../build/). +Use the aggregate `build` target to build `fun`, `fun_test`, and `test_opcodes`. See [Build](../build/). ## Where are the standard libraries? -Under [https://git.xw3.org/fun/fun/src/branch/main/lib](https://git.xw3.org/fun/fun/src/branch/main/lib){:class="git"}. See [../stdlib/](../stdlib/) for an overview. +Under [https://git.xw3.org/fun/fun/src/branch/main/lib](https://git.xw3.org/fun/fun/src/branch/main/lib){:class="git"}. See [stdlib](../stdlib/) for an overview. ## Where can I find internals and opcodes? -Browse [https://git.xw3.org/fun/fun/src/branch/main/src/vm](https://git.xw3.org/fun/fun/src/branch/main/src/vm/) and [../internals/](../internals/) / [../opcodes/](../opcodes/). +Browse [https://git.xw3.org/fun/fun/src/branch/main/src/vm](https://git.xw3.org/fun/fun/src/branch/main/src/vm/) and [Internals](../internals/) / [Opcodes](../opcodes/). diff --git a/web/documentation/opcodes/opcodes.md b/web/documentation/opcodes/opcodes.md index d42d293..f73ac85 100644 --- a/web/documentation/opcodes/opcodes.md +++ b/web/documentation/opcodes/opcodes.md @@ -4,7 +4,7 @@ published: true noToc: false noComments: false noDate: false -title: Fun - Fun VM Opcodes Overview +title: VM Opcodes Overview subtitle: VM opcodes overview grouped by domain with brief behavior/stack notes. description: VM opcodes overview grouped by domain with brief behavior/stack notes. permalink: /documentation/opcodes/ @@ -176,8 +176,6 @@ This document provides an overview of the available VM opcodes implemented under - OP_SQLITE_EXEC: Execute statement; pops handle:int, sql:string; pushes rc:int (0=OK). - OP_SQLITE_QUERY: Run query; pops handle:int, sql:string; pushes array>. - - ## OS, Time, Processes, Threads, Sockets, Serial - OP_ENV: Get environment variable; pops key:string; pushes value:string or Nil. @@ -243,35 +241,6 @@ This document provides an overview of the available VM opcodes implemented under - OP_PCSC_DISCONNECT: Disconnect; pops handle; pushes 1/0. - OP_PCSC_RELEASE: Release context; pops scope/id; pushes 1/0. -## Notcurses (Terminal UI) - -- OP_NC_INIT: Initialize notcurses; pushes handle or 0. -- OP_NC_SHUTDOWN: Shutdown; no args; pushes 1/0. -- OP_NC_CLEAR: Clear screen; pushes 1/0. -- OP_NC_DRAW_TEXT: Draw text at (x,y); pops text, x, y; pushes 1/0. -- OP_NC_GETCH: Get key with timeout; pops timeout_ms:int; pushes int key or -1. -- OP_NC_GET_SIZE: Get stdplane size; pushes [rows:int, cols:int] or -1 if unavailable. -- OP_NC_SET_STYLE: Set stdplane style/colors; pops style:int, bg_rgb:int, fg_rgb:int; pushes 0/-1. -- OP_NC_DRAW_CHAR: Draw a single codepoint at y,x; pops ch:int, x:int, y:int; pushes 0/-1. -- OP_NC_DRAW_HLINE: Draw horizontal line; pops len:int, x:int, y:int, ch:int; pushes 0/-1. -- OP_NC_DRAW_VLINE: Draw vertical line; pops len:int, x:int, y:int, ch:int; pushes 0/-1. -- OP_NC_BOX: Draw a rectangular box; pops x:int, y:int, w:int, h:int, style:int; pushes 0/-1. -- OP_NC_FILL: Fill rectangle with codepoint; pops x:int, y:int, w:int, h:int, ch:int; pushes 0/-1. -- OP_NC_RENDER: Force a render; pushes 0/-1. - - - -## TK (Tcl/Tk UI) - -- OP_TK_EVAL: Evaluate Tcl code; pops text:string; pushes result string or error. -- OP_TK_LABEL: Create/update label; pops text, id; pushes 1/0. -- OP_TK_BUTTON: Create/update button; pops text, id; pushes 1/0. -- OP_TK_PACK: Pack widget; pops id; pushes 1/0. -- OP_TK_BIND: Bind event; pops command, event, id; pushes 1/0. -- OP_TK_WM_TITLE: Set window title; pops title; pushes 1/0. -- OP_TK_LOOP: Enter main event loop; no args; blocks until exit. -- OP_TK_RESULT: Retrieve last Tcl result; pushes string. - ## Miscellaneous - OP_KEYS / OP_VALUES: Map utilities (see Maps). diff --git a/web/documentation/repl/repl.md b/web/documentation/repl/repl.md index a8fee57..5e1c799 100644 --- a/web/documentation/repl/repl.md +++ b/web/documentation/repl/repl.md @@ -17,6 +17,9 @@ tags: - history - launch - tips +- repl +- cli +- fun_with_repl --- This document describes the interactive Read–Eval–Print Loop (REPL) for the Fun programming language: how to build/launch it, how input and execution work, line editing and completion, the REPL buffer workflow, commands, debugging helpers, and tips. @@ -95,10 +98,10 @@ History is persisted in a file named .fun_history in your home directory (HOME/U Tab provides two kinds of completions: -1) :load path completion +- :load path completion - When typing a :load command, Tab completes filesystem paths, including directories. A trailing slash is handled as expected. Completion attempts to compute common suffixes across candidates. -2) Standard library identifier completion +- Standard library identifier completion - For general input, Tab attempts to complete identifiers from the standard library symbols scanned from FUN_LIB_DIR (or DEFAULT_LIB_DIR/lib). If there are multiple matches, a menu of candidates is printed; otherwise the identifier is completed in place. If Tab is pressed in the middle of the line (not at end), the REPL beeps instead of completing. @@ -107,115 +110,115 @@ If Tab is pressed in the middle of the line (not at end), the REPL beeps instead You typically build code incrementally: -1) Type lines; they accumulate in an internal buffer. -2) Press Enter on a blank line to parse and execute the buffer. -3) Output is printed and the buffer is cleared. +- Type lines; they accumulate in an internal buffer. +- Press Enter on a blank line to parse and execute the buffer. +- Output is printed and the buffer is cleared. Alternatively, use the :run command to execute the buffer immediately (without needing a blank line), or :run to execute a file’s contents. ## Timing and profiling -- Toggle a simple elapsed time measurement for executions with :time on|off|toggle. +- Toggle a simple elapsed time measurement for executions with :time on/off/toggle. - Use :profile to parse+run and report parse time, run time, total, and instruction count. ## Command reference Type :help to print the built-in command summary. Full list with clarifications: -- :help | :h +- :help | :h
Show the help. -- :quit | :q | :exit +- :quit | :q | :exit
Exit the REPL. -- :reset | :re +- :reset | :re
Reset VM state (clears globals). -- :dump | :du | :globals | :gl +- :dump | :du | :globals | :gl
Dump current globals (indexes and stringified values). -- :globals [pattern] / :vars | :v [pattern] +- :globals [pattern] / :vars | :v [pattern]
Dump globals, filtering by substring match on the value when a pattern is provided. -- :clear | :cl +- :clear | :cl
Clear the current input buffer. -- :print | :pr +- :print | :pr
Show the current buffer content. -- :run | :ru [file] +- :run | :ru [file]
Execute current buffer, or execute the specified file immediately. Parsing errors are reported with caret highlighting. -- :profile | :pf +- :profile | :pf
Execute buffer and show timing for parse and run plus instruction count. -- :save | :sa +- :save | :sa
Save the current buffer to a file. -- :load | :lo +- :load | :lo
Load a file into the buffer (does not run). Use :run or a blank line to execute afterward. -- :paste | :pa [run] +- :paste | :pa [run]
Enter paste mode to insert multiple lines verbatim. Finish with a single dot line: `.`. If the optional argument `run` (or `exec`) is given, the REPL will run the pasted buffer immediately. -- :history | :hi [N] +- :history | :hi [N]
Show the last N lines of persistent history (default 50). -- :time | :ti on|off|toggle +- :time | :ti on|off|toggle
Toggle/enable/disable timing for subsequent runs. -- :env | :en [NAME[=VALUE]] +- :env | :en [NAME[=VALUE]]
Get or set an environment variable. With NAME only, prints NAME=value. With NAME=VALUE, sets the variable for the current process. -- :backtrace | :bt | :ba +- :backtrace | :bt | :ba
Show a backtrace of VM frames (most recent first), including function name, source file, IP, and line. -- :frame | :fr N +- :frame | :fr N
Select a frame N (0..top) to target with :locals, :list, :disasm and value inspections. By default, the top frame is used. -- :list | :li [±K] +- :list | :li [±K]
Show K lines of source around the current frame’s line (default 5). The current line is marked with `>`. -- :disasm | :di [±N] +- :disasm | :di [±N]
Disassemble around current frame’s instruction pointer (default 5 on each side). Shows index, opcode name, and operand. -- :mdump | :md WHAT [offset [len]] [raw] [to ] - Dump a VM memory region. WHAT is one of: code | stack | globals | consts. Offset and length are optional; if omitted, a sensible default (up to 256 bytes) is used. With `raw`, write binary bytes. With `to `, write output to a file; otherwise print to stdout as a formatted hexdump. +- :mdump | :md WHAT [offset [len]] [raw] [to <file>]
+ Dump a VM memory region. WHAT is one of: code, stack, globals and consts. Offset and length are optional; if omitted, a sensible default (up to 256 bytes) is used. With `raw`, write binary bytes. With `to `, write output to a file; otherwise print to stdout as a formatted hexdump. -- :stack | :st [N] +- :stack | :st [N]
Show top N (or all) stack values, stringified. -- :top | :to +- :top | :to
Show the value at the top of the VM stack. -- :locals | :lc [FRAME] +- :locals | :lc [FRAME]
Show non-nil locals for the selected frame (or the provided frame index). -- :printv | :pv WHAT +- :printv | :pv WHAT
Print a specific value: `local[i]`, `stack[i]`, or `global[i]`. -- :break | :br [file:]line +- :break | :br [file:]line
Set a breakpoint. If file is omitted, the current frame’s source file is used. Prints a numeric breakpoint ID on success. -- :info | :in breaks +- :info | :in breaks
List breakpoints. -- :delete | :de ID +- :delete | :de ID
Delete a breakpoint by ID. -- :clear breaks | :cb +- :clear breaks | :cb
Remove all breakpoints. -- :cont | :co +- :cont | :co
Continue execution. In REPL-on-error/debug stops, this exits the REPL and resumes the program. -- :step | :sp +- :step | :sp
Step a single instruction (REPL-on-error/debug mode). -- :next | :ne +- :next | :ne
Step over in the current frame (REPL-on-error/debug mode). -- :finish | :fi +- :finish | :fi
Run until the current frame returns (REPL-on-error/debug mode). If an unknown command is entered, the REPL prints a hint to use :help. diff --git a/web/documentation/stdlib/stdlib.md b/web/documentation/stdlib/stdlib.md index ca356db..4b69468 100644 --- a/web/documentation/stdlib/stdlib.md +++ b/web/documentation/stdlib/stdlib.md @@ -4,7 +4,7 @@ published: true noToc: false noComments: false noDate: false -title: Fun - Standard Library Overview +title: Standard Library Overview subtitle: Overview of the standard library modules under ./lib with one-line summaries. description: Overview of the standard library modules under ./lib with one-line summaries. permalink: /documentation/stdlib/ @@ -26,17 +26,17 @@ The stdlib is written in Fun and organized by domain. Below is the current layou ## Top-level modules -- `arrays.fun` — helpers for working with array structures. -- `cli.fun` — minimal helpers for building CLI tools. -- `hello.fun` — simple demonstration helper(s). -- `hex.fun` — hexadecimal encode/decode helpers. -- `math.fun` — math helpers in Fun. -- `regex.fun` — simple regex-related helpers (see also `regex/`). -- `strings.fun` — string manipulation utilities. +- `arrays.fun` - helpers for working with array structures. +- `cli.fun` - minimal helpers for building CLI tools. +- `hello.fun` - simple demonstration helper(s). +- `hex.fun` - hexadecimal encode/decode helpers. +- `math.fun` - math helpers in Fun. +- `regex.fun` - simple regex-related helpers (see also `regex/`). +- `strings.fun` - string manipulation utilities. ## Packages -- `crypt/` — cryptographic primitives and hashes. See [https://git.xw3.org/fun/fun/src/branch/main/lib/crypt/](https://git.xw3.org/fun/fun/src/branch/main/lib/crypt/){:class="git"}. +- `crypt/` - cryptographic primitives and hashes. See [https://git.xw3.org/fun/fun/src/branch/main/lib/crypt/](https://git.xw3.org/fun/fun/src/branch/main/lib/crypt/){:class="git"}. - `aes256.fun` - `crc32.fun`, `crc32c.fun` - `md5.fun`, `md5_legacy.fun` @@ -47,26 +47,26 @@ The stdlib is written in Fun and organized by domain. Below is the current layou - `base64.fun` - `io/` — input/output utilities and system interfaces. See [https://git.xw3.org/fun/fun/src/branch/main/lib/io/](https://git.xw3.org/fun/fun/src/branch/main/lib/io/){:class="git"}. - - `console.fun` — console I/O helpers - - `ini.fun` — INI parse helpers - - `json.fun` — JSON helpers - - `pcsc.fun`, `pcsc2.fun` — smart card access (PC/SC) - - `process.fun` — spawn and manage subprocesses - - `serial.fun` — serial port helpers - - `socket.fun` — socket convenience wrappers - - `thread.fun` — simple threading utilities - - `xml.fun` — XML helpers + - `console.fun` - console I/O helpers + - `ini.fun` - INI parse helpers + - `json.fun` - JSON helpers + - `pcsc.fun`, `pcsc2.fun` - smart card access (PC/SC) + - `process.fun` - spawn and manage subprocesses + - `serial.fun` - serial port helpers + - `socket.fun` - socket convenience wrappers + - `thread.fun` - simple threading utilities + - `xml.fun` - XML helpers -- `net/` — networking helpers and example HTTP servers. See [https://git.xw3.org/fun/fun/src/branch/main/lib/net/](https://git.xw3.org/fun/fun/src/branch/main/lib/net/){:class="git"}. - - `cgi.fun` — basic CGI helpers - - `http_server.fun` — blocking HTTP server - - `http_cgi_server.fun` — HTTP server that can execute .fun CGI files - - `http_cgi_lib_server.fun` — variant of the HTTP CGI server using the stdlib +- `net/` - networking helpers and example HTTP servers. See [https://git.xw3.org/fun/fun/src/branch/main/lib/net/](https://git.xw3.org/fun/fun/src/branch/main/lib/net/){:class="git"}. + - `cgi.fun` - basic CGI helpers + - `http_server.fun` - blocking HTTP server + - `http_cgi_server.fun` - HTTP server that can execute .fun CGI files + - `http_cgi_lib_server.fun` - variant of the HTTP CGI server using the stdlib -- `regex/` — regular expression utilities (PCRE2-based when available). See [https://git.xw3.org/fun/fun/src/branch/main/lib/regex/](https://git.xw3.org/fun/fun/src/branch/main/lib/regex/){:class="git"}. +- `regex/` - regular expression utilities (PCRE2-based when available). See [https://git.xw3.org/fun/fun/src/branch/main/lib/regex/](https://git.xw3.org/fun/fun/src/branch/main/lib/regex/){:class="git"}. - `pcre2.fun` -- `utils/` — small reusable helpers and functional utilities. See [https://git.xw3.org/fun/fun/src/branch/main/lib/utils/](https://git.xw3.org/fun/fun/src/branch/main/lib/utils/){:class="git"}. +- `utils/` - small reusable helpers and functional utilities. See [https://git.xw3.org/fun/fun/src/branch/main/lib/utils/](https://git.xw3.org/fun/fun/src/branch/main/lib/utils/){:class="git"}. - `datetime.fun` - `match.fun` - `math.fun` @@ -74,13 +74,13 @@ The stdlib is written in Fun and organized by domain. Below is the current layou - `range.fun` - `result.fun` -Note: Availability of some modules can depend on optional extensions selected at build time (see [../build/](../build/)). For instance, `regex/pcre2.fun` requires PCRE2 support; `ui/*` depends on chosen UI backends. +Note: Availability of some modules can depend on optional extensions selected at build time (see [Build](../build/)). For instance, `regex/pcre2.fun` requires PCRE2 support; `ui/*` depends on chosen UI backends. ## Using modules -
#include <strings.fun
+
#include <strings.fun>
 
 s = trim("  hello  ")
 print(s)
-For search paths and namespacing details, see [../includes/](../includes/) and [../cli/](../cli/) (FUN_LIB_DIR and DEFAULT_LIB_DIR). +For search paths and namespacing details, see [Includes](../includes/) and [CLI](../cli/) (FUN_LIB_DIR and DEFAULT_LIB_DIR). diff --git a/web/documentation/vm/vm.md b/web/documentation/vm/vm.md index acca941..d3aa7bc 100644 --- a/web/documentation/vm/vm.md +++ b/web/documentation/vm/vm.md @@ -4,7 +4,7 @@ published: true noToc: false noComments: false noDate: false -title: Fun - VM Configuration Constants +title: VM Configuration Constants subtitle: Detailed explanation of VM limits and memory management constants. description: Learn about MAX_FRAMES, MAX_FRAME_LOCALS, MAX_GLOBALS, STACK_SIZE, and OUTPUT_SIZE in the Fun VM. permalink: /documentation/vm/ @@ -19,9 +19,10 @@ The Fun Virtual Machine (VM) uses several fixed-size limits to manage memory and This document explains what each of these constants does in plain English. -View [../build/](../build/) to see how to set the params at build time. +View [Build](../build/) to see how to set the params at build time. ## `MAX_FRAMES` (Default: 128) + This constant defines the **maximum depth of the call stack**. When a function is called, the VM creates a "frame" to keep track of that function's execution (where it's at in the code and its local variables). If a function calls another function, a new frame is added on top. @@ -30,6 +31,7 @@ When a function is called, the VM creates a "frame" to keep track of that functi - **Analogy:** Imagine a stack of dinner plates. `MAX_FRAMES` is the maximum height the stack can reach before it becomes unstable or hits the ceiling. ## `MAX_FRAME_LOCALS` (Default: 64) + This constant limits the **number of local variables** each individual function can have. Every time a function is called, it gets its own space for variables that only exist within that function. @@ -38,6 +40,7 @@ Every time a function is called, it gets its own space for variables that only e - **Analogy:** Think of this as the number of pockets in a single person's jacket. You can only carry 64 items in your pockets at once. ## `MAX_GLOBALS` (Default: 128) + This constant defines the **maximum number of global variables** available to the entire program. Global variables are accessible from anywhere in your code, unlike local variables which belong to a specific function. @@ -46,6 +49,7 @@ Global variables are accessible from anywhere in your code, unlike local variabl - **Analogy:** This is like a shared community bulletin board. There is only enough room on the board for 128 different notices. ## `STACK_SIZE` (Default: 1024) + This constant sets the size of the **operand stack**. The VM uses this stack for almost everything it does: adding numbers, comparing values, and passing arguments to functions. Most operations take values from the top of the stack, perform a calculation, and push the result back onto the stack. @@ -54,6 +58,7 @@ The VM uses this stack for almost everything it does: adding numbers, comparing - **Analogy:** Imagine a workbench where you put tools and materials you are currently working on. `STACK_SIZE` is the area of that workbench. If it's too small, you can't work on complex projects. ## `OUTPUT_SIZE` (Default: 1024) + This constant determines the size of the **output buffer**. When your program uses commands like `PRINT` or `ECHO`, the results are stored in an internal list before they are displayed or processed further.