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, sh then python: what grammar.core's :core module composes. discover! keeps the ones written in the runtime's language.
Every built-in probe, sh then python: 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. sh runtimes only.
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. sh runtimes only.The os functions the python realizations reach: pathlib's mkdir calls os.mkdir, its unlink calls os.unlink. Each has a fixed :py.os/<f> probe.
The os functions the python realizations reach: pathlib's mkdir calls os.mkdir, its unlink calls os.unlink. Each has a fixed :py.os/<f> probe.
(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. The scripts hold no single quote, so each one lifts into an sh
probe unchanged (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/subprocess import subprocess :py/urllib import shutil, urllib.request :py.os/<f> os.<f> exists and is callable, for f in os-functions :interp/sh subprocess runs ["sh" "-c" ...], sh found on PATH: the argv :ctx/python->sh runs. A /bin/sh off PATH does not count. 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. The scripts hold no single quote, so each one lifts into an sh
probe unchanged (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/subprocess import subprocess
:py/urllib import shutil, urllib.request
:py.os/<f> os.<f> exists and is callable, for f in os-functions
:interp/sh subprocess runs ["sh" "-c" ...], sh found on PATH:
the argv :ctx/python->sh runs. A /bin/sh off PATH does
not count. Marked :lift false: sh runtimes prove
:interp/sh with their own probe.(python-via-sh {:keys [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.
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.
(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).
(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 |