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