runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/read.js

@@ -0,0 +1,133 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "read",
+    "category": "io/net",
+    "keywords": [
+        "read",
+        "tcpclient",
+        "networking",
+        "socket",
+        "binary data"
+    ],
+    "summary": "Read numeric or text data from a remote host through a MATLAB-compatible tcpclient struct.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/tcpclient.read.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "All TCP reads run on the host CPU. GPU-resident arguments are gathered before any socket I/O; providers do not expose networking hooks."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 3,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::net::read::tests"
+    },
+    "description": "`read(t)` consumes data waiting on the TCP/IP client returned by `tcpclient` (or `accept`). The builtin mimics MATLAB’s behaviour for `read` so existing code that exchanges bytes with remote services behaves identically. It honours the client’s configured `Timeout`, respects the `ByteOrder` property when materialising multi-byte numeric types, and interprets the optional `datatype` argument just like MATLAB.",
+    "behaviors": [
+        "`data = read(t)` waits until at least one byte becomes available (subject to the client timeout) and then drains the socket buffer, returning a **row vector of doubles** whose values come from the received bytes. If the peer closes the connection without sending data, the result is an empty row vector.",
+        "`data = read(t, count)` blocks until exactly `count` values are available (again honouring `Timeout`). When the peer closes the socket before satisfying the request the builtin raises `RunMat:read:ConnectionClosed`.",
+        "`data = read(t, count, datatype)` interprets the values using the requested MATLAB datatype. Supported tokens mirror MATLAB: `\"uint8\"` (default), `\"int8\"`, `\"uint16\"`, `\"int16\"`, `\"uint32\"`, `\"int32\"`, `\"uint64\"`, `\"int64\"`, `\"single\"`, `\"double\"`, `\"char\"`, and `\"string\"`. Numeric outputs are returned as doubles; `\"char\"` produces a MATLAB-style character row vector and `\"string\"` returns a scalar string.",
+        "Every call honours the client’s `ByteOrder` property when decoding multi-byte numbers. Little-endian is the default, but `\"big-endian\"` is respected for data written in network byte order.",
+        "The builtin gathers GPU-resident arguments automatically, executes the socket read on the CPU, and returns host values.",
+        "Errors are raised with MATLAB-compatible identifiers: invalid client structs trigger `RunMat:read:InvalidTcpClient`, timeouts emit `RunMat:read:Timeout`, and connection closures before a requested count is met raise `RunMat:read:ConnectionClosed`."
+    ],
+    "examples": [
+        {
+            "description": "Reading a fixed number of bytes from a TCP echo service",
+            "input": "client = tcpclient(\"127.0.0.1\", 50000);\nwrite(client, uint8(1:6));\npayload = read(client, 6)",
+            "output": "payload =\n     1     2     3     4     5     6"
+        },
+        {
+            "description": "Reading ASCII text as characters",
+            "input": "client = tcpclient(\"127.0.0.1\", 50001);\nwrite(client, \"RunMat TCP\");\nchars = read(client, 10, \"char\")",
+            "output": "chars =\n    'RunMat TCP'"
+        },
+        {
+            "description": "Reading doubles written in big-endian byte order",
+            "input": "client = tcpclient(\"localhost\", 50002, \"ByteOrder\", \"big-endian\");\nwrite(client, swapbytes([1 2 3], \"double\"));\nvalues = read(client, 3, \"double\")",
+            "output": "values =\n     1     2     3"
+        },
+        {
+            "description": "Reading all available data without specifying a count",
+            "input": "client = tcpclient(\"127.0.0.1\", 50003);\nwrite(client, uint8([10 20 30]));\nburst = read(client)",
+            "output": "burst =\n    10    20    30"
+        },
+        {
+            "description": "Handling read timeouts gracefully",
+            "input": "client = tcpclient(\"example.com\", 12345, \"Timeout\", 0.5);\ntry\n    data = read(client, 64);\ncatch err\n    disp(err.identifier)\nend",
+            "output": "RunMat:read:Timeout"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `read` modify the client struct?",
+            "answer": "No. The builtin interacts with the socket stored in RunMat’s internal registry. The visible struct returned from `tcpclient` is passed by value and is not mutated in place."
+        },
+        {
+            "question": "What happens when the remote host closes the connection?",
+            "answer": "If the peer closes the connection before the requested count is satisfied, `read` raises `RunMat:read:ConnectionClosed`. When no specific count is requested (`read(t)`), the builtin returns whatever data was available before the closure (possibly an empty vector)."
+        },
+        {
+            "question": "Does `read` support infinite timeouts?",
+            "answer": "Yes. Setting `t.Timeout = Inf` (or passing `\"Timeout\", inf` when constructing the client) leaves the socket in blocking mode. The builtin waits indefinitely until enough data arrives or the peer closes the connection."
+        },
+        {
+            "question": "How are multibyte integers decoded?",
+            "answer": "RunMat honours the client’s `ByteOrder` property (`\"little-endian\"` or `\"big-endian\"`). For example, `read(t, 4, \"uint16\")` consumes eight bytes and interprets each pair in the configured byte order."
+        },
+        {
+            "question": "Can I read UTF-8 strings directly?",
+            "answer": "Use the `\"string\"` datatype. The builtin converts each received byte directly into a MATLAB string scalar assuming UTF-8 (non-UTF-8 sequences fall back to byte-wise decoding)."
+        }
+    ],
+    "links": [
+        {
+            "label": "tcpclient",
+            "url": "./tcpclient"
+        },
+        {
+            "label": "accept",
+            "url": "./accept"
+        },
+        {
+            "label": "write",
+            "url": "./write"
+        },
+        {
+            "label": "readline",
+            "url": "./readline"
+        },
+        {
+            "label": "close",
+            "url": "./close"
+        },
+        {
+            "label": "tcpserver",
+            "url": "./tcpserver"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/net/read.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/net/read.rs"
+    },
+    "gpu_behavior": [
+        "Networking is a host-only subsystem. When a client struct or argument arrives from the GPU, RunMat gathers the value back to the CPU before reading from the socket. No acceleration-provider hooks participate in the operation, and the result is always a host value (double tensor, char array, or string). Future GPU providers continue to gather metadata automatically so networking remains CPU-bound."
+    ],
+    "key": "read",
+    "slug": "read",
+    "categoryPath": [
+        "io",
+        "net"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=read.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/generated/builtins/read.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,MAAM;IACf,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE;QACV,MAAM;QACN,WAAW;QACX,YAAY;QACZ,QAAQ;QACR,aAAa;KACd;IACD,SAAS,EAAE,4FAA4F;IACvG,YAAY,EAAE;QACZ,+DAA+D;KAChE;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,yIAAyI;KACnJ;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,gCAAgC;KACzC;IACD,aAAa,EAAE,6ZAA6Z;IAC5a,WAAW,EAAE;QACX,iTAAiT;QACjT,yNAAyN;QACzN,ubAAub;QACvb,gMAAgM;QAChM,yHAAyH;QACzH,yPAAyP;KAC1P;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,yDAAyD;YACxE,OAAO,EAAE,kGAAkG;YAC3G,QAAQ,EAAE,iDAAiD;SAC5D;QACD;YACE,aAAa,EAAE,kCAAkC;YACjD,OAAO,EAAE,+GAA+G;YACxH,QAAQ,EAAE,2BAA2B;SACtC;QACD;YACE,aAAa,EAAE,kDAAkD;YACjE,OAAO,EAAE,gKAAgK;YACzK,QAAQ,EAAE,8BAA8B;SACzC;QACD;YACE,aAAa,EAAE,uDAAuD;YACtE,OAAO,EAAE,oGAAoG;YAC7G,QAAQ,EAAE,6BAA6B;SACxC;QACD;YACE,aAAa,EAAE,mCAAmC;YAClD,OAAO,EAAE,4IAA4I;YACrJ,QAAQ,EAAE,qBAAqB;SAChC;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,8KAA8K;SACzL;QACD;YACE,UAAU,EAAE,0DAA0D;YACtE,QAAQ,EAAE,0QAA0Q;SACrR;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,6NAA6N;SACxO;QACD;YACE,UAAU,EAAE,qCAAqC;YACjD,QAAQ,EAAE,+MAA+M;SAC1N;QACD;YACE,UAAU,EAAE,oCAAoC;YAChD,QAAQ,EAAE,mLAAmL;SAC9L;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,WAAW;YACpB,KAAK,EAAE,aAAa;SACrB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,WAAW;YACpB,KAAK,EAAE,aAAa;SACrB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,qDAAqD;QAC9D,KAAK,EAAE,kGAAkG;KAC1G;IACD,cAAc,EAAE;QACd,iZAAiZ;KAClZ;IACD,KAAK,EAAE,MAAM;IACb,MAAM,EAAE,MAAM;IACd,cAAc,EAAE;QACd,IAAI;QACJ,KAAK;KACN;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/readline.js

@@ -0,0 +1,152 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "readline",
+    "category": "io/net",
+    "keywords": [
+        "readline",
+        "tcpclient",
+        "networking",
+        "terminator",
+        "text"
+    ],
+    "summary": "Read ASCII text until the terminator from a MATLAB-compatible tcpclient struct.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/tcpclient.readline.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Socket reads execute on the host CPU. GPU-resident structs are gathered automatically before reading."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::net::readline::tests",
+        "integration": "builtins::io::net::readline::tests::readline_buffers_partial_data_across_timeouts"
+    },
+    "description": "`readline(t)` reads ASCII text from the remote host associated with the MATLAB-compatible `tcpclient` struct `t`. It consumes data until it encounters the line terminator (RunMat currently honours the MATLAB default line feed (LF, `\"\\n\"`)) and returns the characters **without** the terminator. If the terminator is not observed before the timeout elapses, the builtin returns a 0-by-0 double (`[]`) just like MATLAB and preserves the buffered bytes for the next call. When the peer closes the connection, any buffered characters are returned and the internal connection flag is cleared.",
+    "behaviors": [
+        "`readline(t)` waits for data and reads character bytes until the first line feed. The returned value is a MATLAB string scalar that excludes the terminator, mirroring MATLAB’s `tcpclient.readline`.",
+        "If the peer uses carriage-return/line-feed pairs (`\"\\r\\n\"`), RunMat automatically strips both bytes so the returned string matches MATLAB’s behaviour for default CR/LF terminators.",
+        "When the terminator is not encountered before the client’s `Timeout` expires, the builtin returns a 0-by-0 double (`[]`). Any bytes that arrived remain buffered internally so the next `readline` call continues assembling the same logical line.",
+        "If the remote host closes the connection before a terminator is observed, the builtin returns the buffered characters (which might be empty) and marks the underlying client as disconnected so subsequent network calls can react accordingly.",
+        "Inputs passed from the GPU are gathered automatically. Networking always runs on the CPU and the returned string is CPU-resident.",
+        "Invalid structs, missing handles, or disconnected clients raise MATLAB-style diagnostics (for example, `RunMat:readline:InvalidTcpClient`)."
+    ],
+    "examples": [
+        {
+            "description": "Reading a newline-terminated response from an echo server",
+            "input": "client = tcpclient(\"127.0.0.1\", 55000);\nwrite(client, \"ping\\n\");\nreply = readline(client)",
+            "output": "reply = \"ping\""
+        },
+        {
+            "description": "Handling CRLF-terminated lines from legacy services",
+            "input": "client = tcpclient(\"legacy.example.com\", 1600);\nwrite(client, \"HELLO\\r\\n\");\nline = readline(client);  % CRLF is removed automatically",
+            "output": "line = \"OK HELLO\""
+        },
+        {
+            "description": "Looping over streaming telemetry one line at a time",
+            "input": "client = tcpclient(\"telemetry.example.com\", 9000, \"Timeout\", 5);\nwhile true\n    payload = readline(client);\n    if isequal(payload, [])\n        continue   % timeout, try again once more data arrives\n    end\n    disp(payload)\nend"
+        },
+        {
+            "description": "Detecting closed connections without losing buffered text",
+            "input": "client = tcpclient(\"sensor.example.com\", 7000);\ntry\n    line = readline(client);        % returns partial line if peer closed without LF\n    disp(line)\n    readline(client);               % second call raises RunMat:readline:NotConnected\ncatch err\n    if err.identifier == \"RunMat:readline:NotConnected\"\n        disp(\"Sensor disconnected\")\n    else\n        rethrow(err)\n    end\nend"
+        },
+        {
+            "description": "Responding gracefully to quiet periods with finite timeouts",
+            "input": "client = tcpclient(\"chat.example.com\", 4040, \"Timeout\", 0.5);\nmsg = readline(client);    % returns [] when no line arrives within 0.5 s\nif isequal(msg, [])\n    disp(\"No complete chat messages yet.\")\nend"
+        },
+        {
+            "description": "Parsing numeric payloads that arrive as text lines",
+            "input": "client = tcpclient(\"metrics.example.com\", 5050);\nline = readline(client);\nvalues = str2double(split(line, \",\"));  % convert comma-separated numbers"
+        },
+        {
+            "description": "Logging line-delimited JSON messages from a service",
+            "input": "client = tcpclient(\"json.example.com\", 6000);\nwhile true\n    payload = readline(client);\n    if isequal(payload, [])\n        break\n    end\n    decoded = jsondecode(payload);\n    disp(decoded.status)\nend"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which terminator does RunMat use?",
+            "answer": "RunMat currently honours MATLAB’s default line feed (LF, `\"\\n\"`). Support for `configureTerminator` will allow other terminators in a future update."
+        },
+        {
+            "question": "Does `readline` return the terminator?",
+            "answer": "No. The terminator bytes are stripped and the MATLAB string contains only the payload characters."
+        },
+        {
+            "question": "What happens on timeout?",
+            "answer": "If the terminator is not observed before the configured `Timeout`, the builtin returns a 0-by-0 double (`[]`) and retains any buffered bytes so the next call can complete the line once the terminator arrives."
+        },
+        {
+            "question": "How are CR/LF pairs handled?",
+            "answer": "When the payload ends with `\"\\r\\n\"`, both bytes are removed so the result matches MATLAB’s CR/LF behaviour."
+        },
+        {
+            "question": "What if the connection closes mid-line?",
+            "answer": "Any buffered text is returned and subsequent calls raise `RunMat:readline:NotConnected`, signalling that the socket closed."
+        },
+        {
+            "question": "Does the builtin perform Unicode validation?",
+            "answer": "Bytes are decoded using UTF-8. Invalid sequences fall back to lossless byte-to-char mapping so no data is lost."
+        },
+        {
+            "question": "Can I call `readline` after gathering a GPU tensor?",
+            "answer": "Yes. `readline` gathers arguments automatically and always returns host values."
+        },
+        {
+            "question": "Will future GPU providers change the return type?",
+            "answer": "No. Networking results remain CPU strings even when GPUs are available."
+        }
+    ],
+    "links": [
+        {
+            "label": "tcpclient",
+            "url": "./tcpclient"
+        },
+        {
+            "label": "accept",
+            "url": "./accept"
+        },
+        {
+            "label": "read",
+            "url": "./read"
+        },
+        {
+            "label": "write",
+            "url": "./write"
+        },
+        {
+            "label": "close",
+            "url": "./close"
+        },
+        {
+            "label": "tcpserver",
+            "url": "./tcpserver"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/net/readline.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/net/readline.rs"
+    },
+    "gpu_residency": "No. RunMat automatically gathers GPU-resident structs before reading from sockets. The returned string lives on the CPU and there is no benefit to calling `gpuArray` for networking builtins such as `readline`.",
+    "gpu_behavior": [
+        "Networking is exclusively a host-side activity. When a `tcpclient` struct resides on the GPU, RunMat gathers it back to the CPU before touching the socket. Acceleration providers are not consulted and no GPU buffers are produced. Future GPU-aware networking features will continue to gather metadata automatically so sockets remain purely CPU-bound."
+    ],
+    "key": "readline",
+    "slug": "readline",
+    "categoryPath": [
+        "io",
+        "net"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=readline.js.map

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

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

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

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

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

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

package/dist/generated/builtins/readmatrix.js

@@ -0,0 +1,213 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "readmatrix",
+    "category": "io/tabular",
+    "keywords": [
+        "readmatrix",
+        "csv",
+        "delimited text",
+        "numeric import",
+        "table",
+        "range",
+        "logical"
+    ],
+    "summary": "Import numeric data from delimited text files into a RunMat matrix.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/readmatrix.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Performs host-side file I/O and parsing. GPU providers are not involved; gathered results remain CPU-resident."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::tabular::readmatrix::tests",
+        "integration": "builtins::io::tabular::readmatrix::tests::readmatrix_reads_csv_data"
+    },
+    "description": "`readmatrix(filename)` reads numeric data from text or delimited files and returns a dense double-precision matrix. RunMat mirrors MATLAB defaults: the function automatically detects common delimiters, skips leading header lines only when requested, infers a rectangular output, and treats empty fields as missing values.",
+    "behaviors": [
+        "Accepts character vectors or string scalars for the file name. String arrays must contain exactly one element.",
+        "Supports option structs (from `detectImportOptions`) as well as name/value arguments such as `'Delimiter'`, `'NumHeaderLines'`, `'TreatAsMissing'`, `'DecimalSeparator'`, `'ThousandsSeparator'`, and `'EmptyValue'`.",
+        "Accepts `'Range'` as either an Excel-style address (`\"B2:E10\"`) or a numeric vector `[rowStart colStart rowEnd colEnd]` to slice the imported data.",
+        "Automatically detects comma, tab, semicolon, pipe, or whitespace delimiters when none are specified. Detection is based on the first few non-empty data lines.",
+        "Parses numeric values using MATLAB-compatible rules, recognising `NaN`, `Inf`, `-Inf`, and locale-specific decimal/thousands separators.",
+        "Treats empty fields as `NaN` by default; specify `'EmptyValue', value` to inject a replacement scalar, or `'TreatAsMissing', tokens` to mark additional strings as missing.",
+        "`'OutputType','logical'` coalesces non-zero numeric values (including `NaN`) to logical true, mirroring MATLAB's casting behaviour.",
+        "`'Like', prototype` matches the output class and residency of an existing array. Supplying a GPU tensor keeps the parsed matrix on the device when an acceleration provider is active.",
+        "Tolerates ragged rows by padding trailing elements with the configured empty value (default `NaN`).",
+        "Raises descriptive errors when the file cannot be read or when a field cannot be parsed as a numeric value."
+    ],
+    "examples": [
+        {
+            "description": "Read Comma-Separated Values With Automatic Delimiter Detection",
+            "input": "M = readmatrix(\"data/scores.csv\")",
+            "output": "% Returns a numeric matrix containing the CSV data."
+        },
+        {
+            "description": "Skip Header Lines Before Reading Numeric Data",
+            "input": "M = readmatrix(\"data/sensor_log.txt\", 'NumHeaderLines', 2)",
+            "output": "% The first two lines are skipped; the remaining numeric rows are returned."
+        },
+        {
+            "description": "Import Tab-Delimited Text By Specifying The Delimiter",
+            "input": "M = readmatrix(\"data/report.tsv\", 'Delimiter', 'tab')",
+            "output": "% Numeric matrix representing the tab-delimited values."
+        },
+        {
+            "description": "Treat Custom Tokens As Missing Values",
+            "input": "M = readmatrix(\"data/results.csv\", 'TreatAsMissing', [\"NA\", \"missing\"])",
+            "output": "% Entries equal to \"NA\" or \"missing\" become NaN in the output matrix."
+        },
+        {
+            "description": "Use European Decimal And Thousands Separators",
+            "input": "M = readmatrix(\"data/europe.csv\", 'Delimiter', ';', 'DecimalSeparator', ',', 'ThousandsSeparator', '.')",
+            "output": "% Values like \"1.234,56\" are interpreted as 1234.56."
+        },
+        {
+            "description": "Replace Empty Numeric Fields With A Custom Value",
+            "input": "M = readmatrix(\"data/with_blanks.csv\", 'EmptyValue', 0)",
+            "output": "% Blank entries become 0 instead of NaN."
+        },
+        {
+            "description": "Import A Specific Range Of Cells",
+            "input": "M = readmatrix(\"data/quarterly.csv\", 'Range', 'B2:D5')",
+            "output": "% Returns only the rows and columns covered by the specified range."
+        },
+        {
+            "description": "Convert The Result To A Logical Matrix",
+            "input": "flags = readmatrix(\"data/thresholds.csv\", 'OutputType', 'logical')",
+            "output": "% Non-zero entries (including NaN) become logical true, zero stays false."
+        },
+        {
+            "description": "Keep The Result On The GPU By Matching A Prototype",
+            "input": "proto = gpuArray.zeros(1);        % simple prototype to establish residency\nG = readmatrix(\"data/heavy.csv\", 'Like', proto)",
+            "output": "% The parsed matrix is uploaded to the same GPU device as the prototype."
+        },
+        {
+            "description": "Provide Options Using A Struct From detectImportOptions",
+            "input": "opts = struct('Delimiter', ',', 'NumHeaderLines', 1);\nM = readmatrix(\"data/measurements.csv\", opts)",
+            "output": "% Reads the file using the supplied options struct."
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What file encodings does `readmatrix` support?",
+            "answer": "The builtin reads UTF-8 text files by default. If a file starts with a UTF-8 byte-order mark, it is ignored automatically. For other encodings, convert the file with `fileread`/`string` or external tools before calling `readmatrix`."
+        },
+        {
+            "question": "Does `readmatrix` support Excel or binary files?",
+            "answer": "This implementation focuses on delimited text files. For MAT-files use `load`, and for spreadsheets use the `readtable` / `readcell` family (planned)."
+        },
+        {
+            "question": "How are missing values represented?",
+            "answer": "Empty fields become NaN unless `'EmptyValue'` is supplied. Additional tokens can be marked missing with `'TreatAsMissing'`, which also converts them to NaN."
+        },
+        {
+            "question": "What happens when rows have different numbers of columns?",
+            "answer": "RunMat pads short rows with the empty value (default NaN) so the output remains rectangular."
+        },
+        {
+            "question": "Can I import only part of the file?",
+            "answer": "Yes. Pass `'Range', 'B3:F20'` (Excel-style addresses) or `'Range', [3 2 10 6]` (row/column indices) to slice the data before it is materialised. Rows or columns outside the range are ignored entirely."
+        },
+        {
+            "question": "Are comment lines supported?",
+            "answer": "Lines that are entirely blank are ignored. Use `'NumHeaderLines'` to skip introductory text or call `detectImportOptions` for more control."
+        },
+        {
+            "question": "How do I read files stored on the GPU?",
+            "answer": "File paths are always gathered to the CPU before reading. By default the parsed matrix is created on the host; supply `'Like', gpuArray.zeros(1)` (or any GPU prototype) to upload the result automatically, or call `gpuArray` afterwards to move it manually."
+        },
+        {
+            "question": "Can I request single-precision output?",
+            "answer": "`readmatrix` currently returns double-precision arrays, matching MATLAB defaults. Cast the result with `single(...)` when you need single precision."
+        },
+        {
+            "question": "How are delimiters detected automatically?",
+            "answer": "The builtin inspects the first few non-empty data lines and chooses the candidate delimiter (comma, tab, semicolon, pipe, or whitespace) that produces the most columns consistently. Explicit `'Delimiter'` settings override detection."
+        },
+        {
+            "question": "How are thousands separators handled?",
+            "answer": "Specify `'ThousandsSeparator'` to strip that character before parsing, e.g. `'.'` for European locales. The thousands and decimal separators must be different."
+        },
+        {
+            "question": "Does `readmatrix` modify the current directory?",
+            "answer": "No. Relative paths are resolved against the current working directory, exactly like MATLAB."
+        },
+        {
+            "question": "What does readmatrix do in MATLAB?",
+            "answer": "`readmatrix(filename)` reads numeric data from a text file (CSV, TSV, etc.) and returns it as a matrix. Non-numeric values are replaced with `NaN`."
+        },
+        {
+            "question": "How is readmatrix different from csvread?",
+            "answer": "`readmatrix` is the modern replacement for `csvread`. It auto-detects delimiters, handles headers, and supports more file formats. `csvread` only handles comma-separated files with numeric data."
+        },
+        {
+            "question": "Can readmatrix skip header rows?",
+            "answer": "Yes. Use the `'NumHeaderLines'` option: `readmatrix('file.csv', 'NumHeaderLines', 1)` skips the first row. RunMat supports this same option."
+        }
+    ],
+    "links": [
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "load",
+            "url": "./load"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "csvread",
+            "url": "./csvread"
+        },
+        {
+            "label": "csvwrite",
+            "url": "./csvwrite"
+        },
+        {
+            "label": "dlmread",
+            "url": "./dlmread"
+        },
+        {
+            "label": "dlmwrite",
+            "url": "./dlmwrite"
+        },
+        {
+            "label": "writematrix",
+            "url": "./writematrix"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/tabular/readmatrix.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/tabular/readmatrix.rs"
+    },
+    "gpu_behavior": [
+        "`readmatrix` always executes on the host CPU. If the file name or option arguments are GPU-resident scalars, RunMat gathers them automatically before accessing the filesystem. The resulting matrix is created in host memory unless you pass `'Like', gpuPrototype`, in which case the parsed tensor is uploaded to the same provider so subsequent operations remain on the device. Acceleration providers do not need bespoke hooks for this builtin."
+    ],
+    "key": "readmatrix",
+    "slug": "readmatrix",
+    "categoryPath": [
+        "io",
+        "tabular"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=readmatrix.js.map

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

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

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

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

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

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