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

os-functionsclj

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

python-via-shclj

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

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