249 lines
6.4 KiB
Markdown
249 lines
6.4 KiB
Markdown
---
|
|
markup: occlusion
|
|
title: lib/foreign
|
|
description: Run bound code fences and inline sources via local interpreters
|
|
import:
|
|
table: lib/table.mq.md
|
|
---
|
|
|
|
Run bound code fences and inline sources via local interpreters.
|
|
|
|
## set_cmd
|
|
+ `lang`
|
|
+ `cmd`
|
|
+ `args`=None
|
|
|
|
Bind interpreter command cmd for language lang; optional extra argv.
|
|
|
|
*> host_foreign_set_cmd lang=`lang` cmd=`cmd` args=`args`*
|
|
|
|
## run
|
|
+ `code`
|
|
+ `stdin`=None
|
|
+ `env`=None
|
|
+ `cwd`=None
|
|
+ `timeout`=None
|
|
+ `args`=None
|
|
+ `max_output`=None
|
|
|
|
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`
|
|
|
|
*> host_foreign_run code=`code` stdin=`stdin` env=`env` cwd=`cwd` timeout=`timeout` args=`args` max_output=`max_output`*
|
|
|
|
## run_lang
|
|
+ `lang`
|
|
+ `source`
|
|
+ `stdin`=None
|
|
+ `env`=None
|
|
+ `cwd`=None
|
|
+ `timeout`=None
|
|
+ `args`=None
|
|
+ `max_output`=None
|
|
|
|
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`=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
|
|
|
|
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.
|
|
|
|
*> 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`=None
|
|
|
|
Probe one language, or every known language when lang is omitted. Returns
|
|
{lang, cmd, path, ok, version, error} (a list when lang is omitted).
|
|
|
|
*> host_foreign_probe lang=`lang`*
|
|
|
|
## register
|
|
+ `lang`
|
|
+ `cmd`=None
|
|
+ `args`=None
|
|
+ `template`=None
|
|
+ `ext`=None
|
|
+ `env`=None
|
|
+ `version_args`=None
|
|
|
|
Register a language invocation. Provide cmd (+args) or template (placeholders
|
|
{file}, {dir}, {base}, {inline}, {lang}, {cwd}); they are mutually exclusive.
|
|
|
|
*> host_foreign_register lang=`lang` cmd=`cmd` args=`args` template=`template` ext=`ext` env=`env` version_args=`version_args`*
|
|
|
|
## unset
|
|
+ `lang`
|
|
|
|
Remove a process-local registration. Presets/config/env still apply.
|
|
|
|
*> host_foreign_unset lang=`lang`*
|
|
|
|
## load_config
|
|
+ `path`=None
|
|
|
|
Load .marqdo/foreign.toml (or an explicit path); returns the number of language
|
|
tables read.
|
|
|
|
*> host_foreign_load_config path=`path`*
|
|
|
|
## call
|
|
+ `code`=None
|
|
+ `lang`=None
|
|
+ `source`=None
|
|
+ `input`=None
|
|
+ `stdin`=None
|
|
+ `env`=None
|
|
+ `cwd`=None
|
|
+ `timeout`=None
|
|
+ `args`=None
|
|
|
|
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.
|
|
|
|
*> host_foreign_call code=`code` lang=`lang` source=`source` input=`input` stdin=`stdin` env=`env` cwd=`cwd` timeout=`timeout` args=`args`*
|
|
|
|
## run_many
|
|
+ `runs`
|
|
+ `concurrency`=4
|
|
|
|
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.
|
|
|
|
*> host_foreign_run_many runs=`runs` concurrency=`concurrency`*
|
|
|
|
## call_many
|
|
+ `inputs`
|
|
+ `code`=None
|
|
+ `lang`=None
|
|
+ `source`=None
|
|
+ `cmd`=None
|
|
+ `env`=None
|
|
+ `cwd`=None
|
|
+ `timeout`=None
|
|
+ `args`=None
|
|
+ `max_output`=None
|
|
+ `concurrency`=4
|
|
|
|
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.
|
|
|
|
*> 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`=None
|
|
+ `cells`=None
|
|
+ `values`=None
|
|
+ `inputs`=None
|
|
|
|
Declare a document view session. `kernels` and `cells` are ordinary tables:
|
|
kernels are `|名称|语言|命令|` (ZH or EN), cells are `|单元|内核|`.
|
|
Returns a foreign session handle consumed by `view`; without this handle the
|
|
view has no persistent kernel state.
|
|
|
|
**p = > table.empty_map**
|
|
**p = > table.put in=`p` at="kind" value="foreign-session"**
|
|
**p = > table.put in=`p` at="kernels" value=`kernels`**
|
|
**p = > table.put in=`p` at="cells" value=`cells`**
|
|
**p = > table.put in=`p` at="values" value=`values`**
|
|
**p = > table.put in=`p` at="inputs" value=`inputs`**
|
|
*p*
|
|
|
|
## session_open
|
|
+ `lang`
|
|
+ `cmd`=None
|
|
+ `env`=None
|
|
+ `cwd`=None
|
|
+ `timeout`=None
|
|
|
|
Start a persistent Python/Node kernel; returns a session id. `timeout` is the
|
|
default per-eval timeout.
|
|
|
|
*> host_foreign_session_open lang=`lang` cmd=`cmd` env=`env` cwd=`cwd` timeout=`timeout`*
|
|
|
|
## session_eval
|
|
+ `id`
|
|
+ `code`=None
|
|
+ `source`=None
|
|
+ `input`=None
|
|
+ `stdin`=None
|
|
+ `timeout`=None
|
|
|
|
Evaluate code (a code value) or source text in session id; returns a record
|
|
with id/alive. `input` is JSON-encoded for the kernel; `stdin` is raw program
|
|
stdin for this evaluation.
|
|
|
|
*> host_foreign_session_eval id=`id` code=`code` source=`source` input=`input` stdin=`stdin` timeout=`timeout`*
|
|
|
|
## session_set
|
|
+ `id`
|
|
+ `name`
|
|
+ `value`
|
|
|
|
Set one kernel variable from a Marqdo value (JSON copy).
|
|
|
|
*> host_foreign_session_set id=`id` name=`name` value=`value`*
|
|
|
|
## session_get
|
|
+ `id`
|
|
+ `name`
|
|
|
|
Read one kernel variable as a Marqdo value.
|
|
|
|
*> host_foreign_session_get id=`id` name=`name`*
|
|
|
|
## session_names
|
|
+ `id`
|
|
|
|
List kernel variable names.
|
|
|
|
*> host_foreign_session_names id=`id`*
|
|
|
|
## session_close
|
|
+ `id`
|
|
|
|
Kill and remove a session; returns whether it existed.
|
|
|
|
*> host_foreign_session_close id=`id`*
|
|
|
|
## session_interrupt
|
|
+ `id`
|
|
|
|
Interrupt the current evaluation of a persistent kernel. The session remains
|
|
usable for the next evaluation when the worker supports interruption.
|
|
|
|
*> host_foreign_session_interrupt id=`id`*
|
|
|
|
## session_list
|
|
|
|
List live sessions with id/lang/cmd/evals/alive/started_ms.
|
|
|
|
*> host_foreign_session_list*
|
|
|
|
## langs
|
|
|
|
List configured foreign languages.
|
|
|
|
*> host_foreign_langs*
|