Files
marqdo/lib/foreign.mq.md

23 KiB

markup, title, description, import
markup title description import
occlusion lib/foreign Run bound code fences and inline sources via local interpreters
table
lib/table.mq.md

Run bound code fences and inline sources via local interpreters.

Bridge explicit values to external language processes and sessions.

Behavior and limits: Configured languages are not proof that interpreters are installed. invoke exposes exit/timeout/output limits. External execution requires process.exec; close owned persistent sessions.

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/foreign.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.

set_cmd

参数 类型 默认 说明
lang text required Registered interpreter language identifier, such as node
cmd any required Executable command or interpreter override
args any None Argument list passed to the called command or function
返回 类型 说明
result any Bind interpreter command cmd for language lang; optional extra argv

Use lang, cmd, args=None as the inputs for this operation.

Effects: pure.

Bind interpreter command cmd for language lang; optional extra argv.

Return [Bind interpreter command cmd for language lang; optional extra argv](> host_foreign_set_cmd lang=lang cmd=cmd args=args).

run

参数 类型 默认 说明
code any required Bound code-fence value; supply lang and source for inline text
stdin any None Text written to the child process standard input
env any None Environment variable/value record for the child process
cwd any None Child process working directory
timeout any None Execution timeout in seconds; None uses the host default
args any None Argument list passed to the called command or function
max_output any None Maximum captured output bytes; None uses the host default
返回 类型 说明
result any Run a bound code fence value; optional stdin, env map, cwd, timeout (seconds), extra argv and output cap

Use code, stdin=None, env=None, cwd=None, timeout=None, args=None, max_output=None as the inputs for this operation.

Effects: process.exec.

Run a bound code fence value; optional stdin, env map, cwd, timeout (seconds), extra argv and output cap. Returns stdout text; non-zero exit is an error.

Caller: [foreign.run] code=block

Return [Run a bound code fence value; optional stdin, env map, cwd, timeout (seconds), extra argv and output cap](> host_foreign_run code=code stdin=stdin env=env cwd=cwd timeout=timeout args=args max_output=max_output).

run_lang

参数 类型 默认 说明
lang text required Registered interpreter language identifier, such as python
source any required Source text to run with the selected interpreter
stdin any None Text written to the child process standard input
env any None Environment variable/value record for the child process
cwd any None Child process working directory
timeout any None Execution timeout in seconds; None uses the host default
args any None Argument list passed to the called command or function
max_output any None Maximum captured output bytes; None uses the host default
返回 类型 说明
result any Run source text with language lang; same options as run

Use lang, source, stdin=None, env=None, cwd=None, timeout=None, args=None, max_output=None as the inputs for this operation.

Effects: process.exec.

Run source text with language lang; same options as run.

Return [Run source text with language lang; same options as run](> host_foreign_run_lang lang=lang source=source stdin=stdin env=env cwd=cwd timeout=timeout args=args max_output=max_output).

invoke

参数 类型 默认 说明
code any None Bound code-fence value; supply lang and source for inline text
lang any None Registered interpreter language identifier, such as python
source any None Source text to run with the selected interpreter
stdin any None Text written to the child process standard input
input any None Structured value JSON-encoded on stdin; cannot combine with stdin
env any None Environment variable/value record for the child process
cwd any None Child process working directory
timeout any None Execution timeout in seconds; None uses the host default
args any None Argument list passed to the called command or function
output any "auto" Result decoding mode: auto, text, json or lines
max_output any None Maximum captured output bytes; None uses the host default
cmd any None Executable command or interpreter override
keep any False Whether to retain the generated script for inspection
返回 类型 说明
result any Run code or lang+source and return a record map instead of raising on process failure

Use code=None, lang=None, source=None, stdin=None, input=None, env=None, cwd=None, timeout=None, args=None, output="auto", max_output=None, cmd=None, keep=False as the inputs for this operation.

Effects: process.exec.

Run code or lang+source and return a record map instead of raising on process failure. Fields: ok, code, stdout, stderr, ms, lang, cmd, timed_out, truncated, result, result_error, error, script, cached.

input is encoded as JSON on stdin (mutually exclusive with stdin). output is auto | text | json | lines. cmd overrides the interpreter for this call.

Return [Run code or lang+source and return a record map instead of raising on process failure](> host_foreign_invoke code=code lang=lang source=source stdin=stdin input=input env=env cwd=cwd timeout=timeout args=args output=output max_output=max_output cmd=cmd keep=keep).

probe

参数 类型 默认 说明
lang any None Registered interpreter language identifier, such as python
返回 类型 说明
result any Probe one language, or every known language when lang is omitted

Use lang=None as the inputs for this operation.

Effects: process.exec.

Probe one language, or every known language when lang is omitted. Returns {lang, cmd, path, ok, version, error} (a list when lang is omitted).

Return [Probe one language, or every known language when lang is omitted](> host_foreign_probe lang=lang).

register

参数 类型 默认 说明
lang text required Registered interpreter language identifier, such as python
cmd any None Executable command or interpreter override
args any None Argument list passed to the called command or function
template any None Interpreter launch template
ext any None Temporary script filename extension
env any None Environment variable/value record for the child process
version_args any None Arguments used to query the interpreter version
返回 类型 说明
result any Register a language invocation

Use lang, cmd=None, args=None, template=None, ext=None, env=None, version_args=None as the inputs for this operation.

Effects: pure.

Register a language invocation. Provide cmd (+args) or template (placeholders {file}, {dir}, {base}, {inline}, {lang}, {cwd}); they are mutually exclusive.

Return [Register a language invocation](> host_foreign_register lang=lang cmd=cmd args=args template=template ext=ext env=env version_args=version_args).

unset

参数 类型 默认 说明
lang text required Registered interpreter language identifier, such as python
返回 类型 说明
result any Remove a process-local registration

Use lang as the inputs for this operation.

Effects: pure.

Remove a process-local registration. Presets/config/env still apply.

Return [Remove a process-local registration](> host_foreign_unset lang=lang).

load_config

参数 类型 默认 说明
path any None Path relative to the granted filesystem root
返回 类型 说明
result any Load .marqdo/foreign.toml (or an explicit path); returns the number of language tables read

Use path=None as the inputs for this operation.

Effects: fs.read.

Load .marqdo/foreign.toml (or an explicit path); returns the number of language tables read.

Return [Load .marqdo/foreign.toml (or an explicit path); returns the number of language tables read](> host_foreign_load_config path=path).

call

参数 类型 默认 说明
code any None Bound code-fence value; supply lang and source for inline text
lang any None Registered interpreter language identifier, such as python
source any None Source text to run with the selected interpreter
input any None Structured value JSON-encoded on stdin; cannot combine with stdin
stdin any None Text written to the child process standard input
env any None Environment variable/value record for the child process
cwd any None Child process working directory
timeout any None Execution timeout in seconds; None uses the host default
args any None Argument list passed to the called command or function
返回 类型 说明
result any JSON-in / JSON-out call: encode input on stdin, parse stdout JSON and return the value (empty stdout -> None)

Use code=None, lang=None, source=None, input=None, stdin=None, env=None, cwd=None, timeout=None, args=None as the inputs for this operation.

Effects: process.exec.

JSON-in / JSON-out call: encode input on stdin, parse stdout JSON and return the value (empty stdout -> None). Raises on process failure or invalid JSON.

Return [JSON-in / JSON-out call: encode input on stdin, parse stdout JSON and return the value (empty stdout -> None)](> host_foreign_call code=code lang=lang source=source input=input stdin=stdin env=env cwd=cwd timeout=timeout args=args).

run_many

参数 类型 默认 说明
runs any required Ordered per-run code or language/source records
concurrency any 4 Maximum number of concurrent operations
返回 类型 说明
result any Run a list of code values or invoke-option maps in parallel; returns records in input order

Use runs, concurrency=4 as the inputs for this operation.

Effects: process.exec.

Run a list of code values or invoke-option maps in parallel; returns records in input order. One failing item does not stop the others.

Return [Run a list of code values or invoke-option maps in parallel; returns records in input order](> host_foreign_run_many runs=runs concurrency=concurrency).

call_many

参数 类型 默认 说明
inputs any required Input values for the batched calls
code any None Bound code-fence value; supply lang and source for inline text
lang any None Registered interpreter language identifier, such as python
source any None Source text to run with the selected interpreter
cmd any None Executable command or interpreter override
env any None Environment variable/value record for the child process
cwd any None Child process working directory
timeout any None Execution timeout in seconds; None uses the host default
args any None Argument list passed to the called command or function
max_output any None Maximum captured output bytes; None uses the host default
concurrency any 4 Maximum number of concurrent operations
返回 类型 说明
result any Apply one code/function to each input in parallel; returns parsed JSON results in input order

Use inputs, code=None, lang=None, source=None, cmd=None, env=None, cwd=None, timeout=None, args=None, max_output=None, concurrency=4 as the inputs for this operation.

Effects: process.exec.

Apply one code/function to each input in parallel; returns parsed JSON results in input order. Raises with the failing index after all workers finish.

Return [Apply one code/function to each input in parallel; returns parsed JSON results in input order](> host_foreign_call_many inputs=inputs code=code lang=lang source=source cmd=cmd env=env cwd=cwd timeout=timeout args=args max_output=max_output concurrency=concurrency).

session

参数 类型 默认 说明
kernels any None Kernel rows: name/language and optional command/environment settings
cells any None Cell-to-kernel routing rows; referenced code fences belong to the document
values any None Rows naming a kernel, variable name and native value to copy
inputs any None Optional declared per-cell input values
返回 类型 说明
result map Plain view plan with kind, kernels, cells, values and inputs

Use kernels=None, cells=None, values=None and inputs=None to declare a view session from ordinary data tables. The returned map has kind="foreign-session" and the four supplied specifications. This pure task does not launch an interpreter, create a live kernel or read another file. View later consumes the plan and the document's bound code fences. Bind the plan to 会话 in the entry procedure: View uses this documented binding to distinguish a declared plan from ordinary maps and low-level live session handles. A normal ## main function can be called directly and indexed by View; the separate native report example shows the complete declarations.

Kernel rows identify languages explicitly; the native-first public workflow uses Node only for Intl formatting after Marqdo has computed its data. A values row copies a JSON-safe native value into a named kernel variable. Cells in the same kernel share state, while separate kernel rows preserve isolation. Missing or invalid runtime declarations remain the View/session diagnostic.

This result is a serializable plan, so it can be returned by marqdo call. A live session_open handle is a different resource and cannot be reconstructed from a JSON string. For a low-level multi-evaluation task, open, use and close that handle within one callable workflow; format_summary in the native report example demonstrates that lifetime and its real failure exits.

plan =

kind kernels cells values inputs
"foreign-session" kernels cells values inputs

After declaring the explicit view inputs we return plan.

session_open

参数 类型 默认 说明
lang text required Registered interpreter language identifier, such as python
cmd any None Executable command or interpreter override
env any None Environment variable/value record for the child process
cwd any None Child process working directory
timeout any None Execution timeout in seconds; None uses the host default
返回 类型 说明
result any Start a persistent Python/Node kernel; returns an opaque handle value

Use lang, cmd=None, env=None, cwd=None, timeout=None as the inputs for this operation.

Effects: process.exec.

Start a persistent Python/Node kernel; returns an opaque handle value. Text fabrications are refused by session ops; handles cannot cross the JSON bridge. timeout is the default per-eval timeout.

Return [Start a persistent Python/Node kernel; returns an opaque handle value](> host_foreign_session_open lang=lang cmd=cmd env=env cwd=cwd timeout=timeout).

session_eval

参数 类型 默认 说明
id any required Opaque session_open handle retained in this process; never rebuild it from id text
code any None Bound code-fence value; supply lang and source for inline text
source any None Source text to run with the selected interpreter
input any None Structured value JSON-encoded on stdin; cannot combine with stdin
stdin any None Text written to the child process standard input
timeout any None Execution timeout in seconds; None uses the host default
返回 类型 说明
result any Evaluation record: ok/code/result/stdout/stderr/alive/timed_out/ms and diagnostic metadata

Use id, code=None, source=None, input=None, stdin=None, timeout=None as the inputs for this operation.

Effects: process.exec.

Evaluate code (a code value) or source text in session id; returns a record with ok/code/result/stdout/stderr/alive/timed_out/ms. Inspect ok before result: code is zero on success and -1 on a kernel failure. stdout and stderr preserve captured text; error explains a failed evaluation. alive says whether the kernel can still be used. An ordinary language exception can leave it alive; process death or timeout may retire it. Close only the live original handle. The record's text id is diagnostic identity and cannot replace that opaque handle.

input is JSON-encoded for the kernel; stdin is raw program stdin for this evaluation. JSON-unsafe values remain diagnostics, never guessed text. Effects require process.exec, and the timeout is seconds while ms reports elapsed time.

Return [Evaluate code (a code value) or source text in session id; returns a record with id/alive](> host_foreign_session_eval id=id code=code source=source input=input stdin=stdin timeout=timeout).

session_set

参数 类型 默认 说明
id any required Opaque session_open handle retained in this process; never rebuild it from id text
name text required Name to resolve, register or look up
value any required Value to transform or store, without mutating the input
返回 类型 说明
result any Set one kernel variable from a Marqdo value (JSON copy)

Use id, name, value as the inputs for this operation.

Effects: process.exec.

Set one kernel variable from a Marqdo value (JSON copy).

Return [Set one kernel variable from a Marqdo value (JSON copy)](> host_foreign_session_set id=id name=name value=value).

session_get

参数 类型 默认 说明
id any required Opaque session_open handle retained in this process; never rebuild it from id text
name text required Name to resolve, register or look up
返回 类型 说明
result any Read one kernel variable as a Marqdo value

Use id, name as the inputs for this operation.

Effects: process.exec.

Read one kernel variable as a Marqdo value.

Return [Read one kernel variable as a Marqdo value](> host_foreign_session_get id=id name=name).

session_names

参数 类型 默认 说明
id any required Opaque session_open handle retained in this process; never rebuild it from id text
返回 类型 说明
result any List kernel variable names

Use id as the inputs for this operation.

Effects: process.exec.

List kernel variable names.

Return [List kernel variable names](> host_foreign_session_names id=id).

session_close

参数 类型 默认 说明
id any required Opaque session_open handle retained in this process; never rebuild it from id text
返回 类型 说明
result any Consume (affine close) a live session handle: kill and remove it

Use id as the inputs for this operation.

Effects: process.exec.

Consume (affine close) a live session handle: kill and remove it. Returns True on success. Closing an unknown or already-closed id is a fault (foreign session … not found), matching use-after-close on eval/set/get.

Return [Consume (affine close) a live session handle: kill and remove it](> host_foreign_session_close id=id).

session_interrupt

参数 类型 默认 说明
id any required Opaque session_open handle retained in this process; never rebuild it from id text
返回 类型 说明
result any Interrupt the current evaluation of a persistent kernel

Use id as the inputs for this operation.

Effects: process.exec.

Interrupt the current evaluation of a persistent kernel. The session remains usable for the next evaluation when the worker supports interruption.

Return [Interrupt the current evaluation of a persistent kernel](> host_foreign_session_interrupt id=id).

session_list

返回 类型 说明
result any List live sessions with id/lang/cmd/evals/alive/started_ms

Effects: process.exec.

List live sessions with id/lang/cmd/evals/alive/started_ms.

Return List live sessions with id/lang/cmd/evals/alive/started_ms.

langs

返回 类型 说明
result any List configured foreign languages

Effects: pure.

Call this function directly:

marqdo call lib/foreign.mq.md langs  --effects none --json

List configured foreign languages.

Return configured language definitions without launching interpreters. Use probe separately to check executable availability.

Return List configured foreign languages.

oracle_journal

返回 类型 说明
result any Return this document evaluation's admitted eval/get/decode observations as ordinary records with index, channel, value

Effects: pure.

Return this document evaluation's admitted eval/get/decode observations as ordinary records with index, channel, value. Opening, setting and closing do not append observations.

Return [Return this document evaluation's admitted eval/get/decode observations as ordinary records with index, channel, value](> host_oracle_journal ).

replay_check

参数 类型 默认 说明
expected any required Expected observation record used for replay comparison
observed any required Actual observation record used for replay comparison
返回 类型 说明
result any Compare two oracle journals without executing foreign code

Use expected, observed as the inputs for this operation.

Effects: pure.

Compare two oracle journals without executing foreign code. Returns ok and the least mismatching index, with the expected and observed records.

Return [Compare two oracle journals without executing foreign code](> host_oracle_replay_check expected=expected observed=observed).