Files
marqdo/lib/sys.mq.md

217 lines
6.1 KiB
Markdown

---
markup: occlusion
title: lib/sys
description: English system wrappers (load_dotenv accepts optional path via host alias)
---
English system wrappers (load_dotenv accepts optional path via host alias)
Inspect execution metadata and interact with the host system.
Behavior and limits: Metadata describes the entry artifact. module_source is entry source, not the imported library. exec needs process.exec; environment operations declare separate effects.
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.
Implementation: [src/host/sys.rs](../src/host/sys.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.
## env_get
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | text | required | Environment variable name |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Get environment variable name |
Use `name` as the inputs for this operation.
Effects: environment.read.
Get environment variable name.
Return *[Get environment variable name](> host_env_get name=`name`)*.
## env_set
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | text | required | Environment variable name |
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Set environment variable name to value |
Use `name`, `value` as the inputs for this operation.
Effects: environment.write.
Set environment variable name to value.
Return *[Set environment variable name to value](> host_env_set name=`name` value=`value`)*.
## load_dotenv
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | None | Path relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Load `.env` (optional named arg `path=`) |
Use `path`=None as the inputs for this operation.
Effects: environment.write,fs.read.
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
Return *[Load .env (optional named arg path=)](> host_dotenv_load path=`path`)*.
## args
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | Process argv list |
Effects: pure.
Process argv list.
Return *[Process argv list](host_args())*.
## cwd
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Current working directory |
Effects: pure.
Current working directory.
Return *[Current working directory](host_cwd())*.
## meta
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Bound Artifact Metadata from the entry `.mq.md` (map) |
Effects: pure.
Call this function directly:
```sh
marqdo call lib/sys.mq.md meta --effects none --json
```
Bound Artifact Metadata from the entry `.mq.md` (map). See `doc/design/binding.md`.
Return *[Bound Artifact Metadata from the entry .mq.md (map)](host_meta())*.
## meta_get
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | text | required | Field name or key required by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Lookup one metadata key; missing → None |
Use `key` as the inputs for this operation.
Effects: pure.
Lookup one metadata key; missing → None.
Return *[Lookup one metadata key; missing → None](> host_meta_get key=`key`)*.
## artifact_kind
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Classify entry Artifact Metadata: `web` / `endpoint` / `prompt` / `other`, or None if no `type`/`类型` |
Effects: pure.
Classify entry Artifact Metadata: `web` / `endpoint` / `prompt` / `other`, or None if no `type`/`类型`. ADR 0007.
Return *[Classify entry Artifact Metadata: web / endpoint / prompt / other, or None if no type/类型](host_artifact_kind())*.
## module_source
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Entry `.mq.md` source text (for document-as-prompt) |
Effects: pure.
Entry `.mq.md` source text (for document-as-prompt). Empty string if unset.
Return *[Entry .mq.md source text (for document-as-prompt)](host_module_source())*.
## exit
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| code | any | required | Process exit status; zero means success |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Exit process with code |
Use `code` as the inputs for this operation.
Effects: process.control.
Exit process with code.
Return *[Exit process with code](> host_exit code=`code`)*.
## exec
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| cmd | any | required | Executable command or interpreter override |
| args | any | None | Argument list passed to the called command or function |
| capture | any | False | Whether to return command output instead of forwarding it |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Run a process |
Use `cmd`, `args`=None, `capture`=False as the inputs for this operation.
Effects: process.exec.
Run a process. Default return is the exit code (int).
With `capture=True`, return a map `{code, stdout, stderr}` (stdout/stderr may be truncated for huge output).
Inside `**…**` prefer bare `args=args` (variable); `` args=`args` `` is also accepted.
Return *[Run a process](> host_exec cmd=`cmd` args=`args` capture=`capture`)*.
## stream_publish
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| event | any | required | Structured event to publish to the active stream |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Publish a stream event map onto the process EventBus (`marqdo view` SSE) |
Use `event` as the inputs for this operation.
Effects: output.write.
Publish a stream event map onto the process EventBus (`marqdo view` SSE). No-op when nothing is subscribed.
Return *[Publish a stream event map onto the process EventBus (marqdo view SSE)](> host_stream_publish event=`event`)*.