Facade: discover a runtime, plan an intent, run it there, verify the effect.
(def rt (runtime/process-runtime {:id :rbash :argv ["/usr/bin/bash" "-r" "-c"] :env {...}})) (def prof (discover! rt)) (plan prof :sh [:write-file {:path "/tmp/x" :content "hi"}]) (realize! rt prof [:write-file {:path "/tmp/x" :content "hi"}])
Facade: discover a runtime, plan an intent, run it there, verify the effect.
(def rt (runtime/process-runtime {:id :rbash :argv ["/usr/bin/bash" "-r" "-c"] :env {...}}))
(def prof (discover! rt))
(plan prof :sh [:write-file {:path "/tmp/x" :content "hi"}])
(realize! rt prof [:write-file {:path "/tmp/x" :content "hi"}])(compose mods)One registry from mods: their realizations, wrappers and probes concatenated in module order. A module part may be a var, which is read now, so a reloaded namespace is seen without reloading this one.
Refuses, as ex-info:
One registry from mods: their realizations, wrappers and probes concatenated in module order. A module part may be a var, which is read now, so a reloaded namespace is seen without reloading this one. Refuses, as ex-info: - mods that is not a sequence of maps with an :id keyword; - two realizations or two wrappers with one id, or two probes for one capability in one script language (probe :lang, default :sh), because the solver orders by id and a profile keeps one verdict per capability. One cap may have an sh probe and a python probe: a runtime runs only the probes of its own language, so it runs one of them; - a probe needing a capability that no earlier probe of its language proves. Probes run in this order, and only those of the runtime's language run, so such a probe would be skipped on every runtime and its capability would stay :unknown forever.
The built-in languages, :sh and :python. Its probes are grammar.probe/ catalog: the sh probes, then the python ones. Its parts are vars, read by compose at each call, so reloading grammar.realize or grammar.probe is seen without reloading this namespace.
The built-in languages, :sh and :python. Its probes are grammar.probe/ catalog: the sh probes, then the python ones. Its parts are vars, read by compose at each call, so reloading grammar.realize or grammar.probe is seen without reloading this namespace.
Backstop on plan-resolving! passes. Each pass probes at least one cap never probed before in the call, so the bound is reached only by an intent whose :needs keep growing.
Backstop on plan-resolving! passes. Each pass probes at least one cap never probed before in the call, so the bound is reached only by an intent whose :needs keep growing.
(discover! runtime)(discover! runtime {mods :modules :or {mods modules}})Probe runtime with the probes of the language modules (opts :modules,
default modules) written in the runtime's language, and return its
evidence-backed profile. An :sh runtime runs the sh probes, a :python
runtime the python ones; both prove the same cap names (:py/pathlib,
:interp/sh, ...). See discovery-probes for the languages refused.
Probe runtime with the probes of the language modules (opts :modules, default `modules`) written in the runtime's language, and return its evidence-backed profile. An :sh runtime runs the sh probes, a :python runtime the python ones; both prove the same cap names (:py/pathlib, :interp/sh, ...). See discovery-probes for the languages refused.
(discovery-probes mods lang)The probes discover! runs in a runtime of language lang: the composed probes of mods whose script is written in lang (probe :lang, default :sh), in module order. Refuses, as ex-info, a language no module writes probes in: :php and :perl modules probe through sh, so a runtime whose top-level language is :php or :perl has nothing it could run, and an empty profile would claim it had been looked at.
The probes discover! runs in a runtime of language lang: the composed probes of mods whose script is written in lang (probe :lang, default :sh), in module order. Refuses, as ex-info, a language no module writes probes in: :php and :perl modules probe through sh, so a runtime whose top-level language is :php or :perl has nothing it could run, and an empty profile would claim it had been looked at.
(effect [op arg :as _intent])Observe, with no run, whether the state that intent describes holds now: {:check kw :holds? bool}. Defined for state intents (:write-file, :ensure-dir, :remove-file); nil for :str, :run and :http-get, whose effect exists only as the output of a run. The observation reads this JVM's filesystem, so it is only meaningful for a runtime that shares it.
Observe, with no run, whether the state that intent describes holds now:
{:check kw :holds? bool}. Defined for state intents (:write-file,
:ensure-dir, :remove-file); nil for :str, :run and :http-get, whose effect
exists only as the output of a run. The observation reads this JVM's filesystem, so it
is only meaningful for a runtime that shares it.(env profile)(env profile {mods :modules :or {mods modules} :as opts})Planning environment over the realizations and wrappers of the language
modules (opts :modules, default modules). Other opts pass through to
grammar.solve/make-env (e.g. :admit).
Planning environment over the realizations and wrappers of the language modules (opts :modules, default `modules`). Other opts pass through to grammar.solve/make-env (e.g. :admit).
The language modules the facade composes, in order. A module is data in the shapes of grammar.realize and grammar.probe:
{:id kw :realizations [...] :wrappers [...] :probes [...]}
Probes run in module order, so a module's probes may need capabilities that an earlier module proves. PHP and Perl are reached through sh and their probes need :sh/single-quote, which is why :core comes first. A probe may carry :lang (default :sh), the language its script is written in; discover! runs only the probes in the runtime's language. :core writes probes in :sh and :python; PHP and Perl only in :sh.
Every realization and wrapper keeps the length law (grammar.law): its output is never shorter, in UTF-8 bytes, than what it encodes or embeds, because the planner prunes on :max-len by it. An entry that cannot keep it (compression, a short alias) declares :shortens? true, which turns that pruning off beneath it. A module author checks a registry with grammar.law/length-law-violations from a property test.
The language modules the facade composes, in order. A module is data in
the shapes of grammar.realize and grammar.probe:
{:id kw :realizations [...] :wrappers [...] :probes [...]}
Probes run in module order, so a module's probes may need capabilities
that an earlier module proves. PHP and Perl are reached through sh and
their probes need :sh/single-quote, which is why :core comes first.
A probe may carry :lang (default :sh), the language its script is
written in; discover! runs only the probes in the runtime's language.
:core writes probes in :sh and :python; PHP and Perl only in :sh.
Every realization and wrapper keeps the length law (grammar.law): its
output is never shorter, in UTF-8 bytes, than what it encodes or embeds,
because the planner prunes on :max-len by it. An entry that cannot keep
it (compression, a short alias) declares :shortens? true, which turns
that pruning off beneath it. A module author checks a registry with
grammar.law/length-law-violations from a property test.(plan profile lang intent)(plan profile lang intent opts)Pure: choose a realization of intent in lang under profile. opts :admit and :modules shape the environment (see env); the rest go to solve.
Pure: choose a realization of intent in lang under profile. opts :admit and :modules shape the environment (see env); the rest go to solve.
(plan-resolving! runtime profile intent)(plan-resolving! runtime profile intent opts)Plan intent for runtime; when the plan is :blocked-on-unknown, probe its :needs on demand and plan again. Each cap is probed at most once per call: a probe skipped for an unproven prerequisite, or one that cannot run, resolves to :unknown and is not retried. It stops when the plan is no longer blocked (:planned), when every need was already probed in this call (:exhausted), when a pass changed no verdict (:fixpoint, on cap states, not on evidence), or after opts :max-passes plans (default default-max-passes, :pass-bound).
Returns {:result Result :profile profile-after :passes n :stopped why}; when the Result is still blocked it also carries :unresolved, the needs still :unknown. Other opts go to plan.
Plan intent for runtime; when the plan is :blocked-on-unknown, probe its
:needs on demand and plan again. Each cap is probed at most once per call:
a probe skipped for an unproven prerequisite, or one that cannot run,
resolves to :unknown and is not retried. It stops when the plan is no
longer blocked (:planned), when every need was already probed in this
call (:exhausted), when a pass changed no verdict (:fixpoint, on cap
states, not on evidence), or after opts :max-passes plans (default
default-max-passes, :pass-bound).
Returns {:result Result :profile profile-after :passes n :stopped why};
when the Result is still blocked it also carries :unresolved, the needs
still :unknown. Other opts go to plan.(realize! runtime profile intent)(realize! runtime profile intent opts)Plan intent for runtime's language under profile, execute it, verify it. A non-:ok plan is returned unchanged: nothing is run. opts :resolve true probes blocked unknowns on demand first (see plan-resolving!); the enriched profile is then under :profile-after.
Plan intent for runtime's language under profile, execute it, verify it. A non-:ok plan is returned unchanged: nothing is run. opts :resolve true probes blocked unknowns on demand first (see plan-resolving!); the enriched profile is then under :profile-after.
(resolve! runtime profile caps)Probe, in runtime, every cap in caps that is still :unknown and has an on-demand probe (e.g. :bin/git). Returns the enriched profile. A probe whose run never happens (a launch error, a timeout, an execute that throws) or whose prerequisites are unproven leaves its cap :unknown.
Probe, in runtime, every cap in caps that is still :unknown and has an on-demand probe (e.g. :bin/git). Returns the enriched profile. A probe whose run never happens (a launch error, a timeout, an execute that throws) or whose prerequisites are unproven leaves its cap :unknown.
(verify [op arg :as intent] run)Check the observable effect of intent against what the run produced. A state intent verifies when the run exited 0 and its effect holds after it. :run and :http-get verify on exit 0: the bytes an :http-get fetched are the server's to know, so the caller compares (:out-bytes run) itself.
Check the observable effect of intent against what the run produced. A state intent verifies when the run exited 0 and its effect holds after it. :run and :http-get verify on exit 0: the bytes an :http-get fetched are the server's to know, so the caller compares (:out-bytes run) itself.
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 |