weboptions — Create HTTP options structs for webread and webwrite with MATLAB-compatible defaults.
weboptions builds MATLAB-style option structs controlling timeout, headers, content type, authentication, and request-method behavior for webread and webwrite.
Syntax
options = weboptions()
options = weboptions(optionsStruct)
options = weboptions(name, value, ...)
options = weboptions(optionsStruct, name, value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
optionsStruct | Any | Yes | — | Existing options struct to copy and override. |
name | StringScalar | Variadic | — | Option field name. |
value | Any | Variadic | — | Option field value. |
Returns
| Name | Type | Description |
|---|---|---|
options | Any | HTTP options struct for webread/webwrite. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:weboptions:InvalidArgument | Argument shape/type does not match supported weboptions forms. | weboptions: invalid argument |
RunMat:weboptions:InvalidOptionName | Name-value option key is missing or not text scalar. | weboptions: invalid option name |
RunMat:weboptions:MissingOptionValue | A name-value key is not followed by a value. | weboptions: missing option value |
RunMat:weboptions:InvalidOptionValue | An option value fails type or domain validation. | weboptions: invalid option value |
RunMat:weboptions:UnknownOption | Name-value key does not map to a supported option. | weboptions: unknown option |
RunMat:weboptions:InvalidCredentials | Password is provided without a username. | weboptions: invalid credentials |
RunMat:weboptions:Flow | Nested flow fails while gathering input values. | weboptions: flow failure |
How weboptions works
- Returns a struct with canonical field names:
ContentType,Timeout,HeaderFields,UserAgent,Username,Password,RequestMethod,MediaType, andQueryParameters. - Defaults mirror MATLAB:
ContentType="auto",Timeout=60,UserAgent=""(RunMat substitutes a default agent when this is empty),RequestMethod="auto",MediaType="auto", and empty structs forHeaderFieldsandQueryParameters. - 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 forHeaderFieldsandQueryParameters). - 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.
Does RunMat run weboptions on the GPU?
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.
GPU memory and residency
No. weboptions gathers any GPU-resident values automatically and always returns a host struct. HTTP builtins ignore GPU residency for metadata.
Examples
Setting custom timeouts for webread calls
opts = weboptions("Timeout", 10);
html = webread("https://example.com", opts)Providing HTTP basic authentication credentials
opts = weboptions("Username", "ada", "Password", "lovelace");
profile = webread("https://api.example.com/me", opts)Sending JSON payloads with webwrite
opts = weboptions("ContentType", "json", "MediaType", "application/json");
payload = struct("title", "RunMat", "stars", 5);
reply = webwrite("https://api.example.com/projects", payload, opts)Applying custom headers with struct syntax
headers = struct("Accept", "application/json", "X-Client", "RunMat");
opts = weboptions("HeaderFields", headers);
data = webread("https://api.example.com/resources", opts)Combining existing options with overrides
base = weboptions("ContentType", "json");
opts = weboptions(base, "Timeout", 15, "QueryParameters", struct("verbose", true));
result = webread("https://api.example.com/items", opts)Using weboptions with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how weboptions changes the result.
Run a small weboptions example, explain the result, then change one input and compare the output.
FAQ
Which option names are supported in RunMat?⌄
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.
What does RequestMethod="auto" mean?⌄
webread treats "auto" as "get" while webwrite maps it to "post". Override the method when you need put, patch, or delete.
How are empty usernames or passwords handled?⌄
Empty strings leave authentication disabled. A non-empty password without a username raises a MATLAB-compatible error.
Can I pass query parameters through the options struct?⌄
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.
Do I need to manage GPU residency for options?⌄
No. weboptions gathers any GPU-resident values automatically and always returns a host struct. HTTP builtins ignore GPU residency for metadata.
Does weboptions mutate the input struct?⌄
No. A copy is made before overrides are applied, preserving the original struct you pass in.
How can I clear headers or query parameters?⌄
Pass an empty struct (struct()) or empty cell array ({}) to reset the respective option.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · run · savepath · setenv · tempdir · tempname · uigetfile · uiputfile
Tabular
csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · readmatrix · spreadsheetImportOptions · writecell · writematrix · xlsread
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite
Import
Json
Archive
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how weboptions is executed, line by line, in Rust.
- View the source for weboptions in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.