diff --git a/projects/org-eval-tool/README.org b/projects/org-eval-tool/README.org new file mode 100644 index 0000000..ba65bb7 --- /dev/null +++ b/projects/org-eval-tool/README.org @@ -0,0 +1,17 @@ +#+TITLE: org-eval + +Evaluate Lisp source blocks in an .org file via Emacs batch mode. + +== Usage + +#+begin_src shell + org-eval org/file.org # evaluate all blocks + org-eval org/file.org 3 # evaluate block at index 3 (0-based) +#+end_src + +Useful for quick REPL evaluation without starting the daemon — Emacs +tangles and evaluates the block inline. Results are printed to stdout. + +== Dependencies + +Emacs with org-mode (org-babel). diff --git a/projects/repl-tool/README.org b/projects/repl-tool/README.org new file mode 100644 index 0000000..06287ab --- /dev/null +++ b/projects/repl-tool/README.org @@ -0,0 +1,27 @@ +#+TITLE: repl + +Send a Lisp form to the running Passepartout daemon REPL (port 9105). +Prints the response from the daemon. + +== Usage + +#+begin_src shell + repl "(+ 1 2)" + echo "(+ 1 2)" | repl +#+end_src + +== Environment + +- ~PASSEPARTOUT_HOST~ — daemon host (default 127.0.0.1) +- ~PASSEPARTOUT_PORT~ — daemon port (default 9105) +- ~PASSEPARTOUT_REPL_TIMEOUT~ — timeout seconds (default 10) + +== Protocol + +Connects via framed TCP (6-byte hex length prefix). Sends a +~:repl-eval~ sensor event and reads the response. Expects the +daemon to be running (~passepartout daemon~). + +== Dependencies + +Perl (stdlib only). diff --git a/projects/tangle-tool/README.org b/projects/tangle-tool/README.org new file mode 100644 index 0000000..fbe00c4 --- /dev/null +++ b/projects/tangle-tool/README.org @@ -0,0 +1,16 @@ +#+TITLE: tangle + +Generate .lisp files from .org sources via Emacs org-babel-tangle. + +== Usage + +#+begin_src shell + tangle org/file.org +#+end_src + +Requires the org file to have ~#+PROPERTY: header-args:lisp :tangle target.lisp~ +or per-block ~:tangle~ headers. Files without a ~:tangle~ header are skipped. + +== Dependencies + +Emacs with org-mode (ob-tangle). diff --git a/projects/verify-repl-tool/README.org b/projects/verify-repl-tool/README.org new file mode 100644 index 0000000..fbac0b2 --- /dev/null +++ b/projects/verify-repl-tool/README.org @@ -0,0 +1,30 @@ +#+TITLE: verify-repl + +Compliance checker for literate programming discipline. Scans .org files +for violations of the REPL-first and one-per-block rules. + +== Usage + +#+begin_src shell + verify-repl org/ + verify-repl projects/passepartout/org/ +#+end_src + +== Checks performed + +1. **REPL-first** — every ~(defun|defmacro|defvar|defstruct|defmethod|defclass)~ + block must have ~;; REPL-VERIFIED: ~ on the line above + ~#+begin_src lisp~. Any definition block without this comment is a violation. +2. **One-per-block** — each ~#+begin_src lisp~ block must contain exactly one + top-level form. Multiple defuns in the same block are a violation. +3. **Prose-before-code** — each code block must be preceded by an Org headline + (the prose explanation). Blocks without a preceding headline are a violation. + +== Exempt files + +Some core infrastructure files are blacklisted (package definitions, setup), +defined in the script's ~BLACKLIST~ array. Extend as needed. + +== Dependencies + +Bash, grep.