From f7b066b374f1031d38e3d2b344f6680534c3a2b2 Mon Sep 17 00:00:00 2001 From: Udo Date: Wed, 22 Apr 2026 01:56:46 +0000 Subject: [PATCH] changing doc format and HTML literals --- site/doc/index.uce | 295 +++++++++++++---------- site/doc/pages/0_DTree.txt | 233 ++++++++++-------- site/doc/pages/0_Request.txt | 119 ++++----- site/doc/pages/1_COMPONENT.txt | 47 ++-- site/doc/pages/1_RENDER.txt | 26 +- site/doc/pages/1_WS.txt | 20 +- site/doc/pages/3_C++ Preprocessor.txt | 122 ++++++---- site/doc/pages/String.txt | 13 +- site/doc/pages/StringMap.txt | 44 ++-- site/doc/pages/array_merge.txt | 15 +- site/doc/pages/ascii_safe_name.txt | 17 +- site/doc/pages/basename.txt | 13 +- site/doc/pages/component.txt | 38 +-- site/doc/pages/component_exists.txt | 13 +- site/doc/pages/component_render.txt | 25 +- site/doc/pages/component_resolve.txt | 13 +- site/doc/pages/concat.txt | 13 +- site/doc/pages/contains.txt | 13 +- site/doc/pages/cwd_get.txt | 13 +- site/doc/pages/cwd_set.txt | 13 +- site/doc/pages/dirname.txt | 13 +- site/doc/pages/draw_float.txt | 15 +- site/doc/pages/draw_int.txt | 15 +- site/doc/pages/encode_query.txt | 13 +- site/doc/pages/expand_path.txt | 13 +- site/doc/pages/file_append.txt | 13 +- site/doc/pages/file_exists.txt | 13 +- site/doc/pages/file_get_contents.txt | 15 +- site/doc/pages/file_mtime.txt | 13 +- site/doc/pages/file_put_contents.txt | 13 +- site/doc/pages/file_unlink.txt | 13 +- site/doc/pages/filter.txt | 13 +- site/doc/pages/first.txt | 15 +- site/doc/pages/float_val.txt | 12 +- site/doc/pages/gen_float.txt | 14 +- site/doc/pages/gen_int.txt | 14 +- site/doc/pages/gen_noise01.txt | 13 +- site/doc/pages/gen_noise32.txt | 13 +- site/doc/pages/gen_noise64.txt | 13 +- site/doc/pages/gen_sha1.txt | 15 +- site/doc/pages/get_by_path.txt | 26 +- site/doc/pages/html_escape.txt | 20 +- site/doc/pages/int_val.txt | 12 +- site/doc/pages/join.txt | 15 +- site/doc/pages/json_decode.txt | 37 +-- site/doc/pages/json_encode.txt | 9 +- site/doc/pages/load.txt | 19 +- site/doc/pages/ls.txt | 15 +- site/doc/pages/markdown_to_ast.txt | 93 +++---- site/doc/pages/markdown_to_html.txt | 121 +++++----- site/doc/pages/memcache_command.txt | 15 +- site/doc/pages/memcache_connect.txt | 15 +- site/doc/pages/memcache_delete.txt | 15 +- site/doc/pages/memcache_get.txt | 15 +- site/doc/pages/memcache_get_multiple.txt | 15 +- site/doc/pages/memcache_set.txt | 15 +- site/doc/pages/mkdir.txt | 15 +- site/doc/pages/mysql_connect.txt | 15 +- site/doc/pages/mysql_disconnect.txt | 15 +- site/doc/pages/mysql_error.txt | 15 +- site/doc/pages/mysql_escape.txt | 15 +- site/doc/pages/mysql_insert_id.txt | 15 +- site/doc/pages/mysql_query.txt | 20 +- site/doc/pages/nibble.txt | 17 +- site/doc/pages/ob_close.txt | 15 +- site/doc/pages/ob_get.txt | 15 +- site/doc/pages/ob_get_close.txt | 16 +- site/doc/pages/ob_start.txt | 15 +- site/doc/pages/parse_query.txt | 15 +- site/doc/pages/path_join.txt | 17 +- site/doc/pages/print.txt | 15 +- site/doc/pages/redirect.txt | 17 +- site/doc/pages/replace.txt | 15 +- site/doc/pages/session_destroy.txt | 15 +- site/doc/pages/session_id_create.txt | 15 +- site/doc/pages/session_start.txt | 27 ++- site/doc/pages/set_status.txt | 17 +- site/doc/pages/shell_escape.txt | 15 +- site/doc/pages/shell_exec.txt | 15 +- site/doc/pages/socket_close.txt | 15 +- site/doc/pages/socket_connect.txt | 15 +- site/doc/pages/socket_read.txt | 15 +- site/doc/pages/socket_write.txt | 15 +- site/doc/pages/split.txt | 15 +- site/doc/pages/split_space.txt | 15 +- site/doc/pages/split_utf8.txt | 28 ++- site/doc/pages/str_ends_with.txt | 13 +- site/doc/pages/str_starts_with.txt | 13 +- site/doc/pages/strpos.txt | 13 +- site/doc/pages/substr.txt | 13 +- site/doc/pages/task.txt | 17 +- site/doc/pages/task_kill.txt | 19 +- site/doc/pages/task_pid.txt | 15 +- site/doc/pages/task_repeat.txt | 19 +- site/doc/pages/time.txt | 13 +- site/doc/pages/time_format_local.txt | 207 ++++++---------- site/doc/pages/time_format_relative.txt | 75 +++--- site/doc/pages/time_format_utc.txt | 207 ++++++---------- site/doc/pages/time_parse.txt | 13 +- site/doc/pages/time_precise.txt | 13 +- site/doc/pages/to_lower.txt | 17 +- site/doc/pages/to_upper.txt | 17 +- site/doc/pages/trim.txt | 13 +- site/doc/pages/unit_call.txt | 21 +- site/doc/pages/unit_compile.txt | 17 +- site/doc/pages/unit_info.txt | 17 +- site/doc/pages/unit_load.txt | 17 +- site/doc/pages/unit_render.txt | 18 +- site/doc/pages/units_list.txt | 17 +- site/doc/pages/uri_decode.txt | 13 +- site/doc/pages/uri_encode.txt | 13 +- site/doc/pages/var_dump.txt | 10 +- site/doc/pages/ws_close.txt | 13 +- site/doc/pages/ws_connection_count.txt | 13 +- site/doc/pages/ws_connection_id.txt | 13 +- site/doc/pages/ws_connections.txt | 13 +- site/doc/pages/ws_is_binary.txt | 13 +- site/doc/pages/ws_message.txt | 21 +- site/doc/pages/ws_opcode.txt | 13 +- site/doc/pages/ws_scope.txt | 13 +- site/doc/pages/ws_send.txt | 13 +- site/doc/pages/ws_send_to.txt | 13 +- site/doc/singlepage.uce | 228 +++++++++++------- 123 files changed, 1917 insertions(+), 1611 deletions(-) diff --git a/site/doc/index.uce b/site/doc/index.uce index 2072212..2331516 100644 --- a/site/doc/index.uce +++ b/site/doc/index.uce @@ -1,7 +1,132 @@ +struct DocPage { + String title; + String content; + StringList sig_lines; + StringList param_lines; + StringList see_lines; +}; + +String doc_default_title(String page) +{ + String page_title = page; + if(page_title.length() > 1 && page_title[1] == '_') + nibble(page_title, "_"); + return(page_title); +} + +String doc_markdown_inline(String text) +{ + text = trim(text); + if(text == "") + return(""); + String html = markdown_to_html(text); + if(html.length() >= 7 && html.substr(0, 3) == "

" && html.substr(html.length() - 4) == "

") + return(html.substr(3, html.length() - 7)); + return(html); +} + +String doc_legacy_heading(String section) +{ + if(section == "desc") + return(""); + if(section == "related") + return("## PHP & JS Equivalents"); + return("## " + section); +} + +DocPage load_doc_page(String page) +{ + DocPage result; + StringList lines = split(file_get_contents("pages/" + page + ".txt"), "\n"); + String current_section = ""; + bool content_mode = false; + StringList content_lines; + + for(auto line : lines) + { + if(!content_mode && line != "" && line.substr(0, 1) == ":") + { + String section = trim(line.substr(1)); + if(section == "title" || section == "sig" || section == "params" || section == "see") + { + current_section = section; + continue; + } + if(section == "content") + { + content_mode = true; + current_section = "content"; + continue; + } + + current_section = "legacy"; + String heading = doc_legacy_heading(section); + if(heading != "") + { + if(content_lines.size() > 0 && content_lines.back() != "") + content_lines.push_back(""); + content_lines.push_back(heading); + content_lines.push_back(""); + } + continue; + } + + if(current_section == "title") + { + if(result.title != "") + result.title += "\n"; + result.title += line; + } + else if(current_section == "sig") + { + result.sig_lines.push_back(line); + } + else if(current_section == "params") + { + result.param_lines.push_back(line); + } + else if(current_section == "see") + { + if(trim(line) != "") + result.see_lines.push_back(trim(line)); + } + else + { + content_lines.push_back(line); + } + } + + result.content = join(content_lines, "\n"); + result.title = trim(result.title); + return(result); +} + +void render_doc_params(StringList param_lines) +{ + if(param_lines.size() == 0) + return; + + <>
+

Parameters

:
+} void render_see_section(String name) { - StringList lines = split(file_get_contents("areas/"+name+".txt"), "\n"); + StringList lines = split(file_get_contents("areas/" + name + ".txt"), "\n"); s32 idx = 0; for(auto line : lines) { @@ -18,13 +143,40 @@ void render_see_section(String name) <> } +void render_doc_see_links(StringList see_lines) +{ + if(see_lines.size() == 0) + return; + + <>

Related

+ ') + { + render_see_section(sl.substr(1)); + } + else + { + ?>
()
+ +} + RENDER(Request& context) { - String page = first(context.get["p"], "index"); - String page_title = page; - nibble(page_title, "_"); + DocPage doc_page; + String page_title = doc_default_title(page); + if(page != "index") + { + doc_page = load_doc_page(page); + if(doc_page.title != "") + page_title = doc_page.title; + } <> @@ -143,135 +295,35 @@ RENDER(Request& context) } else { - auto doc = split(file_get_contents("pages/"+page+".txt"), "\n"); - - // Pre-extract sidebar-only sections so the article body stays focused. - StringList equiv_lines; - StringList see_lines; - String sidebar_section = ""; - for(auto s : doc) - { - if(s != "" && s.substr(0, 1) == ":") - { - sidebar_section = s.substr(1); - } - else if(sidebar_section == "related" && s != "") - { - equiv_lines.push_back(s); - } - else if(sidebar_section == "see" && s != "") - { - see_lines.push_back(s); - } - } - String detail_class = "detail-layout"; - if(equiv_lines.size() == 0 && see_lines.size() == 0) detail_class += " no-sidebar"; + if(doc_page.see_lines.size() == 0) + detail_class += " no-sidebar"; + ?>
0) { - line_idx++; - if(s == "") - { - - } - else if(s.substr(0, 1) == ":") - { - String new_class = s.substr(1); - - // Close previous section's div if it was rendered - if(line_idx > 1 && !section_hidden) - { - ?>

Parameters

Signature

Description

    • :
    +

    Signature

    +
    +
    0 && !section_hidden) + + render_doc_params(doc_page.param_lines); + + if(trim(doc_page.content) != "") { - ?>
    0 || see_lines.size() > 0) + if(doc_page.see_lines.size() > 0) { ?> - } diff --git a/site/doc/pages/0_DTree.txt b/site/doc/pages/0_DTree.txt index 75cf925..09929d7 100644 --- a/site/doc/pages/0_DTree.txt +++ b/site/doc/pages/0_DTree.txt @@ -1,111 +1,136 @@ -:sig +:title DTree -:desc -Dynamic tree/container type used throughout UCE for structured data. - -:Overview -`DTree` is UCE's general-purpose structured value type. - -This is the runtime's default container for nested data such as configuration trees, call payloads, decoded JSON, connection state, and metadata returned by runtime helpers. - -:Value Kinds -- `DTree` can hold: -- `String` -- `f64` -- `bool` -- pointer -- nested map of child `DTree` values (map-shaped `DTree` values can be used to represent list-like data when the keys are numeric strings in sequence) - -:Used in -`context.var` -`context.cfg` -`context.call` -`context.connection` -`json_decode()` results -`unit_call()` return values -`unit_info()` - -:Reading Values -`["key"]` accesses or creates a child node. -`.has("key")` checks whether a child exists without creating it. -`.key("key")` returns a child pointer when it already exists. -`.get_or_create("key")` returns a child pointer and creates it when missing. -`.get_by_path("a/b/c")` traverses nested children without creating missing keys. -`.to_string()` reads scalar content as text. -`.to_s64()`, `.to_u64()`, and `.to_f64()` perform best-effort numeric conversion. -`.to_bool()` performs best-effort boolean conversion. -`.to_stringmap()` converts a map-shaped tree into `StringMap`. - -`operator[]` creates missing entries, just like `std::map`. -`.has()` and `.key()` are the non-mutating lookup helpers. -`.get_by_path()` is the non-creating traversal helper. -`.json_decode()` currently stores JSON numbers as string-valued `DTree` nodes, so typed numeric conversion is the normal way to consume those values. -References are dereferenced automatically in most normal reads. - -:Conversion Rules -Scalar-looking strings are trimmed before numeric and boolean parsing. -`.to_bool()` understands common textual forms such as `true`, `false`, `yes`, `no`, `1`, and `0`. -`bool` values convert numerically to `1` / `0`. -Pointer values convert numerically when read as numbers. -Single-value maps can act as scalar wrappers for numeric and boolean conversion. -Invalid numeric input falls back to `0`. -`.to_stringmap()` converts map children key-by-key using each child's `to_string()`. - -:Writing Values -`.set(String)` -`.set(f64)` -`.set_bool(bool)` -`.set(StringMap)` -`.set_array()` -`.push(...)` -`.pop()` -`.remove(key)` -`.clear()` - -Use `.set_array()` when you want list-style behavior with `push()` / `pop()`. - -:Inspection Helpers -`.has(key)` -`.key(key)` -`.get_or_create(key)` -`.get_type_name()` -`.is_array()` -`.is_list()` -`.to_json()` - -:each() -`each(std::function f)` iterates over the current tree value. - -For map-shaped `DTree` values, the callback is invoked once for each child entry and receives: -`t` as the child value -`key` as the child key - -For non-map values, `each()` still invokes the callback once: -`t` is the current value -`key` is an empty string - -Typical usage: -`context.var["items"].each([&](DTree item, String key) { print(key, ": ", item.to_string(), "\n"); });` - -:Examples -`String theme = context.cfg.get_by_path("theme/key").to_string()` - -`u64 compiled_mtime = unit_info("test/hello.uce")["compiled_mtime"].to_u64()` - -`bool dark_mode = context.call["dark_mode"].to_bool()` - -`if(DTree* user = payload.key("user")) { print(user->to_json()); }` - -`payload.get_or_create("headers")->get_or_create("Content-Type")->set("text/plain")` - -`StringMap headers = payload["headers"].to_stringmap()` - -:related -**PHP:** Nested associative arrays, `stdClass`, decoded JSON trees, and helper accessors for deep array paths. -**JavaScript / Node.js:** Plain objects, arrays, `Map`, and JSON-shaped data passed between handlers. +:sig +DTree :see >types get_by_path json_decode + +:content +`DTree` is UCE's general-purpose structured value type. It is the runtime's default container for nested data such as configuration trees, call payloads, decoded JSON, connection state, and metadata returned by runtime helpers. + +## Value Kinds + +`DTree` can hold: + +- `String` +- `f64` +- `bool` +- pointer values +- nested child `DTree` values in a map-shaped container + +Map-shaped `DTree` values can also represent list-like data when their keys are numeric strings in sequence. + +## Where It Appears + +You will encounter `DTree` throughout the runtime, especially in: + +- `context.var` +- `context.cfg` +- `context.call` +- `context.connection` +- `json_decode()` results +- `unit_call()` return values +- `unit_info()` + +## Reading Values + +- `["key"]` accesses or creates a child node. +- `.has("key")` checks whether a child exists without creating it. +- `.key("key")` returns a child pointer when it already exists. +- `.get_or_create("key")` returns a child pointer and creates it when missing. +- `.get_by_path("a/b/c")` traverses nested children without creating missing keys. +- `.to_string()` reads scalar content as text. +- `.to_s64()`, `.to_u64()`, and `.to_f64()` perform best-effort numeric conversion. +- `.to_bool()` performs best-effort boolean conversion. +- `.to_stringmap()` converts a map-shaped tree into `StringMap`. + +`operator[]` creates missing entries, just like `std::map`. `.has()` and `.key()` are the non-mutating lookup helpers, and `.get_by_path()` is the non-creating traversal helper. + +`json_decode()` currently stores JSON numbers as string-valued `DTree` nodes, so typed numeric conversion is the normal way to consume those values. + +References are dereferenced automatically in most normal reads. + +## Conversion Rules + +- Scalar-looking strings are trimmed before numeric and boolean parsing. +- `.to_bool()` understands common textual forms such as `true`, `false`, `yes`, `no`, `1`, and `0`. +- `bool` values convert numerically to `1` and `0`. +- Pointer values convert numerically when read as numbers. +- Single-value maps can act as scalar wrappers for numeric and boolean conversion. +- Invalid numeric input falls back to `0`. +- `.to_stringmap()` converts map children key-by-key using each child's `to_string()`. + +## Writing Values + +Common mutating helpers include: + +- `.set(String)` +- `.set(f64)` +- `.set_bool(bool)` +- `.set(StringMap)` +- `.set_array()` +- `.push(...)` +- `.pop()` +- `.remove(key)` +- `.clear()` + +Use `.set_array()` when you want list-style behavior with `push()` and `pop()`. + +## Inspection Helpers + +Useful inspection helpers include: + +- `.has(key)` +- `.key(key)` +- `.get_or_create(key)` +- `.get_type_name()` +- `.is_array()` +- `.is_list()` +- `.to_json()` + +## each() + +`each(std::function f)` iterates over the current tree value. + +For map-shaped `DTree` values, the callback runs once per child entry and receives: + +- `t` as the child value +- `key` as the child key + +For non-map values, `each()` still invokes the callback once: + +- `t` is the current value +- `key` is an empty string + +```cpp +context.var["items"].each([&](DTree item, String key) { + print(key, ": ", item.to_string(), "\n"); +}); +``` + +## Examples + +```cpp +String theme = context.cfg.get_by_path("theme/key").to_string(); + +u64 compiled_mtime = unit_info("test/hello.uce")["compiled_mtime"].to_u64(); + +bool dark_mode = context.call["dark_mode"].to_bool(); + +if(DTree* user = payload.key("user")) { + print(user->to_json()); +} + +payload.get_or_create("headers")->get_or_create("Content-Type")->set("text/plain"); + +StringMap headers = payload["headers"].to_stringmap(); +``` + +## Related Concepts + +- PHP: nested associative arrays, `stdClass`, decoded JSON trees, and helper accessors for deep array paths +- JavaScript / Node.js: plain objects, arrays, `Map`, and JSON-shaped data passed between handlers diff --git a/site/doc/pages/0_Request.txt b/site/doc/pages/0_Request.txt index 3546717..ed678c0 100644 --- a/site/doc/pages/0_Request.txt +++ b/site/doc/pages/0_Request.txt @@ -1,75 +1,56 @@ +:title +Request + :sig Request& context; -:ServerState* server -Contains the current server state - -:StringMap params -All FastCGI server parameters - -:StringMap get -The current request's GET variables - -:StringMap post -The current request's POST variables - -:StringMap cookies -Cookies that have been transmitted by the browser - -:StringMap session -The current session - -:String session_id -ID of the session cookie - -:String session_name -Name of the session cookie - -:DTree var -Variable user-defined data - -:DTree cfg -Request-local configuration tree. Apps can keep structured configuration here and traverse it with `context.cfg.get_by_path("path/to/value")`. - -:DTree call -Invocation or message-local structured data - -:DTree connection -Broker-owned per-WebSocket-connection state. Inside `WS(Request& context)`, updates to this tree persist for the lifetime of that socket connection. - -:std::vector uploaded_files -Files that have been uploaded in the current request - -:StringMap header -Headers to be sent back to the browser - -:StringList set_cookies; -Cookies that should be sent back to the browser - -:context.set_status(s32 code[, String reason]) -Sets the HTTP status line and updates `context.flags.status`. When `reason` is omitted, UCE uses a built-in standard reason phrase for common status codes. - -:u64 random_seed -The current request's "random" noise generator seed - -:u64 random_index -The current request's "random" noise generator index position - -:bool flags.log_request -Whether the request should be logged - -:Stats - u32 stats.bytes_written - f64 stats.time_init - f64 stats.time_start - f64 stats.time_end - -:unit_render(String file_name, [Request& context]) -Invokes another UCE file using the current or supplied request context - :see >types -:related -**PHP:** `$_SERVER`, `$_GET`, `$_POST`, `$_COOKIE`, `$_SESSION`, `header()`, and `http_response_code()` -**JavaScript / Node.js:** Express `req` and `res`, Fetch `Request`, `Headers`, cookies or session middleware, and per-connection state in WebSocket handlers +:content +`Request& context` is the request-local state object passed into UCE handlers. It carries incoming request data, response state, runtime metadata, and helper trees such as `context.cfg`, `context.var`, and `context.call`. + +## Core Fields + +- `ServerState* server`: current server state +- `StringMap params`: FastCGI server parameters +- `StringMap get`: current request GET variables +- `StringMap post`: current request POST variables +- `StringMap cookies`: cookies sent by the browser +- `StringMap session`: current session data +- `String session_id`: session cookie ID +- `String session_name`: session cookie name +- `DTree var`: user-defined request-local data +- `DTree cfg`: request-local configuration tree +- `DTree call`: invocation or message-local structured data +- `DTree connection`: broker-owned WebSocket connection state that persists across `WS(Request& context)` calls for the same socket +- `std::vector uploaded_files`: files uploaded in the current request +- `StringMap header`: headers to send back to the browser +- `StringList set_cookies`: cookies queued for the response +- `u64 random_seed`: current request noise seed +- `u64 random_index`: current request noise index position + +## Response Control + +`context.set_status(s32 code[, String reason])` sets the HTTP status line and updates `context.flags.status`. When `reason` is omitted, UCE uses a built-in standard reason phrase for common status codes. + +## Flags And Stats + +- `bool flags.log_request`: controls whether the request should be logged +- `u32 stats.bytes_written` +- `f64 stats.time_init` +- `f64 stats.time_start` +- `f64 stats.time_end` + +## Common Usage Notes + +- `context.cfg` is the usual place for structured configuration. Use `context.cfg.get_by_path("path/to/value")` for deep reads. +- `context.call` carries invocation data for component calls, unit calls, and WebSocket messages. +- `context.connection` is only meaningful for WebSocket traffic and persists for the lifetime of the connection. + +`unit_render(String file_name, [Request& context])` invokes another UCE file using the current or supplied request context. + +## Related Concepts + +- PHP: `$_SERVER`, `$_GET`, `$_POST`, `$_COOKIE`, `$_SESSION`, `header()`, and `http_response_code()` +- JavaScript / Node.js: Express `req` and `res`, Fetch `Request`, `Headers`, cookies or session middleware, and per-connection state in WebSocket handlers diff --git a/site/doc/pages/1_COMPONENT.txt b/site/doc/pages/1_COMPONENT.txt index dcc284e..e191feb 100644 --- a/site/doc/pages/1_COMPONENT.txt +++ b/site/doc/pages/1_COMPONENT.txt @@ -1,10 +1,21 @@ +:title +COMPONENT + :sig COMPONENT(Request& context) -:desc +:see +>component +>component_render +>1_RENDER +>1_WS + +:content Defines the default component entrypoint for the current `.uce` file. -`component()` and `component_render()` invoke `COMPONENT(Request& context)` by default. Named component entrypoints use `COMPONENT:NAME(Request& context)`. +`component()` and `component_render()` call `COMPONENT(Request& context)` by default. Named component entrypoints use `COMPONENT:NAME(Request& context)`. + +## Why It Exists This keeps page rendering and component rendering separate: @@ -18,23 +29,21 @@ Inside component handlers, props arrive through `context.call`. When you call `component(":NAME", props, context)` or `component_render(":NAME", props, context)`, the runtime resolves `:NAME` against the current `.uce` file instead of requiring the file name again. -Examples: -`COMPONENT(Request& context)` -`{` -` <><section><?: component(":BODY", context.call, context) ?></section></>` -`}` +## Example -`COMPONENT:BODY(Request& context)` -`{` -` <><p><?= context.call["body"] ?></p></>` -`}` +```cpp +COMPONENT(Request& context) +{ + <>
    +} -:see ->component ->component_render ->1_RENDER ->1_WS +COMPONENT:BODY(Request& context) +{ + <>

    +} +``` -:related -**PHP:** View partials, reusable include files, small template helpers, and server-side component-like rendering patterns -**JavaScript / Node.js:** Reusable component functions, React or Vue components, and server-rendered partials +## Related Concepts + +- PHP: view partials, reusable include files, small template helpers, and server-side component-like rendering patterns +- JavaScript / Node.js: reusable component functions, React or Vue components, and server-rendered partials diff --git a/site/doc/pages/1_RENDER.txt b/site/doc/pages/1_RENDER.txt index 94c1b8a..5d12b69 100644 --- a/site/doc/pages/1_RENDER.txt +++ b/site/doc/pages/1_RENDER.txt @@ -1,11 +1,19 @@ +:title +RENDER + :sig RENDER(Request& context) -:desc +:see +>ob + +:content Defines the main HTTP render handler for the current `.uce` page. When a page is requested over HTTP, the runtime loads the target file and calls its `RENDER(Request& context)` function. +## Entry Point Behavior + The default page entrypoint is always the plain `RENDER(Request& context)` handler. Reusable component handlers now live on `COMPONENT(Request& context)` and `COMPONENT:NAME(Request& context)`. The component helpers call those handlers, not `RENDER()`. @@ -16,11 +24,15 @@ For a normal direct page request, `context.call` starts empty. If the page is invoked from another UCE file via `unit_render(file_name, context)`, the callee receives that same `context`. -Pages intended to serve WebSocket traffic may expose both `RENDER(Request& context)` and `WS(Request& context)`. Files may also define `COMPONENT()` handlers when they intentionally need both page and component behavior in one unit. In that case `RENDER(Request& context)` serves the direct HTTP response, `WS(Request& context)` handles subsequent WebSocket messages, and `COMPONENT()` remains available only through the component helpers. +Pages intended to serve WebSocket traffic may expose both `RENDER(Request& context)` and `WS(Request& context)`. Files may also define `COMPONENT()` handlers when they intentionally need both page and component behavior in one unit. -:see ->ob +In that case: -:related -**PHP:** Front controller entrypoints, template files, `include`, `require`, and route handlers that write the HTTP response -**JavaScript / Node.js:** Express or Fastify route handlers, page controller functions, and SSR entrypoints that build a response +- `RENDER(Request& context)` serves the direct HTTP response +- `WS(Request& context)` handles later WebSocket messages +- `COMPONENT()` remains available only through the component helpers + +## Related Concepts + +- PHP: front controller entrypoints, template files, `include`, `require`, and route handlers that write the HTTP response +- JavaScript / Node.js: Express or Fastify route handlers, page controller functions, and SSR entrypoints that build a response diff --git a/site/doc/pages/1_WS.txt b/site/doc/pages/1_WS.txt index 409f2a3..e9667b0 100644 --- a/site/doc/pages/1_WS.txt +++ b/site/doc/pages/1_WS.txt @@ -1,15 +1,25 @@ +:title +WS + :sig WS(Request& context) -:desc +:see +>websocket + +:content Defines the WebSocket message handler for the current `.ws.uce` page. The same page may expose both `RENDER(Request& context)` and `WS(Request& context)`. `RENDER(Request& context)` serves the initial HTTP response, while `WS(Request& context)` is called whenever a complete WebSocket message arrives for that page. UCE reassembles fragmented messages before calling `WS(Request& context)`. Text and binary frames are both delivered. Use `context.call`, `context.connection`, `ws_opcode()`, and `ws_is_binary()` to inspect the current message. +## Connection State + `context.connection` is a broker-owned `DTree` for the current socket. It starts empty for a new client and persists across later `WS(Request& context)` calls on that same connection. +## Message Data + The current message data is available in `context.call`: - `context.call["message"]`: current message payload @@ -18,9 +28,7 @@ The current message data is available in `context.call`: - `context.call["opcode"]`: WebSocket opcode of the current message - `context.call["document_uri"]`: request URI of the current endpoint -:related -**PHP:** Ratchet `onMessage`, Workerman WebSocket handlers, or lower-level callbacks around accepted socket connections. -**JavaScript / Node.js:** Browser `WebSocket` `message` handlers and Node `ws` server `connection` and `message` callbacks. +## Related Concepts -:see ->websocket +- PHP: Ratchet `onMessage`, Workerman WebSocket handlers, or lower-level callbacks around accepted socket connections +- JavaScript / Node.js: browser `WebSocket` `message` handlers and Node `ws` server `connection` and `message` callbacks diff --git a/site/doc/pages/3_C++ Preprocessor.txt b/site/doc/pages/3_C++ Preprocessor.txt index 4158b57..ac54af3 100644 --- a/site/doc/pages/3_C++ Preprocessor.txt +++ b/site/doc/pages/3_C++ Preprocessor.txt @@ -1,12 +1,23 @@ +:title +C++ Preprocessor + :sig UCE source preprocessing -:desc +:see +load +unit_render +unit_call +0_context +1_COMPONENT + +:content UCE runs a small custom source-to-source preprocessor before Clang sees a `.uce` or `.ws.uce` file. The implementation lives in `src/lib/compiler.cpp`. It does not try to parse all of C++. Instead, it performs a narrow character-wise rewrite that understands UCE literal blocks, inline code islands, `#load`, and `EXPORT` harvesting, then writes a generated `.cpp` file and compiles that file into a shared object. -:Syntax +## Syntax + - `<> ... ` enters literal-output mode. - Inside a literal block, `` emits raw C++. - Inside a literal block, `` emits `print(html_escape(expression));`. @@ -16,13 +27,14 @@ The implementation lives in `src/lib/compiler.cpp`. It does not try to parse all - `COMPONENT:NAME(Request& context)` is rewritten by the custom pass into an exported named component handler. - `EXPORT` is also a normal C++ macro, but the custom pass additionally records exported declarations for metadata. -:Pipeline +## Pipeline + - The generated file starts by including `COMPILER_SYS_PATH/src/lib/uce_lib.h`. - It then inlines the configured setup template from `SETUP_TEMPLATE` (by default `scripts/setup.h.template`), which defines the internal hook `__uce_set_current_request(Request*)`. - It inserts `#line 1` before page code so compiler diagnostics point back to the original `.uce` file. - Each literal block is rewritten into one or more `print(R"( ... )");` calls. - `` temporarily breaks out of literal printing, emits the enclosed C++ unchanged, then resumes literal output. -- `` becomes `print(html_escape(...));`. The runtime currently provides `html_escape()` overloads for `String`, `u64`, and `f64`. +- `` becomes `print(html_escape(...));`. - `` becomes `print(...);` and is intended for trusted markup or already-escaped content. - `#load "file.uce"` is replaced with a generated C++ `#include` that points at the loaded unit's preprocessed `.cpp` file under `BIN_DIRECTORY`. - Lines beginning with `EXPORT` are scanned so their declarations can be written to a sibling `.exports.txt` file. @@ -31,53 +43,74 @@ The implementation lives in `src/lib/compiler.cpp`. It does not try to parse all - The final generated source is written to `BIN_DIRECTORY + src_path + "/" + source_file + ".cpp"`. - `scripts/compile` then compiles that generated `.cpp` into `source_file + ".so"` with `clang++ -shared -std=c++20 ...`. -:GeneratedFiles -- Source file: `/some/path/page.uce` -- Generated C++: `BIN_DIRECTORY/some/path/page.uce.cpp` -- Shared object: `BIN_DIRECTORY/some/path/page.uce.so` -- Export list: `BIN_DIRECTORY/some/path/page.uce.exports.txt` +## Generated Files -:Example -Example 1: literal output with escaped data -`RENDER(Request& context)` -`{` -` <><h1><?= context.params["DOCUMENT_URI"] ?></h1></>` -`}` +For a source file like `/some/path/page.uce`, the preprocessor produces: + +- generated C++: `BIN_DIRECTORY/some/path/page.uce.cpp` +- shared object: `BIN_DIRECTORY/some/path/page.uce.so` +- export list: `BIN_DIRECTORY/some/path/page.uce.exports.txt` + +## Examples + +Literal output with escaped data: + +```cpp +RENDER(Request& context) +{ + <>

    +} +``` Roughly becomes: -`print(R"(<h1>)");` -`print(html_escape(context.params["DOCUMENT_URI"]));` -`print(R"(</h1>)");` -Example 1b: literal output with trusted unescaped markup -`RENDER(Request& context)` -`{` -` <><div class="panel"><?: component("components/card", context.call, context) ?></div></>` -`}` +```cpp +print(R"(

    )"); +print(html_escape(context.params["DOCUMENT_URI"])); +print(R"(

    )"); +``` + +Literal output with trusted unescaped markup: + +```cpp +RENDER(Request& context) +{ + <>
    +} +``` Roughly becomes: -`print(R"(<div class="panel">)");` -`print(component("components/card", context.call, context));` -`print(R"(</div>)");` -Example 2: compile-time composition -`#load "partials/nav.uce"` -`RENDER(Request& context)` -`{` -` <><body>...</body></>` -`}` +```cpp +print(R"(
    )"); +print(component("components/card", context.call, context)); +print(R"(
    )"); +``` + +Compile-time composition: + +```cpp +#load "partials/nav.uce" + +RENDER(Request& context) +{ + <>... +} +``` The loaded file is resolved relative to the current source file unless the path is already absolute. -:Rules +## Rules + - Literal mode starts only on the exact token `<>`. - Literal mode ends only on the exact token ``. - `#load` is recognized only when the current line starts with `#load ` at column 1. -- `EXPORT` harvesting likewise only triggers when the current line starts with `EXPORT` at column 1 and is followed by whitespace. +- `EXPORT` harvesting only triggers when the current line starts with `EXPORT` at column 1 and is followed by whitespace. - Relative `#load` paths are expanded against the including unit's source directory. -- `unit_render()` and `unit_call()` are runtime APIs; `#load` is a compile-time include/composition feature. +- `unit_render()` and `unit_call()` are runtime APIs. `#load` is a compile-time composition feature. + +## Limitations -:Limitations - This pass is character-wise, not a full parser. - Outside literal blocks it only tracks double-quoted C++ strings while deciding whether `<>` should open literal mode. - It does not understand comments, raw string literals, templates, or general C++ token structure. @@ -86,18 +119,13 @@ The loaded file is resolved relative to the current source file unless the path - Because literal output is emitted as a C++ raw string literal `R"( ... )"`, literal content must not contain the exact terminator sequence `)"` or the generated C++ will break. - `#load` depends on the target unit's generated `.cpp` existing and being compilable. If the target cannot be preprocessed or compiled correctly, the including file will fail to compile as well. -:Debugging -- When a page is compiled, inspect the generated file under `BIN_DIRECTORY` first. That file shows the exact C++ produced by the UCE preprocessor. +## Debugging + +- Inspect the generated file under `BIN_DIRECTORY` first. That file shows the exact C++ produced by the UCE preprocessor. - Compiler errors usually point back to the `.uce` source because the preprocessor inserts `#line 1`, but the generated `.cpp` is still the best place to inspect expansion problems. - If a `#load` include looks wrong, check the current file's directory, the configured `BIN_DIRECTORY`, and whether the loaded page already produced its own generated `.cpp`. -:see -load -unit_render -unit_call -0_context -1_COMPONENT +## Related Concepts -:related -**PHP:** Template tags like ``, ``, output buffering, and compile-time include patterns -**JavaScript / Node.js:** JSX transforms, tagged templates, server-side rendering pipelines, and build-time HTML generation +- PHP: template tags like ``, ``, output buffering, and compile-time include patterns +- JavaScript / Node.js: JSX transforms, tagged templates, server-side rendering pipelines, and build-time HTML generation diff --git a/site/doc/pages/String.txt b/site/doc/pages/String.txt index dd56fb8..c78d51c 100644 --- a/site/doc/pages/String.txt +++ b/site/doc/pages/String.txt @@ -1,7 +1,10 @@ :sig String -:desc +:see +>types + +:content Primary string type used throughout UCE. `String` is an alias for `std::string`. @@ -12,9 +15,7 @@ Because it is backed by `std::string`, it is binary-safe and may also contain ra For UTF-8-aware splitting, use helpers such as `split_utf8()` instead of assuming one byte equals one character. -:see ->types +## Related Concepts -:related -**PHP:** Native PHP strings with helpers such as `substr()`, `trim()`, `explode()`, and `implode()` -**JavaScript / Node.js:** JavaScript `string` values with methods such as `slice()`, `trim()`, `split()`, and `join()` +- PHP: native PHP strings with helpers such as `substr()`, `trim()`, `explode()`, and `implode()` +- JavaScript / Node.js: JavaScript `string` values with methods such as `slice()`, `trim()`, `split()`, and `join()` diff --git a/site/doc/pages/StringMap.txt b/site/doc/pages/StringMap.txt index fc6dd0b..fab05cb 100644 --- a/site/doc/pages/StringMap.txt +++ b/site/doc/pages/StringMap.txt @@ -1,26 +1,30 @@ :sig StringMap -:desc -Associative container mapping `String` keys to `String` values. - -`StringMap` is an alias for `std::map`. - -It is commonly used for: -`context.params` -`context.get` -`context.post` -`context.cookies` -`context.session` -`context.header` - -Because it uses `std::map`, `map["key"]` will create an empty entry when that key does not already exist. - -Related helpers such as `parse_query()` and `encode_query()` convert between query strings and `StringMap` values. - :see >types -:related -**PHP:** Associative arrays keyed by string, especially request bags like `$_GET` and `$_SERVER` -**JavaScript / Node.js:** Plain objects, dictionaries, `Map`, and header or query objects in web frameworks +:content +Associative container mapping `String` keys to `String` values. + +`StringMap` is an alias for `std::map`. + +## Common Uses + +`StringMap` commonly appears in: + +- `context.params` +- `context.get` +- `context.post` +- `context.cookies` +- `context.session` +- `context.header` + +Because it uses `std::map`, `map["key"]` will create an empty entry when that key does not already exist. + +Helpers such as `parse_query()` and `encode_query()` convert between query strings and `StringMap` values. + +## Related Concepts + +- PHP: associative arrays keyed by string, especially request bags like `$_GET` and `$_SERVER` +- JavaScript / Node.js: plain objects, dictionaries, `Map`, and header or query objects in web frameworks diff --git a/site/doc/pages/array_merge.txt b/site/doc/pages/array_merge.txt index c3407ec..035decc 100644 --- a/site/doc/pages/array_merge.txt +++ b/site/doc/pages/array_merge.txt @@ -7,18 +7,19 @@ a : left-hand source map or tree b : right-hand source map or tree return value : merged result -:desc +:see +>types + +:content Merges two maps or trees using PHP-like merge behavior. For `StringMap`, keys from `b` overwrite keys from `a`. For `DTree`, string keys from `b` overwrite keys from `a`. Numeric keys are appended and reindexed when either side behaves like a list. -This helper is intended as the closest UCE equivalent to PHP `array_merge()` for common request, config, and JSON-shaped data. +This helper is the closest UCE equivalent to PHP `array_merge()` for common request, config, and JSON-shaped data. -:see ->types +## Related Concepts -:related -**PHP:** `array_merge()` -**JavaScript / Node.js:** Object spread, `Object.assign()`, or array concatenation depending on whether the data is map-like or list-like \ No newline at end of file +- PHP: `array_merge()` +- JavaScript / Node.js: object spread, `Object.assign()`, or array concatenation depending on whether the data is map-like or list-like diff --git a/site/doc/pages/ascii_safe_name.txt b/site/doc/pages/ascii_safe_name.txt index fe10e89..59730ee 100644 --- a/site/doc/pages/ascii_safe_name.txt +++ b/site/doc/pages/ascii_safe_name.txt @@ -5,14 +5,15 @@ String ascii_safe_name(String raw) raw : input string to normalize return value : ASCII-safe identifier made from letters, digits, and underscores -:desc -Builds a conservative identifier by keeping ASCII letters, digits, and underscores and dropping other characters. - -This is useful when turning user- or config-provided names into handler suffixes, DOM-safe variable stems, or CSS/JS hook names. - :see >string -:related -**PHP:** Slug or safe-filename helpers built with `preg_replace()` and transliteration utilities -**JavaScript / Node.js:** Regex-based slugify or safe-name helpers used for URLs and filenames +:content +Builds a conservative identifier by keeping ASCII letters, digits, and underscores and dropping other characters. + +This is useful when turning user- or config-provided names into handler suffixes, DOM-safe variable stems, or CSS and JS hook names. + +## Related Concepts + +- PHP: slug or safe-filename helpers built with `preg_replace()` and transliteration utilities +- JavaScript / Node.js: regex-based slugify or safe-name helpers used for URLs and filenames diff --git a/site/doc/pages/basename.txt b/site/doc/pages/basename.txt index b7c6fa6..cbaaeea 100644 --- a/site/doc/pages/basename.txt +++ b/site/doc/pages/basename.txt @@ -5,12 +5,13 @@ String basename(String fn) fn : raw filename return value : the file's name -:desc -Isolates the file name component from a path/file name. - :see >sys -:related -**PHP:** `basename()` -**JavaScript / Node.js:** Node `path.basename()` +:content +Isolates the file name component from a path or file name. + +## Related Concepts + +- PHP: `basename()` +- JavaScript / Node.js: Node `path.basename()` diff --git a/site/doc/pages/component.txt b/site/doc/pages/component.txt index b7bab63..142805e 100644 --- a/site/doc/pages/component.txt +++ b/site/doc/pages/component.txt @@ -1,34 +1,42 @@ :sig String component(String name, [DTree props], [Request& context]) -:desc +:see +>ob + +:content Renders another `.uce` file as a component and returns the captured output as a `String`. -`component()` resolves the target file relative to the current page and also tries the `components/` prefix automatically, mirroring the shorthand used by the web app starter example project. +`component()` resolves the target file relative to the current page and also tries the `components/` prefix automatically, mirroring the shorthand used by the starter example project. Component props are passed in `context.call`. Because `` HTML-escapes its value, embed component markup with ``, `print(component(...))`, or use `component_render(...)` for direct output. +## Named Components + When `name` contains a colon, such as `components/card:BODY`, the part after the colon selects a named component handler exported from the component file through `COMPONENT:BODY(Request& context)`. The default handler is `COMPONENT(Request& context)`. When `name` starts with a colon, such as `:BODY`, the target resolves against the current `.uce` file so component files can call their own named handlers without repeating the file name. -Resolution order is: -exact file name -exact file name with `.uce` -the same two forms under `components/` +## Resolution Order -Example: -`DTree props;` -`props["title"] = "Status";` -`<><?: component("workspace/panel", props, context) ?></>` +- exact file name +- exact file name with `.uce` +- the same two forms under `components/` -:see ->ob +## Example -:related -**PHP:** Reusable template partials or helper-rendered view fragments returned as strings -**JavaScript / Node.js:** Component render helpers, especially patterns that return markup as a string +```cpp +DTree props; +props["title"] = "Status"; + +<> +``` + +## Related Concepts + +- PHP: reusable template partials or helper-rendered view fragments returned as strings +- JavaScript / Node.js: component render helpers, especially patterns that return markup as a string diff --git a/site/doc/pages/component_exists.txt b/site/doc/pages/component_exists.txt index 7cc6429..968c59d 100644 --- a/site/doc/pages/component_exists.txt +++ b/site/doc/pages/component_exists.txt @@ -1,7 +1,10 @@ :sig bool component_exists(String name) -:desc +:see +>ob + +:content Checks whether a component file can be resolved from the current page context. Resolution tries the exact name first and then the `components/` shorthand form. @@ -10,9 +13,7 @@ If `name` contains a colon, only the file portion is used for existence checks. This is useful when a page wants to render an optional component if it is present without hard-failing when it is missing. -:see ->ob +## Related Concepts -:related -**PHP:** `function_exists()`, `class_exists()`, or file-existence checks before including a partial -**JavaScript / Node.js:** Module existence checks, dynamic import guards, or registry lookups for named components +- PHP: `function_exists()`, `class_exists()`, or file-existence checks before including a partial +- JavaScript / Node.js: module existence checks, dynamic import guards, or registry lookups for named components diff --git a/site/doc/pages/component_render.txt b/site/doc/pages/component_render.txt index 1f0930b..58356c6 100644 --- a/site/doc/pages/component_render.txt +++ b/site/doc/pages/component_render.txt @@ -1,7 +1,10 @@ :sig void component_render(String name, [DTree props], [Request& context]) -:desc +:see +>ob + +:content Renders another `.uce` file as a component and writes the result directly to the current output buffer. This is the direct-output counterpart to `component()`. @@ -12,14 +15,16 @@ When `name` starts with `:`, the runtime resolves that named handler against the Use `component_render()` when you want to write component output directly from C++ code instead of capturing it as a `String`. -Example: -`DTree props;` -`props["body"] = "Hello";` -`component_render("components/card:BODY", props, context);` +## Example -:see ->ob +```cpp +DTree props; +props["body"] = "Hello"; -:related -**PHP:** Rendering a partial directly into the current output buffer rather than returning a string -**JavaScript / Node.js:** Direct `res.write()`-style partial rendering or imperative component mount helpers +component_render("components/card:BODY", props, context); +``` + +## Related Concepts + +- PHP: rendering a partial directly into the current output buffer rather than returning a string +- JavaScript / Node.js: direct `res.write()`-style partial rendering or imperative component mount helpers diff --git a/site/doc/pages/component_resolve.txt b/site/doc/pages/component_resolve.txt index bc3bc71..32bad2f 100644 --- a/site/doc/pages/component_resolve.txt +++ b/site/doc/pages/component_resolve.txt @@ -1,7 +1,10 @@ :sig String component_resolve(String name) -:desc +:see +>ob + +:content Resolves a component name to the concrete `.uce` file path that will be loaded. Resolution tries the exact file name first, then the same name with `.uce` appended, and then the same two forms under the `components/` prefix. @@ -10,9 +13,7 @@ If `name` contains a colon, only the file portion is used for resolution. This is primarily a debugging helper so you can see which concrete file a shorthand component name maps to. -:see ->ob +## Related Concepts -:related -**PHP:** Resolving include paths or view names to a concrete template file before rendering -**JavaScript / Node.js:** Resolving module paths, alias-based imports, or component registry entries +- PHP: resolving include paths or view names to a concrete template file before rendering +- JavaScript / Node.js: resolving module paths, alias-based imports, or component registry entries diff --git a/site/doc/pages/concat.txt b/site/doc/pages/concat.txt index 7fba11a..21ec4b3 100644 --- a/site/doc/pages/concat.txt +++ b/site/doc/pages/concat.txt @@ -4,12 +4,13 @@ String concat(...vals) :params ...val : one or more values that should be concatenated -:desc -Returns a string with all the parameters concatenated into one. - :see >string -:related -**PHP:** String concatenation with `.` or helpers like `implode()` -**JavaScript / Node.js:** String concatenation with `+`, template literals, or `Array.prototype.join()` +:content +Returns a string with all parameters concatenated into one result. + +## Related Concepts + +- PHP: string concatenation with `.` or helpers like `implode()` +- JavaScript / Node.js: string concatenation with `+`, template literals, or `Array.prototype.join()` diff --git a/site/doc/pages/contains.txt b/site/doc/pages/contains.txt index dc00be6..5829c12 100644 --- a/site/doc/pages/contains.txt +++ b/site/doc/pages/contains.txt @@ -6,14 +6,15 @@ haystack : string to search in needle : substring to look for return value : `true` when `needle` appears in `haystack`, otherwise `false` -:desc +:see +>string + +:content Returns whether `haystack` contains `needle`. An empty `needle` always returns `true`. -:see ->string +## Related Concepts -:related -**PHP:** `str_contains()` -**JavaScript / Node.js:** `String.prototype.includes()` \ No newline at end of file +- PHP: `str_contains()` +- JavaScript / Node.js: `String.prototype.includes()` diff --git a/site/doc/pages/cwd_get.txt b/site/doc/pages/cwd_get.txt index 4ee8fe4..9dc8906 100644 --- a/site/doc/pages/cwd_get.txt +++ b/site/doc/pages/cwd_get.txt @@ -4,12 +4,13 @@ String cwd_get() :params return value : the current working directory -:desc -Returns the current working directory. - :see >sys -:related -**PHP:** `getcwd()` -**JavaScript / Node.js:** Node `process.cwd()` +:content +Returns the current working directory. + +## Related Concepts + +- PHP: `getcwd()` +- JavaScript / Node.js: Node `process.cwd()` diff --git a/site/doc/pages/cwd_set.txt b/site/doc/pages/cwd_set.txt index a36f7cc..bbec0f4 100644 --- a/site/doc/pages/cwd_set.txt +++ b/site/doc/pages/cwd_set.txt @@ -4,12 +4,13 @@ void cwd_set(String path) :params path : the new working directory -:desc -Sets a new working directory. - :see >sys -:related -**PHP:** `chdir()` -**JavaScript / Node.js:** Node `process.chdir()` +:content +Sets a new working directory. + +## Related Concepts + +- PHP: `chdir()` +- JavaScript / Node.js: Node `process.chdir()` diff --git a/site/doc/pages/dirname.txt b/site/doc/pages/dirname.txt index f171668..a956711 100644 --- a/site/doc/pages/dirname.txt +++ b/site/doc/pages/dirname.txt @@ -5,12 +5,13 @@ String dirname(String fn) fn : raw filename return value : the directory's name -:desc -Isolates the directory name component from a path/file name. - :see >sys -:related -**PHP:** `dirname()` -**JavaScript / Node.js:** Node `path.dirname()` +:content +Isolates the directory component from a path or file name. + +## Related Concepts + +- PHP: `dirname()` +- JavaScript / Node.js: Node `path.dirname()` diff --git a/site/doc/pages/draw_float.txt b/site/doc/pages/draw_float.txt index 64fb453..ca06ffc 100644 --- a/site/doc/pages/draw_float.txt +++ b/site/doc/pages/draw_float.txt @@ -6,12 +6,15 @@ from : minimum value to : maximum value return value : a noise value between 'from' and 'to' -:desc -This function works exactly like generate_float(), but context.random_index is used for the 'index' value and context.random_seed is used for the seed. After this function has been called, the context.random_index is increased by one. At the start of every request, context.random_seed is automatically populated with a new seed value. - :see >noise -:related -**PHP:** `random_int()`, `mt_rand()`, and custom numeric random helpers -**JavaScript / Node.js:** `Math.random()` or `crypto.getRandomValues()`-based helpers for numeric ranges +:content +Works like `generate_float()`, but uses `context.random_index` for the index value and `context.random_seed` for the seed. + +After each call, `context.random_index` is increased by one. At the start of every request, `context.random_seed` is automatically populated with a new seed value. + +## Related Concepts + +- PHP: `random_int()`, `mt_rand()`, and custom numeric random helpers +- JavaScript / Node.js: `Math.random()` or `crypto.getRandomValues()`-based helpers for numeric ranges diff --git a/site/doc/pages/draw_int.txt b/site/doc/pages/draw_int.txt index 412b476..9d3cb1b 100644 --- a/site/doc/pages/draw_int.txt +++ b/site/doc/pages/draw_int.txt @@ -6,12 +6,15 @@ from : minimum value to : maximum value return value : a noise value between 'from' and 'to' -:desc -This function works exactly like generate_int(), but context.random_index is used for the 'index' value and context.random_seed is used for the seed. After this function has been called, the context.random_index is increased by one. At the start of every request, context.random_seed is automatically populated with a new seed value. - :see >noise -:related -**PHP:** `random_int()`, `mt_rand()`, and custom numeric random helpers -**JavaScript / Node.js:** `Math.random()` or `crypto.getRandomValues()`-based helpers for numeric ranges +:content +Works like `generate_int()`, but uses `context.random_index` for the index value and `context.random_seed` for the seed. + +After each call, `context.random_index` is increased by one. At the start of every request, `context.random_seed` is automatically populated with a new seed value. + +## Related Concepts + +- PHP: `random_int()`, `mt_rand()`, and custom numeric random helpers +- JavaScript / Node.js: `Math.random()` or `crypto.getRandomValues()`-based helpers for numeric ranges diff --git a/site/doc/pages/encode_query.txt b/site/doc/pages/encode_query.txt index 921d012..98bb6e4 100644 --- a/site/doc/pages/encode_query.txt +++ b/site/doc/pages/encode_query.txt @@ -5,12 +5,13 @@ String encode_query(StringMap map) q : StringMap containing URL parameters to be encoded return value : a string with the encoded parameters -:desc -Encodes a StringMap containing URL parameters into a single String. - :see >uri -:related -**PHP:** `http_build_query()` -**JavaScript / Node.js:** `URLSearchParams` and `toString()` +:content +Encodes a `StringMap` of URL parameters into a single query-string `String`. + +## Related Concepts + +- PHP: `http_build_query()` +- JavaScript / Node.js: `URLSearchParams` and `toString()` diff --git a/site/doc/pages/expand_path.txt b/site/doc/pages/expand_path.txt index a1b1dd2..f00ece3 100644 --- a/site/doc/pages/expand_path.txt +++ b/site/doc/pages/expand_path.txt @@ -6,12 +6,13 @@ path : a relative path relative_to_path : optional, expand relative to this path (if not given, the current path is used) return value : expanded version of the 'path' -:desc -Converts a relative path name into an absolute path, using the current working directory as a base. - :see >sys -:related -**PHP:** `realpath()` and application-specific path normalization helpers -**JavaScript / Node.js:** Node `path.resolve()` and `path.normalize()` +:content +Converts a relative path name into an absolute path, using the current working directory as a base when `relative_to_path` is not provided. + +## Related Concepts + +- PHP: `realpath()` and application-specific path normalization helpers +- JavaScript / Node.js: Node `path.resolve()` and `path.normalize()` diff --git a/site/doc/pages/file_append.txt b/site/doc/pages/file_append.txt index f1b9759..f28569a 100644 --- a/site/doc/pages/file_append.txt +++ b/site/doc/pages/file_append.txt @@ -5,12 +5,13 @@ void file_append(String file_name, ...val) file_name : file name of file that should be written to ...val : one or more values that should be written into the file -:desc -Opens or creates a given file and appends data to it. - :see >sys -:related -**PHP:** `file_put_contents($file, $data, FILE_APPEND)` -**JavaScript / Node.js:** Node `fs.appendFileSync()` or `fs.promises.appendFile()` +:content +Opens or creates a file and appends data to it. + +## Related Concepts + +- PHP: `file_put_contents($file, $data, FILE_APPEND)` +- JavaScript / Node.js: Node `fs.appendFileSync()` or `fs.promises.appendFile()` diff --git a/site/doc/pages/file_exists.txt b/site/doc/pages/file_exists.txt index 2aad107..ab81264 100644 --- a/site/doc/pages/file_exists.txt +++ b/site/doc/pages/file_exists.txt @@ -5,12 +5,13 @@ bool file_exists(String path) path : the path name to be checked return value : true if the file exists -:desc -Checks whether the file or path specified by 'path' exists. - :see >sys -:related -**PHP:** `file_exists()` or `is_file()` -**JavaScript / Node.js:** Node `fs.existsSync()` or `fs.stat()` +:content +Checks whether the file or path specified by `path` exists. + +## Related Concepts + +- PHP: `file_exists()` or `is_file()` +- JavaScript / Node.js: Node `fs.existsSync()` or `fs.stat()` diff --git a/site/doc/pages/file_get_contents.txt b/site/doc/pages/file_get_contents.txt index b221b7f..c35694b 100644 --- a/site/doc/pages/file_get_contents.txt +++ b/site/doc/pages/file_get_contents.txt @@ -5,12 +5,15 @@ String file_get_contents(String file_name) file_name : file name of file that should be read return value : String containing the file's contents -:desc -Reads the file identified by 'file_name' and returns it as a String. If the file cannot be read, this function will return an empty string. - :see >sys -:related -**PHP:** `file_get_contents()` -**JavaScript / Node.js:** Node `fs.readFileSync()` or `fs.promises.readFile()` +:content +Reads the file identified by `file_name` and returns it as a `String`. + +If the file cannot be read, this function returns an empty string. + +## Related Concepts + +- PHP: `file_get_contents()` +- JavaScript / Node.js: Node `fs.readFileSync()` or `fs.promises.readFile()` diff --git a/site/doc/pages/file_mtime.txt b/site/doc/pages/file_mtime.txt index 1e3df7d..98d0adc 100644 --- a/site/doc/pages/file_mtime.txt +++ b/site/doc/pages/file_mtime.txt @@ -5,13 +5,14 @@ time_t file_mtime(String file_name) file_name : name of the file return value : Unix time stamp of the file's last modification -:desc -Retrieves the last modification date of 'file_name' as a Unix timestamp. - :see >sys >time -:related -**PHP:** `filemtime()` -**JavaScript / Node.js:** Node `fs.statSync().mtimeMs` or `fs.promises.stat()` +:content +Retrieves the last modification date of `file_name` as a Unix timestamp. + +## Related Concepts + +- PHP: `filemtime()` +- JavaScript / Node.js: Node `fs.statSync().mtimeMs` or `fs.promises.stat()` diff --git a/site/doc/pages/file_put_contents.txt b/site/doc/pages/file_put_contents.txt index f6e9d55..ebc2240 100644 --- a/site/doc/pages/file_put_contents.txt +++ b/site/doc/pages/file_put_contents.txt @@ -6,12 +6,13 @@ file_name : file name of file that should be written content : content that should be written return value : true if write was successful -:desc -Writes the String 'content' into a file identified by 'file_name'. Any pre-existing content of the file will be overwritten. - :see >sys -:related -**PHP:** `file_put_contents()` -**JavaScript / Node.js:** Node `fs.writeFileSync()` or `fs.promises.writeFile()` +:content +Writes `content` into the file identified by `file_name`, overwriting any pre-existing content. + +## Related Concepts + +- PHP: `file_put_contents()` +- JavaScript / Node.js: Node `fs.writeFileSync()` or `fs.promises.writeFile()` diff --git a/site/doc/pages/file_unlink.txt b/site/doc/pages/file_unlink.txt index 10c1dbf..689c307 100644 --- a/site/doc/pages/file_unlink.txt +++ b/site/doc/pages/file_unlink.txt @@ -4,12 +4,13 @@ void file_unlink(String file_name) :params file_name : name of the file -:desc -Deletes the file identified by `file_name`. - :see >sys -:related -**PHP:** `unlink()` -**JavaScript / Node.js:** Node `fs.unlinkSync()` or `fs.promises.unlink()` +:content +Deletes the file identified by `file_name`. + +## Related Concepts + +- PHP: `unlink()` +- JavaScript / Node.js: Node `fs.unlinkSync()` or `fs.promises.unlink()` diff --git a/site/doc/pages/filter.txt b/site/doc/pages/filter.txt index 4113f7e..873fc8e 100644 --- a/site/doc/pages/filter.txt +++ b/site/doc/pages/filter.txt @@ -7,12 +7,13 @@ items : list of items to be filtered f : a function that decides which items should be in the new list return value : a new list -:desc -Returns a list containing the members of 'items' for which 'f' returned boolean true. - :see >string -:related -**PHP:** `array_filter()` for arrays or custom predicate-based filtering over strings and collections -**JavaScript / Node.js:** `Array.prototype.filter()` and custom predicate helpers +:content +Returns a new list containing the members of `items` for which `f` returned `true`. + +## Related Concepts + +- PHP: `array_filter()` for arrays or custom predicate-based filtering over strings and collections +- JavaScript / Node.js: `Array.prototype.filter()` and custom predicate helpers diff --git a/site/doc/pages/first.txt b/site/doc/pages/first.txt index 9126e66..b34a31b 100644 --- a/site/doc/pages/first.txt +++ b/site/doc/pages/first.txt @@ -5,12 +5,15 @@ String first(String... args) args : a variable number of String arguments return value : first of the 'args' that was not empty. -:desc -Given a variable number of String parameters, the first() function returns the first of these parameters that was not empty. Leading and trailing whitespace characters are not considered, resulting in a string that contains only whitespace characters being considered empty. - :see >string -:related -**PHP:** Null-coalescing patterns like `$a ?? $b`, fallback helpers, or `reset()` for arrays -**JavaScript / Node.js:** `??`, `||`, and small fallback helper functions +:content +Returns the first non-empty string from the provided arguments. + +Leading and trailing whitespace are ignored when checking emptiness, so a string containing only whitespace counts as empty. + +## Related Concepts + +- PHP: null-coalescing patterns like `$a ?? $b`, fallback helpers, or `reset()` for arrays +- JavaScript / Node.js: `??`, `||`, and small fallback helper functions diff --git a/site/doc/pages/float_val.txt b/site/doc/pages/float_val.txt index b2d76c0..d644650 100644 --- a/site/doc/pages/float_val.txt +++ b/site/doc/pages/float_val.txt @@ -5,10 +5,12 @@ f64 float_val(String s) s : string to be converted return value : a f64 containing the number (0 if no number could be identified). -:desc -Extracts a floating point number from a String. +:content +Extracts a floating point number from a `String`. +If no usable number can be identified, the result is `0`. -:related -**PHP:** `floatval()` -**JavaScript / Node.js:** `Number()` or `parseFloat()` +## Related Concepts + +- PHP: `floatval()` +- JavaScript / Node.js: `Number()` or `parseFloat()` diff --git a/site/doc/pages/gen_float.txt b/site/doc/pages/gen_float.txt index 42ea599..5a8eef5 100644 --- a/site/doc/pages/gen_float.txt +++ b/site/doc/pages/gen_float.txt @@ -8,13 +8,13 @@ index : index position to generate number from seed : seed position to generate number from (defaults to 0) return value : noise value -:desc -Generates a noise value between 'from' and 'to', given the 'index' and 'seed' numbers. - - :see >noise -:related -**PHP:** `random_int()`, `mt_rand()`, and custom numeric random helpers -**JavaScript / Node.js:** `Math.random()` or `crypto.getRandomValues()`-based helpers for numeric ranges +:content +Generates a deterministic noise value between `from` and `to` for the given `index` and `seed`. + +## Related Concepts + +- PHP: `random_int()`, `mt_rand()`, and custom numeric random helpers +- JavaScript / Node.js: `Math.random()` or `crypto.getRandomValues()`-based helpers for numeric ranges diff --git a/site/doc/pages/gen_int.txt b/site/doc/pages/gen_int.txt index 1a0aa54..e56f0ed 100644 --- a/site/doc/pages/gen_int.txt +++ b/site/doc/pages/gen_int.txt @@ -8,13 +8,13 @@ index : index position to generate number from seed : seed position to generate number from (defaults to 0) return value : noise value -:desc -Generates a noise value between 'from' and 'to', given the 'index' and 'seed' numbers. - - :see >noise -:related -**PHP:** `random_int()`, `mt_rand()`, and custom numeric random helpers -**JavaScript / Node.js:** `Math.random()` or `crypto.getRandomValues()`-based helpers for numeric ranges +:content +Generates a deterministic noise value between `from` and `to` for the given `index` and `seed`. + +## Related Concepts + +- PHP: `random_int()`, `mt_rand()`, and custom numeric random helpers +- JavaScript / Node.js: `Math.random()` or `crypto.getRandomValues()`-based helpers for numeric ranges diff --git a/site/doc/pages/gen_noise01.txt b/site/doc/pages/gen_noise01.txt index a828fc1..7ff2fed 100644 --- a/site/doc/pages/gen_noise01.txt +++ b/site/doc/pages/gen_noise01.txt @@ -6,12 +6,13 @@ index : index position seed : seed set (defaults to 0) return value : a noise value from 0 to 1 -:desc -Generates a noise value in the range from 0 to 1 for the given 'index' and 'seed' values. - :see >noise -:related -**PHP:** There is no built-in PHP equivalent; this is closest to userland noise or deterministic pseudo-random helpers -**JavaScript / Node.js:** There is no built-in browser equivalent; closest matches are userland noise libraries or deterministic PRNG helpers +:content +Generates a deterministic noise value in the range from `0` to `1` for the given `index` and `seed`. + +## Related Concepts + +- PHP: no built-in equivalent; closest matches are userland noise or deterministic pseudo-random helpers +- JavaScript / Node.js: no built-in browser equivalent; closest matches are userland noise libraries or deterministic PRNG helpers diff --git a/site/doc/pages/gen_noise32.txt b/site/doc/pages/gen_noise32.txt index 021ea5a..9e014cb 100644 --- a/site/doc/pages/gen_noise32.txt +++ b/site/doc/pages/gen_noise32.txt @@ -6,12 +6,13 @@ index : index position seed : seed set (defaults to 0) return value : a noise value given the 'index' and 'seed' values. -:desc -Generates a noise value for the given 'index' and 'seed' values. - :see >noise -:related -**PHP:** There is no built-in PHP equivalent; this is closest to userland noise or deterministic pseudo-random helpers -**JavaScript / Node.js:** There is no built-in browser equivalent; closest matches are userland noise libraries or deterministic PRNG helpers +:content +Generates a deterministic 32-bit noise value for the given `index` and `seed`. + +## Related Concepts + +- PHP: no built-in equivalent; closest matches are userland noise or deterministic pseudo-random helpers +- JavaScript / Node.js: no built-in browser equivalent; closest matches are userland noise libraries or deterministic PRNG helpers diff --git a/site/doc/pages/gen_noise64.txt b/site/doc/pages/gen_noise64.txt index c8c1757..4454f66 100644 --- a/site/doc/pages/gen_noise64.txt +++ b/site/doc/pages/gen_noise64.txt @@ -6,12 +6,13 @@ index : index position seed : seed set (defaults to 0) return value : a noise value given the 'index' and 'seed' values. -:desc -Generates a noise value for the given 'index' and 'seed' values. - :see >noise -:related -**PHP:** There is no built-in PHP equivalent; this is closest to userland noise or deterministic pseudo-random helpers -**JavaScript / Node.js:** There is no built-in browser equivalent; closest matches are userland noise libraries or deterministic PRNG helpers +:content +Generates a deterministic 64-bit-indexed noise value for the given `index` and `seed`. + +## Related Concepts + +- PHP: no built-in equivalent; closest matches are userland noise or deterministic pseudo-random helpers +- JavaScript / Node.js: no built-in browser equivalent; closest matches are userland noise libraries or deterministic PRNG helpers diff --git a/site/doc/pages/gen_sha1.txt b/site/doc/pages/gen_sha1.txt index 0fb414c..0b8c333 100644 --- a/site/doc/pages/gen_sha1.txt +++ b/site/doc/pages/gen_sha1.txt @@ -6,12 +6,15 @@ s : data to be hashed as_binary : when set to false, returns hash in hexadecimal notation (defaults to false) return value : the resulting hash value -:desc -Returns the sha1 hash of 's'. - :see >noise -:related -**PHP:** `sha1()` -**JavaScript / Node.js:** Node `crypto.createHash("sha1")` or browser `SubtleCrypto` wrappers +:content +Returns the SHA-1 hash of `s`. + +When `as_binary` is `false`, the hash is returned as hexadecimal text. When it is `true`, the raw binary hash bytes are returned. + +## Related Concepts + +- PHP: `sha1()` +- JavaScript / Node.js: Node `crypto.createHash("sha1")` or browser `SubtleCrypto` wrappers diff --git a/site/doc/pages/get_by_path.txt b/site/doc/pages/get_by_path.txt index ceb941a..ad7d982 100644 --- a/site/doc/pages/get_by_path.txt +++ b/site/doc/pages/get_by_path.txt @@ -6,19 +6,23 @@ path : slash-delimited path to traverse delim : optional path separator return value : the resolved child node, or an empty `DTree` when the path cannot be followed -:desc -Traverses a nested `DTree` without creating missing keys. - -Empty path segments are ignored, so leading and trailing `/` characters are harmless. If any intermediate node is not a map or a segment is missing, `get_by_path()` returns an empty `DTree`. - -Typical usage: -`context.cfg.get_by_path("theme/options/portal-dark/label").to_string()` - :see DTree 0_context >types -:related -**PHP:** Deep array access helpers for associative arrays, decoded JSON, or configuration trees -**JavaScript / Node.js:** Optional chaining like `obj?.a?.b`, lodash `get`, or small path-walking helpers +:content +Traverses a nested `DTree` without creating missing keys. + +Empty path segments are ignored, so leading and trailing `/` characters are harmless. If any intermediate node is not a map or a segment is missing, `get_by_path()` returns an empty `DTree`. + +## Example + +```cpp +context.cfg.get_by_path("theme/options/portal-dark/label").to_string() +``` + +## Related Concepts + +- PHP: deep array access helpers for associative arrays, decoded JSON, or configuration trees +- JavaScript / Node.js: optional chaining like `obj?.a?.b`, lodash `get`, or small path-walking helpers diff --git a/site/doc/pages/html_escape.txt b/site/doc/pages/html_escape.txt index c6810a6..e077867 100644 --- a/site/doc/pages/html_escape.txt +++ b/site/doc/pages/html_escape.txt @@ -5,13 +5,15 @@ String html_escape(String s) s : string to be escaped return value : an HTML-safe escaped version of 's' -:desc -Returns a version of the input string where the following characters have been replace by HTML entities: -- & → & -- < → lt; -- > → > -- " → " +:content +Returns a version of the input string where special HTML characters are replaced by entities: -:related -**PHP:** `htmlspecialchars()` or `htmlentities()` -**JavaScript / Node.js:** Safe text insertion via `textContent` or server-side HTML escaping libraries +- `&` becomes `&` +- `<` becomes `<` +- `>` becomes `>` +- `"` becomes `"` + +## Related Concepts + +- PHP: `htmlspecialchars()` or `htmlentities()` +- JavaScript / Node.js: safe text insertion via `textContent` or server-side HTML escaping libraries diff --git a/site/doc/pages/int_val.txt b/site/doc/pages/int_val.txt index 6c8e59c..1defa69 100644 --- a/site/doc/pages/int_val.txt +++ b/site/doc/pages/int_val.txt @@ -6,10 +6,12 @@ s : string to be converted base : number system base (default 10) return value : a u64 containing the number (0 if no number could be identified). -:desc -Extracts an integer from a String. +:content +Extracts an integer value from `s`. +The `base` argument controls which number system is used while parsing. If no usable number can be identified, the function returns `0`. -:related -**PHP:** `intval()` -**JavaScript / Node.js:** `Number()` or `parseInt()` +Related: + +- PHP: `intval()` +- JavaScript / Node.js: `Number()` or `parseInt()` diff --git a/site/doc/pages/join.txt b/site/doc/pages/join.txt index 5efd0b5..bc9c58c 100644 --- a/site/doc/pages/join.txt +++ b/site/doc/pages/join.txt @@ -6,12 +6,15 @@ l : list of strings to be joined delim : delimiter (defaults to newline character) return value : a string containing items joined by 'delim' -:desc -Joins the items contained in 'l' into a single String. - :see >string -:related -**PHP:** `implode()` -**JavaScript / Node.js:** `Array.prototype.join()` +:content +Joins all strings in `l` into a single `String`. + +The delimiter is inserted between items. If `delim` is omitted, the default separator is a newline character. + +Related: + +- PHP: `implode()` +- JavaScript / Node.js: `Array.prototype.join()` diff --git a/site/doc/pages/json_decode.txt b/site/doc/pages/json_decode.txt index b1edb77..f4c3f91 100644 --- a/site/doc/pages/json_decode.txt +++ b/site/doc/pages/json_decode.txt @@ -5,20 +5,6 @@ DTree json_decode(String s) s : string containing JSON data return value : a DTree object containing the deserialized JSON data -:desc -Deserializes 's' into a DTree structure. - -The returned structure is usually consumed through `DTree` accessors such as: -- `tree["key"].to_string()` -- `tree["count"].to_u64()` -- `tree["enabled"].to_bool()` - -Current runtime note: -- JSON objects and arrays become map-shaped `DTree` values -- JSON booleans become native `bool` `DTree` values -- JSON strings become native `String` `DTree` values -- JSON numbers currently deserialize as string-valued `DTree` nodes, so typed conversions like `to_f64()` and `to_u64()` are the normal way to read numeric content - :see DTree json_encode @@ -26,6 +12,23 @@ to_bool to_f64 to_u64 -:related -**PHP:** `json_decode()` -**JavaScript / Node.js:** `JSON.parse()` +:content +Deserializes `s` into a `DTree` structure. + +The returned structure is usually consumed through `DTree` accessors such as: + +- `tree["key"].to_string()` +- `tree["count"].to_u64()` +- `tree["enabled"].to_bool()` + +Current runtime behavior: + +- JSON objects and arrays become map-shaped `DTree` values. +- JSON booleans become native `bool` `DTree` values. +- JSON strings become native `String` `DTree` values. +- JSON numbers currently deserialize as string-valued `DTree` nodes, so typed conversions such as `to_f64()` and `to_u64()` are the normal way to read numeric content. + +Related: + +- PHP: `json_decode()` +- JavaScript / Node.js: `JSON.parse()` diff --git a/site/doc/pages/json_encode.txt b/site/doc/pages/json_encode.txt index af2a7df..30bd807 100644 --- a/site/doc/pages/json_encode.txt +++ b/site/doc/pages/json_encode.txt @@ -7,13 +7,14 @@ s : string to encode as a JSON string literal t : DTree object to be serialized return value : string containing the JSON result -:desc +:content Serializes either a `String` or a `DTree` into JSON notation. When passed a `String`, `json_encode()` returns a quoted and escaped JSON string literal. When passed a `DTree`, scalar values are serialized directly and nested map values are emitted as JSON objects. -:related -**PHP:** `json_encode()` -**JavaScript / Node.js:** `JSON.stringify()` +Related: + +- PHP: `json_encode()` +- JavaScript / Node.js: `JSON.stringify()` diff --git a/site/doc/pages/load.txt b/site/doc/pages/load.txt index 1868afe..e980e28 100644 --- a/site/doc/pages/load.txt +++ b/site/doc/pages/load.txt @@ -4,12 +4,19 @@ :params file name : name of an UCE file that should be included -:desc -Includes another UCE file - :see >ob -:related -**PHP:** `include`, `require`, and config-loader patterns that resolve and import another file -**JavaScript / Node.js:** `import()`, `require()`, or file-loader helpers that resolve modules at runtime +:content +Includes another UCE file. + +Use `#load` when you want the current file to pull in declarations or reusable content from another UCE source file. + +```uce +#load "myfile.uce" +``` + +Related: + +- PHP: `include`, `require`, and config-loader patterns that resolve and import another file +- JavaScript / Node.js: `import()`, `require()`, or file-loader helpers that resolve modules at runtime diff --git a/site/doc/pages/ls.txt b/site/doc/pages/ls.txt index cc8fc7e..4c8689f 100644 --- a/site/doc/pages/ls.txt +++ b/site/doc/pages/ls.txt @@ -5,12 +5,15 @@ StringList ls(String path) path : a filesystem path return value : list of directory entries -:desc -Returns a list of files and subdirectories within the given 'path'. - :see >sys -:related -**PHP:** `scandir()`, `glob()`, or `DirectoryIterator` -**JavaScript / Node.js:** Node `fs.readdirSync()` or `fs.promises.readdir()` +:content +Returns a list of files and subdirectories within `path`. + +This is a simple directory listing helper for filesystem-oriented tasks. + +Related: + +- PHP: `scandir()`, `glob()`, or `DirectoryIterator` +- JavaScript / Node.js: Node `fs.readdirSync()` or `fs.promises.readdir()` diff --git a/site/doc/pages/markdown_to_ast.txt b/site/doc/pages/markdown_to_ast.txt index 58f7842..c318d82 100644 --- a/site/doc/pages/markdown_to_ast.txt +++ b/site/doc/pages/markdown_to_ast.txt @@ -7,11 +7,19 @@ src : markdown source text options : optional markdown options tree return value : a `DTree` document AST -:desc +:see +markdown_to_html +component +component_render +json_encode +DTree + +:content Parses Markdown source into a structured `DTree` document tree. The parser targets a practical GitHub-flavored subset by default: -- ATX headings (`#`) + +- ATX headings with `#` - setext headings - paragraphs - blockquotes @@ -20,62 +28,57 @@ The parser targets a practical GitHub-flavored subset by default: - fenced code blocks - tables - horizontal rules -- emphasis / strong / strikethrough +- emphasis, strong, and strikethrough - links, images, autolinks, and code spans - `:::` directive blocks for component-based extensions The returned AST uses `type` plus node-specific fields such as `level`, `text`, `lang`, `href`, `src`, `name`, `argument`, `attrs`, and `children`. Top-level documents use: -`type = "document"` -`children = [...]` + +```text +type = "document" +children = [...] +``` Common block nodes: -`heading` -`paragraph` -`blockquote` -`list` -`list_item` -`code_block` -`table` -`directive` -`hr` + +- `heading` +- `paragraph` +- `blockquote` +- `list` +- `list_item` +- `code_block` +- `table` +- `directive` +- `hr` Common inline nodes: -`text` -`code` -`strong` -`em` -`strike` -`link` -`image` -`raw_html` -:Example -`DTree options = json_decode("{\"components\":{\":::warning\":\"components/markdown/warning\"}}");` -`DTree ast = markdown_to_ast(file_get_contents("README.md"), options);` -`print(json_encode(ast));` +- `text` +- `code` +- `strong` +- `em` +- `strike` +- `link` +- `image` +- `raw_html` -:Options -`options["gfm"]` -Enables GitHub-style extras such as tables, task lists, strikethrough, and bare-URL autolinks. -Defaults to true. +Example: -`options["allow_html"]` -Allows raw HTML passthrough nodes to be captured and rendered. -Defaults to false. +```uce +DTree options = json_decode("{\"components\":{\":::warning\":\"components/markdown/warning\"}}"); +DTree ast = markdown_to_ast(file_get_contents("README.md"), options); +print(json_encode(ast)); +``` -`options["components"]` -Component hook map used later by `markdown_to_html()`. -The parser preserves directive data needed by those hooks. +Options: -:see -markdown_to_html -component -component_render -json_encode -DTree +- `options["gfm"]` enables GitHub-style extras such as tables, task lists, strikethrough, and bare-URL autolinks. Defaults to `true`. +- `options["allow_html"]` allows raw HTML passthrough nodes to be captured and rendered. Defaults to `false`. +- `options["components"]` provides the component hook map later used by `markdown_to_html()`. The parser preserves directive data needed by those hooks. -:related -**PHP:** CommonMark or Parsedown parsing pipelines that expose a syntax tree or token stream -**JavaScript / Node.js:** `remark`, `micromark`, or `markdown-it` token streams and AST-like structures +Related: + +- PHP: CommonMark or Parsedown parsing pipelines that expose a syntax tree or token stream +- JavaScript / Node.js: `remark`, `micromark`, or `markdown-it` token streams and AST-like structures diff --git a/site/doc/pages/markdown_to_html.txt b/site/doc/pages/markdown_to_html.txt index 259bf21..8e22426 100644 --- a/site/doc/pages/markdown_to_html.txt +++ b/site/doc/pages/markdown_to_html.txt @@ -7,7 +7,14 @@ src : markdown source text options : optional markdown options tree return value : rendered HTML string -:desc +:see +markdown_to_ast +component +component_render +json_decode +String + +:content Renders Markdown source into HTML and returns the generated markup as a `String`. `markdown_to_html()` does not write to the output stream directly. This keeps it aligned with the UCE naming convention where `render_*` names are reserved for direct-output helpers. @@ -16,14 +23,18 @@ Because the return value is HTML markup, embed it with `memcache -:related -**PHP:** The `Memcache` or `Memcached` extension methods such as `get()`, `set()`, `delete()`, and `getMulti()` -**JavaScript / Node.js:** Node clients like `memjs`, `memcached`, or similar Memcached packages +:content +Executes a raw command on an open Memcache connection and returns the server response as a string. + +This is the low-level escape hatch for Memcache operations that are not covered by the dedicated helpers. + +Related: + +- PHP: `Memcache` or `Memcached` methods such as `get()`, `set()`, `delete()`, and `getMulti()` +- JavaScript / Node.js: clients such as `memjs`, `memcached`, or similar Memcached packages diff --git a/site/doc/pages/memcache_connect.txt b/site/doc/pages/memcache_connect.txt index d1c9380..73eb8c4 100644 --- a/site/doc/pages/memcache_connect.txt +++ b/site/doc/pages/memcache_connect.txt @@ -6,12 +6,15 @@ host : optional host name of the memcache server, defaults to local address 127. port : optional memcache server's port, defaults to 11211 return value : the connection handle (or -1 if an error occurred) -:desc -Connects to a memcache server instance. - :see >memcache -:related -**PHP:** The `Memcache` or `Memcached` extension methods such as `get()`, `set()`, `delete()`, and `getMulti()` -**JavaScript / Node.js:** Node clients like `memjs`, `memcached`, or similar Memcached packages +:content +Connects to a Memcache server instance. + +If the connection fails, the function returns `-1`. + +Related: + +- PHP: `Memcache` or `Memcached` methods such as `get()`, `set()`, `delete()`, and `getMulti()` +- JavaScript / Node.js: clients such as `memjs`, `memcached`, or similar Memcached packages diff --git a/site/doc/pages/memcache_delete.txt b/site/doc/pages/memcache_delete.txt index 9780fe2..761e732 100644 --- a/site/doc/pages/memcache_delete.txt +++ b/site/doc/pages/memcache_delete.txt @@ -6,12 +6,15 @@ connection : connection handle key : key string return value : true if the operation was successful -:desc -Deletes entry specified by the 'key'. - :see >memcache -:related -**PHP:** The `Memcache` or `Memcached` extension methods such as `get()`, `set()`, `delete()`, and `getMulti()` -**JavaScript / Node.js:** Node clients like `memjs`, `memcached`, or similar Memcached packages +:content +Deletes the entry identified by `key`. + +The return value is `true` when the operation succeeds. + +Related: + +- PHP: `Memcache` or `Memcached` methods such as `get()`, `set()`, `delete()`, and `getMulti()` +- JavaScript / Node.js: clients such as `memjs`, `memcached`, or similar Memcached packages diff --git a/site/doc/pages/memcache_get.txt b/site/doc/pages/memcache_get.txt index 646db7e..63b1837 100644 --- a/site/doc/pages/memcache_get.txt +++ b/site/doc/pages/memcache_get.txt @@ -7,12 +7,15 @@ key : key string default_value : optional default value return value : value that was returned by the Memcache server -:desc -Retrieves a value from an existing connection to a Memcache server. - :see >memcache -:related -**PHP:** The `Memcache` or `Memcached` extension methods such as `get()`, `set()`, `delete()`, and `getMulti()` -**JavaScript / Node.js:** Node clients like `memjs`, `memcached`, or similar Memcached packages +:content +Retrieves a value from an existing Memcache connection. + +If the key is missing, `default_value` is returned instead. + +Related: + +- PHP: `Memcache` or `Memcached` methods such as `get()`, `set()`, `delete()`, and `getMulti()` +- JavaScript / Node.js: clients such as `memjs`, `memcached`, or similar Memcached packages diff --git a/site/doc/pages/memcache_get_multiple.txt b/site/doc/pages/memcache_get_multiple.txt index bc9f56d..da46b91 100644 --- a/site/doc/pages/memcache_get_multiple.txt +++ b/site/doc/pages/memcache_get_multiple.txt @@ -6,12 +6,15 @@ connection : connection handle keys : a list of strings containing the keys to be retrieved return value : a StringMap with the retrieved entries -:desc -Retrieves a bunch of entries all at once. - :see >memcache -:related -**PHP:** The `Memcache` or `Memcached` extension methods such as `get()`, `set()`, `delete()`, and `getMulti()` -**JavaScript / Node.js:** Node clients like `memjs`, `memcached`, or similar Memcached packages +:content +Retrieves multiple entries in one call. + +The result is returned as a `StringMap` keyed by the requested Memcache keys. + +Related: + +- PHP: `Memcache` or `Memcached` methods such as `get()`, `set()`, `delete()`, and `getMulti()` +- JavaScript / Node.js: clients such as `memjs`, `memcached`, or similar Memcached packages diff --git a/site/doc/pages/memcache_set.txt b/site/doc/pages/memcache_set.txt index 4755a1f..9ed0fbf 100644 --- a/site/doc/pages/memcache_set.txt +++ b/site/doc/pages/memcache_set.txt @@ -8,12 +8,15 @@ value : the value to be set expires_in : optional expiration timeout, defaults to one hour return value : true if the operation was successful -:desc -Stores a 'value' on the Memcache server. - :see >memcache -:related -**PHP:** The `Memcache` or `Memcached` extension methods such as `get()`, `set()`, `delete()`, and `getMulti()` -**JavaScript / Node.js:** Node clients like `memjs`, `memcached`, or similar Memcached packages +:content +Stores `value` under `key` on the Memcache server. + +`expires_in` controls the expiration timeout and defaults to one hour. + +Related: + +- PHP: `Memcache` or `Memcached` methods such as `get()`, `set()`, `delete()`, and `getMulti()` +- JavaScript / Node.js: clients such as `memjs`, `memcached`, or similar Memcached packages diff --git a/site/doc/pages/mkdir.txt b/site/doc/pages/mkdir.txt index 5c02f38..d0b02ec 100644 --- a/site/doc/pages/mkdir.txt +++ b/site/doc/pages/mkdir.txt @@ -5,12 +5,15 @@ bool mkdir(String path) path : the path name to be created return value : returns true if the directory was successfully created -:desc -Creates a directory stated by 'path' - :see >sys -:related -**PHP:** `mkdir()` -**JavaScript / Node.js:** Node `fs.mkdirSync()` or `fs.promises.mkdir()` +:content +Creates the directory named by `path`. + +The function returns `true` when the directory was created successfully. + +Related: + +- PHP: `mkdir()` +- JavaScript / Node.js: Node `fs.mkdirSync()` or `fs.promises.mkdir()` diff --git a/site/doc/pages/mysql_connect.txt b/site/doc/pages/mysql_connect.txt index d4f9c9a..b763d36 100644 --- a/site/doc/pages/mysql_connect.txt +++ b/site/doc/pages/mysql_connect.txt @@ -7,12 +7,15 @@ username : user name password : password return value : pointer to the MySQL connection struct -:desc -Establishes a connection to a MySQL server. - :see >mysql -:related -**PHP:** Modern PHP database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family -**JavaScript / Node.js:** Node database clients such as `mysql2`, query builders, or ORM adapters +:content +Establishes a connection to a MySQL server and returns a pointer to the connection struct. + +This connection handle is then used with helpers such as `mysql_query()`, `mysql_error()`, and `mysql_disconnect()`. + +Related: + +- PHP: modern database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family +- JavaScript / Node.js: clients such as `mysql2`, query builders, or ORM adapters diff --git a/site/doc/pages/mysql_disconnect.txt b/site/doc/pages/mysql_disconnect.txt index c889821..829d963 100644 --- a/site/doc/pages/mysql_disconnect.txt +++ b/site/doc/pages/mysql_disconnect.txt @@ -4,12 +4,15 @@ void mysql_disconnect(MySQL* m) :params m : pointer to an existing MySQL connection struct -:desc -Closes a connection to a MySQL server. - :see >mysql -:related -**PHP:** Modern PHP database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family -**JavaScript / Node.js:** Node database clients such as `mysql2`, query builders, or ORM adapters +:content +Closes an existing connection to a MySQL server. + +Call this when you are done using a `MySQL*` connection handle. + +Related: + +- PHP: modern database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family +- JavaScript / Node.js: clients such as `mysql2`, query builders, or ORM adapters diff --git a/site/doc/pages/mysql_error.txt b/site/doc/pages/mysql_error.txt index b8f6ee9..0568adb 100644 --- a/site/doc/pages/mysql_error.txt +++ b/site/doc/pages/mysql_error.txt @@ -5,12 +5,15 @@ String mysql_error(MySQL* m) m : pointer to a MySQL connection struct return value : MySQL error message (if present, otherwise empty string) -:desc -Returns the last error message from a connection to a MySQL server. - :see >mysql -:related -**PHP:** Modern PHP database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family -**JavaScript / Node.js:** Node database clients such as `mysql2`, query builders, or ORM adapters +:content +Returns the last error message associated with the given MySQL connection. + +If there is no current error, the result is an empty string. + +Related: + +- PHP: modern database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family +- JavaScript / Node.js: clients such as `mysql2`, query builders, or ORM adapters diff --git a/site/doc/pages/mysql_escape.txt b/site/doc/pages/mysql_escape.txt index a0a030b..a7e73dc 100644 --- a/site/doc/pages/mysql_escape.txt +++ b/site/doc/pages/mysql_escape.txt @@ -6,12 +6,15 @@ raw : the string to be escaped quote_char : the character that should be used to wrap the string (pass NULL for no wrapping) return value : the safe version of the 'raw' string -:desc -Escapes a string such that it can be passed as a safe value into an SQL expression. - :see >mysql -:related -**PHP:** Modern PHP database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family -**JavaScript / Node.js:** Node database clients such as `mysql2`, query builders, or ORM adapters +:content +Escapes a string so it can be used safely as a value inside an SQL expression. + +If `quote_char` is provided, the escaped result is wrapped with that quote character. Pass `NULL` when you only want escaping without wrapping. + +Related: + +- PHP: modern database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family +- JavaScript / Node.js: clients such as `mysql2`, query builders, or ORM adapters diff --git a/site/doc/pages/mysql_insert_id.txt b/site/doc/pages/mysql_insert_id.txt index b44fa99..c24d6dd 100644 --- a/site/doc/pages/mysql_insert_id.txt +++ b/site/doc/pages/mysql_insert_id.txt @@ -5,12 +5,15 @@ u64 mysql_insert_id(MySQL* m) m : pointer to an active MySQL connection return value : the last used automatic row ID -:desc -This retrieves the last row ID that was used for a column with an AUTO_INCREMENT row key. - :see >mysql -:related -**PHP:** Modern PHP database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family -**JavaScript / Node.js:** Node database clients such as `mysql2`, query builders, or ORM adapters +:content +Returns the last automatically assigned row ID used by the current MySQL connection. + +This is typically used after an `INSERT` into a table with an `AUTO_INCREMENT` primary key. + +Related: + +- PHP: modern database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family +- JavaScript / Node.js: clients such as `mysql2`, query builders, or ORM adapters diff --git a/site/doc/pages/mysql_query.txt b/site/doc/pages/mysql_query.txt index daf6d99..88372e3 100644 --- a/site/doc/pages/mysql_query.txt +++ b/site/doc/pages/mysql_query.txt @@ -7,15 +7,17 @@ q : a string containing a MySQL query params : optional, a list of query parameter keys and values return value : a list of rows returned from executing the query -:desc -Executes a MySQL query and returns the resulting data (if any). - -:Examples -(tbd) - :see >mysql -:related -**PHP:** Modern PHP database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family -**JavaScript / Node.js:** Node database clients such as `mysql2`, query builders, or ORM adapters +:content +Executes a MySQL query and returns the resulting data, if any. + +`params` provides the query parameter values used by the statement. + +The result is returned as a `DTree`, which makes it easy to iterate through rows and read fields with the usual `DTree` accessors. + +Related: + +- PHP: modern database access through `mysqli_*` or PDO methods rather than the old `mysql_*` family +- JavaScript / Node.js: clients such as `mysql2`, query builders, or ORM adapters diff --git a/site/doc/pages/nibble.txt b/site/doc/pages/nibble.txt index 8bd0322..7af80d9 100644 --- a/site/doc/pages/nibble.txt +++ b/site/doc/pages/nibble.txt @@ -6,12 +6,17 @@ haystack : string to be nibbled at delim : delimiter return value : string before first occurrence of 'delim' -:desc -Returns the part of 'haystack' before the first occurrence of 'delim', removing the corresponding part from 'haystack' (including 'delim'). If the substring 'delim' does not occurr in 'haystack', the entire string is returned and 'haystack' is set to an empty string. - :see >string -:related -**PHP:** Small parsing helpers built with `strpos()`, `substr()`, and `explode()` -**JavaScript / Node.js:** Manual parsing with `indexOf()`, `slice()`, and `split()` +:content +Returns the part of `haystack` before the first occurrence of `delim`. + +As a side effect, the consumed portion is removed from `haystack`, including the delimiter itself. + +If `delim` does not occur in `haystack`, the entire string is returned and `haystack` is set to an empty string. + +Related: + +- PHP: small parsing helpers built with `strpos()`, `substr()`, and `explode()` +- JavaScript / Node.js: manual parsing with `indexOf()`, `slice()`, and `split()` diff --git a/site/doc/pages/ob_close.txt b/site/doc/pages/ob_close.txt index 40bb020..faa9298 100644 --- a/site/doc/pages/ob_close.txt +++ b/site/doc/pages/ob_close.txt @@ -4,12 +4,15 @@ void ob_close() :params (none) -:desc -Discard the current output buffer. If are more output buffers on the stack, switch to the next one. - :see >ob -:related -**PHP:** `ob_start()`, `ob_get_contents()`, `ob_get_clean()`, and related output-buffering APIs -**JavaScript / Node.js:** String accumulation, buffer capture, or render-to-string patterns in server code +:content +Discards the current output buffer. + +If more output buffers remain on the stack, UCE switches to the next one. + +Related: + +- PHP: `ob_start()`, `ob_get_contents()`, `ob_get_clean()`, and related output-buffering APIs +- JavaScript / Node.js: string accumulation, buffer capture, or render-to-string patterns in server code diff --git a/site/doc/pages/ob_get.txt b/site/doc/pages/ob_get.txt index 382571c..3503ecb 100644 --- a/site/doc/pages/ob_get.txt +++ b/site/doc/pages/ob_get.txt @@ -4,12 +4,15 @@ String ob_get() :params return value : content of the current output buffer -:desc -Returns the contents of the current output buffer. - :see >ob -:related -**PHP:** `ob_start()`, `ob_get_contents()`, `ob_get_clean()`, and related output-buffering APIs -**JavaScript / Node.js:** String accumulation, buffer capture, or render-to-string patterns in server code +:content +Returns the contents of the current output buffer. + +Unlike `ob_get_close()`, this does not discard the buffer. + +Related: + +- PHP: `ob_start()`, `ob_get_contents()`, `ob_get_clean()`, and related output-buffering APIs +- JavaScript / Node.js: string accumulation, buffer capture, or render-to-string patterns in server code diff --git a/site/doc/pages/ob_get_close.txt b/site/doc/pages/ob_get_close.txt index ff45f89..6903a6f 100644 --- a/site/doc/pages/ob_get_close.txt +++ b/site/doc/pages/ob_get_close.txt @@ -4,13 +4,15 @@ String ob_get_close() :params return value : content of the current output buffer -:desc -Returns the contents of the current output buffer and then discards the buffer. -If are more output buffers on the stack, switch to the next one. - :see >ob -:related -**PHP:** `ob_start()`, `ob_get_contents()`, `ob_get_clean()`, and related output-buffering APIs -**JavaScript / Node.js:** String accumulation, buffer capture, or render-to-string patterns in server code +:content +Returns the contents of the current output buffer and then discards that buffer. + +If more output buffers remain on the stack, UCE switches to the next one. + +Related: + +- PHP: `ob_start()`, `ob_get_contents()`, `ob_get_clean()`, and related output-buffering APIs +- JavaScript / Node.js: string accumulation, buffer capture, or render-to-string patterns in server code diff --git a/site/doc/pages/ob_start.txt b/site/doc/pages/ob_start.txt index dbf0a99..8168f43 100644 --- a/site/doc/pages/ob_start.txt +++ b/site/doc/pages/ob_start.txt @@ -4,12 +4,15 @@ void ob_start() :params (none) -:desc -Starts a new output buffer. All subsequent output will be directed into this buffer. Every call to ob_start() starts a new buffer and puts that buffer on the output buffer stack. ob_close() and ob_get_close() destroy buffers and remove them from the stack. - :see >ob -:related -**PHP:** `ob_start()`, `ob_get_contents()`, `ob_get_clean()`, and related output-buffering APIs -**JavaScript / Node.js:** String accumulation, buffer capture, or render-to-string patterns in server code +:content +Starts a new output buffer. + +All subsequent output is directed into that buffer until it is closed or collected. Every call to `ob_start()` pushes another buffer onto the output buffer stack. `ob_close()` and `ob_get_close()` destroy buffers and remove them from the stack. + +Related: + +- PHP: `ob_start()`, `ob_get_contents()`, `ob_get_clean()`, and related output-buffering APIs +- JavaScript / Node.js: string accumulation, buffer capture, or render-to-string patterns in server code diff --git a/site/doc/pages/parse_query.txt b/site/doc/pages/parse_query.txt index faf8468..3698940 100644 --- a/site/doc/pages/parse_query.txt +++ b/site/doc/pages/parse_query.txt @@ -5,12 +5,15 @@ StringMap parse_query(String q) q : string containing URL parameters return value : a StringMap containing the parameters -:desc -Decodes a string of the format 'a=b&c=d' into a StringMap containing keyed entries. - :see >uri -:related -**PHP:** `parse_str()` -**JavaScript / Node.js:** `URLSearchParams` or Node `querystring.parse()` +:content +Decodes a query-string fragment such as `a=b&c=d` into a `StringMap`. + +This is useful when you need to work with URL parameter data outside the normal request parsing flow. + +Related: + +- PHP: `parse_str()` +- JavaScript / Node.js: `URLSearchParams` or Node `querystring.parse()` diff --git a/site/doc/pages/path_join.txt b/site/doc/pages/path_join.txt index cc6322d..93ae197 100644 --- a/site/doc/pages/path_join.txt +++ b/site/doc/pages/path_join.txt @@ -6,14 +6,15 @@ base : parent path child : child path or absolute override return value : combined path -:desc -Joins two filesystem-style path fragments with a single `/` when needed. - -If `child` is empty, `base` is returned. If `child` already starts with `/`, it is returned unchanged. This makes `path_join()` a better fit for app-level path assembly than open-coded string concatenation. - :see >sys -:related -**PHP:** Manual path composition with `DIRECTORY_SEPARATOR` or helper wrappers around it -**JavaScript / Node.js:** Node `path.join()` +:content +Joins two filesystem-style path fragments with a single `/` when needed. + +If `child` is empty, `base` is returned. If `child` already starts with `/`, it is returned unchanged. That makes `path_join()` a better fit for app-level path assembly than open-coded string concatenation. + +Related: + +- PHP: manual path composition with `DIRECTORY_SEPARATOR` or helper wrappers around it +- JavaScript / Node.js: Node `path.join()` diff --git a/site/doc/pages/print.txt b/site/doc/pages/print.txt index 272df0f..fb1c5e7 100644 --- a/site/doc/pages/print.txt +++ b/site/doc/pages/print.txt @@ -4,12 +4,15 @@ void print(...val) :params ...val : one or more values that should be output -:desc -Appends data to the current request's output stream. - :see >string -:related -**PHP:** `echo`, `print`, and output buffering patterns -**JavaScript / Node.js:** `res.write()`, stream writes, or string-returning render helpers depending on context +:content +Appends data to the current request output stream. + +Use `print()` when you want to emit response content directly from UCE code. + +Related: + +- PHP: `echo`, `print`, and output buffering patterns +- JavaScript / Node.js: `res.write()`, stream writes, or string-returning render helpers depending on context diff --git a/site/doc/pages/redirect.txt b/site/doc/pages/redirect.txt index bfae26d..5bb958a 100644 --- a/site/doc/pages/redirect.txt +++ b/site/doc/pages/redirect.txt @@ -5,15 +5,16 @@ void redirect(String url, s32 code = 302) url : target URL for the redirect code : optional HTTP redirect status, defaults to `302` -:desc -Sets the `Location` response header and updates the current HTTP status code. - -Use this helper instead of manually assigning `context.header["Location"]` and `context.set_status(...)` when you want to redirect the current response. - :see set_status 0_context -:related -**PHP:** `header("Location: ...")` together with `http_response_code()` or implicit redirect semantics -**JavaScript / Node.js:** `res.redirect(...)`, setting `Location`, or returning a redirect `Response` \ No newline at end of file +:content +Sets the `Location` response header and updates the current HTTP status code. + +Use this helper instead of manually assigning `context.header["Location"]` and `context.set_status(...)` when you want to redirect the current response. + +Related: + +- PHP: `header("Location: ...")` together with `http_response_code()` or implicit redirect semantics +- JavaScript / Node.js: `res.redirect(...)`, setting `Location`, or returning a redirect `Response` diff --git a/site/doc/pages/replace.txt b/site/doc/pages/replace.txt index 6b27a54..d6af024 100644 --- a/site/doc/pages/replace.txt +++ b/site/doc/pages/replace.txt @@ -7,12 +7,15 @@ search : the string that should be searched for replace_with : the string that should appear in places where 'search' occurs return value : a version of 's' where all instances of 'search' have been replaced with 'replace_with' -:desc -Replace all occurrences of 'search' with the string defined in 'replace_with'. - :see >string -:related -**PHP:** `str_replace()` or `preg_replace()` -**JavaScript / Node.js:** `String.prototype.replace()` or `replaceAll()` +:content +Replaces every occurrence of `search` in `s` with `replace_with`. + +The returned string contains the fully replaced result. + +Related: + +- PHP: `str_replace()` or `preg_replace()` +- JavaScript / Node.js: `String.prototype.replace()` or `replaceAll()` diff --git a/site/doc/pages/session_destroy.txt b/site/doc/pages/session_destroy.txt index 3adfc98..c392101 100644 --- a/site/doc/pages/session_destroy.txt +++ b/site/doc/pages/session_destroy.txt @@ -4,12 +4,15 @@ void session_destroy(String session_name) :params session_name : the name of the session -:desc -Deletes the cookie specified by 'session_name' and clears the data stored under the session ID. This empties the 'context.session_id' and 'context.session' variables. - :see >session -:related -**PHP:** `session_destroy()` -**JavaScript / Node.js:** Express session store teardown or manual cookie-session invalidation +:content +Deletes the cookie specified by `session_name` and clears the data stored under the current session ID. + +This also empties `context.session_id` and `context.session`. + +Related: + +- PHP: `session_destroy()` +- JavaScript / Node.js: Express session store teardown or manual cookie-session invalidation diff --git a/site/doc/pages/session_id_create.txt b/site/doc/pages/session_id_create.txt index c50edd0..6e61de5 100644 --- a/site/doc/pages/session_id_create.txt +++ b/site/doc/pages/session_id_create.txt @@ -4,12 +4,15 @@ String session_id_create() :params return value : a new session ID -:desc -Creates a session ID. - :see >session -:related -**PHP:** `session_create_id()` or custom session token generators -**JavaScript / Node.js:** `crypto.randomUUID()` or custom secure session ID generation +:content +Creates and returns a new session ID. + +This helper is useful when you need to generate a session token directly rather than starting a full session flow with `session_start()`. + +Related: + +- PHP: `session_create_id()` or custom session token generators +- JavaScript / Node.js: `crypto.randomUUID()` or custom secure session ID generation diff --git a/site/doc/pages/session_start.txt b/site/doc/pages/session_start.txt index 1130600..2df1454 100644 --- a/site/doc/pages/session_start.txt +++ b/site/doc/pages/session_start.txt @@ -5,18 +5,21 @@ String session_start(String session_name = "uce-session") session_name : optional name of the session cookie, defaults to "uce-session" return value : the current session ID -:desc -Starts session or connects to existing session. This function sets a cookie with the name contained in 'session_name' if it does not exist and fills that cookie with a new unique session ID. It then loads the session data for that session ID. Afterwards, the following fields are populated in the 'context' variable: - -context.session_id : the current session ID - -context.session_name : the current session cookie name - -context.session : the current session data. The session data is automatically saved after a request completes. - :see >session -:related -**PHP:** `session_start()` -**JavaScript / Node.js:** Express `express-session`, `cookie-session`, or similar request-bound session middleware +:content +Starts a session or reconnects to an existing one. + +If the cookie named by `session_name` does not exist, UCE creates it and fills it with a new unique session ID. The function then loads the session data for that ID. + +After `session_start()` completes, the following `context` fields are populated: + +- `context.session_id` contains the current session ID. +- `context.session_name` contains the current session cookie name. +- `context.session` contains the current session data. The session data is automatically saved after the request completes. + +Related: + +- PHP: `session_start()` +- JavaScript / Node.js: Express `express-session`, `cookie-session`, or similar request-bound session middleware diff --git a/site/doc/pages/set_status.txt b/site/doc/pages/set_status.txt index 2adabe1..ed8711a 100644 --- a/site/doc/pages/set_status.txt +++ b/site/doc/pages/set_status.txt @@ -5,15 +5,16 @@ void context.set_status(s32 code, String reason = "") code : HTTP status code reason : optional reason phrase override -:desc -Sets the current request status line and mirrors the numeric status into `context.flags.status`. - -When `reason` is omitted, UCE fills in a standard reason phrase for common HTTP status codes such as `200`, `302`, `400`, `404`, and `500`. - :see 0_context >types -:related -**PHP:** `http_response_code()` and explicit status-line header control -**JavaScript / Node.js:** `res.status(...)`, `Response` init status, or low-level status assignment on an HTTP response +:content +Sets the current request status line and mirrors the numeric status into `context.flags.status`. + +When `reason` is omitted, UCE fills in a standard reason phrase for common HTTP status codes such as `200`, `302`, `400`, `404`, and `500`. + +Related: + +- PHP: `http_response_code()` and explicit status-line header control +- JavaScript / Node.js: `res.status(...)`, `Response` init status, or low-level status assignment on an HTTP response diff --git a/site/doc/pages/shell_escape.txt b/site/doc/pages/shell_escape.txt index 15776a5..644f5b1 100644 --- a/site/doc/pages/shell_escape.txt +++ b/site/doc/pages/shell_escape.txt @@ -5,12 +5,15 @@ String shell_escape(String raw) raw : string that should be escaped return value : escaped version of 'raw' -:desc -Escapes a parameter for shell_exec - :see >sys -:related -**PHP:** `escapeshellarg()` and `escapeshellcmd()` -**JavaScript / Node.js:** There is no direct built-in equivalent; prefer `spawn()` argument arrays and avoid shell interpolation +:content +Escapes a parameter so it can be used more safely with `shell_exec()`. + +This is the helper to reach for when building shell command lines from dynamic input. + +Related: + +- PHP: `escapeshellarg()` and `escapeshellcmd()` +- JavaScript / Node.js: there is no direct built-in equivalent; prefer `spawn()` argument arrays and avoid shell interpolation diff --git a/site/doc/pages/shell_exec.txt b/site/doc/pages/shell_exec.txt index acea46a..47ffbb2 100644 --- a/site/doc/pages/shell_exec.txt +++ b/site/doc/pages/shell_exec.txt @@ -5,12 +5,15 @@ String shell_exec(String cmd) cmd : string that contains the shell command line to be executed return value : output of the command execution -:desc -Executes a Linux shell command and returns the generated output - :see >sys -:related -**PHP:** `shell_exec()`, `exec()`, or `proc_open()` -**JavaScript / Node.js:** Node `child_process.exec()` or `spawn()` +:content +Executes a Linux shell command and returns the generated output. + +When command text includes user-controlled input, escape that input first with `shell_escape()`. + +Related: + +- PHP: `shell_exec()`, `exec()`, or `proc_open()` +- JavaScript / Node.js: Node `child_process.exec()` or `spawn()` diff --git a/site/doc/pages/socket_close.txt b/site/doc/pages/socket_close.txt index eb42870..e341b2b 100644 --- a/site/doc/pages/socket_close.txt +++ b/site/doc/pages/socket_close.txt @@ -4,12 +4,15 @@ void socket_close(u64 sockfd) :params sockfd : socket handle -:desc -Closes an existing socket connection. - :see >socket -:related -**PHP:** PHP sockets and stream APIs like `socket_connect()`, `fread()`, `fwrite()`, and stream clients -**JavaScript / Node.js:** Node `net.Socket` connect, read, write, and close operations +:content +Closes an existing socket connection. + +Use this when you are done with a socket opened through `socket_connect()`. + +Related: + +- PHP: PHP sockets and stream APIs like `socket_connect()`, `fread()`, `fwrite()`, and stream clients +- JavaScript / Node.js: Node `net.Socket` connect, read, write, and close operations diff --git a/site/doc/pages/socket_connect.txt b/site/doc/pages/socket_connect.txt index 681ed77..4a7704b 100644 --- a/site/doc/pages/socket_connect.txt +++ b/site/doc/pages/socket_connect.txt @@ -6,12 +6,15 @@ host : host name port : port number return value : the socket handle -:desc -Opens a socket connection to the given 'host' and 'port'. - :see >socket -:related -**PHP:** PHP sockets and stream APIs like `socket_connect()`, `fread()`, `fwrite()`, and stream clients -**JavaScript / Node.js:** Node `net.Socket` connect, read, write, and close operations +:content +Opens a socket connection to the given `host` and `port`. + +The returned socket handle is then used with `socket_read()`, `socket_write()`, and `socket_close()`. + +Related: + +- PHP: PHP sockets and stream APIs like `socket_connect()`, `fread()`, `fwrite()`, and stream clients +- JavaScript / Node.js: Node `net.Socket` connect, read, write, and close operations diff --git a/site/doc/pages/socket_read.txt b/site/doc/pages/socket_read.txt index e7b1319..b4bbce9 100644 --- a/site/doc/pages/socket_read.txt +++ b/site/doc/pages/socket_read.txt @@ -7,12 +7,15 @@ max_length : optional maximum data size, defaults to 128kBytes timeout : optional operation timeout, defaults to one second return value : string containing the data that was read -:desc -Reads data from a socket connection. - :see >socket -:related -**PHP:** PHP sockets and stream APIs like `socket_connect()`, `fread()`, `fwrite()`, and stream clients -**JavaScript / Node.js:** Node `net.Socket` connect, read, write, and close operations +:content +Reads data from a socket connection. + +`max_length` limits how much data is read, and `timeout` controls how long the operation is allowed to wait. + +Related: + +- PHP: PHP sockets and stream APIs like `socket_connect()`, `fread()`, `fwrite()`, and stream clients +- JavaScript / Node.js: Node `net.Socket` connect, read, write, and close operations diff --git a/site/doc/pages/socket_write.txt b/site/doc/pages/socket_write.txt index d86c591..0e433b1 100644 --- a/site/doc/pages/socket_write.txt +++ b/site/doc/pages/socket_write.txt @@ -6,12 +6,15 @@ sockfd : socket handle data : a string containing the data to be written to the socket return value : true if the write operation was successful -:desc -Writes a string of 'data' to the given socket. - :see >socket -:related -**PHP:** PHP sockets and stream APIs like `socket_connect()`, `fread()`, `fwrite()`, and stream clients -**JavaScript / Node.js:** Node `net.Socket` connect, read, write, and close operations +:content +Writes `data` to the given socket. + +The function returns `true` when the write succeeds. + +Related: + +- PHP: PHP sockets and stream APIs like `socket_connect()`, `fread()`, `fwrite()`, and stream clients +- JavaScript / Node.js: Node `net.Socket` connect, read, write, and close operations diff --git a/site/doc/pages/split.txt b/site/doc/pages/split.txt index 0d4d943..7be02e7 100644 --- a/site/doc/pages/split.txt +++ b/site/doc/pages/split.txt @@ -6,12 +6,15 @@ str : string to be split delim : delimiter return value : a list of strings -:desc -Splits 'str' into multiple strings based on the given delimiter 'delim'. - :see >string -:related -**PHP:** `explode()` or `preg_split()` -**JavaScript / Node.js:** `String.prototype.split()` +:content +Splits `str` into multiple strings using `delim` as the separator. + +Every exact occurrence of `delim` creates a new entry in the returned `StringList`. + +Related: + +- PHP: `explode()` or `preg_split()` +- JavaScript / Node.js: `String.prototype.split()` diff --git a/site/doc/pages/split_space.txt b/site/doc/pages/split_space.txt index 883fc11..074b8c7 100644 --- a/site/doc/pages/split_space.txt +++ b/site/doc/pages/split_space.txt @@ -5,12 +5,15 @@ StringList split_space(String str) str : string to be split return value : a list of strings -:desc -Splits 'str' into multiple strings along any whitespace characters (multiple whitespace characters count as one). - :see >string -:related -**PHP:** Whitespace splitting via `preg_split(/\s+/, ...)` -**JavaScript / Node.js:** Whitespace splitting via regex with `split(/\\s+/)` +:content +Splits `str` on runs of whitespace. + +Multiple adjacent whitespace characters are treated as a single separator, so repeated spaces, tabs, or line breaks do not create empty entries. + +Related: + +- PHP: whitespace splitting via `preg_split(/\s+/, ...)` +- JavaScript / Node.js: regex-based splitting with `split(/\\s+/)` diff --git a/site/doc/pages/split_utf8.txt b/site/doc/pages/split_utf8.txt index c8d168a..4e73b9d 100644 --- a/site/doc/pages/split_utf8.txt +++ b/site/doc/pages/split_utf8.txt @@ -7,18 +7,22 @@ str : string to be split compound_characters : optional, if true tries to combine compound characters return value : a list of Unicode characters -:desc -Splits the string 'str' into its constituent Unicode code points. - -If 'compound_characters' is true, split_utf8 will attempt to combine compound characters based on very simple rules: -
  • combine characters if they're connected by a Zero-Width Joiner (ZWJ) character
    • -
  • combine two characters if they're both a Regional Indicator Symbol Letter
    • -
  • if a character is a Variation Selector, append it to the previous character
    • -
  • in all other cases, characters remain on their own
    • - :see >string -:related -**PHP:** `preg_split(//u, ...)`, `mb_*` helpers, or grapheme-aware libraries -**JavaScript / Node.js:** `Array.from(str)` or iterator-based Unicode-aware splitting +:content +Splits `str` into its constituent Unicode code points. + +If `compound_characters` is `true`, `split_utf8()` also applies a small amount of grouping so some multi-code-point glyphs stay together. The current rules are: + +- combine characters joined by a Zero-Width Joiner (ZWJ) +- combine two Regional Indicator Symbol Letter characters +- append Variation Selectors to the previous character +- otherwise leave characters as separate entries + +This is useful when simple byte-wise or ASCII splitting would break Unicode text incorrectly. + +Related: + +- PHP: `preg_split(//u, ...)`, `mb_*` helpers, or grapheme-aware libraries +- JavaScript / Node.js: `Array.from(str)` or iterator-based Unicode-aware splitting diff --git a/site/doc/pages/str_ends_with.txt b/site/doc/pages/str_ends_with.txt index fe6ddc4..63cf005 100644 --- a/site/doc/pages/str_ends_with.txt +++ b/site/doc/pages/str_ends_with.txt @@ -6,12 +6,13 @@ haystack : string to inspect needle : suffix to compare against the end of `haystack` return value : `true` when `haystack` ends with `needle`, otherwise `false` -:desc -Checks whether `haystack` ends with the given suffix. - :see >string -:related -**PHP:** `str_ends_with()` -**JavaScript / Node.js:** `String.prototype.endsWith()` \ No newline at end of file +:content +Checks whether `haystack` ends with `needle`. + +Related: + +- PHP: `str_ends_with()` +- JavaScript / Node.js: `String.prototype.endsWith()` diff --git a/site/doc/pages/str_starts_with.txt b/site/doc/pages/str_starts_with.txt index 3c2a0aa..7ca94b3 100644 --- a/site/doc/pages/str_starts_with.txt +++ b/site/doc/pages/str_starts_with.txt @@ -6,12 +6,13 @@ haystack : string to inspect needle : prefix to compare against the start of `haystack` return value : `true` when `haystack` begins with `needle`, otherwise `false` -:desc -Checks whether `haystack` starts with the given prefix. - :see >string -:related -**PHP:** `str_starts_with()` -**JavaScript / Node.js:** `String.prototype.startsWith()` \ No newline at end of file +:content +Checks whether `haystack` starts with `needle`. + +Related: + +- PHP: `str_starts_with()` +- JavaScript / Node.js: `String.prototype.startsWith()` diff --git a/site/doc/pages/strpos.txt b/site/doc/pages/strpos.txt index 3bcddab..d400e88 100644 --- a/site/doc/pages/strpos.txt +++ b/site/doc/pages/strpos.txt @@ -7,16 +7,17 @@ needle : substring to search for offset : optional start offset; negative values count from the end of the string return value : zero-based position of the first match, or `-1` if `needle` is not found -:desc +:see +>string + +:content Finds the first occurrence of `needle` inside `haystack`. This is the closest UCE equivalent to PHP `strpos()`, but it returns `-1` instead of `false` when no match is found. If `needle` is an empty string, `strpos()` returns the normalized start offset. -:see ->string +Related: -:related -**PHP:** `strpos()` -**JavaScript / Node.js:** `String.prototype.indexOf()` \ No newline at end of file +- PHP: `strpos()` +- JavaScript / Node.js: `String.prototype.indexOf()` diff --git a/site/doc/pages/substr.txt b/site/doc/pages/substr.txt index fef930d..ed6f717 100644 --- a/site/doc/pages/substr.txt +++ b/site/doc/pages/substr.txt @@ -8,7 +8,10 @@ start_pos : zero-based start position; negative values count from the end of the length : optional substring length; negative values trim bytes from the end of the result range return value : extracted substring, or an empty string if the requested range is outside the source string -:desc +:see +>string + +:content Extracts part of a string using PHP-style start and length semantics. Use the two-argument form to return everything from `start_pos` to the end of the string. @@ -17,9 +20,7 @@ If `start_pos` is negative, counting starts from the end of the string. If `length` is negative, the returned range stops that many bytes before the end of the string. -:see ->string +Related: -:related -**PHP:** `substr()` -**JavaScript / Node.js:** `String.prototype.slice()` or `substring()` \ No newline at end of file +- PHP: `substr()` +- JavaScript / Node.js: `String.prototype.slice()` or `substring()` diff --git a/site/doc/pages/task.txt b/site/doc/pages/task.txt index c7c675b..04f46ae 100644 --- a/site/doc/pages/task.txt +++ b/site/doc/pages/task.txt @@ -6,12 +6,17 @@ key : string uniquely identifying the task exec_func : function to execute return value : the process ID of the started (or still running) task -:desc -task() starts the 'exec_func' in a new process and returns that process' ID. If a process with the same 'key' is already running, task will not start a new process but instead just return the PID of the process that is already running. - :see >task -:related -**PHP:** Background-process patterns using `proc_open()`, queues, cron, or worker supervisors -**JavaScript / Node.js:** Node `child_process`, worker queues, timers, schedulers, and supervised background jobs +:content +Starts `exec_func` in a new process and returns that process ID. + +If a process with the same `key` is already running, `task()` does not start a second copy. Instead it returns the PID of the already-running task. + +Use the `key` to make a background job idempotent across repeated calls. + +Related: + +- PHP: background-process patterns using `proc_open()`, queues, cron, or worker supervisors +- JavaScript / Node.js: Node `child_process`, worker queues, timers, schedulers, and supervised background jobs diff --git a/site/doc/pages/task_kill.txt b/site/doc/pages/task_kill.txt index 35c12c2..abbd70e 100644 --- a/site/doc/pages/task_kill.txt +++ b/site/doc/pages/task_kill.txt @@ -6,14 +6,17 @@ pid : PID of the process sig : signal number return value : 0 if signal was sent, -1 otherwise -:desc -Wraps the standard POSIX `kill()` function. - -Possible signal numbers are: SIGABND, SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGHUP, SIGILL, SIGINT, SIGKILL, SIGPIPE, SIGPOLL, SIGPROF, SIGQUIT, SIGSEGV, SIGSYS, SIGTERM, SIGTRAP, SIGURG, SIGUSR1, SIGUSR2, SIGVTALRM, SIGXCPU, SIGXFSZ, SIGCHLD, SIGIO, SIGIOERR, SIGWINCH, SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU, SIGCONT. - :see >task -:related -**PHP:** Background-process patterns using `proc_open()`, queues, cron, or worker supervisors -**JavaScript / Node.js:** Node `child_process`, worker queues, timers, schedulers, and supervised background jobs +:content +Wraps the standard POSIX `kill()` function. + +`sig` may be any supported POSIX signal, including values such as `SIGTERM`, `SIGKILL`, `SIGINT`, `SIGUSR1`, `SIGUSR2`, `SIGCHLD`, `SIGCONT`, and related process-control signals. + +Passing `0` as the signal performs an existence and permission check without actually delivering a signal. + +Related: + +- PHP: background-process patterns using `proc_open()`, queues, cron, or worker supervisors +- JavaScript / Node.js: Node `child_process`, worker queues, timers, schedulers, and supervised background jobs diff --git a/site/doc/pages/task_pid.txt b/site/doc/pages/task_pid.txt index 0ffb97e..ff8b10f 100644 --- a/site/doc/pages/task_pid.txt +++ b/site/doc/pages/task_pid.txt @@ -5,12 +5,15 @@ pid_t task_pid(String key) key : string uniquely identifying the task return value : the process ID of the task -:desc -Checks whether a process with the given 'key' is running and returns its PID if it is. Returns 0 otherwise. - :see >task -:related -**PHP:** Background-process patterns using `proc_open()`, queues, cron, or worker supervisors -**JavaScript / Node.js:** Node `child_process`, worker queues, timers, schedulers, and supervised background jobs +:content +Checks whether a process with the given `key` is running and returns its PID if it is. + +Returns `0` when no matching task is active. + +Related: + +- PHP: background-process patterns using `proc_open()`, queues, cron, or worker supervisors +- JavaScript / Node.js: Node `child_process`, worker queues, timers, schedulers, and supervised background jobs diff --git a/site/doc/pages/task_repeat.txt b/site/doc/pages/task_repeat.txt index bbf923f..d6618bb 100644 --- a/site/doc/pages/task_repeat.txt +++ b/site/doc/pages/task_repeat.txt @@ -8,14 +8,17 @@ exec_func : function to execute repeatedly timeout : optional task timeout value return value : the process ID of the started (or still running) task -:desc -Starts a repeating background worker process. The function `exec_func` is executed in a loop and the worker sleeps for `interval` seconds between executions. - -If a process with the same `key` is already running, `task_repeat()` does not start a second worker and instead returns the PID of the existing one. - :see >task -:related -**PHP:** Background-process patterns using `proc_open()`, queues, cron, or worker supervisors -**JavaScript / Node.js:** Node `child_process`, worker queues, timers, schedulers, and supervised background jobs +:content +Starts a repeating background worker process. + +`exec_func` runs in a loop, and the worker sleeps for `interval` seconds between executions. + +If a process with the same `key` is already running, `task_repeat()` does not start a second worker and instead returns the PID of the existing one. + +Related: + +- PHP: background-process patterns using `proc_open()`, queues, cron, or worker supervisors +- JavaScript / Node.js: Node `child_process`, worker queues, timers, schedulers, and supervised background jobs diff --git a/site/doc/pages/time.txt b/site/doc/pages/time.txt index 558c404..77cee0d 100644 --- a/site/doc/pages/time.txt +++ b/site/doc/pages/time.txt @@ -4,12 +4,13 @@ u64 time() :params return value : second-accurate current Unix timestamp -:desc -Returns a 64 bit integer containing the current Unix timestamp. - :see >time -:related -**PHP:** `time()` -**JavaScript / Node.js:** `Math.floor(Date.now() / 1000)` or `Date.now()` depending on units +:content +Returns the current Unix timestamp as a 64-bit integer with second precision. + +Related: + +- PHP: `time()` +- JavaScript / Node.js: `Math.floor(Date.now() / 1000)` or `Date.now()` depending on units diff --git a/site/doc/pages/time_format_local.txt b/site/doc/pages/time_format_local.txt index 27ef3fe..f81e6f1 100644 --- a/site/doc/pages/time_format_local.txt +++ b/site/doc/pages/time_format_local.txt @@ -6,137 +6,84 @@ format : formatting string specifying the date format timestamp : optional timestamp value, defaults to current time return value : a formatted date -:desc -Returns a formatted date. This is based on the Linux date() command. The formatting string supports the following sequences: -:pre - %% a literal % - - %a locale's abbreviated weekday name (e.g., Sun) - - %A locale's full weekday name (e.g., Sunday) - - %b locale's abbreviated month name (e.g., Jan) - - %B locale's full month name (e.g., January) - - %c locale's date and time (e.g., Thu Mar 3 23:05:25 2005) - - %C century; like %Y, except omit last two digits (e.g., 20) - - %d day of month (e.g., 01) - - %D date; same as %m/%d/%y - - %e day of month, space padded; same as %_d - - %F full date; like %+4Y-%m-%d - - %g last two digits of year of ISO week number (see %G) - - %G year of ISO week number (see %V); normally useful only - with %V - - %h same as %b - - %H hour (00..23) - - %I hour (01..12) - - %j day of year (001..366) - - %k hour, space padded ( 0..23); same as %_H - - %l hour, space padded ( 1..12); same as %_I - - %m month (01..12) - - %M minute (00..59) - - %n a newline - - %N nanoseconds (000000000..999999999) - - %p locale's equivalent of either AM or PM; blank if not known - - %P like %p, but lower case - - %q quarter of year (1..4) - - %r locale's 12-hour clock time (e.g., 11:11:04 PM) - - %R 24-hour hour and minute; same as %H:%M - - %s seconds since 1970-01-01 00:00:00 UTC - - %S second (00..60) - - %t a tab - - %T time; same as %H:%M:%S - - %u day of week (1..7); 1 is Monday - - %U week number of year, with Sunday as first day of week - (00..53) - - %V ISO week number, with Monday as first day of week (01..53) - - %w day of week (0..6); 0 is Sunday - - %W week number of year, with Monday as first day of week - (00..53) - - %x locale's date representation (e.g., 12/31/99) - - %X locale's time representation (e.g., 23:13:48) - - %y last two digits of year (00..99) - - %Y year - - %z +hhmm numeric time zone (e.g., -0400) - - %:z +hh:mm numeric time zone (e.g., -04:00) - - %::z +hh:mm:ss numeric time zone (e.g., -04:00:00) - - %:::z numeric time zone with : to necessary precision (e.g., - -04, +05:30) - - %Z alphabetic time zone abbreviation (e.g., EDT) - - %deltaS total elapsed seconds between the timestamp and now - - %deltaM total elapsed minutes between the timestamp and now - - %deltaH total elapsed hours between the timestamp and now - - %deltad total elapsed days between the timestamp and now - - %deltam total elapsed 30-day months between the timestamp and now - - %deltaY total elapsed 365-day years between the timestamp and now - - By default, date pads numeric fields with zeroes. The following - optional flags may follow '%': - - - (hyphen) do not pad the field - - _ (underscore) pad with spaces - - 0 (zero) pad with zeros - - + pad with zeros, and put '+' before future years with >4 - digits - - ^ use upper case if possible - - # use opposite case if possible - :see >time >time_format_relative -:related -**PHP:** `date()` and `DateTime` formatting in the server local timezone -**JavaScript / Node.js:** `Intl.DateTimeFormat`, `Date#toLocaleString()`, or date libraries +:content +Formats a timestamp in the server's local timezone. + +This formatter is based on the Linux `date` command and supports the same core formatting tokens plus UCE's relative-time delta tokens. + +Supported format sequences: + +```text +%% a literal % +%a locale's abbreviated weekday name (e.g., Sun) +%A locale's full weekday name (e.g., Sunday) +%b locale's abbreviated month name (e.g., Jan) +%B locale's full month name (e.g., January) +%c locale's date and time (e.g., Thu Mar 3 23:05:25 2005) +%C century; like %Y, except omit last two digits (e.g., 20) +%d day of month (e.g., 01) +%D date; same as %m/%d/%y +%e day of month, space padded; same as %_d +%F full date; like %+4Y-%m-%d +%g last two digits of year of ISO week number (see %G) +%G year of ISO week number (see %V); normally useful only with %V +%h same as %b +%H hour (00..23) +%I hour (01..12) +%j day of year (001..366) +%k hour, space padded ( 0..23); same as %_H +%l hour, space padded ( 1..12); same as %_I +%m month (01..12) +%M minute (00..59) +%n a newline +%N nanoseconds (000000000..999999999) +%p locale's equivalent of either AM or PM; blank if not known +%P like %p, but lower case +%q quarter of year (1..4) +%r locale's 12-hour clock time (e.g., 11:11:04 PM) +%R 24-hour hour and minute; same as %H:%M +%s seconds since 1970-01-01 00:00:00 UTC +%S second (00..60) +%t a tab +%T time; same as %H:%M:%S +%u day of week (1..7); 1 is Monday +%U week number of year, with Sunday as first day of week (00..53) +%V ISO week number, with Monday as first day of week (01..53) +%w day of week (0..6); 0 is Sunday +%W week number of year, with Monday as first day of week (00..53) +%x locale's date representation (e.g., 12/31/99) +%X locale's time representation (e.g., 23:13:48) +%y last two digits of year (00..99) +%Y year +%z +hhmm numeric time zone (e.g., -0400) +%:z +hh:mm numeric time zone (e.g., -04:00) +%::z +hh:mm:ss numeric time zone (e.g., -04:00:00) +%:::z numeric time zone with : to necessary precision (e.g., -04, +05:30) +%Z alphabetic time zone abbreviation (e.g., EDT) +%deltaS total elapsed seconds between the timestamp and now +%deltaM total elapsed minutes between the timestamp and now +%deltaH total elapsed hours between the timestamp and now +%deltad total elapsed days between the timestamp and now +%deltam total elapsed 30-day months between the timestamp and now +%deltaY total elapsed 365-day years between the timestamp and now +``` + +Padding and case flags may follow `%`: + +```text +- do not pad the field +_ pad with spaces +0 pad with zeros ++ pad with zeros, and put '+' before future years with >4 digits +^ use upper case if possible +# use opposite case if possible +``` + +Related: + +- PHP: `date()` and `DateTime` formatting in the server local timezone +- JavaScript / Node.js: `Intl.DateTimeFormat`, `Date#toLocaleString()`, or date libraries diff --git a/site/doc/pages/time_format_relative.txt b/site/doc/pages/time_format_relative.txt index 0724d18..37a689b 100644 --- a/site/doc/pages/time_format_relative.txt +++ b/site/doc/pages/time_format_relative.txt @@ -10,46 +10,45 @@ not_recent_seconds : cutoff between the medium-recent and not-recent formats, de format_not_recent : output format for older timestamps, defaults to `%deltaH hours ago` return value : a formatted relative-time string -:desc -Formats a timestamp relative to the current time using the same formatting engine as `time_format_local()` and `time_format_utc()`. - -The chosen format depends on the elapsed time: -- if `now - timestamp` is less than `medium_recency_seconds`, use `format_very_recent` -- else if it is less than `not_recent_seconds`, use `format_medium_recent` -- otherwise use `format_not_recent` - -The custom relative-time sequences available in all time formatters are: - -:pre - %deltaS total elapsed seconds between the timestamp and now - - %deltaM total elapsed minutes between the timestamp and now - - %deltaH total elapsed hours between the timestamp and now - - %deltad total elapsed days between the timestamp and now - - %deltam total elapsed 30-day months between the timestamp and now - - %deltaY total elapsed 365-day years between the timestamp and now - -:pre -Default behavior examples: - - time_format_relative(time() - 12) - => just now - - time_format_relative(time() - 600) - => 10 minutes ago - - time_format_relative(time() - 7200) - => 2 hours ago - :see >time >time_format_local >time_format_utc -:related -**PHP:** `DateTimeImmutable` diff formatting or libraries such as Carbon `diffForHumans()` -**JavaScript / Node.js:** relative time helpers such as `Intl.RelativeTimeFormat`, `date-fns/formatDistanceToNow`, or Luxon \ No newline at end of file +:content +Formats a timestamp relative to the current time using the same formatting engine as `time_format_local()` and `time_format_utc()`. + +The formatter chooses one of three output formats: + +- if `now - timestamp` is less than `medium_recency_seconds`, use `format_very_recent` +- else if it is less than `not_recent_seconds`, use `format_medium_recent` +- otherwise use `format_not_recent` + +The relative-time tokens available in all time formatters are: + +```text +%deltaS total elapsed seconds between the timestamp and now +%deltaM total elapsed minutes between the timestamp and now +%deltaH total elapsed hours between the timestamp and now +%deltad total elapsed days between the timestamp and now +%deltam total elapsed 30-day months between the timestamp and now +%deltaY total elapsed 365-day years between the timestamp and now +``` + +Default behavior examples: + +```text +time_format_relative(time() - 12) +=> just now + +time_format_relative(time() - 600) +=> 10 minutes ago + +time_format_relative(time() - 7200) +=> 2 hours ago +``` + +Related: + +- PHP: `DateTimeImmutable` diff formatting or libraries such as Carbon `diffForHumans()` +- JavaScript / Node.js: relative time helpers such as `Intl.RelativeTimeFormat`, `date-fns/formatDistanceToNow`, or Luxon diff --git a/site/doc/pages/time_format_utc.txt b/site/doc/pages/time_format_utc.txt index e215866..d5d74d0 100644 --- a/site/doc/pages/time_format_utc.txt +++ b/site/doc/pages/time_format_utc.txt @@ -6,137 +6,84 @@ format : formatting string specifying the date format timestamp : optional timestamp value, defaults to current time return value : a formatted date -:desc -Returns a formatted date in the GMT/UTC timezone. This is based on the Linux date() command. The formatting string supports the following sequences: -:pre - %% a literal % - - %a locale's abbreviated weekday name (e.g., Sun) - - %A locale's full weekday name (e.g., Sunday) - - %b locale's abbreviated month name (e.g., Jan) - - %B locale's full month name (e.g., January) - - %c locale's date and time (e.g., Thu Mar 3 23:05:25 2005) - - %C century; like %Y, except omit last two digits (e.g., 20) - - %d day of month (e.g., 01) - - %D date; same as %m/%d/%y - - %e day of month, space padded; same as %_d - - %F full date; like %+4Y-%m-%d - - %g last two digits of year of ISO week number (see %G) - - %G year of ISO week number (see %V); normally useful only - with %V - - %h same as %b - - %H hour (00..23) - - %I hour (01..12) - - %j day of year (001..366) - - %k hour, space padded ( 0..23); same as %_H - - %l hour, space padded ( 1..12); same as %_I - - %m month (01..12) - - %M minute (00..59) - - %n a newline - - %N nanoseconds (000000000..999999999) - - %p locale's equivalent of either AM or PM; blank if not known - - %P like %p, but lower case - - %q quarter of year (1..4) - - %r locale's 12-hour clock time (e.g., 11:11:04 PM) - - %R 24-hour hour and minute; same as %H:%M - - %s seconds since 1970-01-01 00:00:00 UTC - - %S second (00..60) - - %t a tab - - %T time; same as %H:%M:%S - - %u day of week (1..7); 1 is Monday - - %U week number of year, with Sunday as first day of week - (00..53) - - %V ISO week number, with Monday as first day of week (01..53) - - %w day of week (0..6); 0 is Sunday - - %W week number of year, with Monday as first day of week - (00..53) - - %x locale's date representation (e.g., 12/31/99) - - %X locale's time representation (e.g., 23:13:48) - - %y last two digits of year (00..99) - - %Y year - - %z +hhmm numeric time zone (e.g., -0400) - - %:z +hh:mm numeric time zone (e.g., -04:00) - - %::z +hh:mm:ss numeric time zone (e.g., -04:00:00) - - %:::z numeric time zone with : to necessary precision (e.g., - -04, +05:30) - - %Z alphabetic time zone abbreviation (e.g., EDT) - - %deltaS total elapsed seconds between the timestamp and now - - %deltaM total elapsed minutes between the timestamp and now - - %deltaH total elapsed hours between the timestamp and now - - %deltad total elapsed days between the timestamp and now - - %deltam total elapsed 30-day months between the timestamp and now - - %deltaY total elapsed 365-day years between the timestamp and now - - By default, date pads numeric fields with zeroes. The following - optional flags may follow '%': - - - (hyphen) do not pad the field - - _ (underscore) pad with spaces - - 0 (zero) pad with zeros - - + pad with zeros, and put '+' before future years with >4 - digits - - ^ use upper case if possible - - # use opposite case if possible - :see >time >time_format_relative -:related -**PHP:** `gmdate()` and UTC `DateTime` formatting -**JavaScript / Node.js:** `Date#toISOString()` and UTC formatting helpers +:content +Formats a timestamp in the GMT/UTC timezone. + +This formatter is based on the Linux `date` command and supports the same core formatting tokens plus UCE's relative-time delta tokens. + +Supported format sequences: + +```text +%% a literal % +%a locale's abbreviated weekday name (e.g., Sun) +%A locale's full weekday name (e.g., Sunday) +%b locale's abbreviated month name (e.g., Jan) +%B locale's full month name (e.g., January) +%c locale's date and time (e.g., Thu Mar 3 23:05:25 2005) +%C century; like %Y, except omit last two digits (e.g., 20) +%d day of month (e.g., 01) +%D date; same as %m/%d/%y +%e day of month, space padded; same as %_d +%F full date; like %+4Y-%m-%d +%g last two digits of year of ISO week number (see %G) +%G year of ISO week number (see %V); normally useful only with %V +%h same as %b +%H hour (00..23) +%I hour (01..12) +%j day of year (001..366) +%k hour, space padded ( 0..23); same as %_H +%l hour, space padded ( 1..12); same as %_I +%m month (01..12) +%M minute (00..59) +%n a newline +%N nanoseconds (000000000..999999999) +%p locale's equivalent of either AM or PM; blank if not known +%P like %p, but lower case +%q quarter of year (1..4) +%r locale's 12-hour clock time (e.g., 11:11:04 PM) +%R 24-hour hour and minute; same as %H:%M +%s seconds since 1970-01-01 00:00:00 UTC +%S second (00..60) +%t a tab +%T time; same as %H:%M:%S +%u day of week (1..7); 1 is Monday +%U week number of year, with Sunday as first day of week (00..53) +%V ISO week number, with Monday as first day of week (01..53) +%w day of week (0..6); 0 is Sunday +%W week number of year, with Monday as first day of week (00..53) +%x locale's date representation (e.g., 12/31/99) +%X locale's time representation (e.g., 23:13:48) +%y last two digits of year (00..99) +%Y year +%z +hhmm numeric time zone (e.g., -0400) +%:z +hh:mm numeric time zone (e.g., -04:00) +%::z +hh:mm:ss numeric time zone (e.g., -04:00:00) +%:::z numeric time zone with : to necessary precision (e.g., -04, +05:30) +%Z alphabetic time zone abbreviation (e.g., EDT) +%deltaS total elapsed seconds between the timestamp and now +%deltaM total elapsed minutes between the timestamp and now +%deltaH total elapsed hours between the timestamp and now +%deltad total elapsed days between the timestamp and now +%deltam total elapsed 30-day months between the timestamp and now +%deltaY total elapsed 365-day years between the timestamp and now +``` + +Padding and case flags may follow `%`: + +```text +- do not pad the field +_ pad with spaces +0 pad with zeros ++ pad with zeros, and put '+' before future years with >4 digits +^ use upper case if possible +# use opposite case if possible +``` + +Related: + +- PHP: `gmdate()` and UTC `DateTime` formatting +- JavaScript / Node.js: `Date#toISOString()` and UTC formatting helpers diff --git a/site/doc/pages/time_parse.txt b/site/doc/pages/time_parse.txt index 81b8415..ec8e6eb 100644 --- a/site/doc/pages/time_parse.txt +++ b/site/doc/pages/time_parse.txt @@ -5,12 +5,13 @@ u64 time_parse(String time_string) time_string : a string containing a date and/or time in text form return value : the interpreted 'time_string' as a Unix timestamp -:desc -Attempts to parse the given 'time_string' into a Unix timestamp. - :see >time -:related -**PHP:** `strtotime()` or `DateTimeImmutable` parsing -**JavaScript / Node.js:** `Date.parse()` or date-library parsing helpers +:content +Attempts to parse `time_string` into a Unix timestamp. + +Related: + +- PHP: `strtotime()` or `DateTimeImmutable` parsing +- JavaScript / Node.js: `Date.parse()` or date-library parsing helpers diff --git a/site/doc/pages/time_precise.txt b/site/doc/pages/time_precise.txt index f77c191..6e1afcc 100644 --- a/site/doc/pages/time_precise.txt +++ b/site/doc/pages/time_precise.txt @@ -4,12 +4,13 @@ f64 time_precise() :params return value : current Unix timestamp -:desc -Returns a 64 bit float containing the current Unix timestamp with millisecond accuracy or better. - :see >time -:related -**PHP:** `microtime(true)` or high-resolution timers -**JavaScript / Node.js:** `performance.now()` or high-resolution Node timers +:content +Returns the current Unix timestamp as a 64-bit float with millisecond accuracy or better. + +Related: + +- PHP: `microtime(true)` or high-resolution timers +- JavaScript / Node.js: `performance.now()` or high-resolution Node timers diff --git a/site/doc/pages/to_lower.txt b/site/doc/pages/to_lower.txt index bd03f04..3980247 100644 --- a/site/doc/pages/to_lower.txt +++ b/site/doc/pages/to_lower.txt @@ -5,14 +5,15 @@ String to_lower(String s) s : the string to be converted return value : returns a version of 's' where all upper case characters have been changed into lower case -:desc -Returns a lower case version of the input string 's'. - -Note: this function is not yet Unicode-aware. - :see >string -:related -**PHP:** `strtolower()` -**JavaScript / Node.js:** `String.prototype.toLowerCase()` +:content +Returns a lower-case version of `s`. + +This function is not yet Unicode-aware. + +Related: + +- PHP: `strtolower()` +- JavaScript / Node.js: `String.prototype.toLowerCase()` diff --git a/site/doc/pages/to_upper.txt b/site/doc/pages/to_upper.txt index c965fca..c9be3dc 100644 --- a/site/doc/pages/to_upper.txt +++ b/site/doc/pages/to_upper.txt @@ -5,14 +5,15 @@ String to_upper(String s) s : the string to be converted return value : returns a version of 's' where all lower case characters have been changed into upper case -:desc -Returns a upper case version of the input string 's'. - -Note: this function is not yet Unicode-aware. - :see >string -:related -**PHP:** `strtoupper()` -**JavaScript / Node.js:** `String.prototype.toUpperCase()` +:content +Returns an upper-case version of `s`. + +This function is not yet Unicode-aware. + +Related: + +- PHP: `strtoupper()` +- JavaScript / Node.js: `String.prototype.toUpperCase()` diff --git a/site/doc/pages/trim.txt b/site/doc/pages/trim.txt index ec7adbe..a9ec6b6 100644 --- a/site/doc/pages/trim.txt +++ b/site/doc/pages/trim.txt @@ -5,12 +5,13 @@ String trim(String raw) raw : string to be trimmed return value : string with leading and trailing whitespace characters removed -:desc -Returns a string where leading an trailing whitespace characters have been trimmed off. - :see >string -:related -**PHP:** `trim()` -**JavaScript / Node.js:** `String.prototype.trim()` +:content +Returns `raw` with leading and trailing whitespace removed. + +Related: + +- PHP: `trim()` +- JavaScript / Node.js: `String.prototype.trim()` diff --git a/site/doc/pages/unit_call.txt b/site/doc/pages/unit_call.txt index 43a22ff..556e6a8 100644 --- a/site/doc/pages/unit_call.txt +++ b/site/doc/pages/unit_call.txt @@ -7,26 +7,31 @@ function_name : name of the function to invoke call_param : optional, call parameter return value : DTree* returned from function -:desc +:see +>ob + +:content Calls an exported function inside another UCE file. -Use `unit_call()` when you need a structured data exchange between units rather than rendered HTML output. +Use `unit_call()` when you need structured data exchange between units rather than rendered HTML output. The callee must expose an `EXPORT` function whose name matches `function_name`. Arguments are passed through `call_param`, and the return value is a `DTree*` owned by the callee. -:Example +Example: + +```cpp // export a function EXPORT DTree* test_func(DTree* call_param) { print("HELLO FROM TEST FUNCTION"); return(0); } + // use that function in another file unit_call("call_file_funcs.uce", "test_func"); +``` -:related -**PHP:** `include`, `require`, or calling a function from an included module, especially when returning arrays or objects instead of rendering a view. -**JavaScript / Node.js:** Importing a module and calling an exported function, or dynamically loading a module and passing structured arguments. +Related: -:see ->ob +- PHP: `include`, `require`, or calling a function from an included module, especially when returning arrays or objects instead of rendering a view +- JavaScript / Node.js: importing a module and calling an exported function, or dynamically loading a module and passing structured arguments diff --git a/site/doc/pages/unit_compile.txt b/site/doc/pages/unit_compile.txt index cfaf0ab..9d3cd84 100644 --- a/site/doc/pages/unit_compile.txt +++ b/site/doc/pages/unit_compile.txt @@ -5,15 +5,16 @@ bool unit_compile(String path = "") path : optional UCE unit path. If empty, recompiles the current executing unit. return value : `true` when the unit was compiled and loaded successfully -:desc -Triggers a manual recompile of a UCE compilation unit. - -If `path` is relative, it is resolved relative to the current executing unit. Successful manual compiles also refresh the in-memory metadata for that unit. - :see unit_info units_list -:related -**PHP:** Template compilation or preloading steps that generate cached PHP artifacts -**JavaScript / Node.js:** Build-step compilation, bundling, or ahead-of-time template transforms +:content +Triggers a manual recompile of a UCE compilation unit. + +If `path` is relative, it is resolved relative to the current executing unit. Successful manual compiles also refresh the in-memory metadata for that unit. + +Related: + +- PHP: template compilation or preloading steps that generate cached PHP artifacts +- JavaScript / Node.js: build-step compilation, bundling, or ahead-of-time template transforms diff --git a/site/doc/pages/unit_info.txt b/site/doc/pages/unit_info.txt index e2c1806..aa6d154 100644 --- a/site/doc/pages/unit_info.txt +++ b/site/doc/pages/unit_info.txt @@ -5,7 +5,12 @@ DTree unit_info(String path = "") path : optional UCE unit path. If empty, uses the current executing unit. return value : metadata tree for the resolved unit, or an empty tree if the unit cannot be resolved -:desc +:see +units_list +unit_compile +0_context + +:content Returns runtime metadata for a UCE compilation unit. The returned tree includes: @@ -22,11 +27,7 @@ If `path` is relative, it is resolved relative to the current executing unit. Because unit metadata lives in process memory alongside `SharedUnit`, request and timing counters reflect the current runtime process, not an aggregate across every worker process. -:see -units_list -unit_compile -0_context +Related: -:related -**PHP:** Reflection-style metadata about included modules, callables, or exported capabilities -**JavaScript / Node.js:** Module metadata, reflection-like inspection, or manifest-based capability lookup +- PHP: reflection-style metadata about included modules, callables, or exported capabilities +- JavaScript / Node.js: module metadata, reflection-like inspection, or manifest-based capability lookup diff --git a/site/doc/pages/unit_load.txt b/site/doc/pages/unit_load.txt index 5625464..6a6a083 100644 --- a/site/doc/pages/unit_load.txt +++ b/site/doc/pages/unit_load.txt @@ -5,16 +5,17 @@ SharedUnit* unit_load(String file_name) file_name : UCE file to load return value : loaded shared unit, or `null` if the unit could not be loaded -:desc -Loads a UCE compilation unit and returns its in-memory `SharedUnit` record. - -This is a low-level runtime helper. Most application code should prefer `unit_render()`, `unit_call()`, `component()`, or `component_render()`. - :see unit_render unit_call load -:related -**PHP:** `include`, `require`, autoloaders, and lazy-loading of modules -**JavaScript / Node.js:** Dynamic `import()`, lazy module loading, or require-on-demand patterns +:content +Loads a UCE compilation unit and returns its in-memory `SharedUnit` record. + +This is a low-level runtime helper. Most application code should prefer `unit_render()`, `unit_call()`, `component()`, or `component_render()`. + +Related: + +- PHP: `include`, `require`, autoloaders, and lazy-loading of modules +- JavaScript / Node.js: dynamic `import()`, lazy module loading, or require-on-demand patterns diff --git a/site/doc/pages/unit_render.txt b/site/doc/pages/unit_render.txt index 3bf6587..6fc717e 100644 --- a/site/doc/pages/unit_render.txt +++ b/site/doc/pages/unit_render.txt @@ -6,21 +6,25 @@ void unit_render(String file_name, Request& context) file_name : UCE file to load and execute context : optional request context to pass into the target page -:desc +:see +>ob + +:content Calls another UCE file and executes its `RENDER(Request& context)` function. If `context` is omitted, the current active request context is used. -:Example +Examples: + +```cpp // call a common page template unit_render("page-template.uce"); // explicitly pass a request context unit_render("page-template.uce", context); +``` -:see ->ob +Related: -:related -**PHP:** Rendering another view or template with the current request state and captured output -**JavaScript / Node.js:** Calling another template renderer or SSR partial with the current request context +- PHP: rendering another view or template with the current request state and captured output +- JavaScript / Node.js: calling another template renderer or SSR partial with the current request context diff --git a/site/doc/pages/units_list.txt b/site/doc/pages/units_list.txt index 92c7104..0b57d8b 100644 --- a/site/doc/pages/units_list.txt +++ b/site/doc/pages/units_list.txt @@ -1,15 +1,16 @@ :sig std::vector units_list() -:desc -Returns the normalized paths of all known `.uce` units. - -This includes the shared known-unit registry plus any units already loaded in the current runtime process. - :see unit_info unit_compile -:related -**PHP:** Enumerating available modules, templates, or plugin entrypoints -**JavaScript / Node.js:** Listing registered modules, routes, or dynamically discovered components +:content +Returns the normalized paths of all known `.uce` units. + +This includes the shared known-unit registry plus any units already loaded in the current runtime process. + +Related: + +- PHP: enumerating available modules, templates, or plugin entrypoints +- JavaScript / Node.js: listing registered modules, routes, or dynamically discovered components diff --git a/site/doc/pages/uri_decode.txt b/site/doc/pages/uri_decode.txt index 44a9c57..d3b5f64 100644 --- a/site/doc/pages/uri_decode.txt +++ b/site/doc/pages/uri_decode.txt @@ -5,12 +5,13 @@ String uri_decode(String s) s : string containing URI encoded data return value : a string that contains the decoded version of 's' -:desc -Decodes an URI-encoded string 's'. - :see >uri -:related -**PHP:** `urldecode()` or `rawurldecode()` -**JavaScript / Node.js:** `decodeURIComponent()` +:content +Decodes a URI-encoded string. + +Related: + +- PHP: `urldecode()` or `rawurldecode()` +- JavaScript / Node.js: `decodeURIComponent()` diff --git a/site/doc/pages/uri_encode.txt b/site/doc/pages/uri_encode.txt index 6aaccfb..6db7d29 100644 --- a/site/doc/pages/uri_encode.txt +++ b/site/doc/pages/uri_encode.txt @@ -5,12 +5,13 @@ String uri_encode(String s) s : string that should be encoded return value : an URI-encoded version of 's' -:desc -URI-encodes a string. - :see >uri -:related -**PHP:** `urlencode()` or `rawurlencode()` -**JavaScript / Node.js:** `encodeURIComponent()` +:content +URI-encodes a string. + +Related: + +- PHP: `urlencode()` or `rawurlencode()` +- JavaScript / Node.js: `encodeURIComponent()` diff --git a/site/doc/pages/var_dump.txt b/site/doc/pages/var_dump.txt index ed20a78..9b1b769 100644 --- a/site/doc/pages/var_dump.txt +++ b/site/doc/pages/var_dump.txt @@ -7,10 +7,10 @@ String var_dump(DTree t, String prefix = "", String postfix = "\n") t : object to be dumped into a string return value : string containing a human-friendly representation of 't' -:desc -Returns a string representation of 't' intended for debugging. +:content +Returns a string representation of `t` intended for debugging. +Related: -:related -**PHP:** `var_dump()` and `print_r()` -**JavaScript / Node.js:** `console.log()`, `console.dir()`, and structured inspection helpers like `util.inspect()` +- PHP: `var_dump()` and `print_r()` +- JavaScript / Node.js: `console.log()`, `console.dir()`, and structured inspection helpers like `util.inspect()` diff --git a/site/doc/pages/ws_close.txt b/site/doc/pages/ws_close.txt index dbc44bc..ac5d5b7 100644 --- a/site/doc/pages/ws_close.txt +++ b/site/doc/pages/ws_close.txt @@ -5,14 +5,15 @@ bool ws_close(String connection_id = "") connection_id : optional target client ID, defaults to the current WebSocket client return value : true if the target connection exists and was scheduled to close -:desc +:see +>websocket + +:content Queues a WebSocket close frame and closes the targeted connection. If `connection_id` is omitted, the current connection handled by `WS(Request& context)` is closed. -:see ->websocket +Related: -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_connection_count.txt b/site/doc/pages/ws_connection_count.txt index 367aa5d..07fbfd3 100644 --- a/site/doc/pages/ws_connection_count.txt +++ b/site/doc/pages/ws_connection_count.txt @@ -5,14 +5,15 @@ u64 ws_connection_count(String scope = "") scope : optional scope identifier, defaults to the current WebSocket page scope return value : number of connected WebSocket clients in that scope -:desc +:see +>websocket + +:content Returns the number of currently connected WebSocket clients for the given scope. If `scope` is omitted, the current page scope is used. -:see ->websocket +Related: -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_connection_id.txt b/site/doc/pages/ws_connection_id.txt index d0ea57d..90c96a2 100644 --- a/site/doc/pages/ws_connection_id.txt +++ b/site/doc/pages/ws_connection_id.txt @@ -4,14 +4,15 @@ String ws_connection_id() :params return value : connection ID of the current WebSocket client -:desc +:see +>websocket + +:content Returns the runtime-generated connection ID of the client whose message is currently being handled. This ID can be passed to `ws_send_to()` or `ws_close()` to target a single connected client. -:see ->websocket +Related: -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_connections.txt b/site/doc/pages/ws_connections.txt index 8bb1924..4ced641 100644 --- a/site/doc/pages/ws_connections.txt +++ b/site/doc/pages/ws_connections.txt @@ -5,14 +5,15 @@ StringList ws_connections(String scope = "") scope : optional scope identifier, defaults to the current WebSocket page scope return value : list of connection IDs currently connected to that scope -:desc +:see +>websocket + +:content Returns the currently connected WebSocket client IDs for the given scope. If `scope` is omitted, the current page scope is used. -:see ->websocket +Related: -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_is_binary.txt b/site/doc/pages/ws_is_binary.txt index cada785..ceecc87 100644 --- a/site/doc/pages/ws_is_binary.txt +++ b/site/doc/pages/ws_is_binary.txt @@ -4,14 +4,15 @@ bool ws_is_binary() :params return value : true if the current WebSocket message is binary -:desc +:see +>websocket + +:content Returns whether the message currently being handled by `WS(Request& context)` arrived as a binary frame. If this returns `false`, the current message was delivered as a text frame. -:see ->websocket +Related: -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_message.txt b/site/doc/pages/ws_message.txt index 342fdf4..c81a542 100644 --- a/site/doc/pages/ws_message.txt +++ b/site/doc/pages/ws_message.txt @@ -4,16 +4,17 @@ String ws_message() :params return value : payload of the current WebSocket message -:desc -Returns the payload of the current WebSocket message being handled by `WS(Request& context)`. - -For text frames this is the decoded text payload. For binary frames this String contains the raw message bytes. - -Use `ws_is_binary()` or `ws_opcode()` to decide how the payload should be interpreted. - :see >websocket -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +:content +Returns the payload of the current WebSocket message being handled by `WS(Request& context)`. + +For text frames this is the decoded text payload. For binary frames this `String` contains the raw message bytes. + +Use `ws_is_binary()` or `ws_opcode()` to decide how the payload should be interpreted. + +Related: + +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_opcode.txt b/site/doc/pages/ws_opcode.txt index a7179c2..5bc64b5 100644 --- a/site/doc/pages/ws_opcode.txt +++ b/site/doc/pages/ws_opcode.txt @@ -4,7 +4,10 @@ u8 ws_opcode() :params return value : opcode of the current WebSocket message -:desc +:see +>websocket + +:content Returns the opcode of the message currently being handled by `WS(Request& context)`. Common values are: @@ -12,9 +15,7 @@ Common values are: - `0x1` for text messages - `0x2` for binary messages -:see ->websocket +Related: -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_scope.txt b/site/doc/pages/ws_scope.txt index eabf0fd..1420515 100644 --- a/site/doc/pages/ws_scope.txt +++ b/site/doc/pages/ws_scope.txt @@ -4,16 +4,17 @@ String ws_scope() :params return value : scope identifier of the current WebSocket endpoint -:desc +:see +>websocket + +:content Returns the runtime's scope identifier for the current WebSocket endpoint. This is the same default scope used by `ws_send()`, `ws_connections()`, and `ws_connection_count()` when no explicit scope is supplied. In the current runtime implementation this scope is the page's internal endpoint identifier, typically the absolute `SCRIPT_FILENAME` of the `.ws.uce` file. -:see ->websocket +Related: -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_send.txt b/site/doc/pages/ws_send.txt index e835471..d45eaeb 100644 --- a/site/doc/pages/ws_send.txt +++ b/site/doc/pages/ws_send.txt @@ -7,14 +7,15 @@ binary : set to true to send a binary frame instead of a text frame scope : optional scope identifier, defaults to the current WebSocket page scope return value : true if the message was queued for at least one connected client -:desc +:see +>websocket + +:content Queues a WebSocket message for every client connected to the given scope. If `scope` is omitted, the current page scope is used. -:see ->websocket +Related: -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/pages/ws_send_to.txt b/site/doc/pages/ws_send_to.txt index 340d69f..842715d 100644 --- a/site/doc/pages/ws_send_to.txt +++ b/site/doc/pages/ws_send_to.txt @@ -7,12 +7,13 @@ message : message payload to send binary : set to true to send a binary frame instead of a text frame return value : true if the target connection exists and the message was queued -:desc -Queues a WebSocket message for one specific connected client. - :see >websocket -:related -**PHP:** WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks -**JavaScript / Node.js:** Browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods +:content +Queues a WebSocket message for one specific connected client. + +Related: + +- PHP: WebSocket connection metadata and send APIs in Ratchet, Workerman, or similar server frameworks +- JavaScript / Node.js: browser `WebSocket` properties and Node `ws` server-side connection inspection and send methods diff --git a/site/doc/singlepage.uce b/site/doc/singlepage.uce index 9b392d6..8a57252 100644 --- a/site/doc/singlepage.uce +++ b/site/doc/singlepage.uce @@ -1,97 +1,157 @@ +struct DocPage { + String title; + String content; + StringList sig_lines; + StringList param_lines; + StringList see_lines; +}; + StringMap* already_shown_items; +String doc_default_title(String page) +{ + String page_title = page; + if(page_title.length() > 1 && page_title[1] == '_') + nibble(page_title, "_"); + return(page_title); +} + +String doc_markdown_inline(String text) +{ + text = trim(text); + if(text == "") + return(""); + String html = markdown_to_html(text); + if(html.length() >= 7 && html.substr(0, 3) == "

    " && html.substr(html.length() - 4) == "

    ") + return(html.substr(3, html.length() - 7)); + return(html); +} + +String doc_legacy_heading(String section) +{ + if(section == "desc") + return(""); + if(section == "related") + return("## PHP & JS Equivalents"); + return("## " + section); +} + +DocPage load_doc_page(String page) +{ + DocPage result; + StringList lines = split(file_get_contents("pages/" + page + ".txt"), "\n"); + String current_section = ""; + bool content_mode = false; + StringList content_lines; + + for(auto line : lines) + { + if(!content_mode && line != "" && line.substr(0, 1) == ":") + { + String section = trim(line.substr(1)); + if(section == "title" || section == "sig" || section == "params" || section == "see") + { + current_section = section; + continue; + } + if(section == "content") + { + content_mode = true; + current_section = "content"; + continue; + } + + current_section = "legacy"; + String heading = doc_legacy_heading(section); + if(heading != "") + { + if(content_lines.size() > 0 && content_lines.back() != "") + content_lines.push_back(""); + content_lines.push_back(heading); + content_lines.push_back(""); + } + continue; + } + + if(current_section == "title") + { + if(result.title != "") + result.title += "\n"; + result.title += line; + } + else if(current_section == "sig") + { + result.sig_lines.push_back(line); + } + else if(current_section == "params") + { + result.param_lines.push_back(line); + } + else if(current_section == "see") + { + if(trim(line) != "") + result.see_lines.push_back(trim(line)); + } + else + { + content_lines.push_back(line); + } + } + + result.content = join(content_lines, "\n"); + result.title = trim(result.title); + return(result); +} + +void render_doc_params(StringList param_lines) +{ + if(param_lines.size() == 0) + return; + + <>

    Parameters

    + for(auto line : param_lines) + { + if(trim(line) == "") + continue; + String name = trim(nibble(line, ":")); + String value = trim(line); + <>
    :
    + } + <>
    +} + void render_doc_page(String page) { (*already_shown_items)[page] = "Y"; - auto doc = split(file_get_contents("pages/"+page+".txt"), "\n"); - String layout_class = "text"; - u32 line_idx = 0; - for(auto s : doc) + DocPage doc_page = load_doc_page(page); + String title = doc_default_title(page); + if(doc_page.title != "") + title = doc_page.title; + + <>

    + if(doc_page.sig_lines.size() > 0) { - line_idx++; - if(s == "") - { + <>
    + } + <>
    - } - else if(s.substr(0, 1) == ":") - { - layout_class = s.substr(1); - if(line_idx > 1) - { - <> - } - <>
    - if(layout_class == "params") - { - <>

    Parameters

    - } - else if(layout_class == "sig") - { - String page_name = page; - if(page[1] == '_') - { - nibble(page_name, "_"); - } - <>

    - } - else if(layout_class == "pre") - { - layout_class = "sig"; - } - else if(layout_class == "desc") - { - <>

    Description

    - } - else if(layout_class == "related") - { - <>

    Related PHP and JS

    - } - else if(layout_class == "see") - { + render_doc_params(doc_page.param_lines); - } - else - { - <>

    - } - } - else - { - if(s.substr(0, 1) == "-") - { - nibble(s, "-"); - <>
    • - } - else if(layout_class == "sig") - { - <>
    - } - else if(layout_class == "params") - { - <>
    :
    - } - else if(layout_class == "see") - { - if(s[0] == '>') - { - //render_see_section(s.substr(1)); - } - else - { - <> - } - } - else - { - <>
    - } - } - } + if(trim(doc_page.content) != "") + { + <>
    + } + <>
    } void render_see_section(String name) { - StringList lines = split(file_get_contents("areas/"+name+".txt"), "\n"); + StringList lines = split(file_get_contents("areas/" + name + ".txt"), "\n"); s32 idx = 0; for(auto line : lines) { @@ -110,12 +170,9 @@ void render_see_section(String name) RENDER(Request& context) { - StringMap shown_items; already_shown_items = &shown_items; - String page = first(context.get["p"], "index"); - <> @@ -143,5 +200,4 @@ RENDER(Request& context) ?> - }