weboptions — Create options for HTTP requests.
weboptions creates a host options structure for webread, websave, 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
- The implemented fields are
CharacterEncoding,UserAgent,Timeout,Username,Password,KeyName,KeyValue,ContentType,ContentReader,MediaType,RequestMethod,ArrayFormat,HeaderFields,CertificateFilename, and the RunMat-onlyQueryParametersfield. - The default timeout is 5 seconds.
Timeoutaccepts a positive numeric scalar up to 2147.483647 seconds orInf; native integer scalars are read exactly. KeyValueaccepts a text, numeric, or logical scalar and preserves a native integer scalar exactly.- Name-value arguments are case-insensitive. Implemented text properties require text scalars, and
HeaderFieldsaccepts a struct or two-column cell array. - Passing an existing structure as the first argument and the
QueryParametersproperty are independently gated RunMat extensions. CharacterEncoding,ContentReader,ArrayFormat, andCertificateFilenameare represented in the returned structure but are not yet fully applied by every HTTP operation.- Unknown option names raise descriptive errors.
Does RunMat run weboptions on the GPU?
weboptions operates on host metadata. Automatic residency does not change source-language behavior, while an explicit gpuArray argument crosses the weboptions-explicit-gpu-input extension gate before provider access.
GPU memory and residency
The result is a host structure. Automatically resident inputs can gather transparently; explicit gpuArray input requires RunMat mode.
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?⌄
RunMat recognizes CharacterEncoding, UserAgent, Timeout, Username, Password, KeyName, KeyValue, ContentType, ContentReader, MediaType, RequestMethod, ArrayFormat, HeaderFields, CertificateFilename, and the RunMat-only QueryParameters property. Unknown names raise an 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?⌄
In RunMat mode, supply a struct or two-column cell array in the QueryParameters option. This convenience is outside the compatibility target and is rejected in MATLAB-compatible mode.
Do I need to manage GPU residency for options?⌄
No manual gather is needed for values that became resident automatically. Explicit gpuArray option values are a named RunMat extension and are rejected in MATLAB-compatible mode. The returned options structure is host-resident.
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 · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
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.