Moved all docs from ./docs/ to ./web/documentation/ to be available on the website. No code changes. (0.40.5)

2026-04-10 23:27:55 +02:00 · 2026-04-10 23:27:55 +02:00 · 567fa73796
commit 567fa73796
parent 8f2847abfb
224 changed files with 4584 additions and 1139 deletions
--- a/web/documentation/external/README.md
+++ b/web/documentation/external/README.md
@ -0,0 +1,49 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - External integrations (optional extensions)
+subtitle: Catalog of all example scripts under ./examples/, what each area contains, how to run them, required env vars, and extension requirements.
+description: Catalog of all example scripts under ./examples/, what each area contains, how to run them, required env vars, and extension requirements.
+permalink: /documentation/external/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# External integrations (optional extensions)
+
+This section documents Fun's optional, build-time selectable extensions. Each page covers:
+- How to enable the extension via CMake option (FUN_WITH_*)
+- Build requirements and detection notes
+- Available opcodes and/or helper functions
+- Minimal usage examples and links to example scripts
+
+## Extensions:
+
+- [cURL (libcurl)](./curl/)
+- [INI (iniparser)](./ini/)
+- [JSON (json-c)](./json/)
+- [libxml2 (XML)](./xml2/)
+- [SQLite](./sqlite/)
+- [PCRE2 (Perl-compatible regex)](./pcre2/)
+- [PC/SC (Smart cards)](./pcsc/)
+- [OpenSSL](./openssl/)
+
+## Notes:
+
+- These integrations are optional; the VM compiles without them.
+- When disabled, related builtins usually return empty strings/neutral values rather than fail hard, mirroring existing optionality patterns.
--- a/web/documentation/external/curl.md
+++ b/web/documentation/external/curl.md
@ -0,0 +1,42 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - cURL (libcurl) extension (optional)
+subtitle: Documentation for cURL (libcurl) extension (optional)
+description: Documentation for cURL (libcurl) extension (optional)
+permalink: /documentation/external/curl/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# cURL (libcurl) extension (optional)
+
+- CMake option: FUN_WITH_CURL=ON
+- Purpose: HTTP helpers using libcurl.
+- Homepage: https://curl.se/libcurl/
+
+## 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:
+
+- Requires libcurl development headers/libs.
+- When disabled, helpers return empty strings/0 to match optional behavior.
--- a/web/documentation/external/ini.md
+++ b/web/documentation/external/ini.md
@ -0,0 +1,48 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - INI (iniparser) extension (optional)
+subtitle: Documentation for INI (iniparser) extension (optional)
+description: Documentation for INI (iniparser) extension (optional)
+permalink: /documentation/external/ini/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# INI (iniparser) extension (optional)
+
+- CMake option: FUN_WITH_INI=ON
+- Purpose: Read/write simple INI configuration files.
+- Homepage: https://github.com/ndevilla/iniparser
+
+## Opcodes:
+
+- OP_INI_LOAD: pops path; pushes handle (>0) or 0
+- OP_INI_FREE: pops handle; pushes 1/0
+- OP_INI_GET_STRING: pops def, key, section, handle; pushes string
+- OP_INI_GET_INT: pops def, key, section, handle; pushes int
+- OP_INI_GET_DOUBLE: pops def, key, section, handle; pushes float
+- OP_INI_GET_BOOL: pops def, key, section, handle; pushes 0/1
+- OP_INI_SET: pops value, key, section, handle; pushes 1/0
+- OP_INI_UNSET: pops key, section, handle; pushes 1/0
+- OP_INI_SAVE: pops path, handle; pushes 1/0
+
+## Notes:
+
+- Requires iniparser development headers/libs.
+- When disabled, helpers return neutral values (0/empty strings) like other optional extensions.
--- a/web/documentation/external/json.md
+++ b/web/documentation/external/json.md
@ -0,0 +1,43 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - JSON (json-c) extension (optional)
+subtitle: Documentation for JSON (json-c) extension (optional)
+description: Documentation for JSON (json-c) extension (optional)
+permalink: /documentation/external/json/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# JSON (json-c) extension (optional)
+
+- CMake option: FUN_WITH_JSON=ON
+- Purpose: JSON parse/stringify and file helpers via json-c.
+- Homepage: https://json-c.github.io/json-c/
+
+## 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:
+
+- Requires json-c development headers/libs.
+- When disabled, functions push empty/neutral values similar to other optional modules.
--- a/web/documentation/external/openssl.md
+++ b/web/documentation/external/openssl.md
@ -0,0 +1,69 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - OpenSSL extension (optional)
+subtitle: Documentation for OpenSSL extension (optional)
+description: Documentation for OpenSSL extension (optional)
+permalink: /documentation/external/openssl/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# OpenSSL extension (optional)
+
+- CMake option: FUN_WITH_OPENSSL=ON
+- Purpose: provide small crypto helpers backed by OpenSSL. Includes md5, sha256, sha512, ripemd160 helpers.
+- Homepage: https://www.openssl.org/
+
+## 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:
+
+- 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).
+- Function: openssl_sha512(data:string) -> string (lowercase hex).
+- 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:
+
+- Configure: cmake -S . -B build -DFUN_WITH_OPENSSL=ON
+- Build: cmake --build build --target fun
+- Run examples:
+  - ./build/fun examples/crypto/openssl_md5.fun
+  - ./build/fun examples/crypto/openssl_sha256.fun
+  - ./build/fun examples/crypto/openssl_sha512.fun
+  - ./build/fun examples/crypto/openssl_ripemd160.fun
+
+## Example output:
+
+- md5(abc) = 900150983cd24fb0d6963f7d28e17f72
+- md5("") = d41d8cd98f00b204e9800998ecf8427e
+- sha256(abc) = ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
+- sha256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+- sha512(abc) = ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f
+- sha512("") = cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
+- ripemd160(abc) = 8eb208f7e05d987a9b044a8e98c6b087f15a0bfc
+- ripemd160("") = 9c1185a5c5e9fc54612808977ee8f548b2258d31
+
+## 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.
--- a/web/documentation/external/pcre2.md
+++ b/web/documentation/external/pcre2.md
@ -0,0 +1,42 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - PCRE2 (Perl-Compatible Regex) extension (optional)
+subtitle: Documentation for PCRE2 (Perl-Compatible Regex) extension (optional)
+description: Documentation for PCRE2 (Perl-Compatible Regex) extension (optional)
+permalink: /documentation/external/pcre2/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# PCRE2 (Perl-Compatible Regex) extension (optional)
+
+- CMake option: FUN_WITH_PCRE2=ON
+- Purpose: Advanced regular expressions via PCRE2.
+- Homepage: https://www.pcre.org/
+
+## 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:
+
+- Requires PCRE2 development headers/libs.
+- Flags are backend-specific; see implementation for supported bits.
--- a/web/documentation/external/pcsc.md
+++ b/web/documentation/external/pcsc.md
@ -0,0 +1,45 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - PC/SC (smart cards) extension (optional)
+subtitle: Documentation for PC/SC (smart cards) extension (optional)
+description: Documentation for PC/SC (smart cards) extension (optional)
+permalink: /documentation/external/pcsc/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# PC/SC (smart cards) extension (optional)
+
+- CMake option: FUN_WITH_PCSC=ON
+- Purpose: Access smart card readers/cards via PC/SC (pcsclite).
+- Homepage: https://pcsclite.apdu.fr/
+
+## Opcodes:
+
+- OP_PCSC_ESTABLISH: returns context id (>0) or 0
+- OP_PCSC_RELEASE: pops ctx id; returns 1/0
+- OP_PCSC_LIST_READERS: pops ctx id; returns array of reader names
+- OP_PCSC_CONNECT: pops reader, ctx id; returns handle (>0) or 0
+- OP_PCSC_DISCONNECT: pops handle id; returns 1/0
+- OP_PCSC_TRANSMIT: pops apdu, handle id; returns map with data/SW/rc
+
+## Notes:
+
+- Requires PC/SC lite development headers/libs.
+- Behavior and availability depend on platform and reader drivers.
--- a/web/documentation/external/sqlite.md
+++ b/web/documentation/external/sqlite.md
@ -0,0 +1,43 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - SQLite extension (optional)
+subtitle: Documentation for SQLite extension (optional)
+description: Documentation for SQLite extension (optional)
+permalink: /documentation/external/sqlite/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# SQLite extension (optional)
+
+- CMake option: FUN_WITH_SQLITE=ON
+- Purpose: Access SQLite databases via the native C API.
+- Homepage: https://www.sqlite.org/
+
+## Opcodes:
+
+- OP_SQLITE_OPEN: pops path; pushes handle (>0) or 0
+- OP_SQLITE_CLOSE: pops handle; pushes Nil
+- OP_SQLITE_EXEC: pops sql, handle; pushes rc:int (0=OK)
+- OP_SQLITE_QUERY: pops sql, handle; pushes array<map>
+
+## Notes:
+
+- Requires SQLite development headers/libs.
+- See also: `libSQL` for a compatible alternative backend.
--- a/web/documentation/external/xml2.md
+++ b/web/documentation/external/xml2.md
@ -0,0 +1,43 @@
+---
+layout: page
+published: true
+noToc: true
+noComments: false
+noDate: false
+title: Fun - XML (libxml2) extension (optional)
+subtitle: Documentation for XML (libxml2) extension (optional)
+description: Documentation for XML (libxml2) extension (optional)
+permalink: /documentation/external/xml2/
+lang: en
+tags:
+- documentation
+- handbook
+- installation
+- usage
+- introduction
+- help
+- guide
+- howto
+- docs
+- specifications
+- specs
+- repl
+---
+
+# XML (libxml2) extension (optional)
+
+- CMake option: FUN_WITH_XML2=ON
+- Purpose: Minimal XML parsing helpers using libxml2.
+- Homepage: http://xmlsoft.org/
+
+## Opcodes:
+
+- OP_XML_PARSE: pops text; pushes doc handle (>0) or 0
+- OP_XML_ROOT: pops doc handle; pushes node handle (>0) or 0
+- OP_XML_NAME: pops node handle; pushes string (node name)
+- OP_XML_TEXT: pops node handle; pushes string (concatenated text)
+
+## Notes:
+
+- Requires libxml2 development headers/libs.
+- On many systems, the include path is `/usr/include/libxml2`.