Liking cljdoc? Tell your friends :D

grammar.probe

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.
raw docstring

catalogclj

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.
sourceraw docstring

discoverclj

(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.
sourceraw docstring

evidence-idclj

(evidence-id runtime-id cap)
source

for-langclj

(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.
sourceraw docstring

judgeclj

(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.
sourceraw docstring

on-demandclj

(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.
sourceraw docstring

probe-langclj

(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.
sourceraw docstring

probesclj

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.
sourceraw docstring

py-probesclj

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.
sourceraw docstring

py-sh-argvclj

(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.
sourceraw docstring

py-sh-probesclj

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.
sourceraw docstring

python-via-shclj

(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).
sourceraw docstring

resolve-capsclj

(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.
sourceraw docstring

run-evidenceclj

(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).
sourceraw docstring

sh-via-pythonclj

(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.
sourceraw docstring

skip-evidenceclj

(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.
sourceraw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close