Some documentation refactoring. No code changes. (0.39.12)

docs/README.md

@@ -38,10 +38,9 @@ This file serves as an index of the documents in this directory. Links are relat
 - [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.
 
-## Example deep-dives
+## Examples
 
  - [examples/README.md](./examples/README.md) - Catalog of all example scripts under ./examples/: what each area contains, how to run them, required env vars, and extension requirements.
- - [examples/httpserver.md](./examples/httpserver.md) - Design and walkthrough of all HTTP server examples under ./examples/net (static, CGI, and multi-threaded variants), how they route requests, run CGI, and which stdlib modules they use. Future example-focused docs will be collected in this section.
 
 ## External extensions
 

docs/examples/README.md

@@ -14,8 +14,6 @@ Notes
 - Networking examples often bind to 127.0.0.1 on high ports; read the file header for the exact port.
 
 Deep‑dives
-- HTTP servers: docs/examples/httpserver.md — end‑to‑end walkthrough of all HTTP server variants in examples/net/
-
 
 ## Top‑level examples (./examples)
 
@@ -25,52 +23,75 @@ Run pattern:
 - fun examples/<file>.fun
 
 Highlights (selection):
-- builtins_extended.fun — tour of core built‑ins beyond the basics
-- byte_for_demo.fun — iterating bytes with for
-- byte_overflow_try_catch.fun — error handling on overflow
-- cast_demo.fun — conversions and casting helpers
-- class_constructor.fun, class_test.fun, classes_demo.fun — class basics and usage
-- class_without_object.fun — class features without an instance helper
-- cli_argv_dump.fun — prints argv/argc handling
-- conversions_showcase.fun — numbers, strings, bytes conversions
-- cpp_add.fun — calling into the optional C++ extension (if enabled)
-- datetime_basic.fun, datetime_extended.fun, datetime_timer.fun — time/date helpers
-- echo_example.fun — simple echo of input/args
-- env_all.fun, os_env.fun — reading environment variables
-- error_handling.fun, try_catch_finally.fun — error patterns
-- expressions_test.fun — precedence and grouping
-- features.fun — grab bag of language features
-- file_print_for_file_line_by_line.fun — iterate file content
-- floats.fun — float ops and formatting
-- for_range_test.fun — ranges and loops
-- functions_test.fun — functions, closures, returns
-- have_fun.fun, have_fun_function.fun — playful demos
-- hex_example.fun — hex encode/decode
-- if_else_test.fun, nested_loops.fun, loops_break_continue.fun — control flow
-- include_local.fun, include_lib.fun, include_local_util.fun — include mechanics
-- inheritance_demo.fun — simple class inheritance
-- maps.fun, match.fun — data structures and pattern matching
-- namespaced_mod.fun — namespaced includes with as
-- objects_basic.fun, objects_more.fun — OO basics
-- process_example.fun — spawn and capture subprocess output
-- progress.fun, progress_inline.fun — simple progress displays
-- random_demo.fun, random_number_example.fun — RNG usage
-- regex_demo.fun, regex_procedural.fun — regex helpers (PCRE2 when enabled)
-- rust_hello.fun, rust_hello_args*.fun — Rust opcodes (if FUN_WITH_RUST)
-- serial_demo.fun, test_serial.fun — serial port (when available)
-- short_circuit_test.fun — boolean evaluation order
-- signed_ints.fun, uint_types.fun, types_integers.fun — integer families
-- stdlib_showcase.fun — sampler of common stdlib modules
-- strings_test.fun — string helpers and edge cases
-- tcp_http_get.fun, tcp_http_get_class.fun — manual HTTP client over sockets
-- test_bits/rol/shl/xor/dec_to_hex/hex_to_dec — bitwise utilities
-- thread_class_example.fun, threads_demo.fun — threading building blocks
-- typeof*.fun — type inspection
-- type_safety*.fun — static/dynamic type checks
-- types_overview.fun — language types tour
-- unix_socket_echo.fun — local domain socket echo demo
-- version.fun — print VM/version info
-- while_test.fun — simple while loop example
+
+- [builtins_extended.fun](./builtins_extended.md) — tour of core built‑ins beyond the basics
+- [byte_for_demo.fun](./byte_for_demo.md) — iterating bytes with for
+- [byte_overflow_try_catch.fun](./byte_overflow_try_catch.md) — error handling on overflow
+- [cast_demo.fun](./cast_demo.md) — conversions and casting helpers
+- [class_constructor.fun](./class_constructor.md) — basic constructor usage and init patterns
+- [class_test.fun](./class_test.md) — small class feature checks
+- [classes_demo.fun](classes_demo.md) — class basics and usage
+- [class_without_object.fun](./class_without_object.md) — class features without an instance helper
+- [cli_argv_dump.fun](./cli_argv_dump.md) — prints argv/argc handling
+- [conversions_showcase.fun](./conversions_showcase.md) — numbers, strings, bytes conversions
+- [cpp_add.fun](./cpp_add.md) — calling into the optional C++ extension (if enabled)
+- [datetime_basic.fun](./datetime_basic.md) — minimal date/time helpers
+- [datetime_extended.fun](./datetime_extended.md) — richer date/time operations
+- [datetime_timer.fun](datetime_timer.md) — time/date helpers
+- [echo_example.fun](./echo_example.md) — simple echo of input/args
+- [env_all.fun](./env_all.md) — enumerate environment variables
+- [os_env.fun](./os_env.md) — reading environment variables
+- [error_handling.fun](./error_handling.md) — try/catch and error objects
+- [try_catch_finally.fun](try_catch_finally.md) — error patterns
+- [expressions_test.fun](./expressions_test.md) — precedence and grouping
+- [features.fun](./features.md) — grab bag of language features
+- [file_print_for_file_line_by_line.fun](./file_print_for_file_line_by_line.md) — iterate file content
+- [floats.fun](./floats.md) — float ops and formatting
+- [for_range_test.fun](./for_range_test.md) — ranges and loops
+- [functions_test.fun](./functions_test.md) — functions, closures, returns
+- [have_fun.fun](./have_fun.md) — playful starter demo
+- [have_fun_function.fun](have_fun_function.md) — playful demos
+- [hex_example.fun](./hex_example.md) — hex encode/decode
+- [if_else_test.fun](./if_else_test.md) — conditional branching examples
+- [nested_loops.fun](./nested_loops.md) — loops inside loops
+- [loops_break_continue.fun](loops_break_continue.md) — control flow
+- [include_local.fun](./include_local.md) — include a local file/module
+- [include_lib.fun](./include_lib.md) — include from the stdlib path
+- [include_local_util.fun](include_local_util.md) — include mechanics
+- [inheritance_demo.fun](./inheritance_demo.md) — simple class inheritance
+- [maps.fun](./maps.md), [match.fun](match.md) — data structures and pattern matching
+- [namespaced_mod.fun](./namespaced_mod.md) — namespaced includes with as
+- [objects_basic.fun](./objects_basic.md) — simple objects and methods
+- [objects_more.fun](./objects_more.md) — OO basics
+- [process_example.fun](./process_example.md) — spawn and capture subprocess output
+- [progress.fun](./progress.md) — progress bar helper
+- [progress_inline.fun](./progress_inline.md) — simple progress displays
+- [random_demo.fun](./random_demo.md) — random helpers overview
+- [random_number_example.fun](random_number_example.md) — RNG usage
+- [regex_demo.fun](./regex_demo.md) — regex basics (PCRE2 when enabled)
+- [regex_procedural.fun](./regex_procedural.md) — regex helpers (PCRE2 when enabled)
+- [rust_hello.fun](./rust_hello.md), rust_hello_args*.fun — Rust opcodes (if FUN_WITH_RUST)
+- [serial_demo.fun](./serial_demo.md) — serial port usage
+- [test_serial.fun](./test_serial.md) — serial port (when available)
+- [short_circuit_test.fun](./short_circuit_test.md) — boolean evaluation order
+- [signed_ints.fun](./signed_ints.md) — signed integers overview
+- [uint_types.fun](./uint_types.md) — unsigned integers overview
+- [types_integers.fun](./types_integers.md) — integer families
+- [stdlib_showcase.fun](./stdlib_showcase.md) — sampler of common stdlib modules
+- [strings_test.fun](./strings_test.md) — string helpers and edge cases
+- [tcp_http_get.fun](./tcp_http_get.md) — simple HTTP GET over raw TCP
+- [tcp_http_get_class.fun](./tcp_http_get_class.md) — manual HTTP client over sockets
+- [test_bits.fun](./test_bits.md) — /rol/shl/xor/dec_to_hex/hex_to_dec bitwise utilities
+- [thread_class_example.fun](./thread_class_example.md) — define and run a thread class
+- [threads_demo.fun](./threads_demo.md) — threading building blocks
+- [typeof.fun](./typeof.md) — type inspection
+- [typeof_features.fun](./typeof_features.md) — type inspection of declared integer subtypes and runtime categories
+- [type_safety.fun](./type_safety.md) — static/dynamic type checks
+- [type_safety_fails.fun](./type_safety_fails.md) — static/dynamic type checks
+- [types_overview.fun](./types_overview.md) — language types tour
+- [unix_socket_echo.fun](./unix_socket_echo.md) — local domain socket echo demo
+- [version.fun](./version.md) — print VM/version info
+- [while_test.fun](./while_test.md) — simple while loop example
 
 Tip: If a file name is listed above but not present on your build, it may depend on an extension you did not enable.
 
@@ -152,7 +173,8 @@ Small, focused math helpers and demonstrations:
 - math_gcd_lcm
 
 ## Networking (./examples/net)
-Servers and socket utilities. See docs/examples/httpserver.md for the HTTP family.
+Servers and socket utilities. See docs/examples/net/httpserver.md for the HTTP family.
+- HTTP servers: [httpserver.md](./net/httpserver.md) — end‑to‑end walkthrough of all HTTP server variants in examples/net/
 - http_static_server.fun — minimal static server over sockets
 - http_server.fun — blocking static/CGI dispatcher using lib/net/http_server.fun
 - http_server_cgi.fun — blocking server with CGI via lib/net/http_cgi_server.fun
@@ -181,7 +203,6 @@ Historical or intentionally broken examples kept for reference/regression.
 - notcurses_* — experiments around Notcurses
 - ripemd160* — legacy or experimental hash routines
 
-
 ### Running examples reliably
 
 Prefer the local build when running from the repository root:
@@ -189,8 +210,8 @@ Prefer the local build when running from the repository root:
 - or: ./build_release/fun <path/to/example.fun>
 
 Set up env if needed:
-- export FUN_LIB_DIR="./lib"           # to find stdlib
-- export FUN_EXEC="./build_debug/fun"  # used by CGI examples
-- export FUN_HTDOCS="./examples/data/htdocs"  # override docroot
+- export FUN_LIB_DIR="./lib" # to find stdlib
+- export FUN_EXEC="./build_debug/fun" # used by CGI examples
+- export FUN_HTDOCS="./examples/data/htdocs" # override docroot
 
 When optional extensions are not enabled, their examples will not run; reconfigure the build with the required -D flags shown in docs/external/.

docs/examples/builtins_extended.md

@@ -0,0 +1,13 @@
+# builtins_extended.fun — overview
+
+What it shows
+- A tour of core built‑ins beyond the basics: printing, typing, math helpers, conversions, and utility functions commonly used in small scripts.
+
+How to run
+- From repo root with local build:
+  - export FUN_LIB_DIR="./lib"
+  - ./build_debug/fun examples/builtins_extended.fun
+- Or, if installed: fun examples/builtins_extended.fun
+
+Notes
+- Exact behavior and outputs are documented inline at the top of the script; open the .fun file for details.

docs/examples/builtins_maps_and_more.md

@@ -0,0 +1,12 @@
+# builtins_maps_and_more.fun — overview
+
+What it shows
+- Exploring built‑ins while working with maps and related data structures.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/builtins_maps_and_more.fun
+- Or: fun examples/builtins_maps_and_more.fun
+
+Notes
+- Open the .fun file to see the exact behaviors and printed output.

docs/examples/byte_for_demo.md

@@ -0,0 +1,9 @@
+# byte_for_demo.fun — overview
+
+What it shows
+- Iterating bytes with a for-loop; indexing and printing byte values.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/byte_for_demo.fun
+- Or: fun examples/byte_for_demo.fun

docs/examples/byte_overflow_try_catch.md

@@ -0,0 +1,9 @@
+# byte_overflow_try_catch.fun — overview
+
+What it shows
+- Error handling around byte/integer overflow using try/catch.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/byte_overflow_try_catch.fun
+- Or: fun examples/byte_overflow_try_catch.fun

docs/examples/cast_demo.md

@@ -0,0 +1,9 @@
+# cast_demo.fun — overview
+
+What it shows
+- Conversions and casting helpers; demonstrates changing between numeric and string types safely.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/cast_demo.fun
+- Or: fun examples/cast_demo.fun

docs/examples/class_constructor.md

@@ -0,0 +1,9 @@
+# class_constructor.fun — overview
+
+What it shows
+- Class basics and constructor behavior; initializing fields and using methods.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/class_constructor.fun
+- Or: fun examples/class_constructor.fun

docs/examples/class_test.md

@@ -0,0 +1,12 @@
+# class_test.fun — overview
+
+What it shows
+- Simple class usage and method invocation; small sanity checks around classes.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/class_test.fun
+- Or: fun examples/class_test.fun
+
+Notes
+- Open the script to see the exact behavior and outputs.

docs/examples/class_without_object.md

@@ -0,0 +1,9 @@
+# class_without_object.fun — overview
+
+What it shows
+- Class features that can be used without creating an instance (static-like usage patterns).
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/class_without_object.fun
+- Or: fun examples/class_without_object.fun

docs/examples/classes_demo.md

@@ -0,0 +1,9 @@
+# classes_demo.fun — overview
+
+What it shows
+- Class basics and usage: defining classes, instantiating objects, calling methods.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/classes_demo.fun
+- Or: fun examples/classes_demo.fun

docs/examples/cli_argv_dump.md

@@ -0,0 +1,9 @@
+# cli_argv_dump.fun — overview
+
+What it shows
+- Prints argv/argc handling to demonstrate CLI arguments parsing at a low level.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/cli_argv_dump.fun --foo bar 123
+- Or: fun examples/cli_argv_dump.fun --foo bar 123

docs/examples/conversions_showcase.md

@@ -0,0 +1,9 @@
+# conversions_showcase.fun — overview
+
+What it shows
+- Numbers, strings, and bytes conversions; typical idioms and edge cases.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/conversions_showcase.fun
+- Or: fun examples/conversions_showcase.fun

docs/examples/cpp_add.md

@@ -0,0 +1,12 @@
+# cpp_add.fun — overview
+
+What it shows
+- Calling into the optional C++ extension from Fun.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/cpp_add.fun
+- Or: fun examples/cpp_add.fun
+
+Notes
+- Requires the optional C++ extension to be enabled in your build; otherwise this example may be unavailable.

docs/examples/datetime_basic.md

@@ -0,0 +1,9 @@
+# datetime_basic.fun — overview
+
+What it shows
+- Basic time/date helpers and formatting.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/datetime_basic.fun
+- Or: fun examples/datetime_basic.fun

docs/examples/datetime_extended.md

@@ -0,0 +1,9 @@
+# datetime_extended.fun — overview
+
+What it shows
+- Extended datetime helpers: parsing, arithmetic, timers, and formatting variants.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/datetime_extended.fun
+- Or: fun examples/datetime_extended.fun

docs/examples/datetime_timer.md

@@ -0,0 +1,9 @@
+# datetime_timer.fun — overview
+
+What it shows
+- Measuring elapsed time and simple timers using datetime helpers.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/datetime_timer.fun
+- Or: fun examples/datetime_timer.fun

docs/examples/echo_example.md

@@ -0,0 +1,9 @@
+# echo_example.fun — overview
+
+What it shows
+- Simple echo of input/args; prints back what you type or pass as arguments.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/echo_example.fun hello world
+- Or: fun examples/echo_example.fun hello world

docs/examples/env_all.md

@@ -0,0 +1,9 @@
+# env_all.fun — overview
+
+What it shows
+- Reading and listing environment variables.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/env_all.fun
+- Or: fun examples/env_all.fun

docs/examples/error_handling.md

@@ -0,0 +1,9 @@
+# error_handling.fun — overview
+
+What it shows
+- Error patterns and handling strategies using try/catch/finally.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/error_handling.fun
+- Or: fun examples/error_handling.fun

docs/examples/expressions_test.md

@@ -0,0 +1,9 @@
+# expressions_test.fun — overview
+
+What it shows
+- Operator precedence and expression grouping tests/demonstrations.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/expressions_test.fun
+- Or: fun examples/expressions_test.fun

docs/examples/features.md

@@ -0,0 +1,9 @@
+# features.fun — overview
+
+What it shows
+- Grab bag of language features in a single script.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/features.fun
+- Or: fun examples/features.fun

docs/examples/file_print_for_file_line_by_line.md

@@ -0,0 +1,9 @@
+# file_print_for_file_line_by_line.fun — overview
+
+What it shows
+- Iterate a file line-by-line and print each line; basic file IO idioms.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/file_print_for_file_line_by_line.fun path/to/file.txt
+- Or: fun examples/file_print_for_file_line_by_line.fun path/to/file.txt

docs/examples/floats.md

@@ -0,0 +1,9 @@
+# floats.fun — overview
+
+What it shows
+- Floating point operations and formatting details.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/floats.fun
+- Or: fun examples/floats.fun

docs/examples/for_range_test.md

@@ -0,0 +1,9 @@
+# for_range_test.fun — overview
+
+What it shows
+- Ranges and loops; iterating numeric ranges and verifying bounds.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/for_range_test.fun
+- Or: fun examples/for_range_test.fun

docs/examples/functions_test.md

@@ -0,0 +1,9 @@
+# functions_test.fun — overview
+
+What it shows
+- Functions, closures, and return behavior; call semantics basics.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/functions_test.fun
+- Or: fun examples/functions_test.fun

docs/examples/have_fun.md

@@ -0,0 +1,9 @@
+# have_fun.fun — overview
+
+What it shows
+- Playful demo showing off small language tricks.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/have_fun.fun
+- Or: fun examples/have_fun.fun

docs/examples/have_fun_function.md

@@ -0,0 +1,9 @@
+# have_fun_function.fun — overview
+
+What it shows
+- A playful function-centric demo; small utility behaviors.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/have_fun_function.fun
+- Or: fun examples/have_fun_function.fun

docs/examples/hex_example.md

@@ -0,0 +1,9 @@
+# hex_example.fun — overview
+
+What it shows
+- Hex encode/decode helpers; working with hexadecimal representations.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/hex_example.fun
+- Or: fun examples/hex_example.fun

docs/examples/if_else_test.md

@@ -0,0 +1,9 @@
+# if_else_test.fun — overview
+
+What it shows
+- Control flow with if/else; branching and comparisons.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/if_else_test.fun
+- Or: fun examples/if_else_test.fun

docs/examples/include_lib.md

@@ -0,0 +1,9 @@
+# include_lib.fun — overview
+
+What it shows
+- Including modules from the standard library path using #include <...>.
+
+How to run
+- export FUN_LIB_DIR="./lib"  # ensure stdlib is discoverable
+- ./build_debug/fun examples/include_lib.fun
+- Or: fun examples/include_lib.fun

docs/examples/include_local.md

@@ -0,0 +1,9 @@
+# include_local.fun — overview
+
+What it shows
+- Including local files relative to the script and reusing helpers.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/include_local.fun
+- Or: fun examples/include_local.fun

docs/examples/include_local_util.md

@@ -0,0 +1,9 @@
+# include_local_util.fun — overview
+
+What it shows
+- Local include mechanics with a small utility module.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/include_local_util.fun
+- Or: fun examples/include_local_util.fun

docs/examples/inheritance_demo.md

@@ -0,0 +1,9 @@
+# inheritance_demo.fun — overview
+
+What it shows
+- Simple class inheritance and method overriding examples.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/inheritance_demo.fun
+- Or: fun examples/inheritance_demo.fun

docs/examples/loops_break_continue.md

@@ -0,0 +1,9 @@
+# loops_break_continue.fun — overview
+
+What it shows
+- Loop control: break and continue; demonstrating control flow within loops.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/loops_break_continue.fun
+- Or: fun examples/loops_break_continue.fun

docs/examples/maps.md

@@ -0,0 +1,9 @@
+# maps.fun — overview
+
+What it shows
+- Working with maps: creation, indexing, iteration, and typical idioms.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/maps.fun
+- Or: fun examples/maps.fun

docs/examples/match.md

@@ -0,0 +1,9 @@
+# match.fun — overview
+
+What it shows
+- Pattern matching constructs and examples of branching by value/shape.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/match.fun
+- Or: fun examples/match.fun

docs/examples/namespaced_mod.md

@@ -0,0 +1,9 @@
+# namespaced_mod.fun — overview
+
+What it shows
+- Namespaced includes and using the "as" aliasing pattern for modules.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/namespaced_mod.fun
+- Or: fun examples/namespaced_mod.fun

docs/examples/nested_loops.md

@@ -0,0 +1,9 @@
+# nested_loops.fun — overview
+
+What it shows
+- Control flow with nested loops; inner/outer loop coordination.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/nested_loops.fun
+- Or: fun examples/nested_loops.fun

docs/examples/objects_basic.md

@@ -0,0 +1,9 @@
+# objects_basic.fun — overview
+
+What it shows
+- OO basics: defining objects, fields, and invoking methods.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/objects_basic.fun
+- Or: fun examples/objects_basic.fun

docs/examples/objects_more.md

@@ -0,0 +1,9 @@
+# objects_more.fun — overview
+
+What it shows
+- Additional object patterns: composition, methods, and utilities.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/objects_more.fun
+- Or: fun examples/objects_more.fun

docs/examples/os_env.md

@@ -0,0 +1,9 @@
+# os_env.fun — overview
+
+What it shows
+- Reading and writing environment variables from the operating system.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/os_env.fun
+- Or: fun examples/os_env.fun

docs/examples/process_example.md

@@ -0,0 +1,9 @@
+# process_example.fun — overview
+
+What it shows
+- Spawning and capturing subprocess output; simple process management.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/process_example.fun
+- Or: fun examples/process_example.fun

docs/examples/progress.md

@@ -0,0 +1,9 @@
+# progress.fun — overview
+
+What it shows
+- Simple progress display in the terminal.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/progress.fun
+- Or: fun examples/progress.fun

docs/examples/progress_inline.md

@@ -0,0 +1,9 @@
+# progress_inline.fun — overview
+
+What it shows
+- Inline progress updates (same line updates) for simple terminal UIs.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/progress_inline.fun
+- Or: fun examples/progress_inline.fun

docs/examples/random_demo.md

@@ -0,0 +1,9 @@
+# random_demo.fun — overview
+
+What it shows
+- Random number generator usage and seeding basics.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/random_demo.fun
+- Or: fun examples/random_demo.fun

docs/examples/random_number_example.md

@@ -0,0 +1,9 @@
+# random_number_example.fun — overview
+
+What it shows
+- Generating random numbers and printing them; small utility demo.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/random_number_example.fun
+- Or: fun examples/random_number_example.fun

docs/examples/regex_demo.md

@@ -0,0 +1,12 @@
+# regex_demo.fun — overview
+
+What it shows
+- Regex helpers usage; simple matching and replacement tasks.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/regex_demo.fun
+- Or: fun examples/regex_demo.fun
+
+Notes
+- Some regex examples depend on the optional PCRE2 extension; enable it in your build to run.

docs/examples/regex_procedural.md

@@ -0,0 +1,12 @@
+# regex_procedural.fun — overview
+
+What it shows
+- Procedural approach to regex work: compiling patterns and iterating matches.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/regex_procedural.fun
+- Or: fun examples/regex_procedural.fun
+
+Notes
+- May require the optional PCRE2 extension in your build.

docs/examples/rust_hello.md

@@ -0,0 +1,12 @@
+# rust_hello.fun — overview
+
+What it shows
+- Using Rust opcodes from Fun (when built with Rust support).
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/rust_hello.fun
+- Or: fun examples/rust_hello.fun
+
+Notes
+- Requires building with FUN_WITH_RUST; otherwise this example will be unavailable.

docs/examples/rust_hello_args.md

@@ -0,0 +1,12 @@
+# rust_hello_args.fun — overview
+
+What it shows
+- Passing arguments into Rust-backed opcodes and handling returns.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/rust_hello_args.fun
+- Or: fun examples/rust_hello_args.fun
+
+Notes
+- Requires building with FUN_WITH_RUST.

docs/examples/rust_hello_args_return.md

@@ -0,0 +1,12 @@
+# rust_hello_args_return.fun — overview
+
+What it shows
+- Demonstrates returning values from Rust-backed opcodes with arguments.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/rust_hello_args_return.fun
+- Or: fun examples/rust_hello_args_return.fun
+
+Notes
+- Requires building with FUN_WITH_RUST.

docs/examples/serial_demo.md

@@ -0,0 +1,12 @@
+# serial_demo.fun — overview
+
+What it shows
+- Serial port access and basic read/write (when available on your system).
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/serial_demo.fun
+- Or: fun examples/serial_demo.fun
+
+Notes
+- Requires serial device access; may depend on platform support and permissions.

docs/examples/short_circuit_test.md

@@ -0,0 +1,9 @@
+# short_circuit_test.fun — overview
+
+What it shows
+- Boolean evaluation order and short-circuit behavior with && and ||.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/short_circuit_test.fun
+- Or: fun examples/short_circuit_test.fun

docs/examples/signed_ints.md

@@ -0,0 +1,9 @@
+# signed_ints.fun — overview
+
+What it shows
+- Signed integer types and operations; ranges and conversions.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/signed_ints.fun
+- Or: fun examples/signed_ints.fun

docs/examples/stdlib_showcase.md

@@ -0,0 +1,9 @@
+# stdlib_showcase.fun — overview
+
+What it shows
+- Sampler of common standard library modules and utilities.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/stdlib_showcase.fun
+- Or: fun examples/stdlib_showcase.fun

docs/examples/strings_test.md

@@ -0,0 +1,9 @@
+# strings_test.fun — overview
+
+What it shows
+- String helpers and edge cases; splitting, joining, trimming, and formatting.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/strings_test.fun
+- Or: fun examples/strings_test.fun

docs/examples/tcp_http_get.md

@@ -0,0 +1,12 @@
+# tcp_http_get.fun — overview
+
+What it shows
+- Manual HTTP client over raw TCP sockets: connect, write request, read response.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/tcp_http_get.fun
+- Or: fun examples/tcp_http_get.fun
+
+Notes
+- Requires network access to the target host used in the script.

docs/examples/tcp_http_get_class.md

@@ -0,0 +1,12 @@
+# tcp_http_get_class.fun — overview
+
+What it shows
+- Manual HTTP client implemented with a small helper class over sockets.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/tcp_http_get_class.fun
+- Or: fun examples/tcp_http_get_class.fun
+
+Notes
+- Requires network access to the target host used in the script.

docs/examples/test_bits.md

@@ -0,0 +1,9 @@
+# test_bits.fun — overview
+
+What it shows
+- Bitwise utilities demonstration (and/or/xor/shifts) and small tests.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_bits.fun
+- Or: fun examples/test_bits.fun

docs/examples/test_dec_to_hex.md

@@ -0,0 +1,9 @@
+# test_dec_to_hex.fun — overview
+
+What it shows
+- Decimal to hexadecimal conversion helper/tests.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_dec_to_hex.fun
+- Or: fun examples/test_dec_to_hex.fun

docs/examples/test_hex_to_dec.md

@@ -0,0 +1,9 @@
+# test_hex_to_dec.fun — overview
+
+What it shows
+- Hexadecimal to decimal conversion helper/tests.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_hex_to_dec.fun
+- Or: fun examples/test_hex_to_dec.fun

docs/examples/test_include.md

@@ -0,0 +1,9 @@
+# test_include.fun — overview
+
+What it shows
+- Small include mechanics test; ensures local and stdlib includes work.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_include.fun
+- Or: fun examples/test_include.fun

docs/examples/test_rol.md

@@ -0,0 +1,9 @@
+# test_rol.fun — overview
+
+What it shows
+- Bit rotation (ROL) helper/tests.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_rol.fun
+- Or: fun examples/test_rol.fun

docs/examples/test_serial.md

@@ -0,0 +1,12 @@
+# test_serial.fun — overview
+
+What it shows
+- Serial port test; opens a port and exchanges a few bytes (when available).
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_serial.fun
+- Or: fun examples/test_serial.fun
+
+Notes
+- Requires serial device access; may depend on platform support and permissions.

docs/examples/test_shl.md

@@ -0,0 +1,9 @@
+# test_shl.fun — overview
+
+What it shows
+- Bit shift left (SHL) helper/tests.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_shl.fun
+- Or: fun examples/test_shl.fun

docs/examples/test_types.md

@@ -0,0 +1,9 @@
+# test_types.fun — overview
+
+What it shows
+- Type checks and simple assertions around type behavior.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_types.fun
+- Or: fun examples/test_types.fun

docs/examples/test_xor.md

@@ -0,0 +1,9 @@
+# test_xor.fun — overview
+
+What it shows
+- Bitwise XOR helper/tests.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/test_xor.fun
+- Or: fun examples/test_xor.fun

docs/examples/thread_class_example.md

@@ -0,0 +1,9 @@
+# thread_class_example.fun — overview
+
+What it shows
+- Threading building blocks using a small thread class; start/join patterns.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/thread_class_example.fun
+- Or: fun examples/thread_class_example.fun

docs/examples/threads_demo.md

@@ -0,0 +1,9 @@
+# threads_demo.fun — overview
+
+What it shows
+- Threading building blocks and concurrent execution demo.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/threads_demo.fun
+- Or: fun examples/threads_demo.fun

docs/examples/try_catch_finally.md

@@ -0,0 +1,9 @@
+# try_catch_finally.fun — overview
+
+What it shows
+- Structured error handling with try/catch/finally blocks.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/try_catch_finally.fun
+- Or: fun examples/try_catch_finally.fun

docs/examples/type_safety.md

@@ -0,0 +1,9 @@
+# type_safety.fun — overview
+
+What it shows
+- Static/dynamic type checks and enforcing type safety in small examples.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/type_safety.fun
+- Or: fun examples/type_safety.fun

docs/examples/type_safety_fails.md

@@ -0,0 +1,9 @@
+# type_safety_fails.fun — overview
+
+What it shows
+- Examples that intentionally violate type expectations to illustrate safety checks.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/type_safety_fails.fun
+- Or: fun examples/type_safety_fails.fun

docs/examples/typeof.md

@@ -0,0 +1,9 @@
+# typeof.fun — overview
+
+What it shows
+- Type inspection using typeof and related helpers.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/typeof.fun
+- Or: fun examples/typeof.fun

docs/examples/typeof_features.md

@@ -0,0 +1,9 @@
+# typeof_features.fun — overview
+
+What it shows
+- A tour of typeof-related features and type introspection helpers.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/typeof_features.fun
+- Or: fun examples/typeof_features.fun

docs/examples/types_integers.md

@@ -0,0 +1,9 @@
+# types_integers.fun — overview
+
+What it shows
+- Integer type families, ranges, and basic operations.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/types_integers.fun
+- Or: fun examples/types_integers.fun

docs/examples/types_overview.md

@@ -0,0 +1,9 @@
+# types_overview.fun — overview
+
+What it shows
+- Overview of language types with small examples.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/types_overview.fun
+- Or: fun examples/types_overview.fun

docs/examples/uint_types.md

@@ -0,0 +1,9 @@
+# uint_types.fun — overview
+
+What it shows
+- Unsigned integer types and operations; ranges and conversions.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/uint_types.fun
+- Or: fun examples/uint_types.fun

docs/examples/unix_socket_echo.md

@@ -0,0 +1,12 @@
+# unix_socket_echo.fun — overview
+
+What it shows
+- Local domain (UNIX) socket echo server/client demonstration.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/unix_socket_echo.fun
+- Or: fun examples/unix_socket_echo.fun
+
+Notes
+- Uses a UNIX domain socket path on the local filesystem; ensure you have permissions to create it.

docs/examples/version.md

@@ -0,0 +1,9 @@
+# version.fun — overview
+
+What it shows
+- Prints VM and version info for the Fun interpreter/runtime.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/version.fun
+- Or: fun examples/version.fun

docs/examples/while_test.md

@@ -0,0 +1,9 @@
+# while_test.fun — overview
+
+What it shows
+- Simple while loop example; loop conditions and counters.
+
+How to run
+- export FUN_LIB_DIR="./lib"
+- ./build_debug/fun examples/while_test.fun
+- Or: fun examples/while_test.fun