Liking cljdoc? Tell your friends :D

grammar.candidate

Candidate programs: code plus the provenance that justifies it.

{:code program text :via realization and wrapper ids, pre-order :requires every capability the text relies on :stack languages from outermost to innermost}

Candidate programs: code plus the provenance that justifies it.

{:code     program text
 :via      realization and wrapper ids, pre-order
 :requires every capability the text relies on
 :stack    languages from outermost to innermost}
raw docstring

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

grammar.lit

Pure literal encoders.

Each encoder returns program text that, read in its context, denotes exactly the input string, or nil when that context cannot denote it at all (a shell word cannot hold NUL). Encoders never consult a profile: whether a construct is allowed is the solver's business.

Pure literal encoders.

Each encoder returns program text that, read in its context, denotes
exactly the input string, or nil when that context cannot denote it at
all (a shell word cannot hold NUL). Encoders never consult a profile:
whether a construct is allowed is the solver's business.
raw docstring

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

grammar.profile

Tri-state capability profile: pure construction and queries.

A capability absent from the profile is :unknown. Nothing in this namespace turns :unknown into :yes or :no; only evidence does, and every verdict keeps the ids of the evidence that produced it.

Tri-state capability profile: pure construction and queries.

A capability absent from the profile is :unknown. Nothing in this
namespace turns :unknown into :yes or :no; only evidence does, and every
verdict keeps the ids of the evidence that produced it.
raw docstring

grammar.realize

Built-in realizations and context wrappers, as data.

A realization renders one intent in one language. It declares every capability its text relies on, and the solver admits it only when the profile holds evidence that each one is :yes.

A wrapper is a context emitter: it turns a program in an inner language into a program in an outer one (sh running python3 -c, python running sh -c, ...). Wrappers build context stacks, both for automatic delegation and for an explicitly requested stack.

:render receives an env whose (:lit env) is (fn [lang s] candidates) and returns a lazy seq of candidates (see grammar.candidate).

Built-in realizations and context wrappers, as data.

A realization renders one intent in one language. It declares every
capability its text relies on, and the solver admits it only when the
profile holds evidence that each one is :yes.

A wrapper is a context emitter: it turns a program in an inner language
into a program in an outer one (sh running python3 -c, python running
sh -c, ...). Wrappers build context stacks, both for automatic
delegation and for an explicitly requested stack.

:render receives an env whose (:lit env) is (fn [lang s] candidates) and
returns a lazy seq of candidates (see grammar.candidate).
raw docstring

grammar.runtime

Boundary: the only namespace that starts processes.

A Runtime is a port: something that can execute program text in one language and report what happened. ProcessRuntime is the adapter for a real interpreter: an argv prefix (e.g. ["/usr/bin/bash" "-r" "-c"]) and a complete environment. The program is passed as the last argv element, never through a shell, so the planner's text arrives byte for byte.

Boundary: the only namespace that starts processes.

A Runtime is a port: something that can execute program text in one
language and report what happened. ProcessRuntime is the adapter for a
real interpreter: an argv prefix (e.g. ["/usr/bin/bash" "-r" "-c"])
and a complete environment. The program is passed as the last argv
element, never through a shell, so the planner's text arrives byte for
byte.
raw docstring

grammar.schema

Value objects. Every other namespace speaks in these shapes.

Intent what the caller wants, language-neutral. Verdict tri-state truth of a capability: :yes, :no, :unknown. Evidence why a verdict (or a text constraint) holds: a probe run with its exit status and output, or an explicit declaration. Profile capabilities + text constraints + the evidence behind them. Result what the planner returns, always carrying its justification.

Value objects. Every other namespace speaks in these shapes.

Intent      what the caller wants, language-neutral.
Verdict     tri-state truth of a capability: :yes, :no, :unknown.
Evidence    why a verdict (or a text constraint) holds: a probe run with
            its exit status and output, or an explicit declaration.
Profile     capabilities + text constraints + the evidence behind them.
Result      what the planner returns, always carrying its justification.
raw docstring

grammar.solve

Deterministic planner. Pure: a profile and a registry in, a Result out.

Search order is fixed: realizations by [cost id], direct ones before delegation through a context wrapper, children left to right. The first candidate whose text satisfies the profile's text constraints wins.

A realization is admitted only when every capability it requires is :yes. An :unknown never selects a program. When nothing is admitted the search runs again with unknowns let through, only to report what resolving them would unlock (:blocked-on-unknown).

Deterministic planner. Pure: a profile and a registry in, a Result out.

Search order is fixed: realizations by [cost id], direct ones before
delegation through a context wrapper, children left to right. The first
candidate whose text satisfies the profile's text constraints wins.

A realization is admitted only when every capability it requires is
:yes. An :unknown never selects a program. When nothing is admitted the
search runs again with unknowns let through, only to report what
resolving them would unlock (:blocked-on-unknown).
raw 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