From f2e319c4a47fdac09a67cc5963311086aec1c92d Mon Sep 17 00:00:00 2001 From: hanez Date: Fri, 27 Mar 2026 22:53:40 +0100 Subject: [PATCH] Some documentation refactoring. No code changes. (0.39.12) --- docs/README.md | 3 +- docs/examples/README.md | 196 +++++++++++++++++++++ docs/examples/data/htdocs/counter.md | 17 ++ docs/examples/data/htdocs/form_post.md | 17 ++ docs/examples/data/htdocs/hello.md | 17 ++ docs/examples/data/htdocs/info.md | 17 ++ docs/examples/data/htdocs/json_like_api.md | 17 ++ docs/examples/data/htdocs/redirect.md | 17 ++ docs/examples/net/http_mt_server.md | 20 +++ docs/examples/net/http_mt_server_cgi.md | 22 +++ docs/examples/net/http_server.md | 24 +++ docs/examples/net/http_server_cgi.md | 22 +++ docs/examples/net/http_server_cgi_lib.md | 22 +++ docs/examples/net/http_static_server.md | 20 +++ 14 files changed, 430 insertions(+), 1 deletion(-) create mode 100644 docs/examples/README.md create mode 100644 docs/examples/data/htdocs/counter.md create mode 100644 docs/examples/data/htdocs/form_post.md create mode 100644 docs/examples/data/htdocs/hello.md create mode 100644 docs/examples/data/htdocs/info.md create mode 100644 docs/examples/data/htdocs/json_like_api.md create mode 100644 docs/examples/data/htdocs/redirect.md create mode 100644 docs/examples/net/http_mt_server.md create mode 100644 docs/examples/net/http_mt_server_cgi.md create mode 100644 docs/examples/net/http_server.md create mode 100644 docs/examples/net/http_server_cgi.md create mode 100644 docs/examples/net/http_server_cgi_lib.md create mode 100644 docs/examples/net/http_static_server.md diff --git a/docs/README.md b/docs/README.md index 50712cd..bdcaf46 100644 --- a/docs/README.md +++ b/docs/README.md @@ -40,7 +40,8 @@ This file serves as an index of the documents in this directory. Links are relat ## Example deep-dives -- [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. + - [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 diff --git a/docs/examples/README.md b/docs/examples/README.md new file mode 100644 index 0000000..0e58b52 --- /dev/null +++ b/docs/examples/README.md @@ -0,0 +1,196 @@ +# Examples catalog and how to run them + +This page is a practical catalog of the example areas that ship with the Fun language. It explains what you’ll find in each folder under ./examples/, how to run the scripts, and where deeper walkthroughs live. + +If you’re building/running from the repository without installing, set FUN_LIB_DIR to the local ./lib directory so examples can locate the stdlib: + +- export FUN_LIB_DIR="./lib" +- Then run an example: ./build_debug/fun examples/basics/hello_world.fun + - Or, if installed: fun examples/basics/hello_world.fun + +Notes +- Most scripts are self‑documented with a short header comment at the top. Open them to see exact behavior and expected output. +- Some examples depend on optional extensions (cURL, PCRE2, SQLite, Notcurses, Tk, PC/SC, OpenSSL/LibreSSL). See docs/external/ for enablement and availability. +- 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) + +Quick micro demos covering language features and tiny utilities. + +Run pattern: +- fun examples/.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 + +Tip: If a file name is listed above but not present on your build, it may depend on an extension you did not enable. + + +## Algorithms (./examples/algos) +- deduplicate.fun — removing duplicates from arrays/maps +- sort_and_search.fun — sorting and lookup patterns +- stack_queue.fun — basic stack and queue implementation + +## Arrays (./examples/arrays) +- arrays.fun — create, index, slice; typical idioms +- arrays_iter.fun — iteration and enumeration +- arrays_advanced.fun — copying, filtering, transformations + +## Basics (./examples/basics) +- boolean_decl.fun, booleans.fun — boolean values and operators +- builtins_conversions.fun — core built‑ins, type conversions +- collections.fun — arrays, maps, nested structures +- fibonacci.fun, fizzbuzz.fun — classic exercises +- hello_world.fun — the canonical first program + +## CLI (./examples/cli) +- args_parse.fun — arguments parsing patterns for small CLIs + +## Compose (./examples/compose) +Compositional patterns, small abstractions to combine behavior. + +## Crypto (./examples/crypto) +Hashing and cryptographic helpers. Availability depends on whether OpenSSL/LibreSSL is enabled. +- openssl_md5.fun — MD5 via OpenSSL (if -DFUN_WITH_OPENSSL) +- libressl_md5.fun — MD5 via LibreSSL (if -DFUN_WITH_LIBRESSL) +- aes256.fun and hash samples if present on your build + +## Data (./examples/data) +Static assets for example servers; not meant to be run directly. +- htdocs/ — files used by HTTP server examples (index.html, hello.fun, info.fun, form_post.fun, counter.fun, redirect.fun, json_like_api.fun) + +## Error handling and diagnostics (./examples/error) +- debug_reporting.fun — enabling debug output and reading traces +- exit_example.fun — exit codes +- fail.fun — triggering and observing failures +- repl_on_error.fun — dropping into REPL on error +- rust_vm_access.fun — Rust opcode errors (if enabled) +- test_indent.fun — parser/indentation corner cases +- try_catch_with_error.fun — capturing error objects + +## Extra integrations (./examples/extra) +These require optional external libraries. See docs/external/. +- curl_* — cURL HTTP client examples (download, GET JSON, POST) +- ini_* — parsing INI files (simple to complex) +- json_showcase.fun — JSON helpers +- libsql_example.fun — libSQL client usage +- notcurses_* — rich TUI demos (if Notcurses enabled) +- pcre2_* — PCRE2 regex engine demos +- pcsc*.fun — smart card access via PC/SC +- sqlite_example.fun — SQLite usage +- tcp_echo_server*.fun — basic TCP echo server +- tk_* — Tcl/Tk GUI examples +- xml_* — XML parsing with libxml2 + +## Interactive (./examples/interactive) +- console_prompt.fun — simple prompt loop +- input_example.fun — reading user input +- input_hidden_example.fun, input_hidden_pam_auth.fun — hidden input/passwords + +## IO (./examples/io) +- async_http_client.fun — non‑blocking HTTP client +- csv_reader.fun — parse CSV files +- file_io.fun, read_write_file.fun — file operations +- word_count.fun — classic WC example + +## Math (./examples/math) +Small, focused math helpers and demonstrations: +- math_ceil, math_floor, math_round, math_trunc, math_sign +- math_cos, math_sin, math_tan +- math_sqrt, math_isqrt +- math_exp_log +- math_fmin_fmax +- math_gcd_lcm + +## Networking (./examples/net) +Servers and socket utilities. See docs/examples/httpserver.md for the HTTP family. +- 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 +- http_server_cgi_lib.fun — blocking server leveraging net/cgi.fun helpers +- http_mt_server.fun — thread‑per‑connection static server +- http_mt_server_cgi.fun — thread‑per‑connection with CGI support + +## Patterns (./examples/patterns) +Small idioms and reusable patterns. +- assert_like.fun — assert‑style checks via language constructs + +## Snippets (./examples/snippets) +Miscellaneous one‑off code snippets demonstrating particular opcodes or tricks. + +## SQLite daemon (./examples/sqlited) +- Files related to running a small SQLite‑backed service (see source for details) + +## Strings (./examples/strings) +- base64_demo.fun — base64 encode/decode using encoding/base64 +- split_join_trim.fun — string splitting and trimming +- templating_min.fun — bare‑bones templating +- urlencode_decode.fun — percent‑encoding helpers + +## Broken (./examples/broken) +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: +- ./build_debug/fun +- or: ./build_release/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 + +When optional extensions are not enabled, their examples will not run; reconfigure the build with the required -D flags shown in docs/external/. diff --git a/docs/examples/data/htdocs/counter.md b/docs/examples/data/htdocs/counter.md new file mode 100644 index 0000000..48b6952 --- /dev/null +++ b/docs/examples/data/htdocs/counter.md @@ -0,0 +1,17 @@ +# counter.fun (CGI) + +- Location: examples/data/htdocs/counter.fun +- Category: CGI script used by HTTP server examples + +Description +- Simple stateful counter example for CGI; demonstrates reading and updating a value across requests (implementation details in script). + +How to run +- Through one of the HTTP server examples, e.g.: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" + - ./build_debug/fun examples/net/http_server_cgi.fun + - Open: http://127.0.0.1:8080/counter.fun + +See also +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/data/htdocs/form_post.md b/docs/examples/data/htdocs/form_post.md new file mode 100644 index 0000000..d0fb86f --- /dev/null +++ b/docs/examples/data/htdocs/form_post.md @@ -0,0 +1,17 @@ +# form_post.fun (CGI) + +- Location: examples/data/htdocs/form_post.fun +- Category: CGI script used by HTTP server examples + +Description +- Demonstrates handling of POST form data via the CGI interface. + +How to run +- Through one of the HTTP server examples, e.g.: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" + - ./build_debug/fun examples/net/http_server_cgi.fun + - Submit a form to: http://127.0.0.1:8080/form_post.fun + +See also +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/data/htdocs/hello.md b/docs/examples/data/htdocs/hello.md new file mode 100644 index 0000000..3192ff6 --- /dev/null +++ b/docs/examples/data/htdocs/hello.md @@ -0,0 +1,17 @@ +# hello.fun (CGI) + +- Location: examples/data/htdocs/hello.fun +- Category: CGI script used by HTTP server examples + +Description +- Simple CGI .fun script that prints a greeting, optionally using query parameters (e.g., ?name=Fun). + +How to run +- Through one of the HTTP server examples, e.g.: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" + - ./build_debug/fun examples/net/http_server_cgi.fun + - Open: http://127.0.0.1:8080/hello.fun?name=Fun + +See also +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/data/htdocs/info.md b/docs/examples/data/htdocs/info.md new file mode 100644 index 0000000..ee441a9 --- /dev/null +++ b/docs/examples/data/htdocs/info.md @@ -0,0 +1,17 @@ +# info.fun (CGI) + +- Location: examples/data/htdocs/info.fun +- Category: CGI script used by HTTP server examples + +Description +- CGI script that prints request/environment information, useful for debugging CGI variables. + +How to run +- Through one of the HTTP server examples, e.g.: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" + - ./build_debug/fun examples/net/http_server_cgi.fun + - Open: http://127.0.0.1:8080/info.fun + +See also +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/data/htdocs/json_like_api.md b/docs/examples/data/htdocs/json_like_api.md new file mode 100644 index 0000000..509dbf2 --- /dev/null +++ b/docs/examples/data/htdocs/json_like_api.md @@ -0,0 +1,17 @@ +# json_like_api.fun (CGI) + +- Location: examples/data/htdocs/json_like_api.fun +- Category: CGI script used by HTTP server examples + +Description +- Demonstrates returning JSON-like output from a CGI endpoint. + +How to run +- Through one of the HTTP server examples, e.g.: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" + - ./build_debug/fun examples/net/http_server_cgi.fun + - Open: http://127.0.0.1:8080/json_like_api.fun + +See also +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/data/htdocs/redirect.md b/docs/examples/data/htdocs/redirect.md new file mode 100644 index 0000000..c968268 --- /dev/null +++ b/docs/examples/data/htdocs/redirect.md @@ -0,0 +1,17 @@ +# redirect.fun (CGI) + +- Location: examples/data/htdocs/redirect.fun +- Category: CGI script used by HTTP server examples + +Description +- Demonstrates issuing HTTP redirects from a CGI script (setting Status and Location headers). + +How to run +- Through one of the HTTP server examples, e.g.: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" + - ./build_debug/fun examples/net/http_server_cgi.fun + - Open: http://127.0.0.1:8080/redirect.fun + +See also +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/net/http_mt_server.md b/docs/examples/net/http_mt_server.md new file mode 100644 index 0000000..c038f2a --- /dev/null +++ b/docs/examples/net/http_mt_server.md @@ -0,0 +1,20 @@ +# http_mt_server.fun + +- Location: examples/net/http_mt_server.fun +- Category: Networking / HTTP (multi-threaded) + +Description +- Thread-per-connection HTTP server built on io/socket.fun and io/thread.fun. For each accepted client, spawns a thread and returns a small HTML page. + +How to run +- From the repository root: + - export FUN_LIB_DIR="./lib" + - ./build_debug/fun examples/net/http_mt_server.fun + - Then open http://127.0.0.1:8080/ (or the port printed on start) + +Requirements +- Uses stdlib io/socket.fun and io/thread.fun. No external extensions required. + +See also +- docs/examples/README.md +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/net/http_mt_server_cgi.md b/docs/examples/net/http_mt_server_cgi.md new file mode 100644 index 0000000..78298cb --- /dev/null +++ b/docs/examples/net/http_mt_server_cgi.md @@ -0,0 +1,22 @@ +# http_mt_server_cgi.fun + +- Location: examples/net/http_mt_server_cgi.fun +- Category: Networking / HTTP with CGI (multi-threaded) + +Description +- Multi-threaded HTTP server (thread-per-connection) with CGI support. Serves static files from htdocs and executes .fun scripts as CGI using net/cgi.fun helpers. + +How to run +- From the repository root: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" # optional; auto-detected if omitted + - export FUN_HTDOCS="./examples/data/htdocs" # optional + - ./build_debug/fun examples/net/http_mt_server_cgi.fun + - Try: http://127.0.0.1:8080/ and /hello.fun?name=Fun, /info.fun + +Requirements +- Uses stdlib io/socket.fun, io/thread.fun, and net/cgi.fun. No external extensions required. + +See also +- docs/examples/README.md +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/net/http_server.md b/docs/examples/net/http_server.md new file mode 100644 index 0000000..bc97233 --- /dev/null +++ b/docs/examples/net/http_server.md @@ -0,0 +1,24 @@ +# http_server.fun + +- Location: examples/net/http_server.fun +- Category: Networking / HTTP (blocking) + +Description +- Blocking HTTP server that serves static files and executes .fun CGI scripts via lib/net/http_server.fun. + +How to run +- From the repository root: + - export FUN_LIB_DIR="./lib" + - ./build_debug/fun examples/net/http_server.fun + - Default docroot: ./examples/data/htdocs + - Visit: http://127.0.0.1:8080/ + +Notes +- For CGI .fun under htdocs, the server uses the Fun interpreter to execute them and forwards output as HTTP. + +Requirements +- Uses io/socket.fun and strings.fun; no external extensions required. + +See also +- docs/examples/README.md +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/net/http_server_cgi.md b/docs/examples/net/http_server_cgi.md new file mode 100644 index 0000000..caaa5ed --- /dev/null +++ b/docs/examples/net/http_server_cgi.md @@ -0,0 +1,22 @@ +# http_server_cgi.fun + +- Location: examples/net/http_server_cgi.fun +- Category: Networking / HTTP with CGI (blocking) + +Description +- Minimal CGI-capable HTTP server (blocking) using lib/net/http_cgi_server.fun. Serves static files and executes .fun scripts as CGI. + +How to run +- From the repository root: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" # optional; auto-detected if omitted + - export FUN_HTDOCS="./examples/data/htdocs" # optional + - ./build_debug/fun examples/net/http_server_cgi.fun + - Try: http://127.0.0.1:8080/ and /hello.fun, /info.fun + +Requirements +- Uses stdlib io/socket.fun, strings.fun, and net/cgi.fun. No external extensions required. + +See also +- docs/examples/README.md +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/net/http_server_cgi_lib.md b/docs/examples/net/http_server_cgi_lib.md new file mode 100644 index 0000000..0b0dbca --- /dev/null +++ b/docs/examples/net/http_server_cgi_lib.md @@ -0,0 +1,22 @@ +# http_server_cgi_lib.fun + +- Location: examples/net/http_server_cgi_lib.fun +- Category: Networking / HTTP with CGI (blocking, stdlib helpers) + +Description +- Blocking HTTP server that serves static files and runs .fun as CGI using helpers from lib/net/http_cgi_lib_server.fun and net/cgi.fun. + +How to run +- From the repository root: + - export FUN_LIB_DIR="./lib" + - export FUN_EXEC="./build_debug/fun" # optional; auto-detected if omitted + - export FUN_HTDOCS="./examples/data/htdocs" # optional + - ./build_debug/fun examples/net/http_server_cgi_lib.fun + - Try: http://127.0.0.1:8080/ and /hello.fun, /info.fun + +Requirements +- Uses stdlib io/socket.fun, strings.fun, net/cgi.fun. No external extensions required. + +See also +- docs/examples/README.md +- docs/examples/httpserver.md (deep-dive) diff --git a/docs/examples/net/http_static_server.md b/docs/examples/net/http_static_server.md new file mode 100644 index 0000000..16dbf82 --- /dev/null +++ b/docs/examples/net/http_static_server.md @@ -0,0 +1,20 @@ +# http_static_server.fun + +- Location: examples/net/http_static_server.fun +- Category: Networking / Sockets + +Description +- Minimal static HTTP server implemented directly on sockets. Accepts connections and always returns a small HTML page. + +How to run +- From the repository root: + - export FUN_LIB_DIR="./lib" + - ./build_debug/fun examples/net/http_static_server.fun + - Then open http://127.0.0.1:8088/ + +Requirements +- Uses core IO/socket stdlib (io/socket.fun). No optional extensions required. + +See also +- docs/examples/README.md +- docs/examples/httpserver.md (deep-dive over HTTP servers)