diff --git a/.gitignore b/.gitignore index 5fe7c3f..b950b0f 100644 --- a/.gitignore +++ b/.gitignore @@ -36,7 +36,7 @@ tmp/* bin/* pkg/* - +dist/* # Python cache artifacts __pycache__/ diff --git a/site/doc/areas/runtime.txt b/site/doc/areas/runtime.txt index 0cfc6f3..bfd5256 100644 --- a/site/doc/areas/runtime.txt +++ b/site/doc/areas/runtime.txt @@ -1,5 +1,8 @@ Runtime +backtrace_frames_string +capture_backtrace_string error_pages +signal_name unit_info units_list unit_compile diff --git a/site/doc/areas/string.txt b/site/doc/areas/string.txt index 481531e..dac2959 100644 --- a/site/doc/areas/string.txt +++ b/site/doc/areas/string.txt @@ -1,10 +1,13 @@ String Functions ascii_safe_name +base64_decode +base64_encode contains filter first join +json_consume_space json_encode list_every list_find @@ -19,6 +22,8 @@ str_ends_with str_starts_with substr split +split_http_headers +split_kv split_space split_utf8 replace diff --git a/site/doc/areas/sys.txt b/site/doc/areas/sys.txt index 1bb2a26..b67bbc1 100644 --- a/site/doc/areas/sys.txt +++ b/site/doc/areas/sys.txt @@ -4,6 +4,7 @@ basename dirname expand_path file_append +file_append_contents file_exists file_get_contents file_mtime diff --git a/site/doc/areas/time.txt b/site/doc/areas/time.txt index 1506cef..4b26639 100644 --- a/site/doc/areas/time.txt +++ b/site/doc/areas/time.txt @@ -1,5 +1,6 @@ Time and Date Functions +usleep time_precise time time_format_local diff --git a/site/doc/areas/uri.txt b/site/doc/areas/uri.txt index d3d7ae9..3edde51 100644 --- a/site/doc/areas/uri.txt +++ b/site/doc/areas/uri.txt @@ -12,5 +12,6 @@ route_path_normalize route_path_sanitize session_id_create parse_query +parse_uri uri_decode uri_encode diff --git a/site/doc/pages/backtrace_frames_string.txt b/site/doc/pages/backtrace_frames_string.txt new file mode 100644 index 0000000..e408fae --- /dev/null +++ b/site/doc/pages/backtrace_frames_string.txt @@ -0,0 +1,18 @@ +:sig +String backtrace_frames_string(void* const* frames, size_t size, u32 skip_frames = 0) + +:params +frames : frame pointer array returned by native backtrace collection +size : number of frames in the array +skip_frames : number of newest frames to omit +return value : formatted backtrace string + +:see +>runtime +capture_backtrace_string +signal_name + +:content +Formats a captured native backtrace frame array. + +Most page code should use `capture_backtrace_string()` instead. Use this helper when you already have raw frame pointers from lower-level diagnostic code. diff --git a/site/doc/pages/capture_backtrace_string.txt b/site/doc/pages/capture_backtrace_string.txt new file mode 100644 index 0000000..d2f7776 --- /dev/null +++ b/site/doc/pages/capture_backtrace_string.txt @@ -0,0 +1,24 @@ +:sig +String capture_backtrace_string(u32 max_frames = 32, u32 skip_frames = 0) + +:params +max_frames : maximum number of frames to capture +skip_frames : number of newest frames to omit +return value : formatted backtrace string + +:see +>runtime +backtrace_frames_string +signal_name + +:content +Captures and formats a native backtrace for the current call stack. + +This helper is for diagnostics. It is used by runtime error reporting paths and can also be useful in local debugging pages. + +Example: + +```uce +String trace = capture_backtrace_string(16, 0); +print("
", html_escape(trace), "
"); +``` diff --git a/site/doc/pages/file_append_contents.txt b/site/doc/pages/file_append_contents.txt new file mode 100644 index 0000000..262d7a9 --- /dev/null +++ b/site/doc/pages/file_append_contents.txt @@ -0,0 +1,26 @@ +:sig +bool file_append_contents(String file_name, String content) + +:params +file_name : path to open or create +content : bytes to append +return value : `true` when the append succeeds + +:see +>sys +file_append +file_put_contents +file_get_contents + +:content +Appends one string to a file. + +`file_append()` is the variadic convenience wrapper for ordinary page code. Use `file_append_contents()` when you already have one string buffer. + +Example: + +```uce +bool ok = file_append_contents("/tmp/uce-log.txt", "line\n"); +``` + +The file is created if it does not exist. diff --git a/site/doc/pages/json_consume_space.txt b/site/doc/pages/json_consume_space.txt new file mode 100644 index 0000000..5665dc5 --- /dev/null +++ b/site/doc/pages/json_consume_space.txt @@ -0,0 +1,24 @@ +:sig +void json_consume_space(String s, u32& i) + +:params +s : JSON source string +i : current byte offset; advanced past JSON whitespace + +:see +>string +json_encode +json_decode + +:content +Advances `i` past JSON whitespace in `s`. + +This helper is mainly useful when writing a parser that follows UCE's JSON parsing rules. Most page code should call `json_decode()` instead. + +Example: + +```uce +u32 i = 0; +json_consume_space(" \n {\"ok\":true}", i); +// i now points at the opening brace +``` diff --git a/site/doc/pages/parse_uri.txt b/site/doc/pages/parse_uri.txt new file mode 100644 index 0000000..aef1636 --- /dev/null +++ b/site/doc/pages/parse_uri.txt @@ -0,0 +1,28 @@ +:sig +URI parse_uri(String uri_string) + +:params +uri_string : URI or URL string +return value : URI object with `parts` and `query` maps + +:see +>uri +parse_query +uri_decode +uri_encode + +:content +Parses a URI into its component maps. + +`return.parts` contains the parsed URI fields. `return.query` contains query parameters decoded with the same rules as `parse_query()`. + +Example: + +```uce +URI uri = parse_uri("https://example.test/docs/index.uce?q=uce#top"); +String host = uri.parts["host"]; +String path = uri.parts["path"]; +String q = uri.query["q"]; +``` + +Use `parse_uri()` when you need to inspect a full URL. Use `parse_query()` when you only have the query string. diff --git a/site/doc/pages/signal_name.txt b/site/doc/pages/signal_name.txt new file mode 100644 index 0000000..9cc922c --- /dev/null +++ b/site/doc/pages/signal_name.txt @@ -0,0 +1,23 @@ +:sig +String signal_name(int sig) + +:params +sig : POSIX signal number +return value : signal name such as `SIGSEGV`, or an empty string when unknown + +:see +>runtime +capture_backtrace_string +backtrace_frames_string + +:content +Returns a readable name for a POSIX signal number. + +Example: + +```uce +String name = signal_name(11); +// name == "SIGSEGV" +``` + +This is mostly useful in diagnostics and error reporting code. diff --git a/site/doc/pages/split_http_headers.txt b/site/doc/pages/split_http_headers.txt new file mode 100644 index 0000000..61833d9 --- /dev/null +++ b/site/doc/pages/split_http_headers.txt @@ -0,0 +1,29 @@ +:sig +StringMap split_http_headers(String s) + +:params +s : HTTP request or header text +return value : parsed request/header fields + +:see +>string +split_kv +parse_query +0_Request + +:content +Parses HTTP request/header text into a `StringMap`. + +For a request line, the returned map includes fields such as `REQUEST_METHOD`, `REQUEST_URI`, `SCRIPT_NAME`, `QUERY_STRING`, and `SERVER_PROTOCOL`. Header names are normalized to uppercase CGI-style keys, for example `Host` becomes `HTTP_HOST`. + +Example: + +```uce +StringMap h = split_http_headers("GET /demo.uce?x=1 HTTP/1.1\r\nHost: example.test\r\n\r\n"); +// h["REQUEST_METHOD"] == "GET" +// h["SCRIPT_NAME"] == "/demo.uce" +// h["QUERY_STRING"] == "x=1" +// h["HTTP_HOST"] == "example.test" +``` + +Most page code should read `context.params` instead. Use this helper when parsing raw HTTP text in tests or protocol helpers. diff --git a/site/doc/pages/usleep.txt b/site/doc/pages/usleep.txt new file mode 100644 index 0000000..cb60b55 --- /dev/null +++ b/site/doc/pages/usleep.txt @@ -0,0 +1,23 @@ +:sig +int usleep(unsigned int usec) + +:params +usec : microseconds to sleep +return value : `0` after sleeping + +:see +>time +sleep + +:content +Pauses the current request or task for a number of microseconds. + +Use this for short waits in local tests, polling loops, or background tasks. Avoid long sleeps in normal HTTP render paths because they hold a worker process for the duration. + +Example: + +```uce +usleep(250000); // 0.25 seconds +``` + +For whole-second waits, use `sleep()`.