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

core-moduleclj

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

discovery-probesclj

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

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