runmat 0.3.5 → 0.4.0

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

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

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

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

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

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

package/dist/generated/builtins/fgets.js

@@ -0,0 +1,156 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fgets",
+    "category": "io/filetext",
+    "keywords": [
+        "fgets",
+        "text file",
+        "line input",
+        "newline"
+    ],
+    "summary": "Read the next line from a file, keeping newline characters in the result.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/fgets.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host CPU. When arguments live on the GPU, RunMat gathers them before performing host I/O."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::fgets::tests"
+    },
+    "description": "`fgets(fid)` returns the next line from the text file associated with `fid`, preserving any newline characters that terminate the line. It mirrors MATLAB's behaviour for optional length limits, line-terminator reporting, and end-of-file handling so existing scripts work without modification.",
+    "behaviors": [
+        "`tline = fgets(fid)` reads from the current position to the next newline (including the newline) or to end-of-file when no terminator is found. The result is a character row vector with MATLAB's column-major semantics.",
+        "`tline = fgets(fid, nchar)` limits the read to at most `nchar-1` characters (with `nchar` rounded toward zero), matching MATLAB. The call stops early if a newline is encountered before the limit. When the newline appears beyond the limit, the delimiter is left unread for the next call.",
+        "`[tline, ltout] = fgets(___)` additionally returns the line terminators as a row vector of doubles. For Windows newlines (`\\r\\n`) the second output is `[13 10]`, for Unix newlines (`\\n`) it is `10`, and it is empty when the line has no terminator.",
+        "When the file is empty or the file position indicator is already at end-of-file, `tline` (and `ltout`, if requested) return `-1`.",
+        "Lines are decoded using the text encoding recorded by `fopen`. UTF-8, US-ASCII, ISO-8859-1 (`latin1`), Windows-1252, Shift_JIS, and binary mode are recognised without additional user work."
+    ],
+    "examples": [
+        {
+            "description": "Read the first line of a file",
+            "input": "fname = tempname;\nfid = fopen(fname, 'w');\nfprintf(fid, 'RunMat\\nSecond line\\n');\nfclose(fid);\n\nfid = fopen(fname, 'r');\nline = fgets(fid);\nfclose(fid);\ndelete(fname);\n\ndouble(line)",
+            "output": "ans =\n    82   117   110    77    97   116    10"
+        },
+        {
+            "description": "Limit the number of characters returned",
+            "input": "fname = tempname;\nfid = fopen(fname, 'w');\nfprintf(fid, 'Example line\\n');\nfclose(fid);\n\nfid = fopen(fname, 'r');\nsnippet = fgets(fid, 5);\nfclose(fid);\ndelete(fname);\n\nsnippet\ndouble(snippet)",
+            "output": "snippet =\n    'Exam'\nans =\n    69   120    97   109"
+        },
+        {
+            "description": "Retrieve line terminators separately",
+            "input": "fname = tempname;\nfid = fopen(fname, 'w');\nfprintf(fid, 'Windows line\\r\\n');\nfclose(fid);\n\nfid = fopen(fname, 'r');\n[line, ltout] = fgets(fid);\nfclose(fid);\ndelete(fname);\n\ncontent = line(1:end-numel(ltout));\nterminators = double(ltout);\n\ncontent\nterminators",
+            "output": "content =\n    'Windows line'\nterminators =\n    13    10"
+        },
+        {
+            "description": "Handle lines without a trailing newline",
+            "input": "fname = tempname;\nfid = fopen(fname, 'w');\nfprintf(fid, 'last line');\nfclose(fid);\n\nfid = fopen(fname, 'r');\n[line1, lt1] = fgets(fid);\nline2 = fgets(fid);\nfclose(fid);\ndelete(fname);\n\nline1\nlt1\nline2",
+            "output": "line1 =\n    'last line'\nlt1 =\n     []\nline2 =\n    -1"
+        },
+        {
+            "description": "Detect end of file using the return value",
+            "input": "fname = tempname;\nfid = fopen(fname, 'w');\nfprintf(fid, 'one\\n');\nfprintf(fid, 'two\\n');\nfclose(fid);\n\nfid = fopen(fname, 'r');\ntline = fgets(fid);\nwhile tline ~= -1\n    fprintf('> %s', tline);\n    tline = fgets(fid);\nend\nfclose(fid);\ndelete(fname)",
+            "output": "> one\n> two"
+        },
+        {
+            "description": "Read Latin-1 encoded text",
+            "input": "fname = tempname;\nfid = fopen(fname, 'w', 'n', 'latin1');\nfprintf(fid, 'Español\\n');\nfclose(fid);\n\nfid = fopen(fname, 'r', 'n', 'latin1');\nline = fgets(fid);\nfclose(fid);\ndelete(fname);\n\ntext = line(1:end-1);\ncodes = double(text);\n\ntext\ncodes",
+            "output": "text =\n    'Español'\ncodes =\n    69   115   112    97   241   111   108"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does `fgets` return at end-of-file?",
+            "answer": "When no characters can be read because the file position indicator is at end-of-file, `fgets` returns the numeric value `-1`. If you request two outputs, `ltout` is also `-1` in this case."
+        },
+        {
+            "question": "Does `fgets` strip newline characters?",
+            "answer": "No. Unlike `fgetl`, `fgets` keeps any newline bytes in the returned character vector so you can distinguish empty lines from lines that end in a newline."
+        },
+        {
+            "question": "How do I interpret the second output `ltout`?",
+            "answer": "`ltout` contains the numeric codes for the terminators that ended the line. Use `char(ltout)` or `double(ltout)` to inspect them. On Windows you typically see `[13 10]`, on Unix-like platforms `10`, `[]` when the line has no terminator, and `-1` when end-of-file is reached."
+        },
+        {
+            "question": "What happens if I specify an `nchar` limit?",
+            "answer": "RunMat reads at most `nchar-1` characters (MATLAB-compatible). If the newline characters appear before reaching the limit, they are included in the output. If the limit is reached first, the newline remains unread and `ltout` is empty."
+        },
+        {
+            "question": "Which encodings are supported?",
+            "answer": "`fgets` honours the encoding recorded by `fopen`. UTF-8, US-ASCII, Latin-1 (ISO-8859-1), Windows-1252, Shift_JIS, and binary mode are recognised. On most Unix-like systems the `system` encoding resolves to UTF-8; on Windows it defaults to Windows-1252."
+        },
+        {
+            "question": "How does `fgets` differ from `fgetl`?",
+            "answer": "`fgetl` removes newline characters, while `fgets` keeps them. Use `fgetl` when you want newline-free strings and `fgets` when you need to preserve the exact bytes that appear in the file."
+        },
+        {
+            "question": "Can I call `fgets` on files opened for writing only?",
+            "answer": "No. The file must be opened with read permission (for example `'r'`, `'r+'`, or `'w+'`). Calling `fgets` on a write-only identifier raises an error."
+        }
+    ],
+    "links": [
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "feof",
+            "url": "./feof"
+        },
+        {
+            "label": "fread",
+            "url": "./fread"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "filewrite",
+            "url": "./filewrite"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        },
+        {
+            "label": "frewind",
+            "url": "./frewind"
+        },
+        {
+            "label": "fwrite",
+            "url": "./fwrite"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/io/filetext/fgets.rs",
+        "url": "crates/runmat-runtime/src/builtins/io/filetext/fgets.rs"
+    },
+    "gpu_behavior": [
+        "`fgets` is a host-only operation. File identifiers live in the host registry created by `fopen`, so arguments that arrive as GPU-resident scalars are gathered back to the CPU before the read occurs. The returned line and optional terminator vector are regular host values; no GPU residency is tracked."
+    ],
+    "key": "fgets",
+    "slug": "fgets",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fgets.js.map

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

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

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

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

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

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

@@ -0,0 +1,152 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fieldnames",
+    "category": "structs/core",
+    "keywords": [
+        "fieldnames",
+        "struct",
+        "introspection",
+        "struct array",
+        "object",
+        "handle",
+        "properties"
+    ],
+    "summary": "List the field names of structs, struct arrays, or objects.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host. GPU-resident values or handles remain on the device; no kernels are dispatched."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::structs::core::fieldnames::tests",
+        "integration": "builtins::structs::core::fieldnames::tests::fieldnames_struct_array_collects_union"
+    },
+    "description": "`fieldnames(S)` returns a column cell array of character vectors containing the field names defined on `S`. RunMat mirrors MATLAB by supporting scalar structs, struct arrays, and MATLAB-style objects (including handle objects). The output is always deterministic and case-sensitive.",
+    "behaviors": [
+        "Works with scalar structs as well as struct arrays created by `struct`, `load`, or other builtins.",
+        "Returns a column cell array (`n × 1`) whose elements are character vectors (1 × N char arrays).",
+        "Objects (value or handle) report the union of their public, non-static class properties together with any dynamic properties stored on the instance.",
+        "For struct arrays, the union of field names across all elements is reported.",
+        "Field names are sorted alphabetically and remain case-sensitive (`name` and `Name` are distinct).",
+        "Empty structs yield an empty `0 × 1` cell array. GPU-resident field values stay on the device— `fieldnames` only inspects metadata."
+    ],
+    "examples": [
+        {
+            "description": "Listing the fields of a scalar structure",
+            "input": "s = struct(\"name\", \"Ada\", \"score\", 42);\nfields = fieldnames(s)",
+            "output": "fields =\n    {'name'}\n    {'score'}"
+        },
+        {
+            "description": "Inspecting field names before accessing values",
+            "input": "stats = struct(\"min\", 1.2, \"max\", 9.8);\nif any(strcmp(fieldnames(stats), \"median\"))\n    disp(stats.median);\nelse\n    disp(\"median not available\");\nend",
+            "output": "median not available"
+        },
+        {
+            "description": "Gathering field names from a struct array",
+            "input": "people = struct(\"name\", {\"Ada\", \"Grace\"}, \"id\", {101, 102});\nfields = fieldnames(people)",
+            "output": "fields =\n    {'id'}\n    {'name'}"
+        },
+        {
+            "description": "Listing the properties of an object",
+            "input": "% Save this class in Counter.m before running the example:\n% classdef Counter\n%     properties\n%         Value = 0\n%         Step  = 1\n%     end\n% end\nc = Counter;\nprops = fieldnames(c)",
+            "output": "props =\n    {'Step'}\n    {'Value'}"
+        },
+        {
+            "description": "Discovering fields inside nested structs",
+            "input": "config.database = struct(\"host\", \"db.local\", \"port\", 5432);\nnames = fieldnames(config.database)",
+            "output": "names =\n    {'host'}\n    {'port'}"
+        },
+        {
+            "description": "Handling empty structs safely",
+            "input": "emptyScalar = struct();\nemptyArray = struct(\"id\", {});\nfs = fieldnames(emptyScalar);\nfa = fieldnames(emptyArray)",
+            "output": "fs =\n  0x1 empty cell array\n\nfa =\n  0x1 empty cell array"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does `fieldnames` return?",
+            "answer": "It returns a column cell array of character vectors for every field or property defined on the input struct, struct array, or object instance."
+        },
+        {
+            "question": "Are the field names sorted?",
+            "answer": "Yes. RunMat stores fields and properties in hash maps, so `fieldnames` sorts them alphabetically to produce a stable, deterministic result."
+        },
+        {
+            "question": "Does `fieldnames` gather GPU data back to the CPU?",
+            "answer": "No. The builtin only inspects host-side metadata; GPU-resident tensors or handles remain untouched."
+        },
+        {
+            "question": "How do struct arrays affect the result?",
+            "answer": "All struct elements are examined and the union of their field names is returned. Duplicate names are collapsed automatically."
+        },
+        {
+            "question": "Does `fieldnames` work with objects and handle objects?",
+            "answer": "Yes. The builtin merges public, non-static class properties with any dynamic properties stored on the instance. Handle objects reuse the same logic even when their payloads are shared across references."
+        },
+        {
+            "question": "What happens with empty structs or empty struct arrays?",
+            "answer": "The result is an empty column cell array (`0 × 1`). This matches MATLAB behaviour for empty scalars and for struct arrays that contain no elements."
+        },
+        {
+            "question": "Can I use `fieldnames` on unsupported inputs?",
+            "answer": "No. Passing anything other than a struct, struct array, or object raises `fieldnames: expected struct, struct array, or object`."
+        }
+    ],
+    "links": [
+        {
+            "label": "struct",
+            "url": "./struct"
+        },
+        {
+            "label": "isfield",
+            "url": "./isfield"
+        },
+        {
+            "label": "getfield",
+            "url": "./getfield"
+        },
+        {
+            "label": "setfield",
+            "url": "./setfield"
+        },
+        {
+            "label": "class",
+            "url": "./class"
+        },
+        {
+            "label": "orderfields",
+            "url": "./orderfields"
+        },
+        {
+            "label": "rmfield",
+            "url": "./rmfield"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/structs/core/fieldnames.rs",
+        "url": "crates/runmat-runtime/src/builtins/structs/core/fieldnames.rs"
+    },
+    "gpu_residency": "You do not need to call `gpuArray` when using `fieldnames`. RunMat leaves each value—CPU or GPU—where it already resides. When structs or objects contain GPU handles, those handles remain valid and stay resident on the device throughout the introspection call.",
+    "gpu_behavior": [
+        "`fieldnames` is metadata-only. It does not launch kernels or gather data. GPU tensors or handles that live inside structs or objects remain device-resident, and the builtin simply walks the host-side descriptors that remember their names."
+    ],
+    "key": "fieldnames",
+    "slug": "fieldnames",
+    "categoryPath": [
+        "structs",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fieldnames.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fileread.js

@@ -0,0 +1,164 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fileread",
+    "category": "io/filetext",
+    "keywords": [
+        "fileread",
+        "io",
+        "read file",
+        "text file",
+        "character vector"
+    ],
+    "summary": "Read the entire contents of a text file into a 1-by-N character vector.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/fileread.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host CPU. When the file path lives on the GPU, RunMat gathers it first; the file contents remain host-resident."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::fileread::tests",
+        "integration": "builtins::io::filetext::fileread::tests::fileread_reads_text_file"
+    },
+    "description": "`fileread(filename)` loads the complete contents of a text file into memory and returns a row vector of characters that mirrors MATLAB's behaviour. The builtin preserves all bytes, including newlines and extended ASCII characters, so downstream code can parse, split, or convert the text as needed.",
+    "behaviors": [
+        "Accepts paths provided as character vectors or string scalars. String arrays must contain exactly one element.",
+        "Supports an optional encoding argument: `fileread(filename, encoding)` or `fileread(filename, 'Encoding', encoding)`. Recognised values include `auto` (default), `utf-8`, `ascii`, `latin1`, and `raw`.",
+        "Resolves relative paths with respect to the current working directory of the RunMat process, just like MATLAB.",
+        "Returns a `1×N` character array. Empty files yield a `1×0` character vector.",
+        "Leaves line endings untouched (`\\r`, `\\n`, or `\\r\\n`) so scripts can inspect original formatting.",
+        "When `auto` decoding detects invalid UTF-8 sequences, RunMat maps each byte to the corresponding extended-ASCII code point so that callers can recover the raw data.",
+        "Throws a descriptive error when the file cannot be opened or read."
+    ],
+    "examples": [
+        {
+            "description": "Read Entire File Into A Character Vector",
+            "input": "text = fileread(\"LICENSE.md\")",
+            "output": "text =\n    Character vector containing the full license text"
+        },
+        {
+            "description": "Read A File Using A Relative Path",
+            "input": "text = fileread(\"data/config.json\")",
+            "output": "text =\n    Returns the JSON file contents as a character vector"
+        },
+        {
+            "description": "Preserve Extended ASCII Bytes",
+            "input": "bytes = fileread(\"fixtures/high_ascii.txt\");\ndouble_values = double(bytes)",
+            "output": "double_values =\n    65    66    67"
+        },
+        {
+            "description": "Convert File Contents To A String Scalar",
+            "input": "raw = fileread(\"README.md\");\ndoc = string(raw)",
+            "output": "doc =\n    \"RunMat docs\""
+        },
+        {
+            "description": "Read A File With UTF-8 Decoding Explicitly",
+            "input": "text = fileread(\"data/report.txt\", 'Encoding', 'utf-8')",
+            "output": "text =\n    Character vector decoded using UTF-8."
+        },
+        {
+            "description": "Handle Missing Files With Try/Catch",
+            "input": "try\n    fileread(\"missing.txt\");\ncatch err\n    disp(err.message);\nend",
+            "output": "fileread: unable to read 'missing.txt': readFile: not found"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does `fileread` return?",
+            "answer": "It returns a `1×N` character vector containing every byte from the file. Convert it to a string with `string(...)` when you prefer string scalars."
+        },
+        {
+            "question": "Does `fileread` change line endings?",
+            "answer": "No. The builtin preserves whatever newline sequence the file uses so downstream tools can handle formatting explicitly."
+        },
+        {
+            "question": "Can `fileread` read binary data?",
+            "answer": "While designed for text, `fileread` will happily return any bytes. The result is a character vector whose numeric codes match the file's bytes."
+        },
+        {
+            "question": "How are encodings handled?",
+            "answer": "The default `auto` mode attempts UTF-8 decoding and, if the data is not valid UTF-8, falls back to mapping each byte to its extended-ASCII code point (`latin1`). Provide an explicit encoding such as `'utf-8'`, `'latin1'`, `'ascii'`, or `'raw'` to control the conversion. Explicit encodings raise descriptive errors when the bytes are incompatible with the requested format."
+        },
+        {
+            "question": "Can I force raw byte behaviour?",
+            "answer": "Yes. Specify `'raw'` (or `'bytes'`) as the encoding argument to receive a character vector whose code points equal the file's bytes."
+        },
+        {
+            "question": "How do relative paths resolve?",
+            "answer": "Relative paths are evaluated against the current working directory of the RunMat process. Use `pwd` or `cd` to control where `fileread` looks."
+        }
+    ],
+    "links": [
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fread",
+            "url": "./fread"
+        },
+        {
+            "label": "string",
+            "url": "./string"
+        },
+        {
+            "label": "strlength",
+            "url": "./strlength"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "feof",
+            "url": "./feof"
+        },
+        {
+            "label": "fgets",
+            "url": "./fgets"
+        },
+        {
+            "label": "filewrite",
+            "url": "./filewrite"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        },
+        {
+            "label": "frewind",
+            "url": "./frewind"
+        },
+        {
+            "label": "fwrite",
+            "url": "./fwrite"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/filetext/fileread.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/filetext/fileread.rs"
+    },
+    "gpu_behavior": [
+        "`fileread` performs synchronous host I/O and never dispatches GPU work. If the provided file name lives on the GPU (for example, produced by a GPU array that was gathered lazily), RunMat gathers that scalar first. File contents are returned as an ordinary character array that resides on the CPU. Providers do not need to implement any hooks for this builtin."
+    ],
+    "key": "fileread",
+    "slug": "fileread",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fileread.js.map

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

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

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

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

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

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