Liking cljdoc? Tell your friends :D

grammar.core

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"}])
raw docstring

composeclj

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

  • 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, because the solver orders by id and a profile keeps one verdict per capability;
  • a probe needing a capability that no earlier probe proves. Probes run in this order, so such a probe would be skipped on every runtime and its capability would stay :unknown forever.
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, because the solver orders by id and a profile keeps one
  verdict per capability;
- a probe needing a capability that no earlier probe proves. Probes run
  in this order, so such a probe would be skipped on every runtime and
  its capability would stay :unknown forever.
sourceraw docstring

core-moduleclj

The built-in languages, :sh and :python. 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 parts are vars, read by
compose at each call, so reloading grammar.realize or grammar.probe is seen
without reloading this namespace.
sourceraw docstring

discover!clj

(discover! runtime)
(discover! runtime {mods :modules :or {mods modules}})

Probe runtime with the probes of the language modules (opts :modules, default modules) and return its evidence-backed profile.

Probe runtime with the probes of the language modules (opts :modules,
default `modules`) and return its evidence-backed profile.
sourceraw docstring

effectclj

(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 and :run, 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 and :run, 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.
sourceraw docstring

envclj

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

modulesclj

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. A language reached through sh needs :sh/single-quote from :core, which is why :core comes first.

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. A language reached through sh needs
:sh/single-quote from :core, which is why :core comes first.
sourceraw docstring

planclj

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

plan-resolving!clj

(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, until it stops changing. Returns {:result Result :profile profile-after}.

Plan intent for runtime; when the plan is :blocked-on-unknown, probe its
:needs on demand and plan again, until it stops changing.
Returns {:result Result :profile profile-after}.
sourceraw docstring

realize!clj

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

resolve!clj

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

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

verifyclj

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

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