Plan a language-neutral intent into a program that is valid for one observed runtime: the shell it runs in, the tools on its PATH, the syntax it accepts, the characters and length a channel allows.
v1 proves one claim: one intent produces different valid implementations under different observed restrictions, with no handwritten per-environment commands.
deps.edn, with the version from the Clojars badge above:
io.github.buddhilw/grammar {:mvn/version "0.1.1"}
| Namespace | Stratum | Role |
|---|---|---|
grammar.schema | values | malli shapes: Intent, Verdict, Evidence, Profile, Result |
grammar.lit | pure | literal encoders (sh single/double/ANSI-C, printf FORMAT, python) |
grammar.profile | pure | tri-state capability profile; evidence-backed verdicts |
grammar.realize | data | realizations per intent × language, context wrappers |
grammar.solve | pure | deterministic search, text constraints, explanations |
grammar.probe | pure | discovery laws as scripts; verdicts from observed runs |
grammar.runtime | boundary | IRuntime port + ProcessRuntime adapter |
grammar.core | facade | discover!, plan, realize!, verify, effect |
[:str s]: emit exactly the bytes of s on stdout. Proves literal correctness.[:write-file {:path p :content c}]: p holds exactly c. Proves planning,
rendering, execution and verification together.[:run {:argv ["prog" "arg" ...]}]: execute prog with each argv element as
exactly one word (no NUL, which no argv can carry). The program is a
capability resolved on demand: plain planning returns :blocked-on-unknown
with :needs [:sh.cmd/prog]; realize! with {:resolve true} (or
plan-resolving!) probes it in the runtime, records the evidence and plans
again. Verified by exit status 0.[:ensure-dir {:path p}]: p is a directory (parents created, idempotent).
mkdir -p -- when the shell has mkdir, else python pathlib through a
context wrapper.[:remove-file {:path p}]: p is not a file (absent is fine). rm -f --
or python pathlib.unlink(missing_ok=True).(grammar.core/effect intent) observes, with no run, whether a state intent
(:write-file, :ensure-dir, :remove-file) already holds:
{:check kw :holds? bool}, or nil for :str and :run. A caller can skip
work that is already done. verify is that same observation after a run,
plus exit status 0. Both read the local filesystem, so they only apply to a
runtime that shares it.
The fixed probe catalog covers the shell's grammar. Capabilities that depend on the intent are probed when a plan needs them:
| Capability | Holds when | Needed by |
|---|---|---|
:sh.cmd/<prog> | the shell resolves the word (command -v): PATH, builtins, busybox applets | sh simple commands |
:bin/<prog> | exec finds an executable file on PATH ([ -f ] && [ -x ], shutil.which) | python subprocess |
grammar.probe/on-demand gives the probe for a language, grammar.core/resolve!
runs it. A realization adds intent-dependent requirements through
:requires-of (fn [intent] caps).
:yes / :no / :unknown. A capability nobody probed is :unknown and stays
:unknown; it never selects a program. When only unknowns block every option,
the result is :blocked-on-unknown with :needs (what to probe) and
:would-select (what would run). Every verdict keeps the ids of the evidence
behind it: the probe script, exit status, stdout, stderr, or a declared reason.
:status, :realization (ids, pre-order), :stack, :constraints
(:requires, text constraints, byte length), :evidence (ids into the
profile), :unknowns, and on failure :explain (every option, its required
caps split by verdict) and :rejected (text-constraint violations).
(require '[grammar.core :as g] '[grammar.runtime :as rt])
(def r (rt/process-runtime {:id :box :argv ["/usr/bin/bash" "-r" "-c"]
:env {"PATH" "/opt/allowed/bin" "LC_ALL" "C.UTF-8"}}))
(def prof (g/discover! r))
(g/realize! r prof [:write-file {:path "/tmp/x" :content "it's $HOME\n"}])
Interactive tour: dev/grammar/play.clj.
clojure -M:test
Runs against real bash, bash -r, dash, busybox sh and python3, with
PATH cut down per runtime to a scratch bin dir.
Built and published with hive-build
(clojure -T:build <task>; coordinates in version.edn, version floor in
VERSION).
ci.yml: the suite, the licence check and a jar build on every pull request
and every push outside main.release.yml: on a push to main that changes the library (src, test,
deps, version, licence, workflows), runs the suite and checks the licence.
It releases patch+1 of the highest of VERSION, the newest v* tag and the
newest release on Clojars, and stops if Clojars cannot be asked. It deploys
to Clojars and checks the upload, then pushes the tag and publishes a GitHub
release with that version's changelog section and the jar. A tag this
workflow pushes therefore names a version that shipped from that commit.
Nothing is committed back to main. Secrets: CLOJARS_USERNAME,
CLOJARS_DEPLOY_TOKEN.Copyright (C) 2026 buddhilw
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program (see LICENSE). If not, see https://www.gnu.org/licenses/.
Every source file carries SPDX-License-Identifier: GPL-3.0-or-later.
Can you improve this documentation?Edit on GitHub
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 |