RunMat
GitHub

View all functions

CategoryIo: Http

weboptions — Create an options struct that configures webread and webwrite HTTP behaviour.

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.

How does the weboptions function behave in MATLAB / RunMat?

  • 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.

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.

GPU residency

No. weboptions gathers any GPU-resident values automatically and always returns a host struct. HTTP builtins ignore GPU residency for metadata.

Examples of using weboptions in MATLAB / RunMat

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)

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.

See also

webread, webwrite, jsondecode, jsonencode

Source & Feedback