Discovery. A probe is a law stated as a tiny script with an expected stdout, run in the runtime under study.
printed exactly :expect -> :yes (law holds here) ran, printed anything else -> :no (law refuted here) never ran (launch error, timeout) -> :unknown prerequisite (:needs) not :yes -> :unknown, probe skipped
Every verdict becomes Evidence carrying the script, exit status and output, so any later choice can be traced back to what was observed. This namespace is pure: the runner is passed in.
Discovery. A probe is a law stated as a tiny script with an expected stdout, run in the runtime under study. printed exactly :expect -> :yes (law holds here) ran, printed anything else -> :no (law refuted here) never ran (launch error, timeout) -> :unknown prerequisite (:needs) not :yes -> :unknown, probe skipped Every verdict becomes Evidence carrying the script, exit status and output, so any later choice can be traced back to what was observed. This namespace is pure: the runner is passed in.
Every built-in probe: the sh probes, then the python ones, then the sh probes lifted into python (py-sh-probes). What grammar.core's :core module composes. discover! keeps the ones written in the runtime's language.
Every built-in probe: the sh probes, then the python ones, then the sh probes lifted into python (py-sh-probes). What grammar.core's :core module composes. discover! keeps the ones written in the runtime's language.
(discover runtime-id run!)(discover runtime-id run! probes)Run every probe through run! (fn [script] -> {:argv :exit :out :err} or {:argv :error}), in order, folding the evidence into a fresh profile. probes are run as given, whatever their :lang; pick them with for-lang. The 2-arity runs the sh probes.
Run every probe through run! (fn [script] -> {:argv :exit :out :err} or
{:argv :error}), in order, folding the evidence into a fresh profile.
probes are run as given, whatever their :lang; pick them with for-lang.
The 2-arity runs the sh probes.(for-lang lang ps)The probes of ps whose script is written in lang, in order.
The probes of ps whose script is written in lang, in order.
(judge {:keys [expect]} {:keys [out error]})Verdict of one probe run. A run that never happened proves nothing.
Verdict of one probe run. A run that never happened proves nothing.
(on-demand lang cap)Probe for a capability the fixed catalog cannot list ahead of time, in the runtime's language, or nil. :bin/<prog> exec finds prog: an executable file on PATH (or prog itself when it holds a slash). Builtins do not count. :sh.cmd/<prog> the shell resolves the word prog (command -v): PATH, builtins and applets all count. In a python runtime it is the sh probe lifted by sh-via-python: the law of the sh that python reaches.
Probe for a capability the fixed catalog cannot list ahead of time, in
the runtime's language, or nil.
:bin/<prog> exec finds prog: an executable file on PATH (or prog
itself when it holds a slash). Builtins do not count.
:sh.cmd/<prog> the shell resolves the word prog (command -v): PATH,
builtins and applets all count. In a python runtime it
is the sh probe lifted by sh-via-python: the law of the
sh that python reaches.(probe-lang probe)Language a probe's script is written in: its :lang, :sh when absent. discover runs a probe only in a runtime of that language.
Language a probe's script is written in: its :lang, :sh when absent. discover runs a probe only in a runtime of that language.
The sh probes: scripts for a runtime whose language is :sh. Ordered so that every :needs is probed before the probes that rely on it. Probe scripts avoid output redirection on purpose: a restricted shell must still be able to answer every other question.
The :py/ and :py.os/ probes are not written here: each is a py-probe
run as python3 -c '<the python probe>', so a :py/ cap names the same
law whether a python runtime proved it itself or a shell proved it of
the python3 it reaches.
The sh probes: scripts for a runtime whose language is :sh. Ordered so that every :needs is probed before the probes that rely on it. Probe scripts avoid output redirection on purpose: a restricted shell must still be able to answer every other question. The :py/ and :py.os/ probes are not written here: each is a py-probe run as `python3 -c '<the python probe>'`, so a :py/ cap names the same law whether a python runtime proved it itself or a shell proved it of the python3 it reaches.
Probes written in python, for a runtime whose language is :python
(python3 -c). Ordered like probes: every :needs is probed earlier in
this list. A probe performs the operation its law is about, never just an
import: a runtime that refuses it (a missing module, an OSError, an audit
hook raising on subprocess, socket or a write-mode open) prints no. Each
script lifts into an sh probe (see python-via-sh).
:py/sys import sys and sys.stdout.write work :py/stdout-buffer bytes written to sys.stdout.buffer arrive unchanged: NUL, a two-byte UTF-8 sequence and CR LF included :py/pathlib import pathlib :py/open-write pathlib writes a file under $TMPDIR (else /tmp) and reads the same bytes back :py.os/mkdir pathlib.mkdir (os.mkdir) makes a directory there :py.os/unlink pathlib.unlink (os.unlink) removes a symlink made there, so it needs no write-mode open; a runtime that refuses os.symlink refutes it too :py/subprocess subprocess runs sys.executable as a child and reads its stdout :py/urllib urllib.request fetches a body from a server this script listens with on 127.0.0.1 :interp/sh subprocess runs ["sh" "-c" ...], sh found on PATH: the argv :ctx/python->sh runs. With PATH set, a /bin/sh off PATH does not count; with PATH unset python searches os.defpath, as the wrapper does. Marked :lift false: sh runtimes prove :interp/sh with their own probe.
Probes written in python, for a runtime whose language is :python
(python3 -c). Ordered like `probes`: every :needs is probed earlier in
this list. A probe performs the operation its law is about, never just an
import: a runtime that refuses it (a missing module, an OSError, an audit
hook raising on subprocess, socket or a write-mode open) prints no. Each
script lifts into an sh probe (see python-via-sh).
:py/sys import sys and sys.stdout.write work
:py/stdout-buffer bytes written to sys.stdout.buffer arrive unchanged:
NUL, a two-byte UTF-8 sequence and CR LF included
:py/pathlib import pathlib
:py/open-write pathlib writes a file under $TMPDIR (else /tmp) and
reads the same bytes back
:py.os/mkdir pathlib.mkdir (os.mkdir) makes a directory there
:py.os/unlink pathlib.unlink (os.unlink) removes a symlink made
there, so it needs no write-mode open; a runtime that
refuses os.symlink refutes it too
:py/subprocess subprocess runs sys.executable as a child and reads
its stdout
:py/urllib urllib.request fetches a body from a server this
script listens with on 127.0.0.1
:interp/sh subprocess runs ["sh" "-c" ...], sh found on PATH:
the argv :ctx/python->sh runs. With PATH set, a
/bin/sh off PATH does not count; with PATH unset
python searches os.defpath, as the wrapper does.
Marked :lift false: sh runtimes prove :interp/sh with
their own probe.(py-sh-argv script)python expression for the argv [sh -c script] as UTF-8 bytes, the argv :ctx/python->sh hands to subprocess. Bytes, so no locale can refuse a non-ASCII script.
python expression for the argv [sh -c script] as UTF-8 bytes, the argv :ctx/python->sh hands to subprocess. Bytes, so no locale can refuse a non-ASCII script.
The sh probes a python runtime runs through subprocess: every sh probe whose law is about the sh it reaches (see sh-law?), lifted by sh-via-python, in sh order. They follow py-probes, which proves the :py/ caps they need.
This is the probe-side half of a python->sh context layer: a general stacked runtime that probes an inner language through a wrapper would produce these by running the sh probes through :ctx/python->sh.
The sh probes a python runtime runs through subprocess: every sh probe whose law is about the sh it reaches (see sh-law?), lifted by sh-via-python, in sh order. They follow py-probes, which proves the :py/ caps they need. This is the probe-side half of a python->sh context layer: a general stacked runtime that probes an inner language through a wrapper would produce these by running the sh probes through :ctx/python->sh.
(python-via-sh {:keys [cap needs script] :as pr})The sh probe for python probe pr: its script run by python3 -c, one
single-quoted word, needing what pr needs plus :interp/python3 and
:sh/single-quote. The cap is pr's own, so :py/pathlib proved here and
:py/pathlib proved by a python runtime state one law. Refuses, as
ex-info, a script no sh word can hold (NUL).
The sh probe for python probe pr: its script run by `python3 -c`, one single-quoted word, needing what pr needs plus :interp/python3 and :sh/single-quote. The cap is pr's own, so :py/pathlib proved here and :py/pathlib proved by a python runtime state one law. Refuses, as ex-info, a script no sh word can hold (NUL).
(resolve-caps profile runtime-id lang run! caps)Probe every cap in caps that is still :unknown and has an on-demand probe in lang, folding the evidence into profile. Other caps are left as they are.
Probe every cap in caps that is still :unknown and has an on-demand probe in lang, folding the evidence into profile. Other caps are left as they are.
(run-evidence runtime-id {:keys [cap script expect] :as probe} result)Evidence for a probe that ran (or tried to).
Evidence for a probe that ran (or tried to).
(sh-via-python {:keys [needs script] :as pr})The python probe for sh probe pr: its script run as subprocess.run(["sh","-c",script]), the argv :ctx/python->sh runs, its stdout copied byte for byte and judged by the same :expect. It needs what pr needs plus :py/sys, :py/stdout-buffer, :py/subprocess and :interp/sh. The cap is pr's own: in a python runtime :sh/printf names the law of the sh that python reaches, as :py/pathlib in an sh runtime names the law of the python3 it reaches. Marked :lift false, so it is never lifted back into sh.
The python probe for sh probe pr: its script run as subprocess.run(["sh","-c",script]), the argv :ctx/python->sh runs, its stdout copied byte for byte and judged by the same :expect. It needs what pr needs plus :py/sys, :py/stdout-buffer, :py/subprocess and :interp/sh. The cap is pr's own: in a python runtime :sh/printf names the law of the sh that python reaches, as :py/pathlib in an sh runtime names the law of the python3 it reaches. Marked :lift false, so it is never lifted back into sh.
(skip-evidence runtime-id {:keys [cap script expect]} profile unproven)Evidence for a probe not run because a prerequisite was not proven.
Evidence for a probe not run because a prerequisite was not proven.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |