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 :cost structural cost, a number >= 0: realization and wrapper costs summed, a literal encoder adding 0 :key the ranks on the way in pre-order, each [kind cost id], kind 0 for a realization and 1 for a wrapper; it orders equal costs}
Every key is mandatory: stamp, enclose and merge-parts add to :cost and :key, so a hand-built candidate without them throws. Ranks come from realization-rank and wrapper-rank and queue entries from bound and stream, so the [kind cost id] grammar of keys is written only here.
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
:cost structural cost, a number >= 0: realization and wrapper costs
summed, a literal encoder adding 0
:key the ranks on the way in pre-order, each [kind cost id], kind
0 for a realization and 1 for a wrapper; it orders equal costs}
Every key is mandatory: stamp, enclose and merge-parts add to :cost and
:key, so a hand-built candidate without them throws. Ranks come from
realization-rank and wrapper-rank and queue entries from bound and
stream, so the [kind cost id] grammar of keys is written only here.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"}])Perl as a target language: literal encoders, realizations, context wrappers and the probes behind every capability they rely on.
Exports data in exactly the shapes of grammar.realize and grammar.probe.
module bundles them for grammar.core/compose, and grammar.core/modules
includes it by default.
Strings are bytes. A Perl literal here denotes the UTF-8 bytes of the intent's string as a byte string (every char < 256, no utf8 flag), and every handle written to is binmode'd first, so no I/O layer (PERL_UNICODE, -C, a locale) can re-encode what is printed.
Capabilities (all probed through the shell, all needing :interp/perl):
:interp/perl perl -e runs a program from the PATH :pl/binmode binmode(STDOUT) makes STDOUT a raw byte stream :pl/print print(STDOUT ...) writes and reports success :pl/syswrite syswrite writes unbuffered and returns a byte count :pl/open-write 3-arg open(..., '>', path) creates/truncates a file :pl/sysopen Fcntl loads and sysopen(O_WRONLY|O_CREAT|O_TRUNC) works :pl/system system with a LIST runs a program (no shell) and waits
Perl as a target language: literal encoders, realizations, context wrappers and the probes behind every capability they rely on. Exports data in exactly the shapes of grammar.realize and grammar.probe. `module` bundles them for grammar.core/compose, and grammar.core/modules includes it by default. Strings are bytes. A Perl literal here denotes the UTF-8 bytes of the intent's string as a byte string (every char < 256, no utf8 flag), and every handle written to is binmode'd first, so no I/O layer (PERL_UNICODE, -C, a locale) can re-encode what is printed. Capabilities (all probed through the shell, all needing :interp/perl): :interp/perl perl -e runs a program from the PATH :pl/binmode binmode(STDOUT) makes STDOUT a raw byte stream :pl/print print(STDOUT ...) writes and reports success :pl/syswrite syswrite writes unbuffered and returns a byte count :pl/open-write 3-arg open(..., '>', path) creates/truncates a file :pl/sysopen Fcntl loads and sysopen(O_WRONLY|O_CREAT|O_TRUNC) works :pl/system system with a LIST runs a program (no shell) and waits
PHP as a target language, as data in the shapes of grammar.realize and grammar.probe.
realizations :lit, :str and :write-file rendered in :php. Each one
requires :php.fn/<f> for every PHP function its text calls,
so a function removed with -d disable_functions=... takes
the realizations that call it out of the search. Language
constructs (echo, eval, exit) are not functions and cannot
be disabled; they require nothing.
wrappers context emitters into and out of PHP: sh running php -r,
php eval, php running sh or python3 through proc_open,
python running php through subprocess.
probes :interp/php, :php/first-class-callable, :php/proc-open-argv,
then one function_exists probe per function the realizations
and wrappers call. Each needs :interp/php, so without php
they are skipped and stay :unknown.
module bundles the three for grammar.core/compose, and
grammar.core/modules includes it by default.
PHP as a target language, as data in the shapes of grammar.realize and
grammar.probe.
realizations :lit, :str and :write-file rendered in :php. Each one
requires :php.fn/<f> for every PHP function its text calls,
so a function removed with `-d disable_functions=...` takes
the realizations that call it out of the search. Language
constructs (echo, eval, exit) are not functions and cannot
be disabled; they require nothing.
wrappers context emitters into and out of PHP: sh running php -r,
php eval, php running sh or python3 through proc_open,
python running php through subprocess.
probes :interp/php, :php/first-class-callable, :php/proc-open-argv,
then one function_exists probe per function the realizations
and wrappers call. Each needs :interp/php, so without php
they are skipped and stay :unknown.
`module` bundles the three for grammar.core/compose, and
grammar.core/modules includes it by default.Laws a language module must keep, as plain checks a module author can call from a property test.
The length law: no output of an encoder is shorter, in UTF-8 bytes, than the text it encodes, and no output of a realization or wrapper is shorter than any piece it embeds. grammar.solve relies on it to prune every candidate already over a profile's :max-len, together with everything that would be built from it. An entry that cannot keep it declares :shortens? true; pruning is then off beneath it, and the law does not apply to it.
Laws a language module must keep, as plain checks a module author can call from a property test. The length law: no output of an encoder is shorter, in UTF-8 bytes, than the text it encodes, and no output of a realization or wrapper is shorter than any piece it embeds. grammar.solve relies on it to prune every candidate already over a profile's :max-len, together with everything that would be built from it. An entry that cannot keep it declares :shortens? true; pruning is then off beneath it, and the law does not apply to it.
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.
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.
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.
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), ascending by :cost: best-first takes the first one's cost as a lower bound for the rest. grammar.candidate/leaf and grammar.candidate/combine both return such seqs. A realization's :cost and a wrapper's :cost are numbers >= 0 and every :id is a keyword; grammar.solve/make-env refuses anything else.
Length law: no output is shorter, in UTF-8 bytes, than the text an encoder encodes or than any piece a realization or wrapper embeds. The solver relies on it to drop a candidate already over the profile's :max-len together with everything that would be built from it. It is grammar.law/length-law-violations, checked over this registry by grammar.length-law-test; an entry that breaks it declares :shortens?.
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), ascending by :cost: best-first takes the first one's cost as a lower bound for the rest. grammar.candidate/leaf and grammar.candidate/combine both return such seqs. A realization's :cost and a wrapper's :cost are numbers >= 0 and every :id is a keyword; grammar.solve/make-env refuses anything else. Length law: no output is shorter, in UTF-8 bytes, than the text an encoder encodes or than any piece a realization or wrapper embeds. The solver relies on it to drop a candidate already over the profile's :max-len together with everything that would be built from it. It is grammar.law/length-law-violations, checked over this registry by grammar.length-law-test; an entry that breaks it declares :shortens?.
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.
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.Deterministic planner. Pure: a profile and a registry in, a Result out.
Search is best-first by structural cost: a candidate's cost is the sum of its realization and wrapper costs, literal encoders adding 0, so a direct realization can lose to a cheaper delegation. Equal costs break by pre-order (direct before delegation, realizations by [cost id], 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 is best-first by structural cost: a candidate's cost is the sum of its realization and wrapper costs, literal encoders adding 0, so a direct realization can lose to a cheaper delegation. Equal costs break by pre-order (direct before delegation, realizations by [cost id], 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).
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 |