fun/docs/examples/README.md

# 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/<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

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 <path/to/example.fun>
- 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

When optional extensions are not enabled, their examples will not run; reconfigure the build with the required -D flags shown in docs/external/.