runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/warning.js

@@ -0,0 +1,159 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "warning",
+    "category": "diagnostics",
+    "keywords": [
+        "warning",
+        "diagnostics",
+        "state",
+        "query",
+        "backtrace"
+    ],
+    "summary": "Display formatted warnings, control warning state, and query per-identifier settings.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host. GPU tensors appearing in formatted arguments are gathered before formatting."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::diagnostics::warning::tests",
+        "integration": null
+    },
+    "description": "`warning` emits diagnostic messages without aborting execution. It also provides a central interface for enabling, disabling, promoting, or querying warnings by identifier.\n\nRunMat mirrors MATLAB semantics with per-identifier modes (`'on'`, `'off'`, `'once'`, `'error'`), backtrace control, structured state restoration, and formatted message support. When an identifier is promoted to `'error'`, future uses of that warning raise an error instead of printing.",
+    "behaviors": [
+        "`warning(message)` prints the message using the default identifier `RunMat:warning`.",
+        "`warning(id, fmt, args...)` associates the warning with the identifier `id`, formats the message using MATLAB's `sprintf` rules, and honours per-identifier state.",
+        "`warning(MException_obj)` reissues an existing exception as a warning.",
+        "`warning(struct)` restores warning state previously captured with `warning('query', ...)`.",
+        "`warning(state, id)` changes the mode for `id` (`'on'`, `'off'`, `'once'`, `'error'`, and the aliases `'all'` or `'last'`). The call returns a struct describing the prior state so you can restore it later.",
+        "`warning(state, mode)` controls diagnostic verbosity modes such as `'backtrace'` and `'verbose'`, returning a struct snapshot of the previous setting.",
+        "`warning('default', id)` resets `id` (or `'all'`, `'backtrace'`, `'verbose'`, `'last'`) to the factory default, returning the state that was active before the reset. `warning('reset')` restores every warning, mode, and once-tracking flag in one call.",
+        "`warning('query', id)` returns a struct describing the current mode for `id`. Passing `'all'` returns a cell vector of structs covering every configured identifier plus the global default and diagnostic modes.",
+        "`warning('status')` prints the global warning table as a formatted summary.",
+        "All state-changing forms return struct snapshots; pass them back to `warning` later to reinstate the captured state."
+    ],
+    "examples": [
+        {
+            "description": "Displaying a simple warning",
+            "input": "warning(\"Computation took longer than expected.\")"
+        },
+        {
+            "description": "Emitting a warning with a custom identifier",
+            "input": "warning(\"runmat:io:deprecatedOption\", ...\n        \"Option '%s' is deprecated and will be removed in %s.\", ...\n        \"VerboseMode\", \"1.2\")"
+        },
+        {
+            "description": "Turning a specific warning off and back on",
+            "input": "warning(\"off\", \"runmat:io:deprecatedOption\");\n% ... code that triggers the warning ...\nwarning(\"on\", \"runmat:io:deprecatedOption\")"
+        },
+        {
+            "description": "Promoting a warning to an error",
+            "input": "warning(\"error\", \"runmat:solver:illConditioned\");\n% The next call raises an error instead of printing a warning.\nwarning(\"runmat:solver:illConditioned\", ...\n        \"Condition number exceeds threshold %.2e.\", 1e12)"
+        },
+        {
+            "description": "Querying and restoring warning state",
+            "input": "state = warning(\"query\", \"all\");   % capture the current table\nwarning(\"off\", \"all\");              % silence all warnings temporarily\nwarning(\"Some temporary warning.\");\nwarning(state);                    % restore original configuration"
+        },
+        {
+            "description": "Enabling backtraces for debugging",
+            "input": "warning(\"on\", \"backtrace\");   % warning(\"backtrace\",\"on\") is equivalent\nwarning(\"runmat:demo:slowPath\", \"Inspect the call stack above for context.\");\nwarning(\"off\", \"backtrace\")"
+        },
+        {
+            "description": "Displaying verbose suppression guidance",
+            "input": "warning(\"on\", \"verbose\");\nwarning(\"runmat:demo:slowPath\", \"Inspect the call stack above for context.\");\nwarning(\"default\", \"verbose\");   % restore the default verbosity"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does RunMat keep track of the last warning?",
+            "answer": "Yes. The last identifier and message are stored internally and will be exposed through the MATLAB-compatible `lastwarn` builtin."
+        },
+        {
+            "question": "What does `'once'` do?",
+            "answer": "The first occurrence of the warning is shown, and subsequent uses of the same identifier are suppressed until you change the state."
+        },
+        {
+            "question": "How do I restore defaults after experimentation?",
+            "answer": "Call `warning('reset')` to revert the global default, per-identifier table, diagnostic modes, and once-tracking."
+        },
+        {
+            "question": "Do state-changing calls return anything useful?",
+            "answer": "Yes. Forms such as `warning('off','id')`, `warning('on','backtrace')`, and `warning('default')` return struct snapshots describing the state before the change. Store the struct and pass it back to `warning` later to restore the captured configuration."
+        },
+        {
+            "question": "What does the `'verbose'` mode do?",
+            "answer": "When enabled (`warning('on','verbose')`), RunMat prints an additional hint describing how to suppress the warning. Disable it with `warning('default','verbose')`."
+        },
+        {
+            "question": "What happens when a warning is promoted to `'error'`?",
+            "answer": "The warning text is reused to raise an error with the same identifier, just like MATLAB."
+        },
+        {
+            "question": "Does `warning` run on the GPU?",
+            "answer": "No. Control-flow builtins execute on the host. GPU inputs referenced in formatted messages are gathered automatically before the message is emitted."
+        },
+        {
+            "question": "Can I provide multiple state structs to `warning(state)`?",
+            "answer": "Yes. Pass either a struct or a cell array of structs (as returned by `warning('query','all')`); RunMat applies them sequentially."
+        },
+        {
+            "question": "Does `warning('on','backtrace')` match MATLAB output exactly?",
+            "answer": "RunMat prints a Rust backtrace for now. Future releases will map this to MATLAB-style stack frames, but the enable/disable semantics match MATLAB."
+        },
+        {
+            "question": "Is whitespace in identifiers allowed?",
+            "answer": "Identifiers follow MATLAB rules: they must contain at least one colon and no whitespace. RunMat normalises bare names by prefixing `RunMat:`."
+        },
+        {
+            "question": "What if I call `warning` with unsupported arguments?",
+            "answer": "RunMat issues a MATLAB-compatible usage error so you can correct the call."
+        },
+        {
+            "question": "Are repeated calls thread-safe?",
+            "answer": "Internally the warning table is guarded by a mutex, so concurrent invocations are serialised and remain deterministic."
+        }
+    ],
+    "links": [
+        {
+            "label": "error",
+            "url": "./error"
+        },
+        {
+            "label": "sprintf",
+            "url": "./sprintf"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        },
+        {
+            "label": "assert",
+            "url": "./assert"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/diagnostics/warning.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/diagnostics/warning.rs"
+    },
+    "gpu_residency": "`warning` is a control-flow builtin that runs on the host. When formatted arguments include GPU resident arrays (for example via `%g` specifiers), RunMat gathers the values to host memory before formatting the message so the diagnostic text matches MATLAB expectations.",
+    "gpu_behavior": [
+        "`warning` is a control-flow builtin that runs on the host. When formatted arguments include GPU resident arrays (for example via `%g` specifiers), RunMat gathers the values to host memory before formatting the message so the diagnostic text matches MATLAB expectations."
+    ],
+    "key": "warning",
+    "slug": "warning",
+    "categoryPath": [
+        "diagnostics"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=warning.js.map

package/dist/generated/builtins/warning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warning.js","sourceRoot":"","sources":["../../../src/generated/builtins/warning.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/weboptions.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=weboptions.d.ts.map

package/dist/generated/builtins/weboptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weboptions.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/weboptions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAsIjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/weboptions.js

@@ -0,0 +1,139 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "weboptions",
+    "category": "io/http",
+    "keywords": [
+        "weboptions",
+        "http options",
+        "timeout",
+        "headers",
+        "rest client"
+    ],
+    "summary": "Create an options struct that configures webread and webwrite HTTP behaviour.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/weboptions.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "weboptions operates on CPU data structures and gathers gpuArray inputs automatically."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::http::weboptions::tests",
+        "integration": [
+            "builtins::io::http::weboptions::tests::weboptions_default_struct_matches_expected_fields",
+            "builtins::io::http::weboptions::tests::weboptions_overrides_timeout_and_headers",
+            "builtins::io::http::weboptions::tests::weboptions_updates_existing_struct",
+            "builtins::io::http::weboptions::tests::weboptions_rejects_unknown_option",
+            "builtins::io::http::weboptions::tests::weboptions_requires_username_when_password_provided",
+            "builtins::io::http::weboptions::tests::weboptions_rejects_timeout_nonpositive",
+            "builtins::io::http::weboptions::tests::weboptions_rejects_headerfields_bad_cell_shape",
+            "builtins::io::http::weboptions::tests::webread_uses_weboptions_without_polluting_query",
+            "builtins::io::http::weboptions::tests::webwrite_uses_weboptions_auto_request_method"
+        ]
+    },
+    "description": "`weboptions` builds a MATLAB-style options struct that controls HTTP behaviour for functions such as `webread`, `webwrite`, and `websave`. The struct stores option fields like `Timeout`, `ContentType`, `HeaderFields`, and `RequestMethod`, all with MATLAB-compatible defaults.",
+    "behaviors": [
+        "Returns a struct with canonical field names: `ContentType`, `Timeout`, `HeaderFields`, `UserAgent`, `Username`, `Password`, `RequestMethod`, `MediaType`, and `QueryParameters`.",
+        "Defaults mirror MATLAB: `ContentType=\"auto\"`, `Timeout=60`, `UserAgent=\"\"` (RunMat substitutes a default agent when this is empty), `RequestMethod=\"auto\"`, `MediaType=\"auto\"`, and empty structs for `HeaderFields` and `QueryParameters`.",
+        "Name-value arguments are case-insensitive. Values are validated to ensure MATLAB-compatible types (text scalars for string options, positive scalars for `Timeout`, structs or two-column cell arrays for `HeaderFields` and `QueryParameters`).",
+        "Passing an existing options struct as the first argument clones it before applying additional overrides, matching MATLAB's update pattern `opts = weboptions(opts, \"Timeout\", 5)`.",
+        "Unknown option names raise descriptive errors."
+    ],
+    "examples": [
+        {
+            "description": "Setting custom timeouts for webread calls",
+            "input": "opts = weboptions(\"Timeout\", 10);\nhtml = webread(\"https://example.com\", opts)"
+        },
+        {
+            "description": "Providing HTTP basic authentication credentials",
+            "input": "opts = weboptions(\"Username\", \"ada\", \"Password\", \"lovelace\");\nprofile = webread(\"https://api.example.com/me\", opts)"
+        },
+        {
+            "description": "Sending JSON payloads with webwrite",
+            "input": "opts = weboptions(\"ContentType\", \"json\", \"MediaType\", \"application/json\");\npayload = struct(\"title\", \"RunMat\", \"stars\", 5);\nreply = webwrite(\"https://api.example.com/projects\", payload, opts)"
+        },
+        {
+            "description": "Applying custom headers with struct syntax",
+            "input": "headers = struct(\"Accept\", \"application/json\", \"X-Client\", \"RunMat\");\nopts = weboptions(\"HeaderFields\", headers);\ndata = webread(\"https://api.example.com/resources\", opts)"
+        },
+        {
+            "description": "Combining existing options with overrides",
+            "input": "base = weboptions(\"ContentType\", \"json\");\nopts = weboptions(base, \"Timeout\", 15, \"QueryParameters\", struct(\"verbose\", true));\nresult = webread(\"https://api.example.com/items\", opts)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which option names are supported in RunMat?",
+            "answer": "`weboptions` implements the options consumed by `webread` and `webwrite`: `ContentType`, `Timeout`, `HeaderFields`, `UserAgent`, `Username`, `Password`, `RequestMethod`, `MediaType`, and `QueryParameters`. Unknown names raise a MATLAB-style error."
+        },
+        {
+            "question": "What does `RequestMethod=\"auto\"` mean?",
+            "answer": "`webread` treats `\"auto\"` as `\"get\"` while `webwrite` maps it to `\"post\"`. Override the method when you need `put`, `patch`, or `delete`."
+        },
+        {
+            "question": "How are empty usernames or passwords handled?",
+            "answer": "Empty strings leave authentication disabled. A non-empty password without a username raises a MATLAB-compatible error."
+        },
+        {
+            "question": "Can I pass query parameters through the options struct?",
+            "answer": "Yes. Supply a struct or two-column cell array in the `QueryParameters` option. Values may include numbers, logicals, or text scalars, and they are percent-encoded when the request is built."
+        },
+        {
+            "question": "Do I need to manage GPU residency for options?",
+            "answer": "No. `weboptions` gathers any GPU-resident values automatically and always returns a host struct. HTTP builtins ignore GPU residency for metadata."
+        },
+        {
+            "question": "Does `weboptions` mutate the input struct?",
+            "answer": "No. A copy is made before overrides are applied, preserving the original struct you pass in."
+        },
+        {
+            "question": "How can I clear headers or query parameters?",
+            "answer": "Pass an empty struct (`struct()`) or empty cell array (`{}`) to reset the respective option."
+        }
+    ],
+    "links": [
+        {
+            "label": "webread",
+            "url": "./webread"
+        },
+        {
+            "label": "webwrite",
+            "url": "./webwrite"
+        },
+        {
+            "label": "jsondecode",
+            "url": "./jsondecode"
+        },
+        {
+            "label": "jsonencode",
+            "url": "./jsonencode"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/http/weboptions.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/http/weboptions.rs"
+    },
+    "gpu_residency": "No. `weboptions` gathers any GPU-resident values automatically and always returns a host struct. HTTP builtins ignore GPU residency for metadata.",
+    "gpu_behavior": [
+        "`weboptions` operates entirely on CPU metadata. It gathers any `gpuArray` inputs back to host memory before validation, because HTTP requests execute on the CPU regardless of the selected acceleration provider. No GPU provider hooks are required for this function."
+    ],
+    "key": "weboptions",
+    "slug": "weboptions",
+    "categoryPath": [
+        "io",
+        "http"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=weboptions.js.map

package/dist/generated/builtins/weboptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"weboptions.js","sourceRoot":"","sources":["../../../src/generated/builtins/weboptions.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,YAAY;IACrB,UAAU,EAAE,SAAS;IACrB,UAAU,EAAE;QACV,YAAY;QACZ,cAAc;QACd,SAAS;QACT,SAAS;QACT,aAAa;KACd;IACD,SAAS,EAAE,+EAA+E;IAC1F,YAAY,EAAE;QACZ,2DAA2D;KAC5D;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,uFAAuF;KACjG;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,uCAAuC;QAC/C,aAAa,EAAE;YACb,0FAA0F;YAC1F,iFAAiF;YACjF,2EAA2E;YAC3E,0EAA0E;YAC1E,4FAA4F;YAC5F,+EAA+E;YAC/E,uFAAuF;YACvF,wFAAwF;YACxF,qFAAqF;SACtF;KACF;IACD,aAAa,EAAE,qRAAqR;IACpS,WAAW,EAAE;QACX,kLAAkL;QAClL,qPAAqP;QACrP,kPAAkP;QAClP,sLAAsL;QACtL,gDAAgD;KACjD;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,oFAAoF;SAC9F;QACD;YACE,aAAa,EAAE,iDAAiD;YAChE,OAAO,EAAE,gIAAgI;SAC1I;QACD;YACE,aAAa,EAAE,qCAAqC;YACpD,OAAO,EAAE,mNAAmN;SAC7N;QACD;YACE,aAAa,EAAE,4CAA4C;YAC3D,OAAO,EAAE,2LAA2L;SACrM;QACD;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,qMAAqM;SAC/M;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,6CAA6C;YACzD,QAAQ,EAAE,yPAAyP;SACpQ;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,iJAAiJ;SAC5J;QACD;YACE,UAAU,EAAE,+CAA+C;YAC3D,QAAQ,EAAE,wHAAwH;SACnI;QACD;YACE,UAAU,EAAE,yDAAyD;YACrE,QAAQ,EAAE,+LAA+L;SAC1M;QACD;YACE,UAAU,EAAE,gDAAgD;YAC5D,QAAQ,EAAE,mJAAmJ;SAC9J;QACD;YACE,UAAU,EAAE,4CAA4C;YACxD,QAAQ,EAAE,8FAA8F;SACzG;QACD;YACE,UAAU,EAAE,8CAA8C;YAC1D,QAAQ,EAAE,8FAA8F;SACzG;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,cAAc;SACtB;QACD;YACE,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,cAAc;SACtB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,4DAA4D;QACrE,KAAK,EAAE,yGAAyG;KACjH;IACD,eAAe,EAAE,mJAAmJ;IACpK,cAAc,EAAE;QACd,0QAA0Q;KAC3Q;IACD,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,YAAY;IACpB,cAAc,EAAE;QACd,IAAI;QACJ,MAAM;KACP;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/webread.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=webread.d.ts.map

package/dist/generated/builtins/webread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webread.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/webread.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAoJjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/webread.js

@@ -0,0 +1,153 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "webread",
+    "category": "io/http",
+    "keywords": [
+        "webread",
+        "http get",
+        "rest client",
+        "json",
+        "https",
+        "api"
+    ],
+    "summary": "Download web content (JSON, text, or binary) over HTTP/HTTPS.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/webread.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "webread always gathers gpuArray inputs and executes on the CPU."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::http::webread::tests",
+        "integration": [
+            "builtins::io::http::webread::tests::webread_fetches_json_response",
+            "builtins::io::http::webread::tests::webread_fetches_text_response",
+            "builtins::io::http::webread::tests::webread_fetches_binary_payload",
+            "builtins::io::http::webread::tests::webread_appends_query_parameters",
+            "builtins::io::http::webread::tests::webread_struct_argument_supports_options_and_query",
+            "builtins::io::http::webread::tests::webread_headerfields_struct_applies_custom_headers",
+            "builtins::io::http::webread::tests::webread_queryparameters_option_struct"
+        ]
+    },
+    "description": "`webread` issues an HTTP or HTTPS request and returns the response body as a MATLAB-compatible value. Textual payloads become character vectors, JSON responses are decoded into structs, cells, and numeric arrays, while binary payloads return numeric vectors of bytes.",
+    "behaviors": [
+        "Accepts URLs supplied as character vectors or string scalars; the URL must be absolute.",
+        "Optional `weboptions`-style fields (either through a struct argument or name-value pairs) control content decoding (`ContentType`), request timeout (`Timeout`), headers (`HeaderFields`), and authentication (`Username`/`Password`). The builtin currently supports the default `GET` request method; use `webwrite` for POST/PUT uploads.",
+        "Additional name-value pairs that do not match an option are appended to the query string using percent-encoding. A leading struct or cell array argument can also supply query parameters.",
+        "`ContentType 'auto'` (default) inspects the `Content-Type` response header to choose between JSON, text, or binary decoding. Explicit `ContentType 'json'`, `'text'`, or `'binary'` override the detection logic.",
+        "JSON responses are parsed with the same rules as `jsondecode`, producing doubles, logicals, strings, structs, and cell arrays that match MATLAB semantics.",
+        "Text responses preserve the server-provided character encoding (UTF-8 with automatic decoding of exotic charsets exposed in the HTTP headers). Binary payloads return `1×N` double arrays whose entries store byte values in the range 0–255.",
+        "HTTP errors (non-2xx status codes), timeouts, TLS failures, and parsing problems raise descriptive MATLAB-style errors."
+    ],
+    "examples": [
+        {
+            "description": "Reading JSON data from a REST API",
+            "input": "opts = weboptions(\"ContentType\", \"json\", \"Timeout\", 15);\nweather = webread(\"https://api.example.com/weather\", opts, \"city\", \"Reykjavik\");\ndisp(weather.temperatureC)",
+            "output": "    2.3"
+        },
+        {
+            "description": "Downloading plain text as a character vector",
+            "input": "html = webread(\"https://example.com/index.txt\", \"Timeout\", 5);\nextract = html(1:200)"
+        },
+        {
+            "description": "Retrieving binary payloads such as images",
+            "input": "bytes = webread(\"https://example.com/logo.png\", \"ContentType\", \"binary\");\nfilewrite(\"logo.png\", uint8(bytes))"
+        },
+        {
+            "description": "Supplying custom headers and credentials",
+            "input": "headers = struct(\"Accept\", \"application/json\", \"X-Client\", \"RunMat\");\ndata = webread(\"https://api.example.com/me\", ...\n               \"Username\", \"ada\", \"Password\", \"secret\", ...\n               \"HeaderFields\", headers, ...\n               \"ContentType\", \"json\")"
+        },
+        {
+            "description": "Passing query parameters as a struct",
+            "input": "query = struct(\"limit\", 25, \"sort\", \"name\");\nresponse = webread(\"https://api.example.com/resources\", query, \"ContentType\", \"json\")"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Can `webread` decode JSON automatically?",
+            "answer": "Yes. When the server reports a JSON `Content-Type` header (for example `application/json` or `application/vnd.api+json`) the builtin decodes it using the same rules as `jsondecode`. Override the behaviour with `\"ContentType\",\"text\"` or `\"ContentType\",\"binary\"` when needed."
+        },
+        {
+            "question": "How do I control request timeouts?",
+            "answer": "Supply `\"Timeout\", seconds` as a name-value pair or in an options struct. The default timeout is 60 seconds. Timeouts raise `webread: request to <url> timed out`."
+        },
+        {
+            "question": "What headers can I set?",
+            "answer": "Use `\"HeaderFields\", struct(...)` or a `cell` array of name/value pairs. Header names must be valid HTTP tokens. The builtin automatically sets a RunMat-specific `User-Agent` string unless you override it with `\"UserAgent\", \"...\"`"
+        },
+        {
+            "question": "Does `webread` follow redirects?",
+            "answer": "Yes. The underlying HTTP client follows redirects up to the platform default limit while preserving headers and authentication."
+        },
+        {
+            "question": "How do I provide credentials?",
+            "answer": "Use `\"Username\", \"user\", \"Password\", \"pass\"` for HTTP basic authentication. Supplying a password without a username raises an error."
+        },
+        {
+            "question": "Can I send POST or PUT requests?",
+            "answer": "`webread` is designed for read-only requests and currently supports the default `GET` method. Use `webwrite` (planned) for requests that include bodies or mutate server state."
+        },
+        {
+            "question": "How are binary responses represented?",
+            "answer": "Binary payloads return `1×N` double arrays whose elements are byte values. Convert them to the desired integer type (for example `uint8`) before further processing."
+        },
+        {
+            "question": "What happens when the server returns an error status?",
+            "answer": "Non-success HTTP status codes raise `webread: request to … failed with HTTP status XYZ`. Inspect the remote server logs or response headers for additional diagnostics."
+        },
+        {
+            "question": "Does `webread` support compressed responses?",
+            "answer": "Yes. The builtin enables gzip / deflate content decoding through the HTTP client automatically."
+        },
+        {
+            "question": "Can I pass query parameters as GPU arrays?",
+            "answer": "Yes. Inputs wrapped in `gpuArray` are gathered before assembling the query string."
+        }
+    ],
+    "links": [
+        {
+            "label": "webwrite",
+            "url": "./webwrite"
+        },
+        {
+            "label": "weboptions",
+            "url": "./weboptions"
+        },
+        {
+            "label": "jsondecode",
+            "url": "./jsondecode"
+        },
+        {
+            "label": "websave",
+            "url": "./filewrite"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/http/webread.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/http/webread.rs"
+    },
+    "gpu_residency": "No. `webread` gathers any GPU-resident values before contacting the network and produces host results. Keeping inputs on the GPU offers no benefit because HTTP/TLS stacks operate on the CPU.",
+    "gpu_behavior": [
+        "`webread` runs entirely on the CPU. Any `gpuArray` inputs (for example, query parameter values) are gathered to host memory before building the HTTP request. Results are produced on the host, and fusion graphs terminate at this builtin via `ResidencyPolicy::GatherImmediately`."
+    ],
+    "key": "webread",
+    "slug": "webread",
+    "categoryPath": [
+        "io",
+        "http"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=webread.js.map

package/dist/generated/builtins/webread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webread.js","sourceRoot":"","sources":["../../../src/generated/builtins/webread.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,SAAS;IACrB,UAAU,EAAE;QACV,SAAS;QACT,UAAU;QACV,aAAa;QACb,MAAM;QACN,OAAO;QACP,KAAK;KACN;IACD,SAAS,EAAE,+DAA+D;IAC1E,YAAY,EAAE;QACZ,wDAAwD;KACzD;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,iEAAiE;KAC3E;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,oCAAoC;QAC5C,aAAa,EAAE;YACb,mEAAmE;YACnE,mEAAmE;YACnE,oEAAoE;YACpE,sEAAsE;YACtE,wFAAwF;YACxF,wFAAwF;YACxF,2EAA2E;SAC5E;KACF;IACD,aAAa,EAAE,6QAA6Q;IAC5R,WAAW,EAAE;QACX,yFAAyF;QACzF,8UAA8U;QAC9U,4LAA4L;QAC5L,mNAAmN;QACnN,4JAA4J;QAC5J,+OAA+O;QAC/O,yHAAyH;KAC1H;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,mCAAmC;YAClD,OAAO,EAAE,oLAAoL;YAC7L,QAAQ,EAAE,SAAS;SACpB;QACD;YACE,aAAa,EAAE,8CAA8C;YAC7D,OAAO,EAAE,2FAA2F;SACrG;QACD;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,wHAAwH;SAClI;QACD;YACE,aAAa,EAAE,0CAA0C;YACzD,OAAO,EAAE,kSAAkS;SAC5S;QACD;YACE,aAAa,EAAE,sCAAsC;YACrD,OAAO,EAAE,iJAAiJ;SAC3J;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,2RAA2R;SACtS;QACD;YACE,UAAU,EAAE,oCAAoC;YAChD,QAAQ,EAAE,sKAAsK;SACjL;QACD;YACE,UAAU,EAAE,yBAAyB;YACrC,QAAQ,EAAE,8OAA8O;SACzP;QACD;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,iIAAiI;SAC5I;QACD;YACE,UAAU,EAAE,+BAA+B;YAC3C,QAAQ,EAAE,8IAA8I;SACzJ;QACD;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,iLAAiL;SAC5L;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,sKAAsK;SACjL;QACD;YACE,UAAU,EAAE,uDAAuD;YACnE,QAAQ,EAAE,yKAAyK;SACpL;QACD;YACE,UAAU,EAAE,8CAA8C;YAC1D,QAAQ,EAAE,iGAAiG;SAC5G;QACD;YACE,UAAU,EAAE,4CAA4C;YACxD,QAAQ,EAAE,oFAAoF;SAC/F;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,cAAc;SACtB;QACD;YACE,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,cAAc;SACtB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,aAAa;SACrB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,yDAAyD;QAClE,KAAK,EAAE,sGAAsG;KAC9G;IACD,eAAe,EAAE,gMAAgM;IACjN,cAAc,EAAE;QACd,uRAAuR;KACxR;IACD,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,cAAc,EAAE;QACd,IAAI;QACJ,MAAM;KACP;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/webwrite.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=webwrite.d.ts.map

package/dist/generated/builtins/webwrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webwrite.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/webwrite.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAsJjB,CAAC;AAEF,eAAe,UAAU,CAAC"}