diff --git a/web/about/about.md b/web/about/about.md index b2af41d..1be1916 100644 --- a/web/about/about.md +++ b/web/about/about.md @@ -5,7 +5,7 @@ subtitle: More information about having fun... :) description: About _date: 2023-09-20 metasub: news -noToc: true +noToc: false noDate: false tags: - fun @@ -210,15 +210,16 @@ Written primarily in Fun itself (lib/): Enabled via CMake flags, each wrapping a mature C library: -- **JSON** (`FUN_WITH_JSON` / json-c) — parse, stringify, file I/O -- **cURL** (`FUN_WITH_CURL` / libcurl) — HTTP GET, POST, download -- **SQLite** (`FUN_WITH_SQLITE` / libsqlite3) — open, query, exec, close -- **PCRE2** (`FUN_WITH_PCRE2` / libpcre2) — Perl-compatible regex with flags -- **OpenSSL** (`FUN_WITH_OPENSSL` / libcrypto) — MD5, SHA-256, SHA-512, RIPEMD-160 hashing -- **INI** (`FUN_WITH_INI` / iniparser 4.2.6) — load, get/set, save config files -- **XML** (`FUN_WITH_XML2` / libxml2) — parse, navigate, query XML documents -- **PC/SC** (`FUN_WITH_PCSC` / libpcsclite) — smart card communication -- **KCGI** (`FUN_WITH_KCGI` / libkcgi) — CGI web applications +- **[JSON](/documentation/extensions/json/)** (`FUN_WITH_JSON` / [json-c](https://json-c.github.io/json-c/){:class="ext"}) — parse, stringify, file I/O +- **[cURL](/documentation/extensions/curl/)** (`FUN_WITH_CURL` / [libcurl](https://curl.se/libcurl/){:class="ext"}) — HTTP GET, POST, download +- **[SQLite](/documentation/extensions/sqlite/)** (`FUN_WITH_SQLITE` / [libsqlite3](https://www.sqlite.org/){:class="ext"}) — open, query, exec, close +- **[PCRE2](/documentation/extensions/pcre2/)** (`FUN_WITH_PCRE2` / [libpcre2](https://www.pcre.org/){:class="ext"}) — Perl-compatible regex with flags +- **[OpenSSL](/documentation/extensions/openssl/)** (`FUN_WITH_OPENSSL` / [libcrypto](https://www.openssl.org/){:class="ext"}) — MD5, SHA-256, SHA-512, RIPEMD-160 hashing +- **[INI](/documentation/extensions/ini/)** (`FUN_WITH_INI` / [iniparser](https://github.com/ndevilla/iniparser){:class="ext"}) — load, get/set, save config files +- **[XML](/documentation/extensions/xml2/)** (`FUN_WITH_XML2` / [libxml2](http://xmlsoft.org/){:class="ext"}) — parse, navigate, query XML documents +- **[PC/SC](/documentation/extensions/pcsc/)** (`FUN_WITH_PCSC` / [libpcsclite](https://pcsclite.apdu.fr/){:class="ext"}) — smart card communication +- **[KCGI](/documentation/extensions/kcgi/)** (`FUN_WITH_KCGI` / [libkcgi](https://kristaps.bsd.lv/kcgi/){:class="ext"}) — CGI web applications +- **[Redis/Valkey](/documentation/extensions/redis/)** (`FUN_WITH_REDIS` / [hiredis](https://github.com/redis/hiredis){:class="ext"}) — Redis and Valkey support = Done @@ -244,3 +245,4 @@ Each extension also has a corresponding stdlib wrapper class (e.g., `JSON`, `INI ## Code - [https://git.xw3.org/fun/fun/](https://git.xw3.org/fun/fun/){:class="git"} + diff --git a/web/documentation/examples/examples.md b/web/documentation/examples/examples.md index 1e16476..8c71574 100644 --- a/web/documentation/examples/examples.md +++ b/web/documentation/examples/examples.md @@ -27,21 +27,21 @@ All commands assume you are in the repository root. ## Prerequisites -- Build the interpreter (see handbook/). You’ll have `build/fun` (paths may vary by your setup/IDE). +- Build the interpreter (see [handbook](/documentation/handbook/). You’ll have `build/fun` (paths may vary by your setup/IDE). - Set FUN_LIB_DIR to the repo’s lib directory when running without installation so `#include <...>` can find the standard library. -Example (Linux/macOS/BSD): +### 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): +### Windows (PowerShell):
$env:FUN_LIB_DIR = "$PWD/lib"
 ./build/fun.exe .\examples\include_lib.fun
## Interactive showcase: play.fun -The script `./scripts/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 in `./examples` and offers to run them one by one:
./scripts/play.fun
@@ -52,7 +52,7 @@ Notes: Tip: you can run specific examples directly too: -
FUN_LIB_DIR="$(pwd)/lib" fun examples/crypto/openssl_md5.fun
+
FUN_LIB_DIR="$(pwd)/lib" ./build/fun ./examples/extensions/openssl/openssl_md5.fun
## Example categories @@ -72,3 +72,4 @@ Place your `.fun` files anywhere under `examples/` to have them picked up by `pl #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/extensions/curl/curl.md b/web/documentation/extensions/curl/curl.md index be75d48..b9ed099 100644 --- a/web/documentation/extensions/curl/curl.md +++ b/web/documentation/extensions/curl/curl.md @@ -20,13 +20,14 @@ tags: - Purpose: HTTP helpers using libcurl. - Homepage: [https://curl.se/libcurl/](https://curl.se/libcurl/){:class="ext"} -## Opcodes: +## Opcodes - OP_CURL_GET: GET; pops url:string; pushes body:string (empty on error/disabled) - OP_CURL_POST: POST; pops body:string, url:string; pushes response:string - OP_CURL_DOWNLOAD: Download to file; pops path:string, url:string; pushes 1/0 -## Notes: +## Notes - Requires libcurl development headers/libs. - When disabled, helpers return empty strings/0 to match optional behavior. + diff --git a/web/documentation/extensions/ini/ini.md b/web/documentation/extensions/ini/ini.md index 94566e7..095fb96 100644 --- a/web/documentation/extensions/ini/ini.md +++ b/web/documentation/extensions/ini/ini.md @@ -20,7 +20,7 @@ tags: - Purpose: Read/write simple INI configuration files. - Homepage: [https://github.com/ndevilla/iniparser](https://github.com/ndevilla/iniparser){:class="ext"} -## Opcodes: +## Opcodes - OP_INI_LOAD: pops path; pushes handle (>0) or 0 - OP_INI_FREE: pops handle; pushes 1/0 @@ -32,7 +32,8 @@ tags: - OP_INI_UNSET: pops key, section, handle; pushes 1/0 - OP_INI_SAVE: pops path, handle; pushes 1/0 -## Notes: +## Notes - Requires iniparser development headers/libs. - When disabled, helpers return neutral values (0/empty strings) like other optional extensions. + diff --git a/web/documentation/extensions/json/json.md b/web/documentation/extensions/json/json.md index 80e384a..05d2d06 100644 --- a/web/documentation/extensions/json/json.md +++ b/web/documentation/extensions/json/json.md @@ -19,14 +19,15 @@ tags: - Purpose: JSON parse/stringify and file helpers via json-c. - Homepage: [https://json-c.github.io/json-c/](https://json-c.github.io/json-c/){:class="ext"} -## Opcodes: +## Opcodes - OP_JSON_PARSE: pops text; pushes value or Nil on error - OP_JSON_STRINGIFY: pops pretty:int(0/1), value; pushes string - OP_JSON_FROM_FILE: pops path; pushes value or Nil - OP_JSON_TO_FILE: pops pretty:int(0/1), value, path; pushes 1/0 -## Notes: +## Notes - Requires json-c development headers/libs. - When disabled, functions push empty/neutral values similar to other optional modules. + diff --git a/web/documentation/extensions/kcgi/kcgi.md b/web/documentation/extensions/kcgi/kcgi.md index 45e9084..beda451 100644 --- a/web/documentation/extensions/kcgi/kcgi.md +++ b/web/documentation/extensions/kcgi/kcgi.md @@ -18,12 +18,12 @@ tags: - Purpose: integrate the kcgi (CGI/FastCGI) C library; provide request parsing and response helpers for building CGI apps in Fun. - Homepage: [https://kristaps.bsd.lv/kcgi/](https://kristaps.bsd.lv/kcgi/){:class="ext"} -## Build notes: +## Build notes - Requires system kcgi development headers and libraries (pkg-config name: kcgi). - If pkg-config is not available, build falls back to linking against libkcgi and zlib (as configured in cmake/Extensions/KCGI.cmake). -## Provided helper/opcodes: +## Provided helper/opcodes - Function: kcgi_parse(data: none) -> Map | Nil. Parses the current CGI/FastCGI request via kcgi and returns a Map with keys like method, scheme, host, port, path, suffix, query, and fields (GET/POST map). Returns Nil on failure or when the extension is disabled. - Function: kcgi_reply_start(code:int, content_type:string) -> 1/0. Starts the HTTP reply (sets Content-Type and opens the body). @@ -31,19 +31,20 @@ tags: - Function: kcgi_end() -> 1/0. Finalizes the response and frees request resources. - Opcodes: OP_KCGI_PARSE, OP_KCGI_REPLY_START, OP_KCGI_WRITE, OP_KCGI_END (internal mappings for the functions above). -## Quickstart: +## Quickstart - Configure: cmake -S . -B build -DFUN_WITH_KCGI=ON - Build: cmake --build build --target fun - Run example: - FUN_LIB_DIR="$(pwd)/lib" ./build/fun examples/cgi/hello_kcgi.fun -## Example output: +## Example output - Content-Type: text/html; charset=utf-8 -

Hello, Fun!

-## Notes: +## Notes - Running outside a real CGI/FastCGI environment may emit RFC warnings (e.g., missing REMOTE_ADDR); these are benign for local testing. - When FUN_WITH_KCGI is OFF, the helpers behave as no-ops (returning Nil/0) to keep scripts portable. + diff --git a/web/documentation/extensions/openssl/openssl.md b/web/documentation/extensions/openssl/openssl.md index 674e947..af38a23 100644 --- a/web/documentation/extensions/openssl/openssl.md +++ b/web/documentation/extensions/openssl/openssl.md @@ -19,12 +19,12 @@ tags: - Purpose: provide small crypto helpers backed by OpenSSL. Includes md5, sha256, sha512, ripemd160 helpers. - Homepage: [https://www.openssl.org/](https://www.openssl.org/){:class="ext"} -## Build notes: +## Build notes - Requires system OpenSSL development headers and libraries. - On OpenSSL 3.x, legacy MD5_* APIs are deprecated; you may see warnings during build. -## Provided helper/opcodes: +## Provided helper/opcodes - Function: openssl_md5(data:string) -> string (lowercase hex). Falls back to empty string when the extension is disabled, mirroring other optional modules. - Function: openssl_sha256(data:string) -> string (lowercase hex). @@ -32,7 +32,7 @@ tags: - Function: openssl_ripemd160(data:string) -> string (lowercase hex). Note: On OpenSSL 3.x this may require the legacy provider; if the digest is unavailable, the helper returns an empty string. - Opcodes: OP_OPENSSL_MD5, OP_OPENSSL_SHA256, OP_OPENSSL_SHA512, OP_OPENSSL_RIPEMD160 (internal mappings for the functions above). -## Quickstart: +## Quickstart - Configure: cmake -S . -B build -DFUN_WITH_OPENSSL=ON - Build: cmake --build build --target fun @@ -42,7 +42,7 @@ tags: - ./build/fun examples/crypto/openssl_sha512.fun - ./build/fun examples/crypto/openssl_ripemd160.fun -## Example output: +## Example output - md5(abc) = 900150983cd24fb0d6963f7d28e17f72 - md5("") = d41d8cd98f00b204e9800998ecf8427e @@ -53,6 +53,7 @@ tags: - ripemd160(abc) = 8eb208f7e05d987a9b044a8e98c6b087f15a0bfc - ripemd160("") = 9c1185a5c5e9fc54612808977ee8f548b2258d31 -## Notes: +## Notes - The OpenSSL 3.x provider configuration on your system determines availability of RIPEMD-160. If the legacy provider is not enabled, openssl_ripemd160() will return an empty string. + diff --git a/web/documentation/extensions/pcre2/pcre2.md b/web/documentation/extensions/pcre2/pcre2.md index 3a6d449..85cd0e2 100644 --- a/web/documentation/extensions/pcre2/pcre2.md +++ b/web/documentation/extensions/pcre2/pcre2.md @@ -22,13 +22,14 @@ tags: - Purpose: Advanced regular expressions via PCRE2. - Homepage: [https://www.pcre.org/](https://www.pcre.org/){:class="ext"} -## Opcodes: +## Opcodes - OP_PCRE2_TEST: pops flags, text, pattern; pushes 1/0 - OP_PCRE2_MATCH: pops flags, text, pattern; pushes match map or Nil - OP_PCRE2_FINDALL: pops flags, text, pattern; pushes array of match maps -## Notes: +## Notes - Requires PCRE2 development headers/libs. - Flags are backend-specific; see implementation for supported bits. + diff --git a/web/documentation/extensions/pcsc/pcsc.md b/web/documentation/extensions/pcsc/pcsc.md index e3a7fca..d3eb067 100644 --- a/web/documentation/extensions/pcsc/pcsc.md +++ b/web/documentation/extensions/pcsc/pcsc.md @@ -20,7 +20,7 @@ tags: - Purpose: Access smart card readers/cards via PC/SC (pcsclite). - Homepage: [https://pcsclite.apdu.fr/](https://pcsclite.apdu.fr/){:class="ext"} -## Opcodes: +## Opcodes - OP_PCSC_ESTABLISH: returns context id (>0) or 0 - OP_PCSC_RELEASE: pops ctx id; returns 1/0 @@ -29,7 +29,8 @@ tags: - OP_PCSC_DISCONNECT: pops handle id; returns 1/0 - OP_PCSC_TRANSMIT: pops apdu, handle id; returns map with data/SW/rc -## Notes: +## Notes - Requires PC/SC lite development headers/libs. - Behavior and availability depend on platform and reader drivers. + diff --git a/web/documentation/extensions/redis/redis.md b/web/documentation/extensions/redis/redis.md index c218705..9a99534 100644 --- a/web/documentation/extensions/redis/redis.md +++ b/web/documentation/extensions/redis/redis.md @@ -5,12 +5,13 @@ noToc: false noComments: false noDate: false title: Redis (hiredis) Extension -subtitle: Redis client integration for Fun using the hiredis C library. +subtitle: Redis/Valkey client integration for Fun using the hiredis C library. description: Documentation for the optional Redis extension in Fun. Provides redis_connect, redis_cmd, and redis_close builtins backed by hiredis. permalink: /documentation/extensions/redis/ lang: en tags: - redis +- valkey - hiredis - database - cache @@ -21,25 +22,25 @@ tags: The Redis extension adds a minimal client for Redis-compatible servers using the [hiredis](https://github.com/redis/hiredis){:class="ext"} C library. It currently exposes a simple synchronous API; Async I/O through Fun's event loop will be added later. -Requirements ------------- +## Requirements + - Build-time option: `-DFUN_WITH_REDIS=ON` - System libraries: `hiredis` headers and library available (via pkg-config or default linker search paths) - Runtime: a Redis-compatible server (e.g., on `127.0.0.1:6379`) -Enabling the extension ----------------------- +## Enabling the extension + Example CMake configure line enabling Redis along with other options:
cmake -S . -B build_release -DCMAKE_BUILD_TYPE=Release \
-  -DFUN_WITH_REDIS=ON -DFUN_WITH_OPENSSL=ON
+ -DFUN_WITH_REDIS=ON When configured, the build summary will include a line:
Redis (FUN_WITH_REDIS): ENABLED
-Provided builtins/opcodes -------------------------- +## Provided builtins/opcodes + - `redis_connect(host: string, port: int) -> int` - Establishes a TCP connection and returns a positive handle id on success, or `0` on error. - Example: `h = redis_connect('127.0.0.1', 6379)` @@ -56,26 +57,28 @@ Provided builtins/opcodes - `redis_close(handle: int) -> Nil` - Closes the connection associated with the handle and frees resources. -Notes and limitations ---------------------- +## Notes and limitations + - Error handling: invalid handles or failed commands yield `nil` or an empty/neutral value depending on context. - Security: this initial version does not include TLS; TLS support may be added in a future iteration once hiredis SSL is wired in. - Async: the current API is synchronous. Integration with Fun's asyncio is planned. -Examples --------- +## Examples + Runnable examples are included in the source tree: - `examples/extensions/redis/basic_ping.fun` - `examples/extensions/redis/kv_set_get.fun` - `examples/extensions/redis/list_ops.fun` - `examples/extensions/redis/hash_ops.fun` +- `examples/extensions/redis/redis_test.fun` Quick start (from repo root, using a built Fun executable):
build_debug/fun examples/extensions/redis/basic_ping.fun
-Troubleshooting ---------------- +## Troubleshooting + - Ensure a Redis server is reachable at the host/port you pass to `redis_connect`. - If `redis_connect` returns `0`, verify the hiredis library and headers are installed and that Fun was configured with `-DFUN_WITH_REDIS=ON`. + diff --git a/web/features/features.md b/web/features/features.md index 467e7a8..d7449e0 100644 --- a/web/features/features.md +++ b/web/features/features.md @@ -330,16 +330,16 @@ Enabled via CMake flags; each wraps a mature C library: | Extension | CMake Flag | Library | Features | |-----------|-----------|---------|----------| -| **JSON** | `FUN_WITH_JSON` | json-c | `json_parse()`, `json_stringify()`, `json_from_file()`, `json_to_file()` | -| **cURL** | `FUN_WITH_CURL` | libcurl | `curl_get()`, `curl_post()`, `curl_download()` | -| **SQLite** | `FUN_WITH_SQLITE` | libsqlite3 | `sqlite_open()`, `sqlite_close()`, `sqlite_exec()`, `sqlite_query()` | -| **PCRE2** | `FUN_WITH_PCRE2` | libpcre2 | `pcre2_test()`, `pcre2_match()`, `pcre2_find_all()` — with flags (i, m, s, u, x) | -| **OpenSSL** | `FUN_WITH_OPENSSL` | libcrypto | `openssl_md5()`, `openssl_sha256()`, `openssl_sha512()`, `openssl_ripemd160()` | -| **INI** | `FUN_WITH_INI` | iniparser 4.2.6 | `ini_load()`, `ini_get_string/int/double/bool()`, `ini_set()`, `ini_unset()`, `ini_save()` | -| **XML** | `FUN_WITH_XML2` | libxml2 | `xml_parse()`, `xml_root()`, `xml_name()`, `xml_text()` | -| **PC/SC** | `FUN_WITH_PCSC` | libpcsclite | `pcsc_establish()`, `pcsc_list_readers()`, `pcsc_connect()`, `pcsc_transmit()`, etc. | -| **KCGI** | `FUN_WITH_KCGI` | libkcgi | `kcgi_parse()`, `kcgi_reply_start()`, `kcgi_write()`, `kcgi_end()` | -| **Redis** | `FUN_WITH_REDIS` | hiredis | `redis_connect()`, `redis_cmd()`, `redis_close()` | +| **[JSON](/documentation/extensions/json/)** | `FUN_WITH_JSON` | [json-c](https://json-c.github.io/json-c/){:class="ext"} | `json_parse()`, `json_stringify()`, `json_from_file()`, `json_to_file()` | +| **[cURL](/documentation/extensions/curl/)** | `FUN_WITH_CURL` | [libcurl](https://curl.se/libcurl/){:class="ext"} | `curl_get()`, `curl_post()`, `curl_download()` | +| **[SQLite](/documentation/extensions/sqlite/)** | `FUN_WITH_SQLITE` | [libsqlite3](https://www.sqlite.org/){:class="ext"} | `sqlite_open()`, `sqlite_close()`, `sqlite_exec()`, `sqlite_query()` | +| **[PCRE2](/documentation/extensions/pcre2/)** | `FUN_WITH_PCRE2` | [libpcre2](https://www.pcre.org/){:class="ext"} | `pcre2_test()`, `pcre2_match()`, `pcre2_find_all()` — with flags (i, m, s, u, x) | +| **[OpenSSL](/documentation/extensions/openssl/)** | `FUN_WITH_OPENSSL` | [libcrypto](https://www.openssl.org/){:class="ext"} | `openssl_md5()`, `openssl_sha256()`, `openssl_sha512()`, `openssl_ripemd160()` | +| **[INI](/documentation/extensions/ini/)** | `FUN_WITH_INI` | [iniparser](https://github.com/ndevilla/iniparser){:class="ext"} | `ini_load()`, `ini_get_string/int/double/bool()`, `ini_set()`, `ini_unset()`, `ini_save()` | +| **[XML](/documentation/extensions/xml2/)** | `FUN_WITH_XML2` | [libxml2](http://xmlsoft.org/){:class="ext"} | `xml_parse()`, `xml_root()`, `xml_name()`, `xml_text()` | +| **[PC/SC](/documentation/extensions/pcsc/)** | `FUN_WITH_PCSC` | [libpcsclite](https://pcsclite.apdu.fr/){:class="ext"} | `pcsc_establish()`, `pcsc_list_readers()`, `pcsc_connect()`, `pcsc_transmit()`, etc. | +| **[KCGI](/documentation/extensions/kcgi/)** | `FUN_WITH_KCGI` | [libkcgi](https://kristaps.bsd.lv/kcgi/){:class="ext"} | `kcgi_parse()`, `kcgi_reply_start()`, `kcgi_write()`, `kcgi_end()` | +| **[Redis/Valkey](/documentation/extensions/redis/)** | `FUN_WITH_REDIS` | [hiredis](https://github.com/redis/hiredis){:class="ext"} | `redis_connect()`, `redis_cmd()`, `redis_close()` | Some extensions also have a corresponding **stdlib wrapper class** in `lib/io/` or `lib/net/`: @@ -426,3 +426,4 @@ Some extensions also have a corresponding **stdlib wrapper class** in `lib/io/` ## Licensing - **Apache 2.0** — fully open source, freely usable and modifiable +