Files
marqdo/lib/fs.mq.md

788 lines
27 KiB
Markdown

---
markup: occlusion
import:
json: lib/json.mq.md
csv: lib/csv.mq.md
title: lib/fs
description: English filesystem wrappers
---
English filesystem wrappers
Read, write, find and organize files under an explicit root.
Behavior and limits: Legacy remove recursively deletes directories. Prefer remove_file/remove_empty_dir. Atomic operations replace one file; directory batches are not transactions. Native-only operations state their CoW boundary.
This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.
Relative IO paths use --fs-root, or the called file directory when omitted. Writes require explicit fs.write grants, subprocesses require process.exec, and pure transforms require no IO grant.
Implementation: [src/host/fs.rs](../src/host/fs.rs)、[src/host/fs_ops.rs](../src/host/fs_ops.rs)、[src/host/sandbox_fs.rs](../src/host/sandbox_fs.rs)
For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.
## read_text
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Read UTF-8 text from path |
Use `path` as the inputs for this operation.
Effects: fs.read.
Read UTF-8 text from path.
Return *[Read UTF-8 text from path](> host_read_text path=`path`)*.
## write_text
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| text | text | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path`, `text` as the inputs for this operation.
Effects: fs.write.
Write text to path (overwrite).
Return *[Write text to path (overwrite)](> host_write_text path=`path` text=`text`)*.
## append_text
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| text | text | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path`, `text` as the inputs for this operation.
Effects: fs.write.
Append text to path.
Return *[Append text to path](> host_append_text path=`path` text=`text`)*.
## exists
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | Whether path exists |
Use `path` as the inputs for this operation.
Effects: fs.read.
Whether path exists.
Return *[Whether path exists](> host_exists path=`path`)*.
## list_dir
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | List directory entries at path |
Use `path` as the inputs for this operation.
Effects: fs.read.
List directory entries at path.
Return *[List directory entries at path](> host_list_dir path=`path`)*.
## make_dir
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path` as the inputs for this operation.
Effects: fs.write.
Create directory at path.
Return *[Create directory at path](> host_make_dir path=`path`)*.
## make_dirs
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path` as the inputs for this operation.
Effects: fs.write.
Create directories recursively (`mkdir -p`).
Return *[Create directories recursively (mkdir -p)](> host_make_dirs path=`path`)*.
## remove
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path` as the inputs for this operation.
Effects: fs.write.
Remove a file or recursively remove a directory. Legacy behavior; use remove_file or remove_empty_dir for narrow deletion.
Remove a file or recursively remove a directory. For narrow deletion use remove_file or remove_empty_dir.
Return *[Remove a file or recursively remove a directory](> host_remove path=`path`)*.
## remove_tree
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path` as the inputs for this operation.
Effects: fs.write.
Remove a directory recursively. Errors if `path` is a file.
Return *[Remove a directory recursively](> host_remove_tree path=`path`)*.
## stat
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Returns `{size, mtime_unix, is_file, is_dir}` |
Use `path` as the inputs for this operation.
Effects: fs.read.
Returns `{size, mtime_unix, is_file, is_dir}`.
Return *[Returns {size, mtime_unix, is_file, is_dir}](> host_stat path=`path`)*.
## walk
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | Depth-first listing of relative paths under `path` (forward slashes) |
Use `path` as the inputs for this operation.
Effects: fs.read.
Depth-first listing of relative paths under `path` (forward slashes).
Return *[Depth-first listing of relative paths under path (forward slashes)](> host_walk path=`path`)*.
## copy_file
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| src | text | required | Source path under the granted root |
| dest | text | required | Destination path under the granted root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `src`, `dest` as the inputs for this operation.
Effects: fs.write.
Copy a file (overwrites `dest` if it exists). Paths are sandboxed like other fs ops.
Return *[Copy a file (overwrites dest if it exists)](> host_copy_file src=`src` dest=`dest`)*.
## move
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| src | text | required | Source path under the granted root |
| dest | text | required | Destination path under the granted root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `src`, `dest` as the inputs for this operation.
Effects: fs.write.
Rename / move within the sandbox.
Return *[Rename / move within the sandbox](> host_move src=`src` dest=`dest`)*.
## make_temp
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prefix | any | None | Prefix added to the generated name or tested against text |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Create an empty temp file under the program directory; return its relative path |
Use `prefix`=None as the inputs for this operation.
Effects: fs.write.
Create an empty temp file under the program directory; return its relative path.
Return *[Create an empty temp file under the program directory; return its relative path](> host_make_temp prefix=`prefix`)*.
## text_patch
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| find | any | required | Exact text to locate before replacement |
| replace | any | required | Replacement text for each exact match |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Exact FIND→REPLACE once in a UTF-8 text file |
Use `path`, `find`, `replace` as the inputs for this operation.
Effects: fs.write.
Exact FIND→REPLACE once in a UTF-8 text file. `find` must match exactly once.
Return *[Exact FIND→REPLACE once in a UTF-8 text file](> host_text_patch path=`path` find=`find` replace=`replace`)*.
## apply_patch_blocks
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root |
| text | text | required | Text supplied by the caller |
| soft | bool | False | Whether a missing patch match becomes a recoverable outcome |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Apply plan-style triple-angle FIND/REPLACE blocks from `text` to `path` |
Use `path`, `text`, `soft`=False as the inputs for this operation.
Effects: fs.write.
Apply plan-style triple-angle FIND/REPLACE blocks from `text` to `path`.
Also accepts fenced find/replace pairs and minimal Begin Patch hunks.
When `soft=True`, only “FIND not found” returns `0` (run continues). Empty FIND, multi-match, parse errors, and whole-file FIND still abort — whole-file rewrite is forbidden.
Return *[Apply plan-style triple-angle FIND/REPLACE blocks from text to path](> host_apply_patch_blocks path=`path` text=`text` soft=`soft`)*.
## try_read_text
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | Read text as {ok,value,error}; file and permission failures are data |
Use `path` as the inputs for this operation.
Effects: fs.read.
Call this function directly:
```sh
marqdo call lib/fs.mq.md try_read_text 'path="lib/fs.mq.md"' --effects fs.read --fs-root . --json
```
Read at most 8 MiB of UTF-8 text as {ok,value,error}; file, encoding and permission failures are data. The function still requires fs.read.
Return *[Read at most 8 MiB of UTF-8 text as {ok,value,error}; file, encoding and permission failures are data](> host_fs_try_read_text path=`path`)*.
## try_write_text
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| text | text | required | Text to read, transform or emit as described by this operation |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | Overwrite UTF-8 text and return {ok,value,error}; requires fs |
Use `path`, `text` as the inputs for this operation.
Effects: fs.write.
Overwrite UTF-8 text and return {ok,value,error}; requires fs.write.
Return *[Overwrite UTF-8 text and return {ok,value,error}; requires fs.write](> host_fs_try_write_text path=`path` text=`text`)*.
## read_bytes
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| max_bytes | number | 8388608 | Maximum bytes read or expanded; exceeding it fails |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | Read binary data as a bytes record |
Use `path`, `max_bytes`=8388608 as the inputs for this operation.
Effects: fs.read.
Read binary data as a bytes record. Default limit is 8 MiB, maximum is 64 MiB; decoding is explicit via lib/bytes.
Return *[Read binary data as a bytes record](> host_fs_read_bytes path=`path` max_bytes=`max_bytes`)*.
## write_bytes
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| data | map | required | Portable bytes record containing _type=bytes and base64 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path`, `data` as the inputs for this operation.
Effects: fs.write.
Atomically replace a file with bytes; no UTF-8 conversion. Requires fs.write.
Return *[Atomically replace a file with bytes; no UTF-8 conversion](> host_fs_write_bytes path=`path` data=`data`)*.
## read_chunk
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| offset | number | 0 | Zero-based byte offset of the next chunk |
| size | number | 65536 | Number of bytes to read in this chunk |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | Read at most size bytes from offset, returning data/next_offset/eof |
Use `path`, `offset`=0, `size`=65536 as the inputs for this operation.
Effects: fs.read.
Read at most size bytes from offset, returning data/next_offset/eof. Offsets are zero-based bytes; each call closes the file, so no handles escape sessions.
Return *[Read at most size bytes from offset, returning data/next_offset/eof](> host_fs_read_chunk path=`path` offset=`offset` size=`size`)*.
## append_bytes
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| data | map | required | Portable bytes record containing _type=bytes and base64 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path`, `data` as the inputs for this operation.
Effects: fs.write.
Append bytes, creating a file if absent; parent directory must exist.
Return *[Append bytes, creating a file if absent; parent directory must exist](> host_fs_append_bytes path=`path` data=`data`)*.
## atomic_write
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| text | text | required | Text to read, transform or emit as described by this operation |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path`, `text` as the inputs for this operation.
Effects: fs.write.
Replace text through a reserved sibling temporary file and rename; failures remove that temp file. This is one-file replacement, not a multi-file transaction.
Return *[Replace text through a reserved sibling temporary file and rename; failures remove that temp file](> host_fs_atomic_write path=`path` text=`text`)*.
## write_changed
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| text | text | required | Text to read, transform or emit as described by this operation |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | bool | Write atomically only when content differs; return whether it was written |
Use `path`, `text` as the inputs for this operation.
Effects: fs.write.
Write atomically only when content differs; return whether it was written.
Return *[Write atomically only when content differs; return whether it was written](> host_fs_write_changed path=`path` text=`text`)*.
## write_checked
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| text | text | required | Text to read, transform or emit as described by this operation |
| expected_sha256 | text | required | Digest of the exact prior text; None disables the check where allowed |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | Check current SHA-256 before atomic replacement, returning Result |
Use `path`, `text`, `expected_sha256` as the inputs for this operation.
Effects: fs.write.
Check current SHA-256 before atomic replacement, returning Result. Detects stale content; concurrent writers still need external coordination.
Return *[Check current SHA-256 before atomic replacement, returning Result](> host_fs_write_checked path=`path` text=`text` expected_sha256=`expected_sha256`)*.
## read_lines
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| max_bytes | number | 8388608 | Maximum bytes read or expanded; exceeding it fails |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Read bounded UTF-8 lines without terminators; CRLF is accepted and a final newline does not create a phantom row |
Use `path`, `max_bytes`=8388608 as the inputs for this operation.
Effects: fs.read.
Read bounded UTF-8 lines without terminators; CRLF is accepted and a final newline does not create a phantom row.
Return *[Read bounded UTF-8 lines without terminators; CRLF is accepted and a final newline does not create a phantom row](> host_fs_read_lines path=`path` max_bytes=`max_bytes`)*.
## write_lines
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| lines | list | required | List of text lines to write |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path`, `lines` as the inputs for this operation.
Effects: fs.write.
Atomically write text lines using LF and one final newline for nonempty input.
Return *[Atomically write text lines using LF and one final newline for nonempty input](> host_fs_write_lines path=`path` lines=`lines`)*.
## remove_file
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path` as the inputs for this operation.
Effects: fs.write.
Delete a file, refusing directories; missing paths fail. Legacy remove remains recursive for compatibility.
Return *[Delete a file, refusing directories; missing paths fail](> host_fs_remove_file path=`path`)*.
## remove_empty_dir
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path` as the inputs for this operation.
Effects: fs.write.
Delete only an empty directory; refuses nonempty directories. Native filesystem only.
Return *[Delete only an empty directory; refuses nonempty directories](> host_fs_remove_empty_dir path=`path`)*.
## temp_dir
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prefix | text | "mqtmp" | Prefix added to the generated name or tested against text |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | text | Create a directory under the filesystem root and return its relative name |
Use `prefix`="mqtmp" as the inputs for this operation.
Effects: fs.write.
Create a directory under the filesystem root and return its relative name. Caller owns cleanup with remove_tree; never uses a global OS temp directory.
Return *[Create a directory under the filesystem root and return its relative name](> host_fs_temp_dir prefix=`prefix`)*.
## file_hash
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | text | Compute SHA-256 with a 64 KiB read buffer; supports binary and large files without loading the whole file |
Use `path` as the inputs for this operation.
Effects: fs.read.
Compute SHA-256 with a 64 KiB read buffer; supports binary and large files without loading the whole file.
Return *[Compute SHA-256 with a 64 KiB read buffer; supports binary and large files without loading the whole file](> host_fs_file_hash path=`path`)*.
## find
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path within the granted filesystem root |
| pattern | text | "**" | Relative path glob supporting *, ** and ? |
| exclude | any | None | Glob pattern list pruned during traversal; None excludes nothing |
| max_depth | number | 64 | Maximum traversal depth |
| kind | text | "file" | Entry kind filter: file, dir or all (files and directories) |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Find sorted relative paths with star, double-star and question-mark globs; exclude patterns prune directories; kind is file/dir/all |
Use `path`, `pattern`="**", `exclude`=None, `max_depth`=64, `kind`="file" as the inputs for this operation.
Effects: fs.read.
Find sorted relative paths with star, double-star and question-mark globs; exclude patterns prune directories; kind is file/dir/all. No symlink traversal; at most 100000 results. Native filesystem snapshot.
Return *[Find sorted relative paths with star, double-star and question-mark globs; exclude patterns prune directories; kind is file/dir/all](> host_fs_find path=`path` pattern=`pattern` exclude=`exclude` max_depth=`max_depth` kind=`kind`)*.
## copy_tree
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| src | text | required | Source path; archive packing expects a directory |
| dest | text | required | Destination path; overwrite is allowed only where documented |
| overwrite | bool | False | Whether an existing destination file may be replaced |
| exclude | any | None | Glob pattern list pruned during traversal; None excludes nothing |
| dry_run | bool | False | Whether to return the plan without modifying files |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Copy files between disjoint trees |
Use `src`, `dest`, `overwrite`=False, `exclude`=None, `dry_run`=False as the inputs for this operation.
Effects: fs.write.
Copy files between disjoint trees. Preflight conflicts; overwrite is opt-in. Returns relative changed files; dry_run plans only. Does not copy permissions, symlinks or empty directories.
Return *[Copy files between disjoint trees](> host_fs_copy_tree src=`src` dest=`dest` overwrite=`overwrite` exclude=`exclude` dry_run=`dry_run`)*.
## sync_tree
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| src | text | required | Source path; archive packing expects a directory |
| dest | text | required | Destination path; overwrite is allowed only where documented |
| overwrite | bool | False | Whether an existing destination file may be replaced |
| exclude | any | None | Glob pattern list pruned during traversal; None excludes nothing |
| dry_run | bool | False | Whether to return the plan without modifying files |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Copy new or changed files with copy_tree conflict rules |
Use `src`, `dest`, `overwrite`=False, `exclude`=None, `dry_run`=False as the inputs for this operation.
Effects: fs.write.
Copy new or changed files with copy_tree conflict rules. Never deletes destination-only files; execution is not transactional.
Return *[Copy new or changed files with copy_tree conflict rules](> host_fs_sync_tree src=`src` dest=`dest` overwrite=`overwrite` exclude=`exclude` dry_run=`dry_run`)*.
## rename_many
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| moves | list | required | List of source/destination rename records |
| dry_run | bool | False | Whether to return the plan without modifying files |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | number | Preflight src/dest file records, reject existing or duplicate destinations, then rename in input order |
Use `moves`, `dry_run`=False as the inputs for this operation.
Effects: fs.write.
Preflight src/dest file records, reject existing or duplicate destinations, then rename in input order. No cycles or rollback; dry_run reports the planned count.
Return *[Preflight src/dest file records, reject existing or duplicate destinations, then rename in input order](> host_fs_rename_many moves=`moves` dry_run=`dry_run`)*.
## read_json
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to filesystem root |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 解析后的数据 |
Use `path` as the inputs for this operation.
Effects: fs.read.
Read UTF-8 then use the standard parser; errors abort, so batch tasks should first use try_read_text.
We retain **`body` = [Read UTF-8 text from the selected file](read_text(path=`path`))**.
Return *[Parse the JSON transport text](json.parse(text=`body`))*.
## write_json
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to filesystem root |
| value | any | required | Data to serialize |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path`, `value` as the inputs for this operation.
Effects: fs.write.
Serialize then atomically replace the file; formatting and comments are not preserved.
We retain **`body` = [Encode the structured value as JSON text](json.stringify(value=`value`))**.
Return *[Atomic write](atomic_write(path=`path`, text=`body`))*.
## read_csv
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to filesystem root |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 解析后的数据 |
Use `path` as the inputs for this operation.
Effects: fs.read.
Read UTF-8 then use the standard parser; errors abort, so batch tasks should first use try_read_text.
We retain **`body` = [Read UTF-8 text from the selected file](read_text(path=`path`))**.
Return *[Parse](csv.parse(text=`body`))*.
## write_csv
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to filesystem root |
| value | list | required | Data to serialize |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | None after completion; filesystem failures produce a diagnostic |
Use `path`, `value` as the inputs for this operation.
Effects: fs.write.
Serialize then atomically replace the file; formatting and comments are not preserved.
We retain **`body` = [Stringify](csv.stringify(rows=`value`))**.
Return *[Atomic write](atomic_write(path=`path`, text=`body`))*.
## resolve
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Path relative to the granted filesystem root, or an absolute path inside it |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Normalized absolute logical path after the native root and symlink checks |
Use `path` to obtain an absolute address before giving a local file to another resource, such as a SQLite URL. The host resolves it using the same filesystem context as read_text and temp_dir, so a different process working directory does not change the selected root. The destination may not exist yet; its nearest existing ancestor still undergoes the native root and symlink checks. Requires fs.read and creates no file. The returned path remains logical, including permitted links; external plugins and processes retain their own operating-system authority.
Return *[Resolve the path through the native filesystem context](host_fs_resolve(path=`path`))*.