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

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
raw docstring

grammar.lang.php

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

grammar.law

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.
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), 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?.
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 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).
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